Construindo diretrizes de codificação compartilhadas para IA (e também para pessoas)

À medida que as organizações de engenharia crescem, fazer com que todos trabalhem no mesmo software começa a ficar complicado. Cada um tem suas peculiaridades e estilos, o que pode levar a uma Torre de Babel implementada como uma arquitetura orientada a serviços. Então, o pessoal da liderança criou sistemas de tickets, scrum e pipelines de implantação para trazer alguma consistência ao processo. Para o código em si, eles escreveram padrões e diretrizes de codificação.

Em 2026, os engenheiros de software estão escrevendo cada vez menos códigos à mão. Em vez disso, eles usam agentes de codificação para escrever código com base em seus designs. Mas se esses agentes contribuem para uma base de código empresarial, então eles precisam seguir os padrões e as diretrizes. Felizmente, a maioria dos geradores de código implementou maneiras de adicionar padrões e diretrizes aos seus agentes.

O problema é que não é a mesma coisa que integrar um novo desenvolvedor júnior. Você não pode simplesmente jogar alguns documentos neles e deixá-los explorar. Os agentes são rápidos, mas não possuem o contexto do seu código. E muito do contexto para codificadores humanos vem como aprendizados tácitos à medida que eles veem formas, estilos e padrões específicos. Chamamos os sinais de alerta no código de “cheiros”, o que demonstra a natureza baseada na vibração de grande parte da compreensão do código. Apesar do discurso popular, os agentes de codificação não funcionam com vibrações, pelo menos não em situações profissionais.

À medida que os agentes de codificação criam cada vez mais código, a carga cognitiva da engenharia de software está mudando para o design e a arquitetura, bem como para a revisão do código. A revisão do código será a primeira olhada no código pela maioria dos engenheiros, uma vez que eles próprios não o escreveram. Eles apenas sabem o que queriam que o código fizesse. As diretrizes de codificação para agentes podem injetar um pouco de determinismo em um processo não determinístico.

As diretrizes e padrões de codificação (que chamarei apenas de “diretrizes”) para agentes precisam ser um pouco diferentes – mais explícitos, demonstrativos de padrões e óbvios. Mas não muito diferente, já que uma boa documentação é para todas as entidades de codificação.

Veja como criar melhor padrões de codificação para agentes e humanos.

O código que os agentes produzem precisa funcionar com um monte de código que já está em produção (a menos que você viva uma vida abençoada construindo um projeto puramente greenfield). Ele precisa usar as mesmas linguagens e bibliotecas, conectar-se a qualquer sistema de construção e implantação e adequar-se aos sistemas e paradigmas de engenharia de plataforma que você usa. Se o seu front-end usa Express, seu agente não deve codificar com React.

Além da pilha de tecnologia, sua equipe de engenharia possui um conjunto de metodologias e práticas recomendadas usadas para escrever código para uma base de código compartilhada. Algumas delas podem ser práticas recomendadas universais, algumas podem ser a cultura da equipe e algumas podem ser maneiras pelas quais sua equipe se desvia ou ignora as melhores práticas. Embora isso possa ser considerado de conhecimento comum de seus colegas de equipe humanos, não tome nada como garantido com os agentes. “Quais são as instruções que você precisa dar, como DRY?” disse Vish Abrams, arquiteto-chefe da Heroku. “Existem princípios clássicos de programação que são de conhecimento comum para engenheiros experientes. A mesma coisa se aplica à implantação. Você deseja construir seu aplicativo onde a configuração e o código são separados. Você pode dizer ao LLM para construir seu aplicativo dessa maneira, ou você pode apenas dizer, crie um jogo de cobra para mim e ele fará o que quiser. Talvez não seja de todo sustentável.”

Este pode ser o momento de revisar completamente suas diretrizes de codificação. Muitas das melhores práticas foram criadas quando o código era artesanal e escrito à mão. Se você estiver interagindo com o código apenas durante a revisão, talvez algumas diretrizes mudem. Talvez ter várias cópias da funcionalidade seja melhor para revisão de código, para que você veja a funcionalidade com o PR. Talvez não. Mas muitas das melhores práticas servem para tornar o código legível e sustentável para humanos.

