Your AI coding agent just generated a perfectly functional React component — in class syntax, with PropTypes, no TypeScript, and none of the conventions your team has spent two years establishing. Again.
The fix isn’t a better prompt. It’s an AGENTS.md file — the cross-tool standard that gives every AI coding agent persistent, project-specific instructions without you having to repeat yourself every session. But here’s what most guides won’t tell you: a badly written AGENTS.md actively hurts agent performance. Recent ETH Zurich research proves it. The difference between a file that helps and one that costs you money comes down to what you leave out.
This AGENTS.md guide for AI coding agents walks you through the research-backed framework, the discovery mechanics most developers get wrong, and three ready-to-copy templates for the most common project types.
What Is AGENTS.md — and How It Differs from README, CLAUDE.md, and .cursorrules
If you’ve used a `.cursorrules` file or a `CLAUDE.md`, you already understand the concept. AGENTS.md is the open, cross-tool successor to those proprietary formats — a plain markdown file that sits in your repository and gives AI coding agents persistent, project-specific instructions.
The key distinction is audience. A README.md is documentation written for humans. AGENTS.md is instructions written for agents. They serve different readers, so they should contain completely different things.
Here’s how AGENTS.md fits among the related files:
- README.md — Human-readable overview, setup instructions, and documentation. Agents may read it, but it’s not optimized for agent consumption.
- CLAUDE.md — Anthropic’s Claude Code-specific format. More powerful for Claude-specific features like memory types and slash commands, but ignored by other tools.
- .cursorrules — Cursor-specific. Deprecated in favor of `.cursor/rules/` in newer Cursor versions; unsupported everywhere else.
- AGENTS.md — Cross-tool open standard, now supported by 20+ platforms including OpenAI Codex, GitHub Copilot, Cursor, Claude Code, Google Gemini CLI, Aider, Zed, Warp, Windsurf, Factory, Devin, and JetBrains Junie.
GitHub Copilot added native AGENTS.md support in August 2025, cementing the format’s cross-ecosystem status. Over 60,000 open-source repositories have adopted it — including OpenAI’s own Codex, which contains 88 AGENTS.md files spread across its monorepo. The format is now stewarded by the Linux Foundation’s Agentic AI Foundation.
The Thoughtworks Technology Radar (2026) placed AGENTS.md in the “Trial” ring, recommending teams experiment with it on projects that can tolerate some risk. That’s a fair framing: it’s proven enough to use seriously, but the tooling is still maturing.
How AI Tools Actually Read Your AGENTS.md (Hierarchy, Precedence, and the 32 KiB Limit)
Understanding the discovery chain helps you avoid the most common failure mode: writing a perfectly good AGENTS.md that your agent silently ignores.
The file discovery walk
When an AI coding agent runs in a directory, it doesn’t look for a single AGENTS.md. It walks from the repository root down to your current working directory, loading and merging every AGENTS.md it finds along the way. Instructions in deeper directories override conflicting instructions from parent directories.
This makes monorepos particularly powerful — one root-level file for global conventions, per-package files for local overrides. OpenAI’s Codex does exactly this with its 88 files.
The override pattern
For urgent, temporary changes — say, a production incident where you need to suspend certain constraints — drop an `AGENTS.override.md` file. It takes highest precedence over everything else in the discovery stack. Use it for incident response or one-off environments where the normal rules don’t apply, and delete it when you’re done.
The 32 KiB hard limit
Here’s the constraint that matters most: Codex enforces a 32 KiB default cap on the combined size of all discovered AGENTS.md files. Exceed it, and further context is truncated — silently, with no warning.
32 KiB sounds generous until you start stacking architectural overviews, code samples, and full style guide prose. Treat the limit as a forcing function for brevity. That turns out to be a feature, not a bug — for reasons the research below makes clear.
Fallback configuration
Some tools let you configure fallback filenames via `config.toml` when no AGENTS.md is present. Check your specific tool’s documentation, but don’t reach for config-level workarounds before getting an actual AGENTS.md in place.
The Six Sections Every Effective AGENTS.md Needs
An analysis of 2,500+ public repositories by the GitHub Blog identified six content areas that consistently appear in top-performing AGENTS.md files. These aren’t arbitrary — they represent the information gaps that cause agents to produce wrong or inconsistent output.
1. Commands
The most critical section. List the exact commands for development, testing, building, and linting. Agents frequently invoke the wrong test runner or use incorrect flags without this.
“`
Commands
- Install: `npm ci`
- Dev server: `npm run dev`
- Test (all): `npm test`
- Test (single file): `npm test — –testPathPattern=
` - Lint: `npm run lint`
- Type check: `npx tsc –noEmit`
“`
2. Testing expectations
Specify your testing philosophy and non-negotiables. Should every new function have a unit test? Do you require integration tests for API routes? Say it explicitly — agents default to whatever behavior their training data reflects, which may not match your standards.
3. Project structure
A brief, accurate map of where things live — not an architectural overview. The goal is to save the agent from guessing where to create or find files, not to explain your design decisions.
4. Code style
The style rules that aren’t enforced by your linter. Naming conventions, preferred patterns, anti-patterns to avoid. If ESLint or Ruff catches it automatically, don’t repeat it here.
5. Git workflow
Commit message format, branch naming conventions, whether to squash commits before merge. Agents increasingly handle git operations directly, and this section prevents messy history.
6. Operational boundaries
The explicit three-tier list most developers skip — and the one that prevents the most painful mistakes.
“`
Boundaries
- NEVER: modify database migration files directly
- NEVER: change public API contracts without discussion
- ASK FIRST: deleting existing files
- ALWAYS: run tests before marking a task complete
“`
Every section closes a specific class of agent errors. Skip one, and expect that class of mistakes to keep happening regardless of how good your model is.
What to Leave Out — Why Less Is More (and the Research That Proves It)
Here’s the counterintuitive finding that most AGENTS.md guides completely ignore: more context isn’t always better. Sometimes it’s actively worse.
ETH Zurich researchers tested context files across 138 real-world Python tasks using four AI models — Claude 3.5 Sonnet, Codex GPT-5.2, GPT-5.1 mini, and Qwen Code. The results were striking:
LLM-generated context files reduced task success rates by ~3% on average compared to no context file at all. Human-written files produced only a marginal ~4% improvement — and both types increased inference costs by 19–20% due to unnecessary additional agent steps. (InfoQ, March 2026)
Read that again. If your AGENTS.md was written by an AI — a common shortcut — it likely makes your agent worse than having no file at all.
The mechanism explains why. When agents receive excessive context, they spend more steps processing and reconciling it, driving up cost without improving output quality. LLM-generated context tends to be verbose, generic, and full of information the agent can already infer by reading the codebase.
What to ruthlessly cut
- Architectural overviews — The agent can read your code. Explaining that you use a service-repository pattern in prose wastes tokens it could spend on your actual task.
- Repo structure trees — Anything generated by running `tree` and pasted in. Agents can explore the filesystem themselves.
- Technology introductions — “React is a UI library built by Meta…” Your agent knows what React is.
- Duplicated linter rules — Anything enforced automatically by ESLint, Prettier, or Ruff doesn’t need to be restated.
- Decision rationale — Why you chose PostgreSQL over MySQL is interesting to humans, irrelevant to agents.
The practical test before adding any line: “Can the agent figure this out by reading the codebase?” If yes, cut it.
Aim for under 300 lines total. The best AGENTS.md files are boring, specific, and short — not comprehensive.
Copy-Paste Templates for Three Common Project Types
These templates follow the six-section framework, include the three-tier boundary system, and stay well within the 32 KiB limit. Adapt them to your actual project — the specific commands and conventions should reflect reality, not a generic placeholder.
Node/TypeScript web app
“`markdown
# AGENTS.md
Commands
- Install: `npm ci`
- Dev: `npm run dev` (port 3000)
- Test: `npm test` | single: `npm test — –testPathPattern=
` - Lint: `npm run lint`
- Type check: `npx tsc –noEmit`
- Build: `npm run build`
Testing
- Unit tests required for all utility functions and hooks
- Integration tests for all routes in `src/api/**`
- Test files co-located with source: `foo.ts` → `foo.test.ts`
- Mock external services; never call real APIs in tests
Project Structure
- `src/components/` — presentational components only, no data fetching
- `src/features/` — feature modules with co-located hooks, types, utils
- `src/api/` — route handlers
- `src/lib/` — shared utilities and third-party wrappers
Code Style
- Named exports only (no default exports)
- `zod` for all runtime validation — no hand-rolled validators
- Return `Result
- React Query for server state; Zustand for client-only state
Git
- Commits: Conventional Commits (`feat:`, `fix:`, `chore:`, `test:`)
- Branches: `feat/
-short-description` - Never commit directly to `main`
Boundaries
- NEVER modify `src/generated/` (auto-generated from OpenAPI spec)
- NEVER alter DB schema directly — use migrations in `db/migrations/`
- ASK before deleting any existing component
- ALWAYS run `npm test && npm run lint` before marking a task complete
“`
Python / ML project
“`markdown
# AGENTS.md
Commands
- Install: `pip install -e “.[dev]”`
- Test: `pytest` | single: `pytest tests/path/test_file.py::test_name`
- Lint: `ruff check . && ruff format –check .`
- Type check: `mypy src/`
- Format: `ruff format .`
Testing
- Tests in `tests/` mirror `src/` directory structure
- Use `pytest` fixtures, not `unittest.TestCase`
- Mock external API calls with `respx` or `pytest-mock`
- Minimum 80% coverage for new modules
Project Structure
- `src/
/` — application code - `notebooks/` — exploration only; no production logic here
- `tests/` — pytest test suite
- `scripts/` — one-off data scripts (not imported by application code)
Code Style
- Type hints required on all public functions
- Pydantic models for structured data — no raw dicts in function signatures
- Use `pathlib.Path`, never `os.path`
- No `*` imports
Git
- Semantic commits; squash feature branches before merge
- Include benchmark results in commit message for performance-sensitive changes
Boundaries
- NEVER modify `src/generated/`
- NEVER add blocking calls inside async functions
- ASK before adding new dependencies to `pyproject.toml`
- ALWAYS update type stubs when modifying public interfaces
“`
Monorepo (multiple packages)
The root file handles global conventions. Each package gets its own AGENTS.md for local overrides.
Root `/AGENTS.md`:
“`markdown
# AGENTS.md (root)
Commands
- Bootstrap: `pnpm install`
- Test all: `pnpm -r test`
- Lint all: `pnpm -r lint`
- Build all: `pnpm -r build`
Monorepo Structure
- `packages/ui/` — shared component library
- `packages/api/` — backend API
- `packages/web/` — Next.js frontend
- `packages/shared/` — shared types and utilities
Cross-Package Rules
- Never import from `packages/web/` into other packages
- Shared types live in `packages/shared/` — never duplicate them
- Breaking changes to `packages/shared/` require updating all consumers
Boundaries
- NEVER publish packages manually — CI handles releases via changesets
- ASK before adding a new top-level package to the monorepo
“`
Package-level `packages/api/AGENTS.md`:
“`markdown
# AGENTS.md (packages/api — overrides root where specified)
Commands
- Dev: `pnpm dev` (port 4000)
- Test: `pnpm test` | single: `pnpm test —
`
Code Style
- All routes validated with `zod` schemas before handler logic runs
- Repository pattern for all DB access — no raw queries in route handlers
Boundaries
- NEVER expose internal database IDs in API responses — use ULIDs
“`
Multi-Tool Strategy — When to Pair AGENTS.md With CLAUDE.md or .cursorrules
If your team uses one AI coding tool, a single AGENTS.md is sufficient. But many teams use Cursor for interactive development and Claude Code or Codex for automated tasks — and they end up maintaining two or three files that gradually drift out of sync.
The canonical-source strategy solves this:
- AGENTS.md becomes the single source of truth for all project conventions.
- CLAUDE.md defers to it: “See AGENTS.md for project conventions. Claude-specific settings below.” Then add only Claude-specific configuration — memory types, allowed tools, slash command definitions.
- .cursorrules or `.cursor/rules/` does the same — reference AGENTS.md conventions, add only Cursor-specific composer rules.
The rule is straightforward: tool-specific files for tool-specific behavior, AGENTS.md for everything that should be consistent across your entire toolchain. Updating project conventions then means editing one file, not three.
Treating AGENTS.md as Living Documentation — An Iteration Workflow
Writing AGENTS.md once and forgetting it is the second most common mistake (after writing too much). A stale file is worse than no file — it instructs agents to do things that no longer reflect reality, and you won’t know why outputs keep drifting.
The iteration workflow that works in practice:
- After every frustrating agent output, ask: “Could a line in AGENTS.md have prevented this?” If yes, add or refine that instruction.
- When your tech stack changes — new test runner, different formatter, switched ORM — update AGENTS.md before the team starts using the new tool.
- On a quarterly review, read through the file and cut anything agents now handle well by default. The goal is always smaller, not bigger.
Think of AGENTS.md as a shrinking file. As AI models improve and your understanding of agent behavior deepens, the file should get shorter — not accumulate cruft. The best version is the one that solves your actual recurring failures without carrying a single extra line.
Conclusion
An effective AGENTS.md guide for your AI coding agents isn’t about documenting everything — it’s about capturing the specific signals that prevent the specific failures you keep seeing. The ETH Zurich research is unambiguous: bloated, AI-generated files hurt performance; human-written, minimal files help. Start with the six core sections, cut anything the agent can infer from the codebase, and iterate based on real failures rather than theoretical completeness.
Pick the template closest to your project type above, customize it for your actual stack, and commit it today. Your agent will know your conventions in the next session — without being told.