Publique um AGENTS.md: o contrato de repositório de que seus bots de LLM precisam agora

Você já tem README.md, CONTRIBUTING.md e CODEOWNERS. Mas seus agentes de LLM ainda fazem suposições. Essa adivinhação agora é risco de produção. O tópico no HN desta semana pedindo um “AGENTS.md” está certo: você precisa de um contrato simples e aplicável no repositório que diga aos bots o que podem tocar, o que não podem, quanto podem gastar e como escalar quando houver dúvida.

Se acha que isso é exagero, lembre da última vez em que um bot bem-intencionado abriu um PR de “correção rápida” que quebrou a infra ou estourou o orçamento de tokens. O custo não foi o revert — foi a confiança perdida. Times passam a limitar ou banir bots depois de um incidente, e então os reintroduzem, sem estrutura. Esse ciclo desperdiça trimestres.

O que mudou: bots não são mais assistentes — são atores

Dois sinais surgiram recentemente:

• Pedidos de uma padronização de AGENTS.md apareceram no HN, refletindo dor real: agentes não têm um contrato compartilhado e local ao repositório.
• Harnesses de agentes como o OneCLI e agentes nativos emergentes (incluindo “fx” no HN) tornam trivial conectar bots ao CI/CD e aos repositórios. Ótimo para velocidade, péssimo para consistência se cada bot joga com regras diferentes.

Enquanto isso, sua postura de compliance não ficou mais simples. Seus agentes tocam dados regulados, segredos efêmeros, APIs de terceiros e fluxos de produção. Sem um contrato, cada PR vira negociação.

AGENTS.md: o contrato mínimo

Pense no AGENTS.md como um robots.txt do seu repositório — mas com orçamentos, caminhos de escalonamento e níveis de risco. Mantenha conciso. Uma página que um LLM consiga analisar e um humano possa assumir como responsável.

O que incluir (padrão opinativo)

• Escopo e intenção: Quais problemas os agentes podem resolver neste repositório. Exemplo: “Correções de documentação, atualizações de regras de lint, triagem de flakiness em testes, refactors seguros de até 100 linhas.”
• Áreas de alto risco: Paths protegidos ou banidos sem aprovação humana explícita. Exemplo: “infra/ e migrations/ exigem aprovação de CODEOWNERS mesmo para PRs criados por bot.”
• Classificação de dados: Quais dados os agentes podem ler ou gerar; o que é proibido. Exemplo: “Nunca inclua PII de produção em PRs ou fixtures de teste. Use apenas dados sintéticos.”
• Ferramentas e endpoints: Ferramentas externas permitidas, servidores MCP e serviços internos. Exemplo: “Pode chamar o MCP interno de test-runner, não pode chamar gateways de pagamento.”
• Orçamento e rate limits: Tetos de gasto por PR e por dia com paradas rígidas. Exemplo: “Limite de US$ 10/PR em modelos, US$ 100/dia por repositório. Aborte e escale se exceder.”
• Segredos e credenciais: Como tokens de curta duração são provisionados; nunca pedir segredos a humanos em PRs. Exemplo: “Use tokens efêmeros e com escopo a partir do cofre do CI. Sem tokens estáticos.”
• Padrões seguros: Classes de mudanças que podem fazer auto-merge sob testes. Exemplo: “Regenerar lockfiles + CI verde + até 50 LOC = elegível para auto-merge após 2 builds verdes.”
• Alterações inseguras: Mudanças que sempre exigem revisão humana. Exemplo: “Esquema de banco, fluxos de auth, lógica de pagamentos, IaC de infra, adição/upgrade de dependências acima de patch.”
• Observabilidade e logs: O que será registrado, por quanto tempo e onde inspecionar. Exemplo: “Todas as chamadas de ferramentas de agentes logadas em observability/agents com retenção de 30 dias.”
• Caminho de escalonamento: Quem acionar e como quando a confiança for baixa. Exemplo: “Abra um PR em rascunho com o rótulo needs-human e marque @team-leads em até 30 minutos.”
• Dicas de modelo e quantização: Orientações que preservam determinismo. Exemplo: “Use GPT-4.1-mini para rascunhos, passe para Sonnet no final; evite quantização agressiva em tarefas com muitas chamadas de ferramenta.”
• Política de memória: Retenção, autoridade e proveniência da memória do agente. Exemplo: “Pondere memórias por fonte e idade; trate comentários humanos em CODEOWNERS como autoridade maior do que autoanotações do modelo; limpe memórias após 14 dias.”

