do-fastted/AgentDock

Verificação de Qualidade do Código

Verificação abrangente de qualidade para código recém-escrito. Combina conformidade com especificações, segurança entre camadas e verificações de pré-confirmação.

---

Passo 1: Identificar o que Mudou

git diff --name-only HEAD
git status

Passo 2: Ler Artefatos da Tarefa e Especificações Aplicáveis

Leia os artefatos da tarefa atual em ordem:

• prd.md
• design.md se presente
• implement.md se presente

python3 ./.trellis/scripts/get_context.py --mode packages

Para cada pacote/camada alterado, leia o índice da especificação e siga sua seção Verificação de Qualidade:

cat .trellis/spec/<pacote>/<camada>/index.md

Leia os arquivos de diretrizes específicos referenciados — o índice é um ponteiro, não o objetivo.

Passo 3: Executar Verificações do Projeto

Execute os comandos de lint, verificação de tipos e teste do projeto. Corrija quaisquer falhas antes de prosseguir.

Passo 4: Revisar Contra a Checklist

Qualidade do Código

• O linter passa?
• O verificador de tipos passa (se aplicável)?
• Os testes passam?
• Não há logs de depuração deixados?
• Não há avisos suprimidos ou desvios de segurança de tipo?

Cobertura de Testes

• Nova função → teste unitário adicionado?
• Correção de bug → teste de regressão adicionado?
• Comportamento alterado → testes existentes atualizados?

Sincronização de Especificações

• .trellis/spec/ precisa de atualizações? (novos padrões, convenções, lições aprendidas)

"Se corrigi um bug ou descobri algo não óbvio, devo documentá-lo para que eu no futuro não enfrente o mesmo problema?" → Se SIM, atualize o documento de especificação relevante.

Disciplina de Escopo

• Alguma organização de código que a tarefa não exigia?
• Alguma abstração, configuração ou ponto de extensão adicionado para um caso que ainda não existe?
• Algum fallback especulativo para um estado que não pode ocorrer?
• Algum arquivo alterado que os critérios de aceitação não mencionam?
• Alguma solução alternativa adicionada no chamador em vez de uma correção onde o comportamento realmente está?

Passo 5: Dimensões entre Camadas (se aplicável)

Pule este passo se sua alteração estiver confinada a uma única camada.

A. Fluxo de Dados (alterações tocam 3+ camadas)

• Os rastros de fluxo de leitura estão corretos: Armazenamento → Serviço → API → UI
• Os rastros de fluxo de escrita estão corretos: UI → API → Serviço → Armazenamento
• Os tipos/esquemas são passados corretamente entre as camadas?
• Os erros são propagados corretamente para o chamador?

B. Reutilização de Código (modificando constantes, criando utilitários)

• Procurou por código semelhante existente antes de criar novo?

  grep -r "padrão" src/
  

• Se o mesmo valor se repete, ele representa um conceito estável cujos chamadores devem mudar juntos? Extraia apenas nesse caso — dois literais que coincidentemente são iguais hoje devem permanecer separados.
• Após modificação em lote, todas as ocorrências foram atualizadas?

C. Importação/Dependência (criando novos arquivos)

• Caminhos de importação corretos (relativo vs absoluto)?
• Sem dependências circulares?

D. Consistência dentro da Mesma Camada

• Outros lugares que usam o mesmo conceito são consistentes?

---

Passo 6: Relatar e Corrigir

Relate cada violação que encontrar. Em seguida:

• Mecânico e local (nit de lint, tipo ausente, importação errada, ramo morto, asserção falhando) → corrija no local e execute novamente as verificações do projeto.
• Projeto ou julgamento (nomear um conceito compartilhado, mover um limite de módulo, alterar uma interface pública, reatribuir onde o comportamento está) → registre a evidência e sua recomendação, e pare. Não reescreva silenciosamente.

Se uma correção tocaria arquivos fora do escopo da tarefa atual, diga isso e pare em vez de ampliar a alteração.