Every team that tells me their AI agent is “dumb” in 2026 has the same problem, and it is almost never the model. The agent doesn’t know how to run your tests, which folder is generated, or why the design system forbids raw hex values. So it guesses — confidently — and you spend the afternoon reviewing plausible garbage.
That is not a prompting problem. It is a context problem. And in 2026 there is finally a boring, portable place to fix it: a file called AGENTS.md.
The short answer
AGENTS.md is not a prompt. It is an operating manual for your repository — the file an agent reads before it touches a single line. It has exactly three jobs:
- Commands that actually run on this project, not the ones in a tutorial.
- Conventions that differ from the default — the things a competent engineer could not guess.
- Boundaries — what the agent must not touch, install, deploy, or rewrite.
Sixty to a hundred and twenty lines beats six hundred. The format is now an open standard: the first commit landed on 19 August 2025, the site lists 24+ compatible tools, and by 2026 it is used by tens of thousands of repositories and stewarded by the Agentic AI Foundation at the Linux Foundation. Codex, Cursor, Copilot, Gemini CLI, Jules, Aider, Zed, Windsurf and Devin all look for the same filename. The AGENTS.md site calls it “a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project.”
One number to keep in mind: Codex caps AGENTS.md at 32 KiB by default. That is a ceiling, not a target. If your file is approaching the cap, the agent is probably skimming it.
The test: could a contractor ship on day one?
Before you write a word, apply this test. A competent contractor joins the team, reads only your README and AGENTS.md, and has to ship a small fix. Can they:
- install dependencies with the right package manager,
- run the dev server on the right port,
- run one test — not the whole suite —
- find where a new component, route, or utility belongs,
- know what is generated and must not be edited,
- know what “done” means before opening a PR?
If any answer is no, the agent will fail the same way. The contractor test is cheaper than debugging a bad agent run.
What belongs — and what does not
| Include | Why |
|---|---|
| Exact commands for dev, build, test, typecheck, lint, and a single test file | The agent runs commands blindly; a wrong script wastes a whole session |
| A ten-line repo map: entry points, feature folders, generated directories, ownership | Agents don’t infer monorepo structure from file names |
| Conventions that differ from framework defaults | Everything else is already in the model’s training data |
| Hard boundaries: migrations, generated code, deploys, new dependencies | Prevents the expensive mistakes |
| Environment quirks: Node version, env vars, ports, local services | Half of “it doesn’t work” is a missing variable |
| Definition of done: tests, accessibility, bundle budget | Turns vague “make it good” into checkable criteria |
| Exclude | Why |
|---|---|
| Language basics, Prettier defaults, “write clean code” | The model already knows; it is noise that dilutes the rules that matter |
| Full API documentation or database schemas | Link to the doc; don’t paste it |
| Secrets, tokens, internal URLs, customer data | This file gets committed and sent to providers |
| Rules nobody enforces | An ignored rule teaches the agent that rules are optional |
| A copy of the README | Two sources of truth become two wrong answers |
A real AGENTS.md for a Next.js + TypeScript repo
This is the shape I use. It is deliberately boring. Replace the names, keep the structure.
# AGENTS.md
## Commands
- Package manager: pnpm 9. Never npm or yarn.
- Dev: pnpm dev (http://localhost:3000)
- Build: pnpm build
- Typecheck: pnpm typecheck
- Lint: pnpm lint
- Tests: pnpm test
- One file: pnpm test -- src/lib/pricing.test.ts
- E2E: pnpm playwright test --project=chromium
## Structure
- app/ routes; server components by default
- components/ui/ shared primitives; no page-specific logic
- lib/ pure functions and adapters; no React imports
- content/ MDX; never edit generated/ inside it
- Do not edit: .next/, app/generated/, content/generated/
## Conventions
- Server components by default. Add "use client" only for state,
effects, or browser APIs.
- Fetch data in server components. No useEffect data fetching.
- Style with Tailwind v4 tokens from app/globals.css. No raw hex.
- Errors: return Result<T> from lib/result.ts. Do not throw for
expected failures.
- Every interactive element needs a visible focus state and a label.
## Boundaries
- Never run migrations, seeds, or deploys. Ask first.
- No new dependency without a note in the PR description.
- Do not rewrite files outside the task scope.
- Do not commit .env files or paste their contents into chat.
## Definition of done
- pnpm typecheck, lint, and test pass.
- Keyboard navigation works for every new control.
- No client component added without a measured reason.
- PR description lists what was verified, not what was attempted.
The repo map is the section teams skip
Agents do not know that packages/ui is published, that apps/web is the only deployable, or that legacy/ is read-only. They will happily import a server-only module into a client component and then explain why the build is broken.
Keep the map to ten lines and update it when the structure changes. If you use a monorepo, put the root map in the root file and a shorter map in each package. That is what nested files are for.
Layering: root, nested, local
Codex reads nested AGENTS.md files whose scope includes the files being changed, with deeper files taking precedence. Cursor supports the same idea in subdirectories. Claude Code doesn’t read AGENTS.md natively, but its own file can import it:
# CLAUDE.md
@AGENTS.md
## Claude-specific
- Use plan mode before any multi-file change.
- Run the test command before proposing a diff.
For Copilot, a symlink to .github/copilot-instructions.md keeps one source of truth. The rule is simple: one file owns the project rules, every other file imports or points to it. Three diverging instruction files are worse than none, because the agent will follow the wrong one depending on which tool you opened.
Five failure modes I keep seeing
1. Stale commands
The project moved from npm to pnpm eight months ago; the file still says npm install. The agent runs it, gets a lockfile conflict, and spends ten minutes “fixing” the wrong problem. A stale command is worse than no command.
2. Contradictions between root and nested files
The root says “server components by default”; a nested file says “use client for all pages”. The agent picks one, and your reviewer picks the other. Treat instruction files like code: review changes, and delete rules that no longer apply.
3. The essay
Two hundred lines of philosophy about craftsmanship. By line forty, the agent is skimming, and so am I. If a rule cannot be checked, it probably belongs in a blog post, not in the repo.
4. Secrets and internal URLs
I have found staging passwords, admin URLs, and customer IDs in these files. Remember where the file goes: into the repo, into the prompt, and into whichever provider you use that week. Keep secrets in the environment, and rotate anything that ever touched a prompt.
5. Rules with no enforcement
“Never use any.” The agent uses any in the third file. Nobody notices until review. If a rule matters, it needs a failing check — not a sentence in Markdown.
How to tell whether the file is working
Don’t measure lines generated. Measure the things that cost you time:
- First-attempt diff size: is the agent changing ten files when you asked for one?
- Review rounds per PR: a good context file reduces back-and-forth, not just typing.
- CI failures per change: stale commands show up here first.
- Time to merge: the only number that matters to the business.
Pick one, baseline it for two weeks, then change the file. If the number doesn’t move, the file is documentation theatre. This is also how you justify the maintenance cost to a team that would rather ship features.
Instructions are advisory; make the non-negotiables executable
Markdown compliance is partial by nature. A model can read “always run the tests” and still skip them when it is confident. The fix is not a louder sentence. It is a gate:
- CI: typecheck, lint, unit tests, secret scan, bundle budget, accessibility check.
- Pre-commit hooks: block formatting drift and obvious secrets before they leave the laptop.
- Branch protection: no merge with a red check, no exceptions for “just a small change”.
- Sandboxed agents: no production credentials in the environment, no deploy commands in the allowlist.
AGENTS.md tells the agent where the walls are. CI is the wall. Teams that rely on the document alone get a well-documented version of the same mistakes.
A ten-minute audit of your current file
- Run every command in the file, exactly as written. Delete or fix anything that fails.
- Ask a teammate who has never touched the repo to find where a new component goes using only the map.
- Delete every line that restates a framework or language default.
- Move secrets to environment variables and rotate anything exposed.
- Pick the three rules you care about most and add a check that fails the build when they are broken.
- Put a review date in the file. Context rots quietly.
FAQ
Is AGENTS.md better than CLAUDE.md?
It is not either/or. AGENTS.md is the portable, cross-tool file; CLAUDE.md is Claude Code’s native entry point, and it can import AGENTS.md with @AGENTS.md. Use the portable file as the source of truth and keep tool-specific notes in the native file.
How long should it be?
Sixty to a hundred and twenty lines for most projects. Codex’s 32 KiB default is a hard ceiling, not a goal. If the file keeps growing, move detail into linked docs and keep the rules that change behaviour.
Does it work with Copilot and Cursor?
Yes. Cursor reads it at the root and in subdirectories. Copilot’s coding agent reads AGENTS.md, and VS Code’s Copilot integration uses .github/copilot-instructions.md, which you can symlink to the same content. Check your tool’s current docs — support has been moving fast, in a good way.
Should I commit it?
Yes. It is project documentation, and it should be reviewed like code. That is the only way it stays true.
Does a good AGENTS.md replace code review?
No. It improves the odds that the diff is worth reviewing. The review itself is still your job — and that is the next article in this series.
The bottom line: stop writing longer prompts. Write a shorter, more honest operating manual, put the non-negotiables in CI, and measure whether the agent’s first attempt gets closer to mergeable. Context is cheaper than correction.
Next in this series: the senior pre-merge checklist for AI-written code. Start with the overview: AI Coding Workflow 2026, and if you are still choosing tools, AI Code Assistants Compared 2026.
Images: quacktaculous (CC BY), Shixart1985 (CC BY 2.0) via Openverse and Wikimedia Commons.