O que clean-code-guard faz?
Você está revisando código gerado ou alterado antes de ele ser enviado. Aplique as regras abaixo como uma passagem de guarda após a primeira passagem de implementação — e, uma vez que esta habilidade esteja ativa, continue aplicando-a a cada alteração de código posterior na mesma sessão, executando novamente a autoverificação antes da entrega após cada edição, em vez de reverter para saída desprotegida porque a habilidade foi carregada anteriormente. Se o usuário invocar explicitamente esta habilidade antes de escrever código, use as mesmas regras durante a escrita e ainda execute a autoverificação antes da entrega.
Integração com a Equipe do Agente
As regras do repositório, contratos aceitos, permissões de função e escopo do usuário têm precedência sobre este guia e suas referências. DEV usa a passagem de guarda em suas próprias alterações; CR usa modo de revisão somente leitura e não edita a implementação. Trate limites numéricos, proibições de nomenclatura, formas de argumento e regras de abstração como sinais para investigar, não como edições ou bloqueadores automáticos. Uma descoberta deve explicar um custo concreto de correção ou manutenção no contexto; não divida código coeso, quebre interfaces ou adicione comentários de exceção apenas para satisfazer uma contagem. Revise o código alterado e seus chamadores diretamente afetados, não dívida não relacionada.
Todas as orientações e listas de verificação usadas por este pacote são locais. Os nomes de publicações externas são apenas para atribuição; use evidências do repositório e as referências agrupadas, em vez de navegar. Se esta tarefa estiver fora do escopo da habilidade, siga o processo normal do repositório; nenhuma habilidade irmã é necessária.
Compatibilidade
Esta é uma habilidade de instrução portátil. Não requer servidor MCP, acesso à rede, chave de API, comando shell, executável local ou script agrupado. Pode ser usada em qualquer runtime que suporte SKILL.md mais arquivos references/ diretamente vinculados; agents/openai.yaml são metadados de exibição leves.
Esta habilidade não substitui linters, formatadores, verificadores de tipo ou executores de teste do projeto. Use as próprias ferramentas do projeto para verificação mecânica; use esta habilidade para a camada de julgamento em torno da qualidade e revisão do código.
Como usar esta habilidade
Esta habilidade tem três modos — escolha com base na solicitação do usuário.
Modo de passagem de guarda (recomendado): após o código ter sido gerado, editado, refatorado ou corrigido, verifique o diff ou os arquivos de destino em relação aos imperativos sempre aplicados abaixo. Corrija violações antes de apresentar, confirmar ou mesclar o trabalho.
Modo ao vivo (explícito): quando o usuário invocar esta habilidade antes de uma edição de código arriscada, aplique os mesmos imperativos durante a escrita, em seguida, execute a lista de verificação Autoverificação antes da entrega. Se você violar qualquer regra, corrija-a antes de mostrar ao usuário.
Modo de revisão (acionado quando o usuário pede para você revisar, auditar, criticar ou avaliar código): percorra references/review-checklist.md em relação ao(s) arquivo(s) de destino e produza um relatório estruturado de descobertas. Não edite código no modo de revisão, a menos que seja solicitado.
Em todos os três modos, os corpos das regras residem em references/. Leia o arquivo de referência relevante quando:
- Você encontrar uma regra da qual não se lembra totalmente do raciocínio.
- O usuário contestar uma regra e você precisar da citação da fonte.
- Você estiver no modo de revisão e precisar da lista de verificação completa.
- O código em revisão tocar em um princípio específico (por exemplo, subclasse → references/solid.md; desduplicação → references/dry-kiss-yagni.md).
Os arquivos de referência são:
- references/naming-and-functions.md — nomes, tamanho de função, parâmetros, separação comando/consulta.
- references/comments-and-formatting.md — quando comentar, quando deletar, combinar estilo vizinho.
- references/solid.md — SRP, OCP, LSP, ISP, DIP com as formulações modernas e cheiros de detecção.
- references/dry-kiss-yagni.md — duplicação de conhecimento vs código, regra de re-inline de Sandi Metz, complexidade de McCabe, categorias de custo YAGNI de Fowler.
- references/ai-failure-modes.md — as 14 maneiras sistemáticas pelas quais LLMs produzem código ruim. Leia este primeiro se você é um agente de IA lendo esta habilidade. É o arquivo de maior alavancagem na habilidade.
- references/review-checklist.md — percurso estruturado para o modo de revisão.
- references/sources.md — bibliografia central para URLs de fontes. Leia-o apenas quando precisar verificar ou citar uma fonte externa.
Exemplos
- Um agente de codificação implementa um endpoint: use o modo de passagem de guarda no diff antes que o trabalho seja apresentado ou confirmado.
- O usuário pergunta "revise este PR" ou "devo mesclar isso?": use o modo de revisão e relate descobertas de references/review-checklist.md; não edite a menos que seja solicitado.
- O usuário pergunta "implemente este endpoint usando clean-code-guard": use o modo ao vivo durante a escrita, depois execute a autoverificação antes da entrega.
- O usuário pergunta "refatore esta função, mesmo comportamento": preserve o comportamento observável exatamente e trate qualquer correção de bug como uma alteração separada.
Critérios de sucesso
Esta habilidade está funcionando quando tarefas de escrita de código evitam os modos de falha listados, tarefas de revisão de código produzem descobertas priorizadas com evidência concreta, e refatorações preservam o comportamento a menos que o usuário peça explicitamente uma mudança de comportamento. Deve permanecer silenciosa para tarefas conceituais, de CI, fluxo de trabalho git, prosa, análise de dados e execução de testes cobertas pelas exclusões do frontmatter.
Por que esta habilidade existe
Código gerado por LLM tem modos de falha sistemáticos e mensuráveis que instruções genéricas de "siga Clean Code" não capturam. Exemplos apoiados por pesquisa publicada:
- A duplicação de código cresceu 8x em bases de código rastreadas entre 2021 e 2024 (relatório GitClear 2025).
- Taxa de alucinação de pacotes média de 19,6% em 16 modelos (Spracklen et al., USENIX Security '25).
- LLMs frequentemente envolvem operações arriscadas em manipuladores de captura ampla que engolem erros (Karpathy).
- Agentes de IA "declaram sucesso apesar de falhar em testes" retornando valores fixos de fixture (Fowler, Patterns for Reducing Friction).
- O tamanho da função cresceu de 142 para 267 LoC, a complexidade ciclomática de 4,2 para 8,1 em commits assistidos por IA (GitClear).
Os princípios clássicos (Clean Code, SOLID, DRY/KISS/YAGNI) ainda são a base — mas esta habilidade adiciona a camada específica de IA que a maioria dos pacotes de regras perde.
Imperativos sempre aplicados
Estas são as regras a seguir em cada alteração de código. Eles são imperativos, não sugestões.
Funções e nomes
- Nomes revelam intenção. Nunca use
data,data2,result,result_final,item,temp,value,obj,info,helper,manager,utils, ouhandle_*/process_*/do_*sem um qualificador. Um nome deve responder por que existe e o que faz. (Clean Code Ch. 2) - Funções permanecem pequenas. Alvo ≤20 linhas, um nível de abstração, uma coisa. Se você pode extrair uma função com um nome que não reafirma o corpo, o pai estava fazendo mais de uma coisa. (Clean Code Ch. 3)
- Quatro argumentos é o teto absoluto. Com cinco, pare e introduza um objeto de solicitação/configuração (registro, struct, DTO ou equivalente). Nunca use argumentos de sinalizador booleano — divida em duas funções.
- Sem argumentos de saída. Uma função ou retorna um valor (consulta) ou tem um efeito colateral (comando). Nunca ambos. Nomes de comando usam verbos; nomes de consulta usam substantivos ou nomes estilo getter. (CQS)
Comentários e estrutura
- Comentários explicam por que, nunca o que. Delete qualquer comentário que parafraseie a linha abaixo dele. Delete comentários de scaffolding de número de etapa. Delete código comentado — o controle de versão existe. (Clean Code Ch. 4)
- Combine com o estilo existente do arquivo. Leia o arquivo que você está editando e pelo menos um vizinho antes de escrever. Espelhe a capitalização, ordem de importação, tratamento de erros, registro em log e escolhas de cliente HTTP/BD. Não introduza um segundo padrão.
SOLID
- Um ator por módulo. Uma classe deve ser responsável perante um grupo de stakeholders (Contabilidade, Autenticação, Relatórios). Se dois subsistemas não relacionados acessam a mesma classe, divida-a. (SRP, Uncle Bob 2014)
- Extensão via novo código, não edições. Se adicionar uma nova variante requer outro ramo de tipo-tag em uma função existente, refatore para um registro, estratégia ou despacho polimórfico primeiro. (OCP)
- Nenhuma subclasse recusa o contrato de seu pai. Nunca sobrescreva um método para sinalizar "não implementado" ou "operação não suportada". Nunca fortaleça pré-condições ou enfraqueça pós-condições em uma sobrescrita. Se você precisa fazer isso, a herança está errada. (LSP)
- Abstrações vivem com o cliente, não com a implementação. Quando você introduz uma interface, protocolo ou contrato abstrato, coloque-o no pacote que o consome, não ao lado da classe concreta. (DIP)
DRY, KISS, YAGNI
- Delete conhecimento duplicado, não texto duplicado. Duas funções que parecem semelhantes mas codificam regras diferentes não são uma violação DRY. Uma regra expressa em código + docs + esquema é. (Pragmatic Programmer, "DRY")
- A abstração errada é pior que duplicação. Se uma abstração acumulou ramos para o caso especial de cada chamador, re-inline-a de volta nos chamadores, depois delete os ramos mortos antes de re-abstrair. (Sandi Metz, "The Wrong Abstraction")
- Teto de complexidade: ciclomática ≤10, profundidade de aninhamento ≤5. Refatore antes de exceder. (McCabe 1976)
- Nada especulativo. Nenhum parâmetro opcional, sinalizador de configuração, variável de ambiente, alternância de recurso, interface, fábrica ou classe base sem um chamador presente. Se você se pegar adicionando
enable_*,use_*_v2, ou*_mode, delete-o e envie o comportamento concreto. (Fowler, "Yagni")
Diretrizes específicas de IA — a seção de maior alavancagem
- Nunca engula erros com tratamento de captura ampla. Capture apenas o tipo de erro específico do qual você pode se recuperar. Se você não pode se recuperar, deixe o erro propagar. Retornar null/none/empty sucesso de um manipulador de captura é proibido, a menos que o contrato da função documente esse comportamento. (Karpathy)
- Proteja a fronteira; confie no contrato. Em uma fronteira de confiança — entrada externa, payloads de solicitação/API, dados desserializados ou entre processos, qualquer coisa de uma fonte não confiável — valide, mesmo quando o caminho feliz parece bom. Dentro da fronteira, não adicione verificações nulas ou verificações de tipo em tempo de execução para valores cujo tipo declarado ou contrato do chamador já exclui esse caso. O teste para uma guarda não é "isso poderia teoricamente estar errado" mas "dados não confiáveis podem chegar aqui". (arXiv 2409.19182)
- Verifique cada importação e chamada externa. Antes de chamar um método em uma biblioteca, confirme que ele existe na versão instalada (leia o pacote, verifique o lockfile ou importe e inspecione). Não gere código com base no que a API "deveria" parecer. (USENIX Security '25)
- Sem retornos "sucesso" fixos ou fixtures simuladas em código de produção. Nunca retorne
{"status": "ok", ...}ou dados enlatados de uma função cuja especificação diz que faz trabalho real. Se você não pode implementar, falhe explicitamente com o mecanismo de operação não implementada ou não suportada da linguagem e diga isso. Nunca desabilite, pule ou enfraqueça um teste para fazê-lo passar. (Fowler, Claude Code issue #6984) - Re-derive, não copie de semelhante. Quando tentado a copiar uma função e modificá-la, pare. Re-derive da especificação. Erros off-by-one e de semântica nula errada quase sempre entram através de cópia de semelhante. (arXiv 2411.01414)
- Enumere casos de fronteira antes de escrevê-los. Para qualquer intervalo, off-by-one, null/empty/one/many, even/odd, ou unicode/byte boundary, escreva a lista de casos em um comentário primeiro. Cubra cada caso no código antes de prosseguir.
- Elimine código morto antes da entrega. Execute um linter ou grep para importações não utilizadas, símbolos não utilizados, ramos inalcançáveis e exportações "apenas no caso". Remova-os. Uma função que nada chama hoje não ganha o direito de viver para "um dia".
- Leia antes de escrever. Antes de escrever em um repositório desconhecido, leia o arquivo que você editará, um vizinho e qualquer arquivo de regras do projeto (CLAUDE.md, AGENTS.md, seção "convenções" do README). Use os helpers, tipos de erro e registro em log existentes do projeto.
- Nenhuma nova dependência para o que algumas linhas cobrem. Antes de adicionar um pacote, verifique a biblioteca padrão, as dependências já instaladas e se algumas linhas de código local fazem o trabalho. Uma nova dependência é manutenção permanente e superfície de cadeia de suprimentos; adicione uma apenas quando ela possui complexidade real que você não deve reimplementar (criptografia, análise, fusos horários — ilustrativo, não exaustivo), nunca para economizar dez linhas. Veja references/dry-kiss-yagni.md.
O piso — nunca corte estes por simplicidade
A Regra 16 confia no contrato dentro da fronteira; os itens abaixo permanecem mesmo enquanto você elimina especulação (14), guardas defensivas (16) e código morto (21). Remover um destes é uma mudança de comportamento, não uma limpeza — mantenha-o, ou sinalize-o e pergunte.
- Validação e sanitização em cada fronteira de confiança — entrada externa, payloads de solicitação/API, dados desserializados ou entre processos.
- Tratamento de erros que previne perda de dados.
- Medidas de segurança — autorização, escape de saída, consultas parametrizadas, tratamento de segredos.
- Comportamento que o usuário solicitou explicitamente. Mencionado de passagem ≠ solicitado, mas não descarte o que foi pedido.
Disciplina de refatoração
- Preserve o comportamento observável ao refatorar. Quando o usuário pedir para você limpar, simplificar ou refatorar código existente, não mude o contrato — mesmas entradas produzem as mesmas saídas, mesmas exceções levantadas, mesmos efeitos colaterais, mesmas garantias de ordenação. Se você avistar um bug durante a refatoração, sinalize-o separadamente e pergunte antes de alterá-lo. Refatoração é definida como "uma mudança feita na estrutura interna do software para torná-lo mais fácil de entender e mais barato de modificar sem alterar seu comportamento observável" (Fowler, Refatoração). Correções de bugs e refatorações são duas operações — nunca as agrupe em uma única mudança.
Autoverificação antes da entrega
Antes de mostrar o resultado do seu trabalho ao usuário — seja um trecho de código, um diff, um commit ou uma solicitação de merge — execute esta lista de verificação final:
- Revisei todos os imperativos sempre aplicados (1-24)? Se eu violei algum conscientemente, tenho uma razão explícita e documentei-a.
- Eliminei todo código morto? Importações, símbolos, ramos, exportações não utilizados — todos foram removidos.
- Verifiquei importações e chamadas externas? Não estou assumindo uma API que não existe na versão instalada.
- Preservei o comportamento observável (se refatoração)? Testes existentes ainda passam; nenhuma funcionalidade foi alterada acidentalmente.
- Apliquei as diretrizes específicas de IA (#15-23)? Nenhum erro engolido, nenhum retorno fixo, nenhuma fixture simulada, nenhuma dependência desnecessária.
- Verifiquei as fronteiras de confiança? Entrada externa é validada e sanitizada.
- O código segue o estilo do projeto? Nomes, estrutura, tratamento de erros, escolhas de biblioteca — consistentes com o restante do repositório.
- Listei e cobri casos de fronteira (#20)? Off-by-one, vazio/um/muitos, null/empty — cada caso é tratado.
Se alguma verificação falhar, corrija o código antes de apresentar o resultado ao usuário. Esta habilidade está funcionando quando a autoverificação é executada e passa antes de cada entrega.