A codificação, assim como a escrita, envolve muitas pequenas decisões que podem variar entre as organizações. Para quem está de fora, podem parecer pequenos e arbitrários, mas podem ter impactos posteriores e retardar as avaliações de colegas habituados a determinadas convenções. Usamos a vírgula serial aqui no blog Stack Overflow, mas outros não usam e estão errados.

Como um guia de estilo, suas diretrizes de codificação agente devem indicar as decisões que sua equipe tomou sobre quais construções de linguagem usar e por que. Aqui estão algumas decisões a serem consideradas, incluindo:

• Nomenclatura de variáveis ​​e métodos: Nomear coisas é um dos problemas difíceis da engenharia de software. Você quer que seus agentes fiquem soltos e criem `FactoryBuilderBuilderFactory` ou misturem camelCase e underscore_style? Se você tiver diferenças de estilos em uma base de código, digamos entre o código C++ e SQL, indique-as separadamente. Indique como identificar e resolver nomes duplicados.
• Guias x espaços: Se sua equipe tiver uma opinião sobre o debate sobre abas vs. espaçosavise o agente. Alguns IDEs e linguagens podem tornar este debate discutível; certifique-se de que seu agente conheça a pontuação de qualquer maneira.
• Disposição: algumas linguagens de programação como Python exigem recuo e formatação específicos, enquanto outras (particularmente os tipos de chaves) permitem um posicionamento mais livre. Você pode ter sentimentos específicos sobre o layout dessas coisas, e pesquisa sugere esse layout pode afetar a velocidade de compreensão.
• Exceções e registro: seu código precisa falhar bem e os agentes precisam saber como você espera falhas e coletar dados sobre software em produção. Seria ótimo se tudo isso acontecesse automaticamente, mas na maioria das vezes, é necessário código dentro do software para fazer o trabalho direito. É melhor pedir ao agente que escreva isso para você também.
• Comentários: Os agentes podem escrever comentários, mas deveriam fazê-lo antes ou depois de um método? Eles seguem regras de recuo? Você está usando um gerador de documentação de API? Quantos detalhes você deseja? Isso é algo que os programadores humanos provavelmente poderiam adivinhar, mas os agentes precisam de orientação.

Esta não é uma lista abrangente de diretrizes para agentes de codificação, e você provavelmente encontrará peculiaridades mais irritantes que seu agente usa ao longo do caminho. Veja abaixo como lidar com isso.

Eu sei que este é um guia para diretrizes de codificação de agentes, mas, em última análise, uma boa documentação é a mesma, seja para pessoas ou agentes. Na verdade, muitas das qualidades abaixo são mais importantes para os agentes porque são muito mais imprevisíveis.

As diretrizes devem ser claras e consistentes. Deve ser absolutamente óbvio como seguir as diretrizes que você escrever. Teste suas diretrizes abordando-as da maneira mais má-fé possível; se você encontrar uma maneira de interpretá-lo mal, reescreva-o. Escreva em um estilo simples e repetido em todo o documento – você não precisa ser perfeito, apenas previsível. IA adora padrões.

Não confunda a IA. Quando escrevi a documentação, presumi que o leitor poderia ter uma ampla gama de habilidades em inglês. Eles podem ser falantes não nativos. Isso significa não usar linguagem idiomática ou outras construções que exijam interpretação. Seja simples, explícito e chato. O mesmo vale para exemplos de código. Cubra todos os casos extremos para que não haja decisões a serem tomadas pela IA.

Torne suas decisões óbvias. Os engenheiros constroem convenções tacitamente. “Como engenheiros, consideramos que quando você está escrevendo código e passa uma noite inteira escrevendo um monte de novas funções, você também está absorvendo implicitamente o contexto da base de código”, disse Greg FosterCTO de Grafite. Qualquer diretriz precisa pegar esse conhecimento tácito e torná-lo explícito. Forneça razões objetivas para cada diretriz. Algumas diretrizes podem ser herdadas de convenções padrão (“Usamos guias porque somos principalmente uma loja Python e isso torna a indentação mais consistente”).

