PulseFlow Tecnologia
← Insights
·5 min de leitura·guia-tecnico·agents-md·harness-engineering·boas-praticas
PulseFlow Tecnologia

Como estruturar um AGENTS.md para um repositório corporativo

AGENTS.md nasceu com uma proposta simples: "a simple, open format for guiding coding agents" - um lugar único e previsível onde um agente de código procura instruções antes de tocar num repositório. A pergunta que qualquer time de engenharia enfrenta na prática não é se vale a pena ter um, mas o que colocar dentro dele para que funcione.

O que 2.500+ repositórios ensinam

Uma análise do GitHub sobre mais de 2.500 repositórios com agents.md chegou a uma conclusão direta: "the successful agents aren't just vague helpers; they are specialists." Descrições genéricas como "helpful coding assistant" não produzem resultado melhor - o que funciona é instrução específica, com limites claros. O estudo identificou seis blocos que aparecem consistentemente nos AGENTS.md mais eficazes:

  1. Comandos executáveis - npm test, npm run build, e equivalentes, prontos para copiar e colar
  2. Estrutura do projeto - onde cada coisa mora, sem obrigar o agente a explorar
  3. Stack técnico com versões - não "React", mas "React 18", "TypeScript 5", etc.
  4. Exemplos de código real - mostrar o padrão esperado, não apenas descrevê-lo
  5. Padrões de estilo - convenções de nomenclatura e formatação
  6. Limites claros - o que o agente pode fazer sozinho, o que exige aprovação, o que nunca deve fazer

Entre as restrições identificadas, a mais comum e mais útil foi simplesmente "never commit secrets" - uma frase curta que evita um dos erros mais caros que um agente pode cometer.

Por que a estrutura importa em escala: o caso Codex

O quanto isso importa fica mais claro num experimento que a própria OpenAI documentou: um repositório que nasceu vazio em agosto de 2025, com o scaffold inicial gerado pelo Codex CLI (GPT-5) - inclusive o próprio AGENTS.md inicial foi escrito por um agente. Cinco meses depois, o repositório tinha cerca de 1 milhão de linhas de código, mais de 1.500 pull requests mesclados, produzidos por só três engenheiros conduzindo agentes - uma média de 3,5 PRs por engenheiro por dia. Nenhuma linha foi escrita manualmente por um humano.

O aprendizado central desse experimento é o que a OpenAI chama de "legibilidade": o repositório precisa ser otimizado para que um agente consiga entender o domínio de negócio inteiro a partir do próprio código e da própria documentação - sem depender de contexto tácito. Quando decisões de arquitetura ficavam só em conversas de Slack, elas eram tão invisíveis para o agente quanto seriam para um funcionário novo no primeiro dia. A resposta foi trazer esse contexto para dentro do repositório, no lugar onde o agente de fato procura.

Uma estrutura de referência

Juntando a pesquisa dos 2.500 repositórios com o formato aberto do agents.md, um AGENTS.md corporativo consistente cobre, na prática:

  1. Objetivo do projeto e domínio de negócio
  2. Arquitetura e padrões adotados
  3. Setup local (passo a passo, sem pressupor conhecimento prévio)
  4. Comandos permitidos (build, test, lint, deploy)
  5. Testes obrigatórios antes de qualquer PR
  6. Estilo de código e convenções de nomenclatura
  7. Regras de segurança (a começar por "never commit secrets")
  8. Restrições explícitas - o que o agente nunca deve fazer sozinho
  9. Fluxo de pull request esperado
  10. Critérios de aceite para considerar uma tarefa concluída

O ponto prático

Um AGENTS.md não é documentação que se escreve uma vez e esquece - é um artefato vivo, tão versionado quanto o código que ele governa. Times que tratam esse arquivo como parte da arquitetura, e não como nota de rodapé, são os mesmos que conseguem escalar de "um agente ajudando uma tarefa" para "agentes conduzindo entrega real", como no caso documentado pela OpenAI.

Fontes