Unir RFCs e prompts em um único documento permite centralizar decisões, exemplos de código e critérios de teste de modo que humanos leiam com clareza e agentes automatizados tenham tudo o que precisam para executar tarefas e validar mudanças, reduzindo divergências entre fontes de verdade e simplificando a manutenção; o documento ideal descreve problema e contexto, stack e ambiente, soluções propostas, restrições, contratos de interface, critérios de aceite e estrutura de arquivos — e pode ser ilustrado com um exemplo prático, como um sistema de bookmarks, para mostrar rotas, payloads e testes esperados.
O Documento Único propõe unificar RFCs e prompts em um só artefato que sirva tanto para pessoas quanto para agentes automatizados.
A motivação é simples: ter duas fontes de verdade tende a gerar divergências e atrito na manutenção do sistema.
Com um documento único, as decisões, os exemplos de código e os critérios de teste ficam centralizados e mais fáceis de atualizar.
Isso facilita o trabalho em equipe e reduz o risco de comportamentos inesperados por parte dos agentes.
Para que agentes consigam operar com segurança e previsibilidade, o documento precisa expor a stack, caminhos de arquivo, exemplos de uso e critérios de aceitação de forma clara.
Ao mesmo tempo, não deve perder a legibilidade para leitores humanos; a ideia é manter explicações e contexto compreensíveis.
O texto propõe um template com seções como problema, contexto, stack e ambiente, soluções propostas e restrições.
Também inclui contratos de interface, critérios de aceite e uma estrutura de arquivos que servem tanto para implementação quanto para validação automática.
No artigo original, um sistema de bookmarks é usado como exemplo prático para mostrar como preencher cada seção do template.
Nesse exemplo aparecem rotas, exemplos de payload, testes esperados e como o agente deve navegar pelo repositório.
O resultado é um documento acionável: humanos entendem as decisões e agentes têm tudo que precisam para executar tarefas e validar mudanças.
Com uma única fonte de verdade atualizada, a manutenção fica mais simples e o onboarding de novos integrantes é acelerado.
Este texto faz parte de uma série que explora como documentação para humanos e agentes podem caminhar juntas e elevar a qualidade do time.
