Prompts do guia de estilo do Claude Code para revisões de código consistentes

Por que violações do guia de estilo se espalham tão rápido

As violações do guia de estilo raramente aparecem como um grande erro isolado. Elas começam como pequenas escolhas “próximas o suficiente” que parecem inofensivas em um pull request e depois se acumulam até que a base de código pareça desigual e mais difícil de ler.

A deriva de estilo geralmente se parece com isto: um arquivo usa userID, outro usa userId, um terceiro usa uid. Um handler retorna { error: "..." }, outro lança, outro registra e retorna null. Cada mudança é pequena, mas juntas criam um repositório onde os padrões deixam de ser previsíveis.

Iteração rápida e múltiplos colaboradores pioram isso. As pessoas copiam o que veem, especialmente sob pressão de tempo. Se o código mais recente no repositório usou um atalho, esse atalho vira o modelo para a próxima mudança. Depois de algumas semanas, o “estilo padrão” não é o guia escrito. É o que foi feito por último.

Por isso o objetivo tem de ser convenções consistentes, não preferências pessoais. A pergunta não é “Eu gosto desse nome?” e sim “Isso corresponde às regras que combinamos para que a próxima pessoa possa seguir sem pensar?”.

Capturar violações cedo significa interromper padrões ruins antes que se tornem fonte de copy-paste. Foque em código novo e modificado, corrija a primeira aparição de uma nova inconsistência e bloqueie merges que introduzam nova deriva. Quando sinalizar um problema, adicione um exemplo curto e preferido que as pessoas possam imitar na próxima vez.

Um exemplo realista: um desenvolvedor adiciona um novo endpoint de API e registra o corpo da requisição “só para depuração”. Se isso entrar, o próximo endpoint copia, e logo dados sensíveis aparecem nos logs. Capturar isso no primeiro PR é barato. Capturar depois que se espalhou é doloroso e arriscado.

Transforme seu guia de estilo em regras claras e verificáveis

Um guia de estilo só funciona em revisões se for lido como uma checklist, não como um conjunto de preferências. Reescreva cada diretriz como uma regra que possa ser verificada em um diff.

Organize as regras em quatro blocos para que fiquem difíceis de ignorar: naming, layering, tratamento de erros e logging. Para cada bloco, escreva duas coisas: o que deve ser verdade e o que é proibido.

Decida a força de cada regra antecipadamente:

• Mandatory: falhar nela bloqueia a mudança.
• Recommended: corrija salvo motivo claro para não o fazer.
• Optional: bom ter, nunca bloqueante.

Defina o escopo para que as revisões não virem refatorações sem fim. Uma regra simples funciona bem: “código novo e modificado deve estar em conformidade; código existente intocado não é reescrito a menos que bloqueie a correção.” Se quiser limpeza, limite o tempo como uma tarefa separada.

Também defina o resultado que você espera de uma revisão para que seja fácil agir: um veredito passar/falhar, uma lista de violações com arquivo e linha, correções sugeridas escritas como edições concretas e uma breve nota de risco quando algo possa causar bugs ou vazamentos.

Exemplo: se um PR registra tokens de usuário em texto puro, a revisão deve falhar sob “logging: nunca registre segredos” e sugerir registrar um request ID em vez disso.

Estrutura de prompt que aplica regras em vez de opiniões

Prompts de estilo falham quando soam como preferências. Uma boa instrução de revisão lê como um contrato: não negociáveis claros, exceções claramente nomeadas e uma saída previsível.

Comece com dois blocos curtos: o que deve ser verdade e o que pode ser flexibilizado. Depois adicione uma regra de decisão: “Se não estiver claro, marque como Needs Clarification. Não adivinhe.”

Exija evidência. Quando a ferramenta sinalizar uma violação, obrigue-a a citar o identificador exato e o caminho do arquivo, não uma descrição vaga. Essa única restrição remove muito vai-e-vem.

Mantenha o escopo estreito: comente apenas nas linhas alteradas e nas rotas de código diretamente impactadas. Se permitir refatores não relacionados, a aplicação do estilo vira “reescreva o arquivo” e as pessoas param de confiar no feedback.

Aqui está uma estrutura que você pode reusar:

Role: strict style guide reviewer.
Input: diff (or files changed) + style guide rules.
Non-negotiables: [list].
Allowed exceptions: [list].
Scope: ONLY comment on changed lines and directly impacted code paths. No unrelated refactors.
Evidence: Every finding MUST include (a) file path, (b) exact identifier(s), (c) short quote.
Output: structured compliance report with pass/fail per category + minimal fixes.

