From 91dcb31886adc9f511cad2fc93f42d4937285578 Mon Sep 17 00:00:00 2001 From: Paulo Victor Gomes Date: Sat, 21 Mar 2026 14:06:49 +0100 Subject: [PATCH] docs(pt-BR): add rules translation --- docs/pt-BR/rules/agents.md | 50 +++++++++++++++++++++++++++++ docs/pt-BR/rules/coding-style.md | 48 ++++++++++++++++++++++++++++ docs/pt-BR/rules/git-workflow.md | 24 ++++++++++++++ docs/pt-BR/rules/hooks.md | 30 +++++++++++++++++ docs/pt-BR/rules/patterns.md | 31 ++++++++++++++++++ docs/pt-BR/rules/performance.md | 55 ++++++++++++++++++++++++++++++++ docs/pt-BR/rules/security.md | 29 +++++++++++++++++ docs/pt-BR/rules/testing.md | 29 +++++++++++++++++ 8 files changed, 296 insertions(+) create mode 100644 docs/pt-BR/rules/agents.md create mode 100644 docs/pt-BR/rules/coding-style.md create mode 100644 docs/pt-BR/rules/git-workflow.md create mode 100644 docs/pt-BR/rules/hooks.md create mode 100644 docs/pt-BR/rules/patterns.md create mode 100644 docs/pt-BR/rules/performance.md create mode 100644 docs/pt-BR/rules/security.md create mode 100644 docs/pt-BR/rules/testing.md diff --git a/docs/pt-BR/rules/agents.md b/docs/pt-BR/rules/agents.md new file mode 100644 index 00000000..0454a0e1 --- /dev/null +++ b/docs/pt-BR/rules/agents.md @@ -0,0 +1,50 @@ +# Orquestração de Agentes + +## Agentes Disponíveis + +Localizados em `~/.claude/agents/`: + +| Agente | Propósito | Quando Usar | +|--------|-----------|-------------| +| planner | Planejamento de implementação | Recursos complexos, refatoração | +| architect | Design de sistema | Decisões arquiteturais | +| tdd-guide | Desenvolvimento orientado a testes | Novos recursos, correção de bugs | +| code-reviewer | Revisão de código | Após escrever código | +| security-reviewer | Análise de segurança | Antes de commits | +| build-error-resolver | Corrigir erros de build | Quando o build falha | +| e2e-runner | Testes E2E | Fluxos críticos do usuário | +| refactor-cleaner | Limpeza de código morto | Manutenção de código | +| doc-updater | Documentação | Atualização de docs | +| rust-reviewer | Revisão de código Rust | Projetos Rust | + +## Uso Imediato de Agentes + +Sem necessidade de prompt do usuário: +1. Solicitações de recursos complexos - Use o agente **planner** +2. Código acabado de escrever/modificar - Use o agente **code-reviewer** +3. Correção de bug ou novo recurso - Use o agente **tdd-guide** +4. Decisão arquitetural - Use o agente **architect** + +## Execução Paralela de Tarefas + +SEMPRE use execução paralela de Task para operações independentes: + +```markdown +# BOM: Execução paralela +Iniciar 3 agentes em paralelo: +1. Agente 1: Análise de segurança do módulo de autenticação +2. Agente 2: Revisão de desempenho do sistema de cache +3. Agente 3: Verificação de tipos dos utilitários + +# RUIM: Sequencial quando desnecessário +Primeiro agente 1, depois agente 2, depois agente 3 +``` + +## Análise Multi-Perspectiva + +Para problemas complexos, use subagentes com papéis divididos: +- Revisor factual +- Engenheiro sênior +- Especialista em segurança +- Revisor de consistência +- Verificador de redundância diff --git a/docs/pt-BR/rules/coding-style.md b/docs/pt-BR/rules/coding-style.md new file mode 100644 index 00000000..5788f376 --- /dev/null +++ b/docs/pt-BR/rules/coding-style.md @@ -0,0 +1,48 @@ +# Estilo de Código + +## Imutabilidade (CRÍTICO) + +SEMPRE crie novos objetos, NUNCA modifique os existentes: + +``` +// Pseudocódigo +ERRADO: modificar(original, campo, valor) → altera o original in-place +CORRETO: atualizar(original, campo, valor) → retorna nova cópia com a alteração +``` + +Justificativa: Dados imutáveis previnem efeitos colaterais ocultos, facilita a depuração e permite concorrência segura. + +## Organização de Arquivos + +MUITOS ARQUIVOS PEQUENOS > POUCOS ARQUIVOS GRANDES: +- Alta coesão, baixo acoplamento +- 200-400 linhas típico, 800 máximo +- Extrair utilitários de módulos grandes +- Organizar por recurso/domínio, não por tipo + +## Tratamento de Erros + +SEMPRE trate erros de forma abrangente: +- Trate erros explicitamente em cada nível +- Forneça mensagens de erro amigáveis no código voltado para UI +- Registre contexto detalhado de erro no lado do servidor +- Nunca engula erros silenciosamente + +## Validação de Entrada + +SEMPRE valide nas fronteiras do sistema: +- Valide toda entrada do usuário antes de processar +- Use validação baseada em schema onde disponível +- Falhe rapidamente com mensagens de erro claras +- Nunca confie em dados externos (respostas de API, entrada do usuário, conteúdo de arquivo) + +## Checklist de Qualidade de Código + +Antes de marcar o trabalho como concluído: +- [ ] O código é legível e bem nomeado +- [ ] Funções são pequenas (< 50 linhas) +- [ ] Arquivos são focados (< 800 linhas) +- [ ] Sem aninhamento profundo (> 4 níveis) +- [ ] Tratamento adequado de erros +- [ ] Sem valores hardcoded (use constantes ou config) +- [ ] Sem mutação (padrões imutáveis usados) diff --git a/docs/pt-BR/rules/git-workflow.md b/docs/pt-BR/rules/git-workflow.md new file mode 100644 index 00000000..17af0cb4 --- /dev/null +++ b/docs/pt-BR/rules/git-workflow.md @@ -0,0 +1,24 @@ +# Fluxo de Trabalho Git + +## Formato de Mensagem de Commit +``` +: + + +``` + +Tipos: feat, fix, refactor, docs, test, chore, perf, ci + +Nota: Atribuição desabilitada globalmente via ~/.claude/settings.json. + +## Fluxo de Trabalho de Pull Request + +Ao criar PRs: +1. Analisar o histórico completo de commits (não apenas o último commit) +2. Usar `git diff [branch-base]...HEAD` para ver todas as alterações +3. Rascunhar resumo abrangente do PR +4. Incluir plano de teste com TODOs +5. Fazer push com a flag `-u` se for uma nova branch + +> Para o processo de desenvolvimento completo (planejamento, TDD, revisão de código) antes de operações git, +> veja [development-workflow.md](./development-workflow.md). diff --git a/docs/pt-BR/rules/hooks.md b/docs/pt-BR/rules/hooks.md new file mode 100644 index 00000000..5f2b85e8 --- /dev/null +++ b/docs/pt-BR/rules/hooks.md @@ -0,0 +1,30 @@ +# Sistema de Hooks + +## Tipos de Hook + +- **PreToolUse**: Antes da execução da ferramenta (validação, modificação de parâmetros) +- **PostToolUse**: Após a execução da ferramenta (auto-formatação, verificações) +- **Stop**: Quando a sessão termina (verificação final) + +## Permissões de Auto-Aceite + +Use com cautela: +- Habilite para planos confiáveis e bem definidos +- Desabilite para trabalho exploratório +- Nunca use a flag dangerously-skip-permissions +- Configure `allowedTools` em `~/.claude.json` em vez disso + +## Melhores Práticas para TodoWrite + +Use a ferramenta TodoWrite para: +- Rastrear progresso em tarefas com múltiplos passos +- Verificar compreensão das instruções +- Habilitar direcionamento em tempo real +- Mostrar etapas de implementação granulares + +A lista de tarefas revela: +- Etapas fora de ordem +- Itens faltando +- Itens extras desnecessários +- Granularidade incorreta +- Requisitos mal interpretados diff --git a/docs/pt-BR/rules/patterns.md b/docs/pt-BR/rules/patterns.md new file mode 100644 index 00000000..6b9c4c07 --- /dev/null +++ b/docs/pt-BR/rules/patterns.md @@ -0,0 +1,31 @@ +# Padrões Comuns + +## Projetos Skeleton + +Ao implementar novas funcionalidades: +1. Buscar projetos skeleton bem testados +2. Usar agentes paralelos para avaliar opções: + - Avaliação de segurança + - Análise de extensibilidade + - Pontuação de relevância + - Planejamento de implementação +3. Clonar a melhor opção como fundação +4. Iterar dentro da estrutura comprovada + +## Padrões de Design + +### Padrão Repository + +Encapsular acesso a dados atrás de uma interface consistente: +- Definir operações padrão: findAll, findById, create, update, delete +- Implementações concretas lidam com detalhes de armazenamento (banco de dados, API, arquivo, etc.) +- A lógica de negócios depende da interface abstrata, não do mecanismo de armazenamento +- Habilita troca fácil de fontes de dados e simplifica testes com mocks + +### Formato de Resposta da API + +Use um envelope consistente para todas as respostas de API: +- Incluir indicador de sucesso/status +- Incluir o payload de dados (nullable em caso de erro) +- Incluir campo de mensagem de erro (nullable em caso de sucesso) +- Incluir metadados para respostas paginadas (total, página, limite) diff --git a/docs/pt-BR/rules/performance.md b/docs/pt-BR/rules/performance.md new file mode 100644 index 00000000..064efd40 --- /dev/null +++ b/docs/pt-BR/rules/performance.md @@ -0,0 +1,55 @@ +# Otimização de Desempenho + +## Estratégia de Seleção de Modelo + +**Haiku 4.5** (90% da capacidade do Sonnet, 3x economia de custo): +- Agentes leves com invocação frequente +- Programação em par e geração de código +- Agentes worker em sistemas multi-agente + +**Sonnet 4.6** (Melhor modelo para codificação): +- Trabalho principal de desenvolvimento +- Orquestrando fluxos de trabalho multi-agente +- Tarefas de codificação complexas + +**Opus 4.5** (Raciocínio mais profundo): +- Decisões arquiteturais complexas +- Requisitos máximos de raciocínio +- Pesquisa e análise + +## Gerenciamento da Janela de Contexto + +Evite os últimos 20% da janela de contexto para: +- Refatoração em grande escala +- Implementação de recursos abrangendo múltiplos arquivos +- Depuração de interações complexas + +Tarefas com menor sensibilidade ao contexto: +- Edições de arquivo único +- Criação de utilitários independentes +- Atualizações de documentação +- Correções de bugs simples + +## Pensamento Estendido + Modo de Plano + +O pensamento estendido está habilitado por padrão, reservando até 31.999 tokens para raciocínio interno. + +Controle o pensamento estendido via: +- **Toggle**: Option+T (macOS) / Alt+T (Windows/Linux) +- **Config**: Defina `alwaysThinkingEnabled` em `~/.claude/settings.json` +- **Limite de orçamento**: `export MAX_THINKING_TOKENS=10000` +- **Modo verbose**: Ctrl+O para ver a saída de pensamento + +Para tarefas complexas que requerem raciocínio profundo: +1. Garantir que o pensamento estendido esteja habilitado (habilitado por padrão) +2. Habilitar **Modo de Plano** para abordagem estruturada +3. Usar múltiplas rodadas de crítica para análise minuciosa +4. Usar subagentes com papéis divididos para perspectivas diversas + +## Resolução de Problemas de Build + +Se o build falhar: +1. Use o agente **build-error-resolver** +2. Analise mensagens de erro +3. Corrija incrementalmente +4. Verifique após cada correção diff --git a/docs/pt-BR/rules/security.md b/docs/pt-BR/rules/security.md new file mode 100644 index 00000000..c651865d --- /dev/null +++ b/docs/pt-BR/rules/security.md @@ -0,0 +1,29 @@ +# Diretrizes de Segurança + +## Verificações de Segurança Obrigatórias + +Antes de QUALQUER commit: +- [ ] Sem segredos hardcoded (chaves de API, senhas, tokens) +- [ ] Todas as entradas do usuário validadas +- [ ] Prevenção de injeção SQL (queries parametrizadas) +- [ ] Prevenção de XSS (HTML sanitizado) +- [ ] Proteção CSRF habilitada +- [ ] Autenticação/autorização verificada +- [ ] Rate limiting em todos os endpoints +- [ ] Mensagens de erro não vazam dados sensíveis + +## Gerenciamento de Segredos + +- NUNCA hardcode segredos no código-fonte +- SEMPRE use variáveis de ambiente ou um gerenciador de segredos +- Valide que os segredos necessários estão presentes na inicialização +- Rotacione quaisquer segredos que possam ter sido expostos + +## Protocolo de Resposta a Segurança + +Se um problema de segurança for encontrado: +1. PARE imediatamente +2. Use o agente **security-reviewer** +3. Corrija problemas CRÍTICOS antes de continuar +4. Rotacione quaisquer segredos expostos +5. Revise toda a base de código por problemas similares diff --git a/docs/pt-BR/rules/testing.md b/docs/pt-BR/rules/testing.md new file mode 100644 index 00000000..460b7368 --- /dev/null +++ b/docs/pt-BR/rules/testing.md @@ -0,0 +1,29 @@ +# Requisitos de Teste + +## Cobertura Mínima de Teste: 80% + +Tipos de Teste (TODOS obrigatórios): +1. **Testes Unitários** - Funções individuais, utilitários, componentes +2. **Testes de Integração** - Endpoints de API, operações de banco de dados +3. **Testes E2E** - Fluxos críticos do usuário (framework escolhido por linguagem) + +## Desenvolvimento Orientado a Testes (TDD) + +Fluxo de trabalho OBRIGATÓRIO: +1. Escreva o teste primeiro (VERMELHO) +2. Execute o teste - deve FALHAR +3. Escreva a implementação mínima (VERDE) +4. Execute o teste - deve PASSAR +5. Refatore (MELHORE) +6. Verifique cobertura (80%+) + +## Resolução de Falhas de Teste + +1. Use o agente **tdd-guide** +2. Verifique o isolamento de teste +3. Verifique se os mocks estão corretos +4. Corrija a implementação, não os testes (a menos que os testes estejam errados) + +## Suporte de Agentes + +- **tdd-guide** - Use PROATIVAMENTE para novos recursos, aplica escrever-testes-primeiro