AGENTS.md and CLAUDE.md Examples That Actually Work

Every AI coding agent reads a plain Markdown file from your repo before it starts work. Codex, Cursor and most other tools look for AGENTS.md. Claude Code looks for CLAUDE.md. Gemini CLI looks for GEMINI.md. Whatever you put in that file is the agent's standing brief for your project.

Most guides show a generic template. This one shows real files. We run Claude Code and Codex across about 30 repos, each with its own instructions file, so below are trimmed versions of the ones that work, the patterns big open source projects use, and the mistakes that made our own files worse. Everything about tool behaviour was checked against official docs on September 26, 2026.

Which agent reads which file

AGENTS.md started as a joint format from OpenAI Codex, Amp, Google Jules, Cursor and Factory. It is now stewarded by the Agentic AI Foundation under the Linux Foundation, alongside MCP, and the official site says over 60,000 repos use it.

Claude Code finally reads AGENTS.md

For a year, Claude Code was the odd one out. A GitHub issue asking Anthropic to support AGENTS.md, opened in August 2025, became one of the most upvoted requests in the repo, with over 5,000 thumbs up and 400 comments. Teams kept two copies of the same file, or a symlink, or a one-line CLAUDE.md pointing at AGENTS.md.

That changed on September 18, 2026. "We're adding support for AGENTS.md to Claude Code," wrote Thariq Shihipar from Anthropic's Claude Code team in a post on X. From version 2.1.277, if a folder has no CLAUDE.md, Claude checks for AGENTS.md and uses it instead, and you can toggle the behaviour in /config. The post passed 5 million views and 31,000 likes within a week, which says a lot about how many people had been maintaining workarounds. Anthropic's memory docs now describe it, and the AGENTS.md project tracked the news on its own repo.

Two things to know before you delete your CLAUDE.md:

• It is a fallback, not a merge. Claude reads AGENTS.md only when no CLAUDE.md exists. If you have both, it reads CLAUDE.md alone unless you change the setting.
• You need 2.1.277 or later. Run claude --version, and claude update if you are behind. Older versions still need the @AGENTS.md import shown below.

The catch: one file can switch it off

Claude Code's default is "CLAUDE.md or AGENTS.md". If a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists anywhere from your folder up, it ignores AGENTS.md. That catches people: adding a private CLAUDE.local.md quietly switches AGENTS.md off.

You can change the mode in /config under Project instructions, choosing "CLAUDE.md and AGENTS.md" to read both. But the more portable fix, which works on every version, is an import:

@AGENTS.md

That one line is the entire CLAUDE.md in several big repos, including Astral's ruff. Cloudflare's workers-sdk does the same with a two-line version. Your rules live in one place and every agent reads them.

Example 1: a small web app (the one we copy most)

This is a trimmed version of the file from one of our data sites: a Fastify and Nunjucks app with flat JSON data, no database and no front-end framework. It is about 30 lines and it is the best-behaved agent setup we have.

# AGENTS.md

US price database. Fastify + Nunjucks, flat JSON in `data/`,
Tailwind v4, TypeScript via tsx. No database, no client framework.
`README.md` has the map of the repo.

## Commands
- `npm run dev`: foreground dev server on :3000. Never daemonize it.
  Nunjucks caches templates: `touch server.ts` after editing `.njk`.
- `npm run build`: icons + Tailwind CSS (run after class changes).
- `npm test` / `npm run check`: lib tests / placeholder gate.
- `npx tsc --noEmit` must stay clean.

## Read before working
- `docs/DESIGN.md` before touching templates or view models.
- `docs/SCRAPERS.md` before touching any scraper.
- `docs/FINDINGS.md` lists settled dead ends. Do not re-litigate them.

## Hard rules
- Never fabricate data: no placeholder prices or invented addresses.
- Scrapers are polite: robots.txt, ~1 req/sec/host, backoff.
- URLs all lowercase.
- `data/chains.json` is shared state: re-read right before writing.
- Do not commit unless asked. Commit messages are one line.

Why it works:

• The first paragraph says what the project is not. "No database, no client framework" stops the agent from reaching for Prisma or React on day one.
• Commands include the gotcha. The template-cache note saved hours of "my change is not showing" loops.
• Long docs are linked, not pasted. The agent reads DESIGN.md only when it touches templates, which keeps every other session cheap.
• "Do not re-litigate" is gold. Without a findings file, agents cheerfully retry the same dead end you ruled out last week.
• Every rule is checkable. "Never fabricate data" is testable. "Write good code" is not.