Requisite: o relatório deve manter as mesmas seções sempre, mesmo que algumas sejam “No issues found”: Naming, Layering, Error handling, Logging.

Se disser “service layer leaking DB details”, deve citar algo como internal/orders/service/order_service.go e a chamada exata (por exemplo db.QueryContext) para que você possa corrigir o vazamento sem discutir o que significava.

Passo a passo: construir um fluxo de trabalho de prompt para checagem de estilo

Um guia de estilo pega quando o processo é repetível. O objetivo é fazer o modelo checar regras, não discutir gosto, e fazer isso do mesmo jeito toda vez.

Use um fluxo de trabalho simples em duas passagens:

1. Cole seus padrões como uma lista compacta e numerada de regras (10–25 linhas). Mantenha cada regra testável.
2. Adicione contexto para a mudança: o diff, os arquivos tocados e uma frase sobre a intenção.
3. Peça primeiro um relatório de violações. Exija arquivo e referência de linha, um motivo curto e o número exato da regra.
4. Só depois do relatório, peça o menor patch possível para alcançar conformidade.
5. Reexecute o mesmo prompt no código atualizado para confirmar que não resta nada.

Exemplo: um PR adiciona um novo endpoint. A Passagem 1 sinaliza que o handler fala diretamente com PostgreSQL (layering), usa nomes mistos em structs de request (naming) e registra e-mails completos (logging). A Passagem 2 faz correções mínimas: move a chamada ao DB para um service ou repository, renomeia o struct e mascara o e-mail nos logs. Nada mais muda.

Convenções de naming: prompts que pegam as pequenas coisas

Problemas de naming parecem menores, mas geram custo real: as pessoas interpretam mal intenção, a busca fica mais difícil e nomes “quase iguais” se multiplicam.

Declare as regras de naming que o revisor deve aplicar em toda a mudança: nomes de arquivo, tipos exportados, funções, variáveis, constantes e testes. Seja explícito sobre casing (camelCase, PascalCase, snake_case) e escolha uma regra para siglas (por exemplo APIClient vs ApiClient). Depois exija cumprimento em todos os lugares.

Padronize também o vocabulário compartilhado: tipos de erro, campos de log e chaves de config. Se os logs usam request_id, não permita reqId em um arquivo e requestId em outro.

Uma instrução prática para o revisor:

Check every new or renamed identifier. Enforce casing + acronym rules.
Flag vague names (data, info, handler), near-duplicates (userId vs userID), and names that contradict behavior.
Prefer domain language: business terms over generic tech words.

Peça um relatório curto: os três nomes mais confusos, quaisquer near-duplicates e qual deles manter, além de quaisquer nomes em log/config/erro que não batem com o padrão.

Regras de layering: manter responsabilidades separadas

Regras de layering funcionam melhor em linguagem simples: handlers tratam HTTP, services contêm regras de negócio, repositories falam com o banco.

Trave a direção de dependência. Handlers podem chamar services. Services podem chamar repositories. Repositories não devem chamar services nem handlers. Handlers não devem importar código de banco de dados, helpers SQL ou modelos do ORM. Se usar pacotes compartilhados (config, time, IDs), mantenha-os livres de lógica de aplicação.

Atribua responsabilidades cross-cutting a um lugar: validação geralmente pertence à borda para forma da requisição e ao service para regras de negócio. Autorização costuma começar no handler (identidade, scopes), mas o service deve impor a decisão final. Mapping pertence às bordas: handler mapeia HTTP para input de domínio, repository mapeia linhas do DB para tipos de domínio.

Coloque isto num prompt para manter revisões concretas:

Check layering: handler -> service -> repository only.
Report any leaks:
- DB types/queries in handlers or services
- HTTP request/response types inside services or repositories
- repository returning DB models instead of domain objects
- auth/validation mixed into repository
For each leak, propose the smallest fix: move function, add interface, or rename package.

Faça o relatório explícito: nomeie o arquivo, a camada onde deveria estar, a importação ou chamada que quebra a regra e a mudança mínima que previne o padrão de se espalhar.

Convenções de tratamento de erros: consistência sob pressão

A maioria das discussões sobre estilo fica tensa quando algo quebra em produção. Uma política clara de tratamento de erros mantém as correções calmas porque todo mundo sabe o que é “bom”.

Escreva a filosofia e a faça valer. Por exemplo: “Envuelva erros para adicionar contexto; crie um erro novo só quando mudar o significado ou mapear para uma mensagem de usuário. Retorne erros crus apenas na fronteira do sistema.” Essa frase evita padrões aleatórios.

