CLAUDE.md vs AGENTS.md: rules files for coding agents

Every coding agent reads a file of standing instructions when it starts: how to run the tests, which package manager the repo uses, what it must never touch. The trouble is that every tool picked its own filename. Claude Code reads CLAUDE.md. Codex reads AGENTS.md. Cursor has .cursor/rules, Windsurf has .windsurf/rules, GitHub Copilot has .github/copilot-instructions.md. If you use more than one agent, you either maintain several copies or one of them works blind.

This guide explains what each file is for, how to keep a single source of truth, and what actually belongs in a rules file versus somewhere else.

The short answer

• Use AGENTS.md as the one file with your instructions. It's a plain-Markdown convention that several agents read directly, and it isn't tied to one vendor.
• Keep CLAUDE.md as a one-line pointer to it, so Claude Code reads the same content.
• Point the other tools' rules files at it the same way, or keep them to tool-specific settings only.
• Put only things that stay true for weeks in it. Plans, progress and todo lists go elsewhere.

Which agent reads which file

Tools change their conventions often, so treat this as a starting point and check each tool's docs for the current behaviour.

The pattern is clear: one Markdown file of instructions, read at the start of a session, in a location the tool decided. The content is what matters, and the content is almost always the same across tools.

One source of truth

The setup that holds up over time:

1. Write AGENTS.md

# Working in this repo

## Commands
- Install: pnpm install
- Dev server: pnpm dev (http://localhost:3000)
- Tests: pnpm test (unit), pnpm e2e (needs the dev server running)
- Lint and types: pnpm check

## Conventions
- TypeScript strict; no `any` in new code
- Server code lives in src/server, UI in src/components
- Database changes are new files in migrations/, never edits to old ones

## Never
- Commit .env files or print secret values
- Change CI config or migrations unless asked

2. Point CLAUDE.md at it

Claude Code understands imports with @, so CLAUDE.md can be a single line:

@AGENTS.md

Add Claude-specific notes under it if you need them. The repo that runs klio.dev does exactly this: its CLAUDE.md is @AGENTS.md and nothing else.

3. Do the same for the others

For tools that can't import, keep their file short and refer to AGENTS.md ("Follow the instructions in AGENTS.md at the repo root"), or generate their files from AGENTS.md in a small script you run when it changes. What you want to avoid is three hand-edited copies drifting apart.

What belongs in a rules file

A good rules file is short, specific and rarely edited. It answers the questions a capable new teammate would ask in their first hour.

Include:

• Commands. Install, run, test, lint, build, deploy. Exact commands, not descriptions.
• Layout. Where server code, UI, tests and migrations live, if it isn't obvious.
• Conventions that a linter can't enforce. Naming, error handling style, "use the existing api() helper, don't add fetch wrappers".
• Hard limits. Files and actions that need a human: migrations, CI, infrastructure, secrets.
• How to verify work. "Run pnpm test and the e2e suite before saying something is done."

Leave out:

• Progress and todo lists. They change hourly and go stale in days. Every session pays to read them.
• Long explanations of the architecture. Link to a doc instead; the agent can read it when it needs to.
• Secrets or credentials. Rules files are committed and read by every tool you connect.
• Rules nobody follows. If the codebase contradicts the rule, the agent will follow the codebase.

Keeping agents on a plan

The rules file tells an agent how to work. It doesn't tell it what to work on next, or what's already done. People often try to make it do both and end up with a 500-line file whose bottom half is a stale backlog.

Plans and progress need somewhere that changes as work happens and that every agent reads at the start of a session. That can be a progress file, issues in a tracker, or a board the agents read over MCP. Then the rules file only needs a few lines pointing at it.

This is the section Klio adds to a repo's rules file (the same text in CLAUDE.md, AGENTS.md or the tool's own file):

## Klio (project board)
This repo is tracked in Klio; the Klio MCP server is connected.
- All coding work here goes through Klio, follow-ups mid-session included.
  Before writing code for anything new, add it: create_issue (or
  create_feature for a bigger piece).
