TLDR;

Um único arquivo markdown (agents.md / agents.mmd) funciona como um framework de documentação auto-documentante acoplado ao código que dá ao agente de IA o contexto mínimo necessário para fazer a edição certa e manter a consistência da base. A integração é extremamente simples e sem instalação: copie e cole o markdown no seu agents.md existente e os agentes começarão a ler a documentação antes de editar e a atualizá‑la depois. O método escala em bases grandes porque organiza agents.md em uma árvore por pastas, permitindo ao agente navegar até o domínio correto, manter o contexto dos arquivos pais e evitar bloat, duplicação e edições desnecessárias.

Resumo

Yan, desenvolvedor do Agent Zero e do Space Agent, apresenta o Docs, um framework simples e sem instalação que resolve o maior problema dos agentes de programação por IA: falta de consciência de contexto. Agentes inteligentes executam bem tarefas isoladas, mas ao manter bases de código grandes costumam criar funcionalidades no lugar errado, duplicar código e inflar o projeto, gerando ciclos intermináveis de correção. O Docs usa arquivos agents.md distribuídos por toda a árvore do repositório, acoplando documentação e código; cada arquivo documenta um domínio (uma pasta) e inclui índices filhos, permitindo ao agente navegar do topo às folhas, ler instruções de propósito, propriedade, contratos locais, regras, testes e orientações, aplicar a edição mínima necessária e atualizar a documentação correspondente — inclusive arquivos pais quando relevante. Assim o agente mantém visão do “quadro geral” sem sobrecarregar o contexto com tokens desnecessários. A abordagem provou seu valor no Space Agent, um sistema complexo gerado inteiramente por IA, acelerando desenvolvimento e melhorando qualidade de código; o Docs é open source e pode ser integrado copiando o Markdown para o agents.md existente, adicionando responsabilidade de documentação aos agentes. É uma solução prática que reduz erros, acelera entregas e facilita manutenção colaborativa de código realmente.