Separe o texto voltado ao usuário do detalhe interno. Mensagens para usuário devem ser curtas e seguras. Erros internos podem incluir o nome da operação e identificadores-chave, mas não segredos.

Em revisões, cheque algumas falhas recorrentes: erros engolidos (registrados mas não retornados), retornos ambíguos (valor nil com erro nil após uma falha) e mensagens voltadas ao usuário que vazam stack traces, texto de query, tokens ou PII. Se suportar retries ou timeouts, exija que sejam explícitos.

Exemplo: uma chamada de checkout expira. O usuário vê “Payment service is taking too long.” Internamente, envolva o timeout e inclua op=checkout.charge e o ID do pedido para que seja pesquisável e acionável.

Convenções de logging: legível, pesquisável e seguro

Logs só ajudam quando todos os escrevem da mesma forma. Se cada dev escolhe wording, nível e campos, a busca vira um jogo de adivinhação.

Torne níveis de log não negociáveis: debug para detalhe de desenvolvimento, info para marcos normais, warn para situações inesperadas mas tratadas e error quando a ação voltada ao usuário falha ou precisa de atenção. Mantenha “fatal” ou “panic” raros e ligados a uma política clara de crash.

Logs estruturados importam mais do que frases perfeitas. Exija nomes de chave estáveis para que dashboards e alertas não quebrem. Decida um conjunto pequeno de campos centrais (por exemplo event, component, action, status, duration_ms) e mantenha-os consistentes.

Trate dados sensíveis como bloqueio total. Seja explícito sobre o que nunca deve ser logado: senhas, tokens de autenticação, cartões completos, segredos e dados pessoais brutos. Aponte coisas que parecem inofensivas mas não são, como links de reset de senha, IDs de sessão e corpos de requisição completos.

IDs de correlação tornam debugging possível entre camadas. Exija um request_id em cada linha de log dentro de uma requisição. Se você logar user_id, defina quando é permitido e como representar usuários anônimos ou ausentes.

Um bloco de prompt reutilizável:

Review the changes for logging conventions:
- Check level usage (debug/info/warn/error). Flag any level that does not match impact.
- Verify structured fields: require stable keys and avoid free-form context in the message.
- Confirm correlation identifiers: request_id on all request-bound logs; user_id only when allowed.
- Flag any sensitive data risk (tokens, secrets, personal data, request/response bodies).
- Identify noisy logs (in loops, per-item logs, repeated success messages) and missing context.
Return: (1) violations with file/line, (2) suggested rewrite examples, (3) what to add or remove.

Antes de mesclar, faça uma “safety pass” rápida: qualquer novo log sem request_id para trabalho atrelado a requisição, qualquer nova chave que mude nomes existentes (userId vs user_id), qualquer log de erro sem informar o que falhou (operação, recurso, status), logs de alto volume que vão disparar em cada requisição e qualquer chance de segredos ou dados pessoais aparecerem em campos ou mensagens.

Como pegar violações antes que se espalhem

Trate a deriva de estilo como um break de build, não uma sugestão. Adicione um gate estrito que rode antes do merge e retorne um claro passar ou falhar. Se uma regra mandatória for quebrada (naming, limites de camada, segurança de logging, tratamento de erros), ele falha e aponta arquivos e linhas exatos.

Mantenha o gate curto. Um truque prático é exigir um checklist SIM/NÃO por regra e recusar aprovação se algum item for NÃO.

Uma checklist de tamanho PR que pega a maioria dos problemas:

• Naming: corresponde ao padrão aprovado para arquivos, tipos e funções
• Layering: sem chamadas diretas que pulam camadas (por exemplo handlers chamando o DB)
• Errors: retornados consistentemente com contexto, nada é silenciosamente ignorado
• Logging: campos consistentes, sem segredos e nível corresponde ao impacto
• Tests/docs: atualizados quando comportamento ou APIs públicas mudam

Quando a ferramenta sugerir correções, exija um pequeno trecho compatível para cada regra que tocou. Isso evita feedbacks vagos como “renomeie por clareza.”

Armadilhas comuns ao usar prompts para aplicar estilo

A forma mais rápida de um guia de estilo falhar é deixar espaço para interpretação. Se dois revisores conseguem ler a mesma regra e chegar a conclusões diferentes, a ferramenta vai aplicar gosto, não padrão.

Naming é um exemplo comum. “Use nomes claros” não é testável. Aperte para algo verificável: “funções são verbos (ex.: createInvoice), booleanos começam com is/has/can, tipos exportados são PascalCase.”

