O problema
Sejamos honestos: não queremos mais ler código. Não queremos verificar tudo o que os agentes fazem, nem guardar na cabeça cada detalhe técnico do projeto.
Mas se ninguém controlar os agentes, eles transformarão qualquer projeto em um caos insustentável que nem humano nem agente conseguirá desembaraçar. É só questão de tempo.
A ideia
HUMAN-INTENT.md é um arquivo na raiz do seu repositório. Ele guarda a sua intenção: a arquitetura do projeto, as regras de desenvolvimento e as decisões de produto.
Não é documentação do código. É a lei que o código deve obedecer.
As regras
-
Escrito por você — e somente por você
Agentes nunca editam este arquivo. Cada linha nele é uma decisão tomada por um humano.
-
Suas instruções são lei para o agente
O que o HUMAN-INTENT.md diz prevalece sobre todo o resto. Se o código contradiz o arquivo, o código está errado.
-
Ele define arquitetura, regras e produto
Intenção, não receitas. O agente já conhece todos os padrões; seu trabalho é fixar o que deve ser verdade — e por quê.
Por que funciona
É impossível acompanhar os agentes: há mais código do que alguém está disposto a ler. Controlar cada linha é inútil. Controlar a intenção, não.
O HUMAN-INTENT.md eleva o controle um nível: você acompanha um arquivo com as suas decisões em vez de milhares de linhas de código. Enquanto o arquivo for lei, o projeto segue a sua intenção — mesmo que ninguém leia o código.
Como começar
- Crie o HUMAN-INTENT.md na raiz do seu repositório.
- Registre as decisões que você já tomou: arquitetura, regras de desenvolvimento, produto.
- Diga ao seu agente para ler o arquivo e tratá-lo como lei — referencie-o no AGENTS.md ou CLAUDE.md.
- Sempre que tomar uma nova decisão, adicione-a ao arquivo. Nunca deixe um agente escrever nele.
- Revise este arquivo, não o código.