- When I mention an ID like KEY-F4 or KEY-33, load it with get_feature /
  get_issue first. If I just say "continue", call get_next_work.
- start_issue before you start, check_criterion as each acceptance
  criterion passes, complete_issue with a short summary when done.
- Record new dependencies and providers with sync_stack / add_service.
  Never print or commit secret values.

Why in the rules file and not just in the MCP server's own instructions? An MCP server's instructions are read once, when the agent connects. The rules file is read at the start of every session, so follow-up requests ("now add an admin page") land on the board instead of the agent's private todo list.

Monorepos and subfolders

In a monorepo, a single root file gets long fast. Most agents read rules files closer to the code they're editing, so you can split by package:

AGENTS.md               # repo-wide: commands, conventions, limits
apps/web/AGENTS.md      # Next.js app specifics
apps/api/AGENTS.md      # API service specifics
packages/db/AGENTS.md   # migrations and schema rules

Keep the root file about what's shared and let each package file be short. Claude Code reads CLAUDE.md files in subfolders the same way, so a one-line @AGENTS.md next to each works there too.

Personal versus project rules

Some preferences are yours, not the project's: "explain changes briefly", "never run git push". Most tools have a personal rules file outside the repo (~/.claude/CLAUDE.md for Claude Code, user rules in Cursor's settings). Put personal preferences there so they follow you across projects and don't end up in a shared repo.

A complete example

Here's a full AGENTS.md for a typical Next.js app on Cloudflare, about as long as a rules file should get:

# Working in this repo

Next.js 16 app router, deployed to Cloudflare Workers with OpenNext.
Database: Cloudflare D1 through Drizzle.

## Commands
- pnpm dev: local server on :3000 with local D1
- pnpm test: unit tests (vitest)
- pnpm e2e: end-to-end tests; needs pnpm dev running
- pnpm db:migrate:local: apply migrations to the local database

## Layout
- src/app: routes and pages
- src/server: business logic; routes stay thin
- src/components: UI; reuse what's in components/ui before adding new
- migrations/: SQL migrations, numbered; never edit an old one

## Conventions
- Errors to users say what went wrong and what to do next
- Dates are stored as epoch milliseconds
- New env vars go in src/lib/env.ts with a comment

## Before saying something is done
- pnpm test and pnpm e2e pass
- No new TypeScript errors (pnpm check)

## Never
- Print, log or commit secret values
- Run migrations against production
- Change CI or deploy config unless asked

Everything in it is either a command, a location, a rule or a limit. None of it changes week to week, and each line saves the agent a guess.

Mistakes we see often

• Copy-pasted rules from a template. A rule about a framework you don't use teaches the agent to ignore the file. Every line should be true for this repo.
• Contradicting the code. If the file says "use the repository pattern" and the code doesn't, the agent follows the code and you get a mix. Fix one or the other.
• Rules as essays. Agents follow short imperatives better than paragraphs of reasoning. Put the reasoning in a doc and link it if it matters.
• Forgetting the "how to verify" section. Without it, agents decide for themselves what proves the work, and that's usually "it compiles".
• Never pruning. A rules file that only grows ends up full of advice for problems you solved months ago.

Rules files and security

Rules files are read by every agent you connect and usually committed to the repository, so treat them as public. Never put API keys, tokens or connection strings in them, even "temporarily". If an agent needs to know about a secret, tell it the variable's name and where it's set ("STRIPESECRETKEY is in .env.local and in the production dashboard"), never the value. It's also worth a line telling agents not to print or log secret values, since tool output often ends up in transcripts and logs you don't control.

Checklist

1. One AGENTS.md at the root with commands, conventions, limits and how to verify work.
2. CLAUDE.md that imports it (@AGENTS.md), and the other tools pointing at it.
3. No progress, plans or secrets in any rules file.
4. A short section pointing agents at wherever plans and progress live.
5. Package-level files in a monorepo, personal preferences in your user-level file.
6. Read it once a month and delete what's no longer true.