Resisti a exemplos na documentação no início. Mas uma vez que tive que usar a documentação para resolver um problema, cara, entendi. Capturas de tela, código de amostra, playgrounds de API, tudo isso me mostrou como usar as ferramentas melhor do que apenas uma lista numerada de etapas. Há uma razão pela qual oferecemos, de brincadeira, um Teclado CTRL+C+V (e então não tão brincando): esse código de amostra fornece um modelo que você pode usar para personalizar seu próprio código. E as IAs adoram um bom modelo.

Forneça exemplos explícitos de implementações corretas e incorretas das diretrizes do código. As IAs podem usá-los como padrões para determinar a aparência do código correto na maioria das situações. Vários exemplos para cada um não farão mal, mas, novamente, certifique-se de que seus exemplos sejam consistentes.

Considere também dar aos agentes um exemplo geral de como o código fica quando segue todas as diretrizes – um arquivo “padrão ouro”. Exemplos individuais são como testes unitários: seu padrão ouro é o teste ponta a ponta. Há alguma discussão sobre se você precisa apenas do arquivo padrão ouro ou se ele pode funcionar em conjunto com exemplos individuais. Sugerimos testes para ver qual obtém os melhores resultados.

Se você já trabalhou o suficiente com agentes, provavelmente já sabe que não conseguirá isso de uma só vez. Sua primeira versão das diretrizes de codificação não fornecerá um código agente perfeitamente formado. Tudo bem; essas falhas são comentários que você pode usar para melhorar suas diretrizes.

Neste blog, Charity Majors falou sobre usando processos CI/CD para acelerar o ciclo de feedback do SDLC; agentes não são diferentes. Embora você não precise implementar um Laço Ralph Wiggumvocê pode e deve considerar erros no código como uma oportunidade para atualizar seus arquivos de padrões. Esses erros podem até ser úteis para revelar as partes tácitas de suas convenções de codificação, aqueles requisitos secretos dos quais você talvez não estivesse explicitamente ciente.

Usar o fracasso como um ciclo de feedback é como você terá melhores processos de agência em geral. “Há uma grande diferença entre as pessoas que apenas digitam uma mensagem,” disse Quinn SlackCEO e cofundador da Sourcegraph. “Eles realmente não querem que a IA vença. Depois, há pessoas que dedicam muito tempo definindo suas regras, seus `agentes.md`, e eles escrevem o que ele deve fazer. Se cometer um erro, eles atualizarão isso e tentarão fazer com que seja um volante.”

O outro ciclo de feedback ao qual prestar atenção é o humano. Mantenha o arquivo de padrões aberto como um diálogo com sua equipe de engenharia. Coloque-o no Stack Internal ou em outro repositório de documentação e faça com que todos editem, comentem e atualizem. Este é o código que todos construirão e revisarão; eles deveriam ter uma palavra a dizer nas diretrizes.

A última etapa, é claro, é garantir que essas diretrizes correspondam ao seu código e ao contexto do seu agente. Coloque explicitamente todas essas regras em seu `agentes.md` e coloque-os em um repositório padrão ou crie uma habilidade de Claude para eles. Documente o pacote padrão para uma configuração de codificação, como você faz para o pipeline de implantação.

Dito isto, esta não deveria ser sua decisão de desistir de todos os outros aplicadores de padrões de código determinístico. Lintersformatadores e análise estática as ferramentas ainda têm um lugar em seu pipeline de construção. Eles captam o básico que seus agentes falham.

Grandes empresas que tentaram lidar com os estilos de codificação de centenas ou milhares de engenheiros têm uma vantagem sobre as pessoas que estão pensando nisso agora. “As grandes empresas têm guias de estilo bem articulados, práticas recomendadas e processos para construir código e implantar software”, disse Logan Kilpatrickgerente de produto sênior da DeepMind/Google. “Tudo isso é um contexto perfeito para fornecer ao modelo e torná-lo útil para você. Sem muito desse contexto, você está apenas dando um tiro no escuro.”