AGENTS.md: The File Nobody Writes Well (And How It Destroys Your Agent’s Output)
A practical guide to the most powerful and most neglected file in your AI coding setup.
You brief Codex. It writes the feature. You review the PR.
Wrong test command. Wrong import style. Wrong folder.
You fix it. You move on.
Next day, same agent, same mistakes.
The problem isn’t the model. The problem isn’t the prompt. It’s the file you never wrote or wrote once and forgot about.
AGENTS.md is how you stop re-explaining your engineering standards to a machine that doesn’t owe you memory.
In my last post, I covered Skills - reusable procedure packages your agent loads on demand. But Skills don’t work in a vacuum. They need a foundation: the default rules, repo conventions, and working agreements that apply before any Skill triggers.
That foundation is AGENTS.md. If Skills are your playbooks, AGENTS.md is your team culture doc.
What you’ll get in this article:
A precise understanding of what AGENTS.md is, how it works, and why most people get it wrong.
The “instruction budget” concept that changes how you think about agent configuration.
How the cascade mechanism works (and the silent failure mode that nobody talks about).
Exactly what goes in and what stays out.
How to unify AGENTS.md and CLAUDE.md without maintaining two files.
A production checklist you can use today.
1) What AGENTS.md Actually Is (And What It’s Not)
AGENTS.md is a simple idea with outsized impact: a dedicated Markdown file that tells AI coding agents how to work in your project. Think of it as a README, but for machines instead of humans.
The format emerged from a collaboration between OpenAI (Codex), Google (Jules), Cursor, Amp, and Factory. It’s now stewarded by the Agentic AI Foundation under the Linux Foundation, and has been adopted by over 40,000 open-source repositories. It’s just standard Markdown. No special syntax, no YAML front matter required, no proprietary format. Any headings, any structure. The agent simply parses what you provide.
But here’s where most people get confused.
AGENTS.md is not a long prompt. It doesn’t get injected wholesale into every API call. It’s loaded once at the start of a session and becomes part of the agent’s working context.
AGENTS.md is not your README.md. README is the front door for human developers - project purpose, setup instructions, contribution guidelines. AGENTS.md is the front door for your agent - build commands, coding conventions, architectural constraints, and project-specific rules that the agent can’t infer from your code alone.
AGENTS.md is not a linter replacement. If ESLint can enforce a rule, don’t waste your agent’s attention on it. Automate the check; free up the file for things only instructions can solve.
AGENTS.md is not the file you auto-generated with /init and never touched again. That’s actually the single most common failure mode, and I’ll explain why in the next section.
The mental model you need is this:
README.md → for humans. AGENTS.md → for coding agents (Codex, Cursor, Amp, Jules, and others). CLAUDE.md → Anthropic’s proprietary equivalent for Claude Code (same concept, different filename).
And the relationship with Skills and Hooks:
AGENTS.md = policy (your default working agreements). Skills = procedures (repeatable workflows loaded on demand). Hooks = automation (deterministic scripts that run on specific events, no exceptions).
This division matters. Without it, every file becomes a dumping ground for everything, and the agent starts ignoring all of it.
One more thing: right now, the ecosystem is fragmented. Codex reads AGENTS.md. Claude Code reads CLAUDE.md. Cursor has .cursor/rules/. Copilot has .github/copilot-instructions.md. It’s a mess. The good news is that AGENTS.md is converging as the standard. The practical news is that you can solve this today with symlinks. I’ll show you how in section 5.
2) The Instruction Budget - Why Less Is More
This is the most counterintuitive part of the entire article, and arguably the most important.
Your agent has a finite capacity for following instructions. Research from HumanLayer found that frontier thinking LLMs can follow roughly 150 to 200 instructions with reasonable consistency. Smaller models handle fewer. Non-thinking models handle fewer still.
Here’s the part that matters: Claude Code’s own system prompt already contains approximately 50 instructions before you add a single line to CLAUDE.md. Codex has its own baseline too.
Your actual instruction budget is somewhere around 100 to 150 usable slots. Every line you add costs something.
And the failure mode isn’t what you’d expect. When you exceed the budget, the agent doesn’t ignore the instructions at the bottom of the file. It doesn’t forget the newest rules while remembering the oldest. The degradation is uniform. The agent starts following all instructions slightly worse - skipping rules randomly, mixing conventions, hallucinating patterns that feel plausible but aren’t yours.
This is why auto-generated AGENTS.md files are dangerous. Tools like /init in Claude Code or Codex’s scaffolding produce files that prioritize comprehensiveness over restraint. They cover every possible scenario “just in case.” And in doing so, they burn through your instruction budget on generic guidance the agent already knows, leaving no room for the project-specific rules that actually matter.
The rules for managing your budget:
If the agent already does something correctly without the instruction, delete it. You’re wasting a slot on something that’s already working.
If a rule can be enforced by a linter, formatter, or hook, move it there. Hooks are deterministic - they run every time, no exceptions, no budget cost. AGENTS.md is advisory. Use the right tool.
If an instruction is specific to a subdirectory (say, your payments module or your API layer), move it to a nested AGENTS.md in that directory. It only loads when the agent is working there.
If a rule describes a complex, repeatable workflow, convert it to a Skill. Skills load on demand, keeping your base context lean.
The pattern that scales is progressive disclosure. Don’t put everything in one file. Build a hierarchy the agent can navigate:
AGENTS.md ← global policy (short)
├── docs/TYPESCRIPT.md ← TypeScript conventions
├── docs/TESTING.md ← testing strategy
├── packages/api/AGENTS.md ← backend-specific rules
└── packages/web/AGENTS.md ← frontend-specific rules
In your root AGENTS.md, just reference the deeper docs:
For TypeScript conventions, see docs/TYPESCRIPT.md
For testing patterns, see docs/TESTING.md
Agents navigate documentation hierarchies fast. Trust them to find what they need when they need it. Don’t front-load everything into a single file and hope for the best.
Your AGENTS.md should read like a senior engineer’s onboarding checklist - not like the company handbook nobody reads.
3) The Cascade - How Agents Actually Read Your Files
Understanding the cascade is the difference between AGENTS.md files that work and AGENTS.md files that silently fail. Most developers skip this, and it shows.
Codex builds an instruction chain when it starts a session. The discovery follows a strict order:
First, it reads your global file. It checks ~/.codex/AGENTS.override.md, and if that doesn’t exist, it reads ~/.codex/AGENTS.md. Only the first non-empty file at this level is used.
Then it walks down from the project root to your current working directory. In each directory along the path, it checks for AGENTS.override.md, then AGENTS.md, then any fallback filenames you’ve configured.
It concatenates all discovered files with blank lines between them. Files closer to your working directory appear later in the combined prompt, which means they effectively have higher priority - the agent reads them last, so they override earlier guidance.
The critical constraint: Codex caps the combined size at 32 KiB by default (controlled by project_doc_max_bytes in config.toml). When you exceed this limit, Codex truncates silently. No error. No warning. Your instructions just disappear. If your agent suddenly starts ignoring rules it used to follow, check this first.
You can raise the limit or split instructions across nested directories to stay under it:
# ~/.codex/config.toml
project_doc_max_bytes = 65536
Claude Code works similarly but with key differences. It reads ~/.claude/CLAUDE.md globally, then CLAUDE.md at the project root, then any CLAUDE.md files in subdirectories. The important distinction: Claude Code merges subdirectory files upward (layering them on top of parent files), while Codex concatenates from root downward. The practical difference is subtle but can matter if you have conflicting rules at different levels.
Claude Code also supports imports using @path/to/file.md syntax, which lets you modularize without relying on the agent to discover separate files:
# CLAUDE.md
See @README.md for project overview
See @docs/conventions.md for coding standards
In both systems, explicit user prompts always override any file. Your real-time instructions take precedence over everything.
AGENTS.override.md is a Codex-specific feature worth knowing about. When this file exists in a directory, it completely replaces the normal AGENTS.md for that scope. The use case is temporary overrides - a release freeze, an incident mode, a hardening window where you want stricter rules. Create the override, do the work, delete the file, and everything goes back to normal. It’s a simple, elegant pattern for temporary policy changes.
4) What Goes In (And What Stays Out)
This is the most practical section. I’ll give you the exact categories that belong in your AGENTS.md, the things that should never be there, and the golden rule for deciding when to add a new instruction.
What must be in the file:
Executable commands. Build, test, lint, format. The agent needs to know how to verify its own work. Don’t make it guess.
## Commands
- Build: `pnpm build`
- Test single file: `pnpm vitest run -t "<test name>"`
- Lint: `pnpm lint --filter <package>`
- Format: `pnpm prettier --write .`
Stack and architecture. Keep it to 5-10 lines. Just enough for the agent to navigate your repo without exploring every folder.
## Architecture
- Frontend: SwiftUI (iOS 17+)
- State: Observation framework
- Data: SwiftData + CloudKit sync
- Payments: RevenueCat
Conventions the agent can’t infer from your code. This is the most valuable category. These are the rules that exist in your team’s heads but not in any config file.
## Conventions
- Never use class components. Functional + hooks only.
- Error handling: throw typed errors from /utils/errors.ts
- Dates: always Day.js, never native Date
- All new API endpoints need a corresponding integration test
Concrete examples with file paths. This is the single most powerful thing you can put in the file. Instead of describing patterns abstractly, point to real files that demonstrate what you want. Also call out legacy files the agent should avoid copying.
## Good examples to follow
- Forms: copy `app/components/DashForm.tsx`
- Charts: copy `app/components/Charts/Bar.tsx`
- API calls: use client from `app/api/client.ts`
## Legacy code - do NOT copy these patterns
- `Admin.tsx` - class-based, deprecated
- `old-api/` - direct fetch, no typed client
Examples beat abstractions every time. The agent will mirror the patterns in the files you point it to. If you point it at good code, you get good code back. If your repo has legacy code sitting next to modern code and you don’t specify the difference, the agent will happily copy the worst patterns in your codebase.
What should NOT be in the file:
Rules your linter already enforces. Move those to hooks or CI. The file is for judgment calls, not mechanical checks.
Extensive domain documentation. Reference it from a separate file. Don’t burn your instruction budget on paragraphs of context the agent only needs occasionally.
File paths that change frequently. Describe capabilities instead: “authentication logic is in the auth module” rather than “authentication lives in src/services/auth/handlers.ts.” Paths go stale. Capabilities are stable.
Generic instructions that apply to any project. The agent already knows how to write clean code, use meaningful names, and add comments for complex logic. Don’t waste slots on universal knowledge.
Secrets, API keys, or tokens. Obviously. But I’ve seen it.
The golden rule:
Add a rule to your AGENTS.md the second time you see the same mistake. Not the first.
The first time might be a fluke - a context issue, a weird edge case. The second time is a pattern. That pattern deserves an instruction.
And one more anti-pattern to avoid: never use an auto-generated AGENTS.md as your final version. /init and similar commands produce a decent starting point, but they optimize for coverage, not for precision. Always review, prune, and customize by hand. The file that works best is the one shaped by real friction - not by a template’s guess at what might matter.
5) Unification - One File to Rule Them All
If you use both Codex and Claude Code (and many of us do), you’ve probably wondered: do I maintain two files?
No. Here’s how to solve it.
The core problem is that Claude Code looks for CLAUDE.md while Codex and most other tools look for AGENTS.md. There’s an open issue (#6235) on Claude Code’s GitHub repo asking for native AGENTS.md support, but as of today, the filenames are still different.
Project-level solution - the simplest approach:
Make AGENTS.md your source of truth. Then point CLAUDE.md to it:
# Option A: redirect
echo 'See @AGENTS.md' > CLAUDE.md
# Option B: symlink
ln -s AGENTS.md CLAUDE.md
Add CLAUDE.md to your .gitignore so the symlink doesn’t get committed. Only AGENTS.md goes into version control.
User-level solution - for your global preferences:
If you have personal coding preferences that apply across all repos, consolidate them in one place:
# One canonical source
mkdir -p ~/.agents
# Codex
mkdir -p ~/.codex
ln -sfn ~/.agents/AGENTS.md ~/.codex/AGENTS.md
# Claude Code
mkdir -p ~/.claude
ln -sfn ~/.agents/AGENTS.md ~/.claude/CLAUDE.md
Edit ~/.agents/AGENTS.md once, and every tool picks up the changes.
Important nuances when unifying:
Keep the content tool-agnostic. Never write “Hey Claude” or “Hey Codex” in the file. Write instructions that any agent can follow.
Be careful with Claude-specific features. Claude Code supports @path/to/import.md syntax for imports. Codex doesn’t. If you use imports, put them in CLAUDE.md as a thin wrapper that imports from AGENTS.md, and keep AGENTS.md self-contained.
Remember the merge vs. concatenation difference. Claude Code merges subdirectory files upward; Codex concatenates from root down. In practice, this rarely causes issues if your nested files are additive (adding rules) rather than contradictory (overriding rules). But if you have conflicting guidance at different directory levels, test with both tools to confirm behavior.
6) Treat It Like Code (Because It Is)
Your AGENTS.md directly determines the quality of every piece of code your agent produces. It deserves the same rigor as any other configuration file in your repo.
Version it in git. Commit it. Review changes in PRs. A bad edit to AGENTS.md can silently degrade the output of every agent on your team. Treat changes to this file with the same scrutiny you’d give a change to your CI pipeline.
Audit it regularly. Every two weeks, check: is the agent following any rule that a linter now enforces? Remove it. Every month, check: are there file paths that changed? Update them or rewrite them as capability descriptions. After every bug caused by agent output, check: is there a missing rule? Add it.
There’s a useful validation test you can run anytime. Ask your agent: “What custom instructions or context files are you currently using for this project?” Compare its answer to what you expect. The gap between those two answers is where your problems live.
Understand where AGENTS.md fits in the full stack. This is the model I use:
Layer File Nature When loaded Policy AGENTS.md / CLAUDE.md Always present Session start Procedure SKILL.md On-demand When the agent detects relevance Automation Hooks (settings.json) Deterministic On specific events (pre-edit, post-edit) Temporary override AGENTS.override.md Temporary When it exists, replaces AGENTS.md
The decision framework is simple:
If it’s a working agreement that applies to everything → AGENTS.md. If it’s a repeatable workflow with specific steps → Skill. If it must happen every single time with zero exceptions → Hook. If it’s temporary (release freeze, incident mode, audit window) → AGENTS.override.md.
When you use all four layers deliberately, each one stays lean. Your AGENTS.md doesn’t need to carry the weight of procedures, automation, and temporary rules all at once. That’s how you stay under the instruction budget while giving your agent everything it needs.
7) The Production Checklist
Use this as your ship gate.
Content
Includes commands for build, test, lint, and format
Describes stack and architecture in 10 lines or fewer
Lists conventions the agent can’t infer from code alone
Points to real example files worth copying
Explicitly flags legacy code to avoid
Instruction budget
Contains fewer than 100 individual instructions
Doesn’t duplicate rules already enforced by linters or formatters
Uses progressive disclosure (references to external docs, not everything inline)
Was NOT auto-generated without manual review and pruning
Maintenance
Checked into git and reviewed in PRs
Doesn’t contain hardcoded file paths that change frequently
Has an owner accountable for updates
Contains no secrets or API keys
Unification
Compatible with all agents the team uses
Uses symlinks for tools expecting different filenames
Content is tool-agnostic (no tool-specific language)
Close
AGENTS.md is the most powerful file in your AI coding setup, and it’s probably the one you’ve spent the least time on.
It doesn’t ship features. It doesn’t show up in your App Store listing. It doesn’t get likes on Twitter.
But every bad PR your agent opens, every wrong test command, every import from the legacy folder, every convention it ignores for the third time - that’s your AGENTS.md failing silently.
Write it once. Write it well. Prune it regularly. And stop burning your instruction budget on things the agent already knows.
If you haven’t read it yet, check out my previous post on Skills, Not Prompts - because AGENTS.md is the policy layer that makes Skills actually work.
Your next step: Pick one rule you keep repeating to your agent. Add it to your AGENTS.md today.