The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
docs(pt-BR): add rules translation
Paulo Victor Gomes91dcb31886ad
diff --git a/docs/pt-BR/rules/agents.md b/docs/pt-BR/rules/agents.mdnew file mode 100644index 000000000..0454a0e12--- /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ânciadiff --git a/docs/pt-BR/rules/coding-style.md b/docs/pt-BR/rules/coding-style.mdnew file mode 100644index 000000000..5788f376f--- /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.mdnew file mode 100644index 000000000..17af0cb4b--- /dev/null+++ b/docs/pt-BR/rules/git-workflow.md@@ -0,0 +1,24 @@+# Fluxo de Trabalho Git++## Formato de Mensagem de Commit+```+<tipo>: <descrição>++<corpo opcional>+```++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.mdnew file mode 100644index 000000000..5f2b85e8a--- /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 interpretadosdiff --git a/docs/pt-BR/rules/patterns.md b/docs/pt-BR/rules/patterns.mdnew file mode 100644index 000000000..6b9c4c07b--- /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.mdnew file mode 100644index 000000000..064efd40b--- /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çãodiff --git a/docs/pt-BR/rules/security.md b/docs/pt-BR/rules/security.mdnew file mode 100644index 000000000..c651865d8--- /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 similaresdiff --git a/docs/pt-BR/rules/testing.md b/docs/pt-BR/rules/testing.mdnew file mode 100644index 000000000..460b7368a--- /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