Example 2: a content site with a CMS

Our largest file is the CLAUDE.md for this website. It grew to over 30 KB, which is too long, and we are cutting it down. The parts that earn their place are the ones that describe traps the agent could never discover by reading code:

## Content sync: the CMS always wins
The CMS is the source of truth. `pnpm sync` overwrites local files
and deletes files that no longer exist in the CMS. So:
- Any local edit to `src/content/**` must be pushed with
  `pnpm push <slug>` or it is silently lost on the next build.
- Cosmetic edits push with `--no-bump` so the date does not change.

## Git and deploy
- Commit only. Never `git push` unless asked in the current request.
  Every push to main triggers a production build.
- Batch related commits so production builds once.

## Content rules
- Article bodies use our registered Markdoc tags, never raw HTML.
- No em dashes in anything a reader sees.

The "CMS always wins" section matters because nothing in the code warns you: an agent that edits article files locally has no way of knowing the next build will overwrite them. One paragraph closes that trap for every session. That is the test for every line: would removing this cause the agent to make a mistake? If not, cut it.

Example 3: short root file, details nearby

Big monorepos keep the root file tiny and point elsewhere. React's CLAUDE.md is a few hundred bytes: a map of the monorepo, a pointer to the compiler's own instructions file, and a note on current work. Microsoft's vscode repo has an AGENTS.md that just points to its Copilot instructions file.

The pattern for your repo:

# AGENTS.md

Monorepo. pnpm workspaces. Node 22.

- `apps/web`: Next.js site. See apps/web/AGENTS.md
- `apps/api`: Hono API on Cloudflare Workers. See apps/api/AGENTS.md
- `packages/ui`: shared components. Never import from apps/.

## Commands
- `pnpm i` then `pnpm dev --filter web`
- `pnpm test --filter <pkg>` (never run the full suite locally)

Codex and most AGENTS.md readers load the nested file when the agent works in that folder, and the closest file wins. Claude Code does the same for nested CLAUDE.md files.

Example 4: the big, rule-heavy file

At the other end, OpenAI's own codex repo has an AGENTS.md of about 22 KB, organised by crate, with sections on review rules, snapshot tests and API conventions, and a guideline to keep changes around 800 lines or less. Next.js's AGENTS.md is similar in size and centred on build, test and CI commands.

These work because the teams are large and the rules are specific. But note that 22 KB is already most of Codex's 32 KiB default budget. For a normal project, a file this long means rules near the bottom get less attention.

Personal rules: the file in your home folder

Rules that apply to you in every project go in ~/.claude/CLAUDE.md (Claude Code) or ~/.codex/AGENTS.md (Codex). Keep these to preferences, not project facts:

- Use pnpm, never npm, in JavaScript projects.
- Commit messages: one line, no trailers.
- Ask before adding any new dependency.
- Prefer the platform feature (native <dialog>, CSS) over a library.

What to put in (and what to leave out)

A few more rules from Anthropic's and OpenAI's docs that match our experience:

• Aim for under 200 lines. Anthropic's guidance is that longer files are followed less reliably.
• Do not shout. Use "IMPORTANT" rarely. If a rule must always happen, make it a hook or a CI check instead of a louder sentence.
• Remove contradictions. Two rules that disagree get followed randomly.
• Commit the file. It is team config, so review it like code.
• Check what loaded. /context in Claude Code shows which files were read. In Codex, ask it to summarise its current instructions.

Start your own in five minutes

1. Run /init in Claude Code or opencode. It reads the repo and drafts a file.
2. Delete everything the agent could have worked out from the code.
3. Add your commands, with the gotchas.
4. Add three to five hard rules, each with a one-line reason.
5. If your team uses more than one agent, name it AGENTS.md and make CLAUDE.md say @AGENTS.md.

• Under 200 lines
• Every command in it actually runs
• No secrets or internal-only URLs
• Each rule passes the "would removing this cause a mistake?" test
• Long reference docs are linked, not pasted

Instruction files pair well with skills, which hold longer, task-specific instructions that load only when needed. See our best Claude Code skills and plugins, our comparison of Claude Code vs Codex vs Gemini CLI vs opencode, and how to run Claude Code for free.