AGENTS.md
is useful.
It gives AI coding agents a place to find repo-specific guidance:
That is a meaningful improvement over sending an agent into a repo with no instructions at all.
But AGENTS.md
is not enough.
It can tell an agent to be careful.
It cannot, by itself, make execution safe, verification trustworthy, or review inspectable.
For that, a repository needs more than instructions.
It needs:
That is the difference between agent guidance and execution governance.
An instruction file is still prose.
That means it can express intent, but it does not automatically create operational truth.
For example, AGENTS.md
can say:
Those are good rules.
But notice what they leave unresolved:
That is where many agent workflows still break down.
The agent may follow the spirit of the instructions and still take the wrong execution path.
One of the biggest gaps in agent-oriented repos is that they often declare guidance without declaring a safe command surface.
The repo may tell the agent:
Run tests before you finish.
But that still leaves a dangerous amount of interpretation.
Which task is safe?
Is it:
npm test
pnpm test
make check
docker compose run test
And if several exist, which one is canonical for a routine code change?
The repo should not force the agent to infer that from scattered hints.
It should declare safe commands explicitly.
That means giving the repo a machine-readable answer to questions like:
That is much stronger than asking an agent to "be careful" around shell commands it still has to interpret.
The second gap is verification.
Many repos still treat verification like a recommendation rather than a declared path.
An instruction file might say:
Make sure everything still works before handoff.
That sounds fine, but it is too loose for reliable agent execution.
A trustworthy repo should be able to say something more concrete:
That is the difference between advice and governance.
Without a declared verification path, the agent may:
Even explicit commands and verification paths are still weaker than they should be if nothing
records what actually ran.
This is where receipts matter.
A verification receipt is the difference between:
and:
That is the trust boundary most agent workflows still lack.
Receipts help answer questions like:
Without receipts, review still depends too heavily on:
With receipts, verification becomes inspectable.
A stronger repository keeps these layers distinct:
AGENTS.md
for human-written behavioral guidanceFor example:
- Prefer small diffs.
- Do not edit generated files manually.
- Escalate before changing deployment or billing flows.
- Use the declared verification path before handoff.
agent:
safe_tasks:
- lint
- typecheck
- test
verify_after_changes:
- test
tasks:
test:
command:
exe: pnpm
args: [test]
depends_on:
- setup
workflows:
verify:
setup:
task: setup
run:
task: test
And then the execution layer should be able to produce evidence rather than only output:
ota run test --json
ota receipt --json --archive
The exact tool does not matter as much as the structure:
That is the minimum shape of trustworthy agent execution.
This was already useful when agents mostly suggested edits.
It becomes much more important when agents are expected to:
At that point, the problem is no longer just "does the agent have instructions?"
The problem is whether the repo can expose:
That is a higher bar than AGENTS.md
alone can satisfy.
If you only need the boundary between instructions and contracts, read:
This post is narrower.
Its claim is not just that AGENTS.md
and ota.yaml
do different jobs.
Its claim is that even a good instruction file is still not enough unless the repo also declares:
AGENTS.md
is a good start.
But repo instructions alone do not make agent execution safe, reviewable, or trustworthy.
To get there, repositories also need:
That is how you move from:
to:
Original Post: https://ota.run/blog/agents-md-is-not-enough-for-safe-ai-agent-execution