É isso. Uma página. Se precisar de mais, aponte para políticas detalhadas, mas mantenha o AGENTS.md como a interface de alto sinal — o que um agente consegue ingerir em uma única janela de contexto e executar sem ambiguidade.

Torne-o aplicável: um gêmeo mínimo legível por máquina

AGENTS.md serve para humanos e LLMs. Você também precisa de um arquivo mínimo legível por máquina (agents.yaml ou agents.json) para que CI e harnesses possam impor orçamentos, rate limits, restrições de path e regras de escalonamento. Mantenha o schema minúsculo, ou vai apodrecer.

Um esquema mínimo concreto (em bullets, não em código)

• version: 1
• allowed_paths: ["docs/**", "src/**", "tests/**"]
• guarded_paths: ["infra/**", "migrations/**", "auth/**"]
• deny_paths: ["secrets/**", ".github/workflows/prod-deploy.yml"]
• max_loc_change: 100
• budget_usd_per_pr: 10
• budget_usd_per_day: 100
• allowed_tools: ["test-runner-mcp", "lint-mcp"]
• denied_endpoints: ["/payments/*"]
• memory_ttl_days: 14
• escalate_labels: ["needs-human"]
• escalate_mentions: ["@team-leads"]

Use OneCLI, um harness próprio ou um roteador de marketplace — esse arquivo pode controlar o comportamento. Se um PR exceder max_loc_change ou tocar um caminho protegido, o CI desativa auto-merge e exige CODEOWNERS. Se o modelo queimar o budget_usd_per_pr, a execução aborta e rotula o PR para triagem humana.

Como plugar o AGENTS.md na sua stack

1) Verificação no CI: Sem AGENTS.md, sem PRs de bot

Bloqueie PRs originados por agentes a menos que AGENTS.md e agents.yaml existam e validem. Este é um gate de uma hora para implementar. Se não puder bloquear por origem, detecte PRs criados por tokens de bot ou com metadados típicos de agente e aplique a verificação. Ao falhar, adicione um comentário útil apontando para um template.

2) Faça cumprir os orçamentos no harness

Encapsule seu cliente de LLM em um proxy ciente de orçamento. No GitHub Actions, dá para calcular o gasto multiplicando uso de tokens pelo custo por modelo (logue ambos). Pare rigidamente nos tetos. Exponha o gasto em um comentário no PR para que revisores vejam um extrato simples: US$ 2,35 draft, US$ 1,90 refine, US$ 0,65 tests, total US$ 4,90. Se você é nearshore e compartilha ciclos entre pods, essa transparência evita a síndrome da “conta de nuvem misteriosa”.

3) Políticas com consciência de paths

Integre regras de path ao seu bot de política de PR. Se um PR tocar guarded_paths, precisa de aprovação de CODEOWNERS e não pode fazer auto-merge. Se tocar deny_paths, o bot deve fechar o PR com explicação e escalar. Isso transforma “orientação” em comportamento, não promessas.

4) Allowlists de chamadas de ferramentas

A maioria dos incidentes danosos vem de chamadas de ferramenta inesperadas. Se você usa servidores MCP, conecte uma allowlist a partir do agents.yaml e audite as chamadas reais. Uma chamada negada deve gerar um comentário no PR com a chamada, o propósito e um link para o AGENTS.md. Trate diffs de chamadas de ferramenta como você trata diffs de dependências.

5) Memória ponderada e TTL

Uma das críticas mais inteligentes na comunidade: “Tudo o que um agente lembra tem a mesma autoridade, e esse é o bug.” Construa uma camada de memória ponderada: documentos de projeto escritos por humanos e CODEOWNERS têm alta autoridade; autoanotações transitórias de LLM têm baixa. Faça a memória decair com a idade. Faça cumprir o memory_ttl_days. Armazene a proveniência (quem/o quê escreveu, quando) em cada entrada. Um dia de engenharia evita meses de drift sutil.