Outra armadilha é pedir tudo de uma vez. Quando um prompt tenta cobrir naming, layering, erros, logging, testes e performance, o feedback fica raso. Divida em passagens focadas quando precisar de profundidade, ou mantenha o gate limitado a regras mandatórias.

Os problemas que mais levam à deriva de aplicação:

• Vague rules: substitua “limpo” e “consistente” por linguagem mensurável.
• Misturar correções de estilo com redesign: não deixe um prompt de estilo propor nova arquitetura.
• Falta de evidência citada: obrigue cada comentário a citar o identificador ou trecho exato.
• Exceções silenciosas: se permitir uma exceção, exija uma nota curta explicando por quê e quando deve ser removida.

Se tratar prompts como testes, você tem aplicação previsível. Se tratar como conselho, violações entram sorrateiramente e se multiplicam.

Checklist rápido que você pode rodar em cada mudança

Faça uma passagem rápida pelo diff (não pelo repositório inteiro) e confirme:

• Naming: novos identificadores seguem seu padrão (case, prefixes, suffixes). Um conceito é nomeado de uma forma só em todos os arquivos.
• Layering: dependências só seguem a direção permitida. Camadas inferiores nunca importam superiores.
• Errors: falhas são retornadas com contexto. Nada é ignorado silenciosamente.
• Logging: nível correto, campos estáveis e sem segredos ou dados pessoais.
• Passagem final: o revisor afirma exatamente: “no mandatory violations found”, ou lista as violações que devem ser corrigidas antes do merge.

Mantenha um template de prompt minúsculo e cole-o em cada mudança:

Review ONLY the changed code against our rules for naming, layering, errors, and logging.
List mandatory violations first (with file + line if available). Then list optional suggestions.
End with either: “no mandatory violations found” or “mandatory violations found”.

Exemplo: uma nova função procUsr() em um handler que escreve diretamente no PostgreSQL deve falhar em naming e layering mesmo que a feature funcione. Pegá-la aqui evita que o erro se espalhe por copy-paste.

Exemplo: uma revisão realista que corrige problemas cedo

Um colega adiciona um novo endpoint: POST /v1/invoices/{id}/send. Toca um handler, um service e o storage.

Na primeira passagem, você quer um relatório, não uma reescrita:

Pass 1 (report only)
You are a strict style checker. Read the patch.
Rules: naming must match our guide, handlers call services only, services call storage only, no SQL in handlers,
errors must be wrapped with context, logs must be structured and not leak PII.
Output: a numbered list of violations with file:line, rule name, and one-sentence impact. Do not propose fixes.
If a rule might be intentionally broken, ask one clarification question.

Achados típicos: SendInvoiceNow() vs SendInvoice mismatch de naming, o handler chamando db.QueryRow diretamente, retornando err cru sem contexto, e logs ruidosos como log.Printf("sending invoice %v", invoice) que despejam objetos inteiros.

A segunda passagem pede mudanças mínimas e seguras:

Pass 2 (minimal fix suggestions)
Using the violations list, propose the smallest code edits to comply.
Constraints: keep behavior the same, no refactors beyond what is needed, show suggested function names and where code should move.
For each fix, include 1-2 lines of example code.

Se quebrar uma regra for permitido, diga isso desde o início: “Exceptions are permitted only if you add a short comment explaining why, and you add a follow-up task to remove the exception.”

Depois da correção, o handler vira um adaptador fino, o service domina o fluxo, o storage domina a query, erros viram fmt.Errorf("send invoice: %w", err) e logs ficam em uma linha limpa com campos seguros (ID da invoice, não a invoice completa).

Próximos passos: tornar rotineiro sem desacelerar

Escolha um prompt aprovado pela equipe e trate-o como uma ferramenta compartilhada. Comece pelo que mais atrapalha nas suas revisões (deriva de naming, vazamento de camadas, erros inconsistentes, logs inseguros). Atualize o prompt somente quando ver uma violação real no código real.

Mantenha um pequeno bloco de regras no topo do prompt e cole-o em cada revisão sem alterações. Se todo mundo editar as regras cada vez, você não tem um padrão. Tem um debate.

Uma cadência simples ajuda: uma pessoa coleta os principais erros de estilo da semana e você adiciona exatamente uma regra mais clara ou um exemplo melhor.

Se você trabalha em um fluxo ligado a chat como Koder.ai (koder.ai), vale rodar os mesmos checks de gate durante mudanças, não só no fim. Recursos como planejamento, snapshots e rollback ajudam a manter correções de estilo pequenas e reversíveis antes de exportar o código-fonte.