AGENTS.md: Criar / Revisar (com IA)
Dois modos: criar um novo AGENTS.md ou revisar um existente com base em padrões de qualidade apoiados por pesquisas.
Detecção de Modo
- O usuário fornece um AGENTS.md existente ou aponta para um → Modo Revisão
- O usuário pede para criar/esqueletizar/gerar → Modo Criação
- Ambíguo → pergunte:
(c)riar um novo AGENTS.md ou (r)evisar um existente?
Modo Criação
Passo 1: Perguntar o local
Onde o AGENTS.md deve ser colocado?
(r)aiz — base para todo o repositório
(c)aminho — diretório específico (forneça o caminho)
Para monorepositórios: sugerir raiz + arquivos por pacote. O AGENTS.md mais próximo vence.
Se AGENTS.md já existir no caminho alvo → pergunte: Arquivo existe. (r)evisar existente / (s)obrescrever / (Q)uitar?
Passo 2: Pensamento especializado
Antes de escrever, determine para ESTE projeto:
- O que é não descoberto? O que não pode ser inferido a partir de package.json, configurações ou estrutura de diretórios?
- O que é perigoso? Quais comandos ou padrões causam falhas silenciosas?
- O que é ambíguo? Onde existem duas abordagens válidas e o agente adivinharia errado?
- O que não é padrão? Quais convenções diferem dos padrões do framework?
Se todas as respostas forem "nada" — o projeto pode não precisar de um AGENTS.md. Diga isso.
Para repositórios sem package.json ou configurações de build (apenas docs, repositórios de dados, scripts simples): concentre-se apenas nos limites de Missão + Julgamento — as seções de ferramentas e encerramento não se aplicarão.
Passo 3: Escrever em ordem de prioridade
Adicione seções APENAS se elas passarem no teste de não descoberta, nesta ordem:
- Missão (2–4 frases) — propósito do projeto + restrição central que o agente não pode inferir
- Registro de ferramentas — comandos como tabela, NÃO o que as ferramentas impõem
- Limites de julgamento — níveis NUNCA / PERGUNTE / SEMPRE
- Definição de encerramento — "Pronto" = códigos de saída específicos
- Regras de escalonamento — o que fazer quando bloqueado
- Seções organizadas por tarefa — "Ao escrever… / Ao revisar… / Ao lançar…"
Passo 4: Validar
- Total ≤ 150 linhas (ideal: 60–100)
- Cada seção ≤ 50 linhas
- Cada instrução responde: "Qual comando prova que isso foi feito?"
- Cada "não" é pareado com um "sim"
- Nenhuma regra de linter reafirmada (ferramentas primeiro)
- Nenhum parágrafo em prosa sem comandos
OBRIGATÓRIO — LEIA references/knowledge-base.md para padrões e evidências baseados em pesquisa.
OBRIGATÓRIO — LEIA references/template.md para estrutura inicial.
Carregue references/example.md apenas quando o usuário perguntar como é um AGENTS.md finalizado, ou quando o repositório for um monorepo JS/TS (é um exemplo de turborepo + pnpm trabalhado) — pule caso contrário.
NÃO carregue references/knowledge-base.md durante o Modo Revisão se o AGENTS.md alvo tiver < 20 linhas — a lista de verificação do corpo e a lista de antipadrões são suficientes para arquivos trivialmente curtos.
Modo Revisão
Avalie o AGENTS.md fornecido em relação a critérios de qualidade apoiados por pesquisas.
Dimensões de Pontuação
| Dimensão | Peso | O que verificar |
|---|---|---|
| Densidade de sinal | 25% | %% de linhas que são conhecimento especializado não descoberto vs. genérico/redundante |
| Comando-primeiro | 20% | Cada instrução tem um comando verificável ou código de saída |
| Definição de encerramento | 15% | Critérios explícitos de "pronto" com verificações específicas |
| Sistema de limites | 15% | Níveis NUNCA/PERGUNTE/SEMPRE presentes e específicos |
| Disciplina de comprimento | 10% | ≤150 total, ≤50 por seção, sem inchaço |
| Ausência de antipadrões | 15% | Livre de padrões comprovadamente falhos |
Orientações de Pontuação
- Pontue com rigor na densidade de sinal para repositórios maduros com ferramentas estabelecidas — provavelmente a maior parte do conteúdo é redundante
- Pontue com leniência em encerramento/limites para projetos greenfield — eles podem ainda não ter gates de CI
- Pontue com rigor em comprimento para arquivos raiz de monorepo — estes são carregados em todas as sessões em todos os pacotes
- Se pontuação total < 40: recomende reescrita em vez de correções incrementais
Lista de Verificação de Antipadrões
Sinalize qualquer um destes (comprovadamente prejudiciais ao desempenho do agente):
- Parágrafos em prosa sem comandos
- Diretivas ambíguas ("tenha cuidado", "quando possível")
- Prioridades contraditórias sem ordenação explícita
- Regras de estilo já impostas pela configuração do linter
- Visões gerais de arquitetura (causam exploração excessiva)
- 15+ avisos sem alternativas pareadas
- Modelo gerado por LLM a partir de comandos
/init - Reafirmar o que a ferramenta impõe
- Violações de elefante rosa (longas listas de "não fazer" mantendo conceitos proibidos ativos)
Formato de Saída
## Revisão AGENTS.md: <nome do arquivo ou caminho>
**Pontuação**: X/100
**Veredito**: [Pronto para produção / Precisa de trabalho / Reescrita recomendada]
### Pontos Fortes
- ...
### Problemas (por gravidade)
1. [CRÍTICO] ...
2. [ALTO] ...
3. [BAIXO] ...
### Sugestões de Reescrita
1. ...
2. ...
Aplicar
A revisão não é o resultado final — um AGENTS.md melhor é. Após apresentá-la, ofereça:
Aplicar? (t)udo / (s)elecionar por número / (n)enhum
Em (t) ou (s): edite o arquivo no local, um item numerado de cada vez, então reexecute as dimensões de pontuação e relate a nova pontuação junto com a antiga. Cada linha que a revisão não sinalizou sobrevive literalmente — uma revisão não é um mandato de reescrita, e "melhorar" silenciosamente prosa não sinalizada é como uma revisão destrói a voz e a intenção do autor.
Pule a oferta quando o usuário forneceu o conteúdo inline em vez de um caminho, ou o arquivo não é gravável. Diga isso em vez de relatar melhorias como aplicadas.
OBRIGATÓRIO — LEIA references/knowledge-base.md para a evidência de pesquisa por trás de cada critério.
NUNCA
- NUNCA inclua conteúdo que o agente possa descobrir a partir da estrutura do repositório — scripts package.json, layout de diretórios e arquivos de configuração são autodocumentados; reafirmá-los desperdiça tokens e cria desvio de manutenção. EM VEZ DISSO: faça referência ao arquivo (
veja biome.json) e prossiga. - NUNCA reafirme regras de linter/formatador — a ferramenta É a restrição; duplicação cria desatualização e requisitos desnecessários prejudicam ativamente o desempenho do agente. EM VEZ DISSO: liste apenas o comando de execução (
Lint: \pnpm lint``). - NUNCA escreva um "não" sem um "sim" pareado — documentação só com avisos causa exploração excessiva; 15+ não sem alternativas torna os agentes conservadores e menos produtivos. EM VEZ DISSO: pareie cada proibição com a alternativa correta.
- NUNCA exceda 150 linhas — além deste limite, os ganhos revertem e o arquivo prejudica ativamente a qualidade. EM VEZ DISSO: extraia detalhes para arquivos referenciados ou apague.
- NUNCA use conteúdo gerado por LLM como final — a saída
/inité um inventário do que o agente já sabe; reduz desempenho e infla custo. EM VEZ DISSO: trate como rascunho de inventário, depois remova tudo que a ferramenta já impõe. - NUNCA escreva parágrafos em prosa — agentes os ignoram; use comandos, tabelas e marcadores com resultados verificáveis. EM VEZ DISSO: converta para comando + código de saída + descrição de uma linha.