6) Observabilidade: traces de chamadas de ferramentas e de gastos

Guarde cada chamada de ferramenta com inputs, outputs, duração e custo. Coloque em uma pasta simples no repositório (para traces não sensíveis) ou no seu backend de observabilidade. Mantenha 30 dias por padrão; estenda para 90 em repositórios regulados. Se seus agentes rodam no Brazil e nos US, rotule traces com região para auditorias de residência de dados.

Plano de rollout: 30-60-90 dias

Primeiros 30 dias: coloque o contrato no ar

• Esboce um AGENTS.md de uma página. Mantenha abaixo de 25 linhas de política mais links.
• Defina o schema mínimo do agents.yaml (os bullets acima). Publique um JSON Schema se precisar de validação.
• Adicione uma verificação no CI que bloqueia PRs de bot em repositórios sem os dois arquivos. Forneça um botão “Criar a partir do template” na mensagem de falha.
• Instrumente seu cliente de LLM com tetos de orçamento e tracing. Tarefa de 1–2 dias.

Dias 31–60: aplique e ajuste

• Leve para seus top 10 repositórios por volume de PR. Espere 5–10 pequenas exceções de política que exigem tratamento explícito (ex.: migrations em uma feature branch).
• Ative auto-merge ciente de path para mudanças seguras até 50 LOC e CI verde. Meça a redução de cycle time. Times costumam ver 20–30% de merges mais rápidos para mudanças de baixo risco.
• Publique um caminho de suporte. Sobreposição de 6–8 horas com pods baseados no Brazil é suficiente para resolver disputas de política rapidamente.

Dias 61–90: escale e meça

• Expanda para 50+ repositórios. Faça triagem de “policy drift” semanalmente. O drift mais comum é guarded_paths sem cobrir uma nova subárvore de infra/.
• Defina metas trimestrais: menos de 1 revert a cada 100 PRs de bot; gasto mediano abaixo de US$ 5 por PR de bot; menos de 24 horas de mediana de time-to-merge para classes seguras.
• Agende um fire drill trimestral: viole intencionalmente um deny_path e confirme que o CI bloqueia e escala.

Objeções comuns — e respostas

“Isso vai nos atrasar.”

Acelera as mudanças certas. Classes seguras fazem auto-merge mais rápido porque revisores não ficam caçando surpresas. Classes inseguras também aceleram porque as regras são visíveis. Você elimina a negociação PR a PR.

“Vai ficar obsoleto.”

Vai, se for longo. Mantenha o AGENTS.md curto e coloque detalhes propensos a rot no agents.yaml com validação no CI. Torne CODEOWNERS o owner de ambos os arquivos. Se ninguém é dono, não é política.

“Nossos agentes diferem demais para padronizar.”

Por isso o schema é mínimo. Escopo, paths, orçamentos, ferramentas, escalonamento. O resto pode viver em docs mais profundas por bot. A ideia é um contrato que o repositório impõe, não uma enciclopédia.

“Já escrevemos uma página no Notion.”

Docs fora do repositório são invisíveis para agentes e não aplicáveis via CI. Coloque o contrato ao lado do código. Referencie a política longa no Notion se precisar; o gate fica local.

Ângulo nearshore brasileiro: quem faz a parte pouco glamourosa?

O trabalho duro aqui não é o parágrafo que você escreve no AGENTS.md. É a tubulação de enforcement — tetos de orçamento, auto-merge ciente de path, allowlists de chamadas de ferramenta, TTLs de memória, traces. Se seu time de plataforma está no limite, um pod nearshore pode entregar isso em semanas:

• Levantar o gate no CI e a validação do schema: 1–2 dias.
• Wrappers para rastrear gasto de LLM e tetos rígidos: 2–4 dias por linguagem/runtime.
• Allowlist de MCP/ferramentas + audit logging: 3–5 dias.
• Políticas de PR cientes de path atreladas a CODEOWNERS: 2 dias.
• Rollout em toda a organização (50+ repositórios), treinamento e dashboards: 2–3 semanas.

