The problem
Let's be honest: we no longer want to read code. We don't want to verify everything agents do, or keep every technical detail of the project in our heads.
But if nobody controls the agents, they will turn any project into unmaintainable chaos that neither a human nor an agent can untangle. It is only a matter of time.
The idea
HUMAN-INTENT.md is one file in the root of your repository. It holds your intent: the project's architecture, the development rules, and the product decisions.
It is not documentation for the code. It is the law the code must obey.
The rules
-
Written by you — and only you
Agents never edit this file. Every line in it is a decision made by a human.
-
Its instructions are law for the agent
What HUMAN-INTENT.md says overrides everything else. If the code contradicts the file, the code is wrong.
-
It defines architecture, rules, and product
Intent, not recipes. The agent already knows every pattern; your job is to state what must be true — and why.
Why it works
You can't keep up with agents: there is more code than anyone is willing to read. Controlling every line is hopeless. Controlling the intent is not.
HUMAN-INTENT.md moves control one level up: you watch one file with your decisions instead of thousands of lines of code. As long as the file is law, the project follows your intent — even when nobody reads the code.
How to start
- Create HUMAN-INTENT.md in the root of your repository.
- Write down the decisions you have already made: architecture, development rules, product.
- Tell your agent to read the file and treat it as law — reference it from AGENTS.md or CLAUDE.md.
- Every time you make a new decision, add it to the file. Never let an agent write there.
- Review this file, not the code.