📁 Adote estrutura previsível
Um repositório previsível reduz o contexto que o agente precisa carregar e o número de suposições que ele faz. O mesmo vale para a pessoa que entrou no time ontem — as duas audiências querem a mesma coisa.
Como ler: o AGENTS.md no centro aponta para as quatro pastas — ele não copia o conteúdo delas. As setas vão de fora para dentro porque cada pasta é dona da sua verdade; o mapa só diz onde procurar. Um AGENTS.md que tenta conter tudo vira mais uma fonte desatualizada.
Previsível
Achável sem tour guiado
Convenção
Acima de configuração
Nome
É infraestrutura
Duas audiências
Humano novo e agente
🚧 Deixe os limites entre módulos explícitos
Um agente respeita a fronteira que consegue enxergar. Fronteira que existe só na cabeça do arquiteto será atravessada — e, pior, será atravessada de forma consistente e bem escrita, o que torna difícil perceber.
Exemplo de estrutura
/docs arquitetura.md dominios.md decisoes/ playbooks/ /specs pagamentos/ usuarios/ /skills criar-migracao/ revisar-api/ corrigir-bug/ /scripts validate.sh test-changed.sh AGENTS.md README.md
Cada pasta tem um dono e um propósito. Um agente que entra nesse repositório sabe onde procurar spec, onde procurar decisão e o que rodar para validar.
💡 Dica prática
Escreva as fronteiras como regra executável de importação (o que /pagamentos pode importar, o que não pode). Assim ela vira gate no CI, não recomendação em documento — exatamente o princípio do módulo 3.3.
Visível
Senão é atravessada
Verificável
Regra de import
Contrato
Entre domínios
Escopo
Fronteira limita a tarefa
📚 Mantenha documentação próxima ao código
Documentação versionada no repositório entra na revisão junto com o código e no contexto do agente sem esforço. Documentação em ferramenta externa vira folclore em três meses.
✓ Doc que se mantém viva
- ✓Mora no repositório e muda no mesmo PR que o código
- ✓Registra decisões e o porquê, não a sintaxe do framework
- ✓Curta o suficiente para ser lida inteira
- ✓Referencia o código em vez de repetir o que ele faz
✗ Doc que atrapalha
- ✗Descreve o sistema que se pretendia ter, não o que existe
- ✗Duplica informação que já está no código
- ✗Está em três lugares, com três versões diferentes
- ✗Ninguém sabe qual é a atual — nem o agente
No repo
Entra na revisão
Decisão
Registre o porquê
Desatualizada
Pior que ausente
Curta
Lida é a que serve
⌨️ Padronize comandos e testes locais rápidos
Um comando por intenção, igual na máquina de todo mundo e no CI. É o que permite ao agente fechar o loop sozinho — sem comando padrão, ele inventa um, e inventa errado.
🧪 Exercício copiável — auditar a legibilidade do seu repositório
Objetivo: descobrir o que um agente não consegue deduzir do seu repo hoje. Rode numa sessão limpa, sem dar nenhuma explicação prévia.
Você acabou de entrar neste repositório e não tem nenhum contexto além dele. Não pergunte nada agora; responda com o que conseguir deduzir dos arquivos. 1. o que este sistema faz? (3 linhas) 2. como eu instalo, testo, linto e builduei? (comandos exatos) 3. onde ficam: regras de negócio, decisões de arquitetura, specs? 4. quais são as fronteiras entre módulos e o que NÃO pode importar o quê? 5. o que eu NÃO devo alterar sem aprovação? 6. liste tudo que você teve que SUPOR para responder acima. Seja honesto no item 6 — é o item mais importante da resposta.
Como verificar: a lista do item 6 é o seu backlog de legibilidade. Cada suposição é uma coisa que o próximo agente (e a próxima pessoa contratada) vai errar. Corrija o repositório — não o prompt.
Um comando
Por intenção
Local = CI
Mesmo resultado
Rápido
Habilita o loop
Suposição
É seu backlog
📄 Escreva o AGENTS.md como mapa
O AGENTS.md pode conter visão geral do sistema, comandos principais, regras do projeto, localização da documentação, limitações, critérios de qualidade, ações proibidas e referências para skills e playbooks. Ele não deve concentrar todo o conhecimento — deve funcionar como um mapa.
🧭 Teste do bom AGENTS.md
- •Cabe em uma tela e meia? Se não, você está duplicando outra fonte.
- •Traz os comandos exatos, copiáveis, sem "provavelmente é npm test"?
- •As proibições estão explícitas e em destaque?
- •Aponta para onde está a verdade de cada assunto, em vez de repeti-la?
- •Foi revisado no último trimestre?
⚠️ Atenção
Um AGENTS.md de 900 linhas não é lido por inteiro — nem por humanos, nem com proveito por um agente que precisa achar rápido o que importa. Instrução que ninguém lê é instrução que não existe, com o agravante de dar falsa sensação de controle.
Mapa
Aponta, não descreve
Comandos
Exatos e copiáveis
Proibições
Em destaque
Revisado
Como código
🎯 Garanta fontes únicas de verdade
Diante de duas fontes conflitantes, o agente escolhe uma — silenciosamente. Você descobre qual na revisão, e normalmente no pior momento possível.
Um dono por assunto
Comandos moram no AGENTS.md; contrato mora na spec; decisão mora em /docs/decisoes. Quem precisar do assunto referencia o dono.
Referenciar em vez de copiar
Toda cópia diverge — é questão de tempo. Um link para o arquivo certo envelhece muito melhor que um trecho colado.
Deletar o obsoleto é trabalho de verdade
Documento antigo não some sozinho e continua entrando no contexto do agente. Remover a versão velha vale mais que escrever a nova.
Checagem rápida: qual é o melhor AGENTS.md?
Um dono
Por assunto
Referenciar
Nunca copiar
Deletar
O obsoleto atrapalha
Conflito
Ele escolhe sozinho
📌 Resumo do Módulo
Próximo Módulo:
4.3 - Overengineering e dívida técnica gerada por IA.