LLM Wiki — Synaptic Lattice

agents-md-como-instrucao-operacional

Properties1
tagsvibe-coding, orchestration, founder, pm

Leitura de 4 min

AGENTS.md como Instrução Operacional

Definition

AGENTS.md como instrução operacional é o princípio de que o arquivo de instruções para agentes de IA deve ser tratado como comando executável — flags exatas, diretórios mapeados, proibições absolutas — e não como narrativa ou wishlist. A fonte formaliza um limite quantitativo: o arquivo deve ficar entre 60 e 150 linhas; abaixo de 60, falta informação crítica; acima de 150, a qualidade das respostas do agente começa a cair porque a atenção do modelo se distribui igualmente entre instruções boas e ruins — um AGENTS.md inchado piora o desempenho em todas as instruções, não só nas supérfluas.

Key Points

  • Zona ideal: 60-150 linhas. A fonte cita uma queda de mais de 20% na taxa de sucesso do modelo quando o contexto de instrução está inflado — número apresentado sem estudo linkado, tratado aqui como afirmação da fonte, não fato verificado (confidence: medium).
  • Seis seções são suficientes: comandos essenciais (dev/test/lint/build com flags exatas), mapa de arquitetura curto (3-5 linhas), invariantes de produto, definição de “pronto”, restrições, regras de PR.
  • Três categorias de instrução aceitas: segurança/privacidade, formato obrigatório de output, gatilhos de bloqueio (“se não encontrar X, pare e pergunte”). Qualquer instrução fora dessas três categorias é candidata a remoção.
  • Use pointers, não código colado. Referenciar arquivo:linha (ex.: src/utils/validation.ts:42) em vez de colar a função no AGENTS.md — código colado desatualiza quando o código real muda; o pointer continua válido.
  • Não duplique o que o linter já garante. Regras de formatação (aspas, indentação) já enforçadas por linter/formatter são ruído no AGENTS.md; o espaço do arquivo deve ser reservado para o que só a instrução pode transmitir (regras de negócio, restrições de arquitetura).
  • Instrução vaga é pior que silêncio. “Seja cuidadoso com segurança” não muda comportamento; “nunca logue senhas” muda. O teste: se uma linha pode ser removida sem afetar o comportamento do agente, ela não deveria estar lá.
  • Context rot: sessões longas degeneram — o contexto acumula tentativas, correções e idas-e-vindas até a qualidade cair. A prática recomendada é /clear ou /reset após cada tarefa concluída, uma sessão por tarefa.

Posição Oficial da Anthropic (2026-06-18)

O guia oficial “Steering Claude Code” confirma a disciplina desta página e dá destinos para cada linha: manter o CLAUDE.md raiz abaixo de 200 linhas, com dono e revisão como código — e avisa que arquivo compartilhado sem dono cresce por anexação (cada time adiciona, nada é deletado, custo compõe por engenheiro por sessão). Detalhes que estendem esta página: arquivos CLAUDE.md de subdiretório carregam sob demanda e somem até o diretório ser tocado de novo (mesma semântica das rules path-scoped com paths: no frontmatter); em monorepos, cada time ganha seu CLAUDE.md de diretório mais claudeMdExcludes para pular times irrelevantes; padrões org-wide (segurança, compliance) vão em CLAUDE.md central distribuído via MDM, não-burlável por config local. Nota de compatibilidade: a zona 60–150 linhas documentada aqui refere-se ao AGENTS.md como artefato; o teto de 200 da Anthropic refere-se ao CLAUDE.md — limites de artefatos distintos, sem contradição; ambos concordam na direção (menos linhas, cada linha precisa mudar comportamento).

Implications: o founder ganha o respaldo oficial para cobrar as três remoções clássicas — procedimento vira skill, comportamento obrigatório vira hook, restrição de diretório vira rule com paths: — e o argumento do “config sem dono” para nomear um owner do arquivo. Ver o mapa completo dos sete destinos em sete-metodos-para-instruir-claude-code.

Implications

Este princípio trata o AGENTS.md como superfície de engenharia de atenção, não como documentação tradicional — cada linha compete por atenção limitada do modelo com todas as outras. Para founders/PMs que mantêm esse arquivo, a disciplina é de edição contínua (remover o que não é essencial), não de acúmulo. Isso se conecta com plan-first-com-agentes-de-ia, onde a qualidade do plano inicial do agente depende diretamente de instruções operacionais precisas, e com especificacao-de-issues-para-agentes — o AGENTS.md e a issue dividem a mesma responsabilidade de eliminar ambiguidade antes da execução.

Open Questions

  • A fonte apresenta dois números levemente distintos para o limite máximo (150 linhas hard-cap em um princípio, 60-150 como “zona ideal” em outro) — não fica claro se são o mesmo limite reformulado ou uma tensão real não resolvida na fonte.
  • Falta uma auditoria do próprio AGENTS.md deste vault (/home/leovibecoding/projects/LLM-WIKI-OKF/AGENTS.md, ~285 linhas) contra este princípio — está bem acima da zona sugerida, o que levanta a questão de se o princípio se aplica igualmente a um vault de conhecimento (este projeto) e a um repositório de produto (o contexto original da fonte).

Sources

^[raw/vibecoding/articles/workflow-funnel-ai-assisted-development.md]

Visão de gráfico

Backlinks