Skip to content

armgit / ECC

Public Imported from GitHub
0

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.md
new file mode 100644
index 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ância
diff --git a/docs/pt-BR/rules/coding-style.md b/docs/pt-BR/rules/coding-style.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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 interpretados
diff --git a/docs/pt-BR/rules/patterns.md b/docs/pt-BR/rules/patterns.md
new file mode 100644
index 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.md
new file mode 100644
index 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ção
diff --git a/docs/pt-BR/rules/security.md b/docs/pt-BR/rules/security.md
new file mode 100644
index 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 similares
diff --git a/docs/pt-BR/rules/testing.md b/docs/pt-BR/rules/testing.md
new file mode 100644
index 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