AGENTS.md: A README for AI Coding Agents
September 24, 2026 Avishka Devinda
September 24, 2026 Avishka Devinda
A README explains a project to a developer.
An AGENTS.md file does something similar for an AI coding agent.
It gives the agent a predictable place to learn the rules of the repository before it starts changing code.
I think this becomes more useful as AI does larger tasks instead of only completing a few lines.
AGENTS.md is an open format for giving instructions to coding agents.
The basic idea is very simple:
repository/
├── AGENTS.md
├── package.json
├── src/
└── ...
The file can explain:
This is information I would normally explain to another developer joining the project.
Prompts are temporary.
Repository rules are not.
If I have to tell the agent this every time:
Use npm.
Do not remove the animations.
Run the build.
Do not merge.
Keep Resend server-side.
then the repository is missing useful machine-readable context.
Those rules belong closer to the code.
An AGENTS.md for a Next.js project could look like this:
# AGENTS.md
## Project
This is a Next.js App Router project using TypeScript,
Tailwind CSS, Drizzle ORM, and Neon Postgres.
## Development
- Use npm. Do not create pnpm-lock.yaml or bun.lock.
- Prefer Server Components.
- Add "use client" only when interaction requires it.
- Keep environment variables and secrets server-side.
## Design
- Preserve the existing layout and animations.
- Reuse components before creating new ones.
- Support both light and dark mode.
## Validation
Before finishing:
1. Run npm run lint.
2. Run npm run build.
3. Test the affected route.
4. Check the browser console.
5. Review the diff for unrelated changes.
## Git
- Work on the requested branch.
- Do not merge unless explicitly asked.
- Do not force-push.
It is not complicated.
That is the point.
One pattern I like from current agent tooling is separating always-needed context from task-specific workflows.
AGENTS.md should contain rules the agent should know on almost every task.
Examples:
If something is only relevant to one specialized task, it probably does not need to live in the global file.
A giant AGENTS.md can become another problem.
If the file contains hundreds of unrelated instructions, the most important rules become harder to find.
I prefer a short hierarchy.
For example:
AGENTS.md
↓
always-loaded rules
Skills
↓
task-specific workflows
docs/
↓
deep project documentation
The agent starts with the important guardrails and loads more detail only when the task needs it.
Large repositories can benefit from more specific instructions deeper in the tree.
For example:
AGENTS.md
apps/
web/
AGENTS.md
packages/
database/
AGENTS.md
The root file can describe global rules.
A nested file can describe the conventions for one part of the repository.
This is useful in monorepos where the frontend, API, and shared packages have different commands or patterns.
An outdated AGENTS.md can be worse than no file.
Imagine the file says:
This project uses Next.js 15 and Tailwind CSS 3.
but the repository has already moved to Next.js 16 and Tailwind CSS 4.
Now the agent is starting with incorrect information.
I treat AGENTS.md like normal project documentation.
If the architecture changes, the agent instructions should change too.
Recent Next.js versions have added explicit support for coding-agent workflows.
Next.js can provide version-matched framework docs from the installed package, and newer versions generate agent guidance that tells coding agents to consult those docs instead of relying on outdated framework knowledge.
That is a good direction.
Frameworks change too quickly for an AI agent to assume that its training data matches the version inside the repository.
For most projects I focus on five sections:
What is this application?
What framework and major technologies does it use?
What patterns should the agent preserve?
What must not change visually?
What commands and runtime checks are required?
What is the agent allowed to commit, push, merge, or delete?
These five sections cover most mistakes I want to prevent.
AGENTS.md is not a magic prompt.
It is project documentation written with coding agents in mind.
The value comes from consistency.
When the same important constraints are available every time an agent enters the repository, I spend less time repeating instructions and less time repairing changes that ignored the project's architecture.
For AI-assisted development, that is a very small file with a surprisingly large impact.