Once I started using AI coding agents more seriously, I noticed a repetitive problem.
Every new task began with the same explanations.
Which documents should the agent trust?
Which architecture decisions are already final?
Which folders can it modify?
What coding standards should it follow?
What happens if two requirements conflict?
Which shortcuts are not acceptable?
What does “done” actually mean?
I could repeat those instructions every time, but that quickly became inefficient. Worse, the instructions could drift from one session to another.
That was the point when AGENTS.md became useful for me.
I started treating it as the operating manual for the AI agent inside the repository.
Not as another requirements document.
Not as a replacement for the PRD.
Not as a place to dump every technical detail.
Its purpose is different.
The PRD explains what the product should do.AGENTS.md explains how the AI agent should behave while building it.
That distinction turned out to be more important than I expected.
Why I Needed Something Beyond the PRD
While preparing EZSell V2 for AI-assisted development, I already had a fairly complete documentation set.
There were module specifications, database designs, API contracts, security rules, UAT scenarios, architecture decisions, and implementation plans.
On paper, the agent had plenty of information.
But having information available is not the same as knowing how to use it.
An AI coding agent still needs operational guidance.
For example:
Should it trust a newer module specification over an older consolidated document?
Should it modify an existing architectural pattern or preserve it?
Should it add a dependency when a built-in solution already exists?
What should it do if the requirement is unclear?
Should it create migrations automatically?
Can it change shared authentication logic while implementing an unrelated feature?
Can it introduce business rules that are not written anywhere?
These are not product requirements.
They are working rules.
That is what I wanted AGENTS.md to define.
What AGENTS.md Became for Me
I think of AGENTS.md as a combination of:
repository instructions
development guardrails
source-of-truth rules
coding expectations
architectural boundaries
quality standards
escalation rules
It gives the coding agent context about how work should happen inside the project.
That matters because AI agents are very good at being proactive.
Sometimes too proactive.
If the agent sees a problem, it may refactor it.
If it sees duplicated logic, it may redesign it.
If it notices an opportunity to introduce a new abstraction, it may create one.
That can be useful.
But in a serious product, “technically reasonable” is not always the same as “correct for this project.”
The repository needs boundaries.
The First Rule: Tell the Agent What Is Authoritative
This was one of the most important things I added.
In a growing product, there will almost always be multiple documents.
Some are current.
Some are historical.
Some are reference material.
Some have been superseded.
Some contain technical details.
Others contain product rules.
Without guidance, an agent may treat all of them as equally valid.
That is dangerous.
My AGENTS.md therefore needs to explain which documents are authoritative and how conflicts should be resolved.
For example, the rule might be conceptually similar to this:
Follow the current Source-of-Truth Index first.
Use the latest approved module specification for business behavior.
Use the database design for schema constraints.
Use the API contract for endpoint and state-transition rules.
Do not implement from archived or superseded documents.
The exact hierarchy will differ from project to project.
The important part is that the agent should not have to guess.
Define What the Agent Must Read Before Coding
Another lesson I learned was that “read the repository” is too vague.
For every task, I want the agent to know the minimum documents it must inspect before making changes.
That usually includes things like:
AGENTS.mdthe Source-of-Truth Index
the relevant module specification
applicable database definitions
related API contracts
security and permission rules
relevant acceptance criteria or UAT scenarios
This does not mean the agent must read the entire documentation library every time.
In fact, I usually want the opposite.
I want the agent to load the context required for the current task and avoid unrelated areas unless there is a dependency.
This keeps the work focused.
Repository Boundaries Matter
One of the easiest ways an AI agent can create trouble is by changing more than the task requires.
Imagine asking it to add a new inventory workflow.
During implementation, it notices that authentication could be cleaner.
So it modifies authentication.
Then it notices repeated database helpers.
It refactors those.
Then it updates shared error handling.
Technically, each change might be reasonable.
But suddenly a small inventory task touches 30 files across multiple parts of the system.
That makes review harder and increases regression risk.
So I define boundaries.
The agent should know:
which application or package it is working in
which folders are in scope
which shared components should not be changed casually
which infrastructure files require explicit approval
which modules are unrelated to the task
A useful rule is:
Prefer the smallest change that satisfies the requirement.
That sounds obvious, but it is worth stating.
Architecture Rules Should Be Written Down
If certain architecture decisions are final, the AI agent should not rediscover them during every task.
For example, a project may already have decisions around:
framework choices
database structure
tenancy model
authentication
authorization
caching
queueing
storage
service boundaries
frontend state management
API patterns
If those decisions are stable, put the important constraints in AGENTS.md or point the agent to the authoritative architecture document.
The goal is not to duplicate the architecture document.
The goal is to say:
These decisions already exist. Do not replace them just because another approach is also valid.
This matters because AI often presents alternatives confidently.
A developer can look at an architecture and say:
“Maybe we should use a different ORM.”
The agent can do exactly the same thing.
But unless that is the task, I do not want architectural redesign happening accidentally.
Business Rules Must Never Be Invented
This is probably the most important behavioral rule in my workflow.
If the documentation does not define an important business rule, the agent should not silently decide it.
Suppose the agent is building a sales flow and discovers that the specification does not clearly say whether a finalized sale can be edited.
That is not a minor implementation detail.
It affects inventory, audit history, accounting, returns, permissions, and reporting.
The wrong behavior would be:
“Editing seems useful, so I added it.”
The correct behavior is:
“The specification does not define whether finalized sales are editable. This affects multiple modules. Please confirm before implementation.”
That single rule prevents a lot of hidden product decisions from entering the codebase.
I want AI to recommend options when useful.
I do not want it to approve its own product decisions.
Define Security Expectations Explicitly
Security is another area where assumptions are dangerous.
For a multi-tenant or role-based SaaS product, AGENTS.md should make security expectations very clear.
For example:
tenant isolation must never rely only on frontend checks
every protected operation must enforce authorization server-side
data must be queried within the correct tenant boundary
user-provided identifiers must not bypass ownership checks
sensitive actions must respect permission rules
secrets must never be hardcoded
validation must occur on the server even if the UI validates first
These rules may already exist elsewhere in the documentation.
That is fine.
AGENTS.md should reinforce the behavior the coding agent must follow.
Security should not be something an AI agent “fills in reasonably.”
Transaction Rules Also Need Guardrails
Once a product involves stock, money, balances, payments, or accounting, transaction behavior becomes critical.
For EZSell V2, a sale is not just a row in a sales table.
It can affect:
inventory
payment records
counter balances
accounting transactions
customer dues
audit logs
If one part succeeds and another fails, the system can become inconsistent.
So the agent needs to understand that some operations must be treated atomically.
This is where I would put rules such as:
use database transactions for multi-step financial or inventory operations
do not leave partial state after failure
preserve idempotency where the specification requires it
do not update balances independently from the transaction that caused them
use existing ledger or movement patterns instead of inventing parallel logic
These rules save a lot of trouble later.
Tell the Agent What “Done” Means
One of the biggest improvements in my AI workflow came from defining a clear Definition of Done.
Without it, an agent may interpret completion as:
“The code compiles.”
That is not enough.
For a meaningful task, done might require:
implementation completed
validation added
permissions enforced
database migration added if required
automated tests added
tests passing
error cases handled
no unrelated files changed
documentation updated if behavior changed
acceptance criteria verified
no known conflicts with the source documents
That is a much stronger standard.
I want the AI agent to understand that code generation is only one part of completion.
Testing Expectations Should Be Part of the Rules
AI is good at generating tests.
But if you do not tell it what kind of testing matters, it may generate superficial tests that simply confirm the happy path.
I prefer to define expectations.
For example:
Every meaningful business operation should test:
successful execution
validation failure
permission failure
invalid state transition
tenant isolation where relevant
transaction rollback where relevant
duplicate or repeated request behavior where relevant
Not every task needs every test category.
The point is to establish that tests should prove business behavior, not just increase coverage numbers.
Explicitly List Prohibited Shortcuts
This section is surprisingly useful.
AI agents often optimize for getting the task completed quickly.
Sometimes that means taking shortcuts you would not want in production.
Depending on the project, I may explicitly prohibit things like:
hardcoded tenant IDs
bypassing authorization for convenience
direct database manipulation when an existing service exists
duplicate business logic
temporary production credentials
disabling validation to make tests pass
adding TODO placeholders for required functionality
silently swallowing exceptions
removing failing tests instead of fixing the implementation
creating parallel patterns when an approved one already exists
A rule like this might feel unnecessary to an experienced developer.
But AI benefits from explicit boundaries.
I Also Tell the Agent When to Stop
This is an important one.
Most instructions tell the agent what to do.
I also want to tell it when not to continue.
The agent should stop and raise a question if:
two authoritative documents conflict
a required business rule is missing
the requested implementation violates an approved architecture decision
the task requires changing a protected shared component unexpectedly
a migration would create destructive behavior not covered by the requirements
security implications are unclear
acceptance criteria cannot be satisfied with the available information
This is much better than having the agent “use best judgment” for everything.
Good judgment is useful.
But some decisions should remain human decisions.
AGENTS.md Should Not Become Another 100-Page Specification
There is another trap here.
Once you discover how useful AGENTS.md is, it is tempting to put everything inside it.
I do not think that is a good idea.
The file should remain operational.
It should tell the agent how to work and where to find the truth.
It does not need to repeat every product requirement, database table, API response, or UI field.
If the file becomes too large, it creates the same problem we were trying to solve in the first place: too much context.
I prefer AGENTS.md to act as a map.
It should point the agent to the correct sources and define the rules of engagement.
My Mental Model for the Documentation Stack
This is how I separate responsibilities now.
PRD / SRS
What should the product do?
Decision Register
What important product decisions have already been made?
Source-of-Truth Index
Which document is authoritative?
Architecture Documentation
How is the system designed?
Database and API Contracts
How should data and interfaces behave?
UAT / Acceptance Criteria
How do we prove the behavior works?
AGENTS.md
How should the AI coding agent behave while working in this repository?
Each document solves a different problem.
That separation reduces ambiguity.
A Practical AGENTS.md Structure
The exact structure will depend on the product, but a useful starting point could look like this:
1. Project Context
A short explanation of the product, repository, and current development stage.
2. Source of Truth
Which documents are authoritative and how conflicts are resolved.
3. Required Reading
Which documents the agent must inspect before implementing a task.
4. Repository Structure
Important directories, application boundaries, and ownership.
5. Architecture Rules
Technology and design decisions that should not be changed casually.
6. Coding Standards
Naming, patterns, structure, error handling, reuse, and maintainability expectations.
7. Database Rules
Migrations, transactions, constraints, tenancy, and data integrity.
8. Security and Authorization
Authentication, permissions, tenant isolation, secrets, and validation.
9. Testing Requirements
Required tests and expected coverage of important business behavior.
10. Prohibited Shortcuts
Patterns and behaviors the agent must not introduce.
11. Definition of Done
What must be true before a task is considered complete.
12. Escalation Rules
When the agent must stop and ask for clarification.
That is usually enough.
The file should evolve as the project evolves.
An Example Rule Set
A simplified section might read something like this:
## Business Rules
- Do not invent business behavior that is not defined in an authoritative specification.
- If a required business rule is missing, stop and request clarification.
- Do not implement features marked deferred or excluded from the MVP.
- Preserve existing state-machine rules.
- Do not bypass validation, authorization, tenant isolation, or audit requirements.
## Change Scope
- Make the smallest change necessary to satisfy the task.
- Do not refactor unrelated modules unless explicitly requested.
- Do not introduce new frameworks, libraries, or architectural patterns without approval.
- Reuse existing project patterns where appropriate.
## Definition of Done
A task is complete only when:
- the requested behavior is implemented
- applicable validation and authorization are enforced
- automated tests are added and passing
- acceptance criteria are satisfied
- no unrelated behavior is broken
- required documentation is updatedThe value is not in copying these exact rules.
The value is deciding what rules matter for your own repository.
AGENTS.md Is Not a Replacement for Good Prompts
One thing I want to make clear is that AGENTS.md does not eliminate the need for good task instructions.
It handles the persistent rules.
The task prompt still needs to explain the current objective.
For example:
AGENTS.md might say:
Never invent business rules. Use the current module specification as the authoritative source.
The task might say:
Implement customer creation according to Customer Management Specification v1.1. Include server-side validation, permission enforcement, duplicate handling, tests, and the relevant acceptance criteria. Do not implement customer editing in this slice.
The two work together.
One defines how the agent operates.
The other defines what it should build now.
The Real Benefit Is Consistency
The biggest value I get from AGENTS.md is not that it makes the AI smarter.
It makes the workflow more consistent.
Different sessions start with the same rules.
Different tasks inherit the same architectural boundaries.
The agent knows which documents to trust.
It knows what shortcuts are forbidden.
It knows when it should stop instead of guessing.
And I do not need to rewrite those instructions every time.
That matters even more as AI-assisted development becomes a regular workflow instead of an experiment.
It Also Helps Me Think More Clearly
There was an unexpected benefit.
Writing AGENTS.md forced me to make some implicit expectations explicit.
What actually counts as done?
Which architecture decisions are fixed?
When can a coding agent refactor?
Which documents win when requirements conflict?
What must always be tested?
Which decisions should AI never make independently?
Those are useful questions even without AI.
In that sense, AGENTS.md is not just documentation for the agent.
It is also documentation of how I want the project to be built.
What I Would Avoid
I would avoid turning AGENTS.md into a giant copy of the SRS.
I would avoid putting temporary task-specific instructions inside it.
I would avoid writing vague rules like “write clean code” without explaining what that means in the project.
I would avoid allowing the agent to silently resolve business conflicts.
And I would avoid treating the file as something you write once and never revisit.
As the project matures, the rules should evolve.
The repository changes.
The architecture changes.
The Definition of Done may become stricter.
Testing requirements may improve.
New risks appear.
The operating manual should reflect that.
My Workflow Now
For a typical AI-assisted implementation task, my workflow looks like this:
Read AGENTS.md → Identify authoritative specs → Select the relevant context → Plan the change → Raise conflicts → Implement → Test → Validate acceptance criteria → Review → Commit
AGENTS.md sits near the beginning of that loop.
It establishes the rules before the agent starts making decisions.
That is exactly where I want it.
Final Thought
When I first started using AI coding tools, I focused heavily on prompts.
I thought better prompts would produce better software.
Prompts still matter.
But the more I use coding agents on serious products, the more I think the bigger advantage comes from building a controlled environment around them.
Clear requirements.
Clear architecture.
Clear business rules.
Clear testing expectations.
Clear boundaries.
And clear instructions for what the agent should do when something is unclear.
That is what AGENTS.md gives me.
It does not make the AI responsible for the product.
It makes the AI easier to control while building the product.
And that is an important difference.
A good coding agent can write a lot of code quickly.
A good AGENTS.md helps make sure it writes the right code, in the right way, inside the right boundaries.