Como estruturar documentação técnica para agentes de código
Agentes como Claude Code e Cursor seguem melhor instruções claras e verificáveis. Veja como organizar documentação que realmente orienta um agente.
Resumo rápido
- Agentes de código seguem melhor instruções curtas, específicas e verificáveis do que documentos longos e genéricos.
- Convenções, exceções e decisões de arquitetura importam mais do que descrições óbvias do código.
- Manter a documentação junto do repositório evita que ela fique desatualizada.
O que um agente realmente precisa saber
Um agente de código não precisa que se explique o que já está óbvio no próprio código — precisa saber o que não está lá: convenções do time, por que uma decisão foi tomada de um jeito e não de outro, e quais exceções existem.
Onde essa documentação deve viver
Formatos como AGENTS.md, CLAUDE.md e Cursor Rules funcionam melhor perto do código que descrevem, versionados junto com o repositório — assim mudam junto com o sistema em vez de envelhecer isolados em uma wiki separada.
Leve contexto ao time e aos agentes
Base viva, wiki, chat e artefatos — e o mesmo conhecimento exposto via MCP.
Agentes de IADocumentaçãoAGENTS.md