Você ganha 6–8 horas de sobreposição de fuso com times nos US, e um handoff limpo para seu time de plataforma após o primeiro trimestre, com runbooks — não uma caixa‑preta.

Números reais para mirar

• Gasto com tokens: Comece limitando a US$ 10/PR e US$ 100/dia/repositório. Times maduros ficam entre US$ 3–US$ 7 por PR de bot com escopo claro.
• Velocidade de PRs: Com auto-merge para classes seguras, espere 20–30% de redução de cycle time para docs, lint e pequenos refactors.
• Taxa de incidentes: Reverts abaixo de 1% para PRs de bot após o primeiro mês de ajuste fino.
• Cobertura: Cobrir os 50 principais repositórios em 60 dias é factível com um time de plataforma ou pod nearshore de 2–3 pessoas.

Não se prenda a um vendor — mantenha portátil

Vendors vão mudar termos, limitar recursos ou bloquear capacidades. Já vimos isso com acesso a modelos e mudanças de programa. AGENTS.md e agents.yaml não devem referenciar recursos proprietários como dependências rígidas. Trate o harness como plugável: OneCLI hoje, seu runner interno amanhã. O contrato vive no repositório; o executor pode mudar.

Um template mínimo para copiar hoje

Mantenha isto em menos de uma página no AGENTS.md. Aponte para detalhes em vez de inchar.

• Escopo: Edições de docs, regras de lint, testes, pequenos refactors de até 100 LOC.
• Alto risco: infra/, migrations/, auth/ exigem aprovação de CODEOWNERS. Não toque em workflows de deploy de prod.
• Dados: Sem PII em PRs ou fixtures. Use apenas dados sintéticos.
• Ferramentas: MCPs permitidos: test-runner, lint. Negados: quaisquer endpoints de pagamento ou segredos.
• Orçamentos: US$ 10/PR, US$ 100/dia por repositório. Aborte e rotule needs-human se exceder.
• Segredos: Use apenas tokens efêmeros do CI. Nunca faça commit de credenciais.
• Merges seguros: Até 50 LOC, CI aprovado duas vezes, sem paths protegidos: elegível para auto-merge.
• Inseguro: Esquema de DB, auth, pagamentos, infra — sempre revisão humana.
• Memória: Pondere docs escritos por humanos como mais altos, decaia autoanotações; limpe após 14 dias.
• Escalonamento: Rotule needs-human e marque @team-leads em caso de dúvida ou bloqueio.

Isso não é cerimônia — é um SLO de comportamento

Em algum momento deste ano você rodará mais bots do que engenheiros de staff. Sem um contrato, cada um desses bots negocia comportamento em tempo de execução. Com um contrato, você transforma intenção em código: orçamentos aplicados, paths protegidos, memória limitada e humanos envolvidos quando a máquina estiver incerta.

Adicione AGENTS.md e seu pequeno arquivo gêmeo. Trate-os como parte da sua barra de build. Se um repositório não está apto para um bot ler e seguir, não está apto para um humano manter sem conhecimento tribal.

Pontos-chave

• AGENTS.md é um contrato de uma página, local ao repositório, que diz aos bots de LLM o que fazer, o que não tocar, quanto gastar e como escalar.
• Emparelhe com um agents.yaml mínimo para que CI e harnesses imponham orçamentos, regras de path e allowlists de ferramentas.
• Comece com cinco essenciais: escopo, paths protegidos/negados, tetos de orçamento, allowlists de ferramentas e um caminho de escalonamento.
• Instrumente gastos e chamadas de ferramentas; mire gasto mediano de US$ 3–US$ 7 por PR de bot e taxa de revert abaixo de 1% após ajuste.
• Mantenha portátil entre vendors e harnesses; o contrato vive no repositório, não em um painel de SaaS.
• Faça rollout em 90 dias: bloqueie novos PRs de bot, cubra os principais repositórios e meça velocidade e incidentes.
• Se seu time de plataforma estiver sobrecarregado, um pod nearshore pode cuidar da tubulação em semanas, com 6–8 horas de sobreposição e TCO mais baixo.