AGENTS.md Is Not Just Documentation
Persistent agent instructions do more than describe a repository. They shape which options an AI considers, which actions it avoids, and which early assumptions become enduring operating policy for future work.
AGENTS.md is often introduced as a convenience: a place to put repository conventions, commands, boundaries, and working notes for an AI coding agent.
That description is correct, but incomplete. A persistent instruction file is not merely documentation when an agent repeatedly receives it as context. It becomes part of the environment in which the agent decides what to do.
It can tell the agent which directories are safe to change, which tools to use, what quality means, which architectural pattern is preferred, and which actions require approval. In other words, it can behave like policy.
Policy is valuable. It gives a system consistency and prevents expensive mistakes. The problem begins when every statement in a policy file receives the same authority.
A sentence can become a boundary
Consider these statements:
- Never expose customer credentials.
- Destructive actions require human approval.
- Use PostgreSQL for transactional data.
- The current prototype uses a vector database.
- We may eventually need a dedicated research agent.
The first two are safety constraints. The third might be a current architectural decision. The fourth is a fact about today. The fifth is a hypothesis about tomorrow.
An agent that sees all five in one undifferentiated instruction block has little reason to treat them differently. A temporary implementation choice can quietly acquire the force of a constitutional rule.
That is the central issue in awareness before architecture. Early assumptions do not become risky because they are written down. They become risky when their status is hidden.
Documentation informs. Context directs.
Humans generally read documentation with a sense of history. We know a README may be out of date. We know the person who wrote it had a partial view. We can ask whether it still applies.
An agent does not automatically carry that skepticism. If an instruction is presented as a requirement, it reasonably treats it as a requirement. Asking it to independently reconsider every explicit instruction would also make it unreliable.
The responsibility therefore belongs to the system designer. Context needs labels, ownership, and a lifespan. A useful pattern is to separate four things:
| Context type | Example | Agent behaviour |
|---|---|---|
| Hard boundary | Do not reveal secrets | Must obey |
| Stable principle | Prefer evidence over assertion | Must follow, explain conflicts |
| Current decision | This service owns billing | Follow, flag conflict when relevant |
| Hypothesis | A research agent may be needed | Treat as open to testing |
This is not bureaucracy for its own sake. It lets a system be reliable without confusing today’s implementation with permanent truth.
The file should include a way to disagree
There is an important nuance. An execution agent should not decide that a repository rule is optional simply because it has found a more elegant implementation. That would make every task an architecture debate.
But the system should give it a safe way to report a conflict. A useful instruction pattern is: follow the current rule, then flag it when it blocks the stated objective, repeatedly causes an exception, creates material cost, or conflicts with a higher-priority boundary.
That keeps the agent accountable to the current operating model without requiring it to pretend the operating model can never be wrong. It also creates evidence. One complaint may be noise. Ten similar exceptions across separate tasks may be a signal that the rule deserves review.
The difference is between an agent that silently works around a rule and one that records the constraint, follows the escalation path, and lets a responsible person decide whether the policy should change.
The instruction file should reveal uncertainty
Good agent context is not simply more context. It is context with a visible hierarchy.
For architectural choices, record why the choice was made, what it optimises for, who owns it, and what would cause a review. For hypotheses, include the evidence still missing. For safety rules, be explicit that they are not available for agent-led reinterpretation.
The resulting file is more honest and more useful. It lets the agent execute familiar work with confidence while knowing where a human or a dedicated exploration process should question the design.
That is also why a pile of role prompts does not by itself create a sophisticated system. What makes an AI system an agent is about who controls the next action. This article adds a related question: what information is allowed to control the decision space in the first place?
Treat policy as a product
Instruction files deserve versioning, review, and retirement. If a rule is no longer true, deleting or downgrading it is not housekeeping. It is an architectural change.
Teams can make this concrete with a small “review queue” section alongside their rules. It should list the hypothesis, the responsible owner, the next review date or trigger, and the evidence needed for a decision. The queue is not context the agent must obey. It is context that tells the agent where honest uncertainty is allowed to exist.
That small distinction stops the file from becoming a graveyard of half-remembered decisions. It gives future contributors, human and machine, a way to understand not only what the system does but also what the system is still trying to learn.
The mature move is not to make an agent endlessly sceptical. It is to make the authority of its instructions legible. That is how you get consistency without locking a future system inside the beliefs of its first week.
References
- Anthropic, Building effective AI agents
- OpenAI Developers, Agents
- Related on this site: Awareness Before Architecture, What Makes an AI System an Agent