CLAUDE.md, AGENTS.md, and .cursorrules: Managing Agent Instructions

Ask three different AI coding tools to follow your team's conventions and you'll end up maintaining three different files: CLAUDE.md for Claude Code, AGENTS.md for a growing list of agents, and .cursorrules for Cursor. This is a tour of what each of these instruction files does, where they overlap, and how to stop them from sprawling across every repo and teammate you have.

What CLAUDE.md, AGENTS.md, and .cursorrules actually do

All three solve the same problem. An agent starts each session knowing your language and framework but nothing about your project — the build command, the folder layout, the rule everyone forgets. An instruction file is ambient context the tool loads automatically so you don't have to repeat yourself every prompt.

CLAUDE.md

CLAUDE.md is read by Claude Code. Drop one at the root of a repo and its contents are pulled into every session as standing context. You can also place a CLAUDE.md in a subdirectory so it applies only when work happens in that part of the tree, and keep a personal one at ~/.claude/CLAUDE.md for machine-wide preferences that never get committed. It's plain Markdown, so it's good for the things you'd otherwise say out loud: "run npm test before claiming done," "the API layer lives in src/lib," "never edit generated files."

AGENTS.md

AGENTS.md is the same idea but deliberately vendor-neutral — an open convention rather than one tool's format. It's a Markdown file at the repo root describing how any agent should behave in the project, and a growing number of coding agents (OpenAI's Codex among the tools that adopted it) look for it. The pitch is simple: write the instructions once and let many tools read them, instead of maintaining a separate file per vendor. Like CLAUDE.md, an AGENTS.md deeper in a monorepo can scope rules to a single package.

.cursorrules (and .cursor/rules)

.cursorrules is Cursor's original format: a single file at the repo root with your project rules. Cursor has since moved toward a .cursor/rules/ directory of .mdc files ("Project Rules"), where each rule carries frontmatter that decides when it applies — always on, auto-attached when you touch files matching a glob, pulled in on request, or invoked manually. The newer format is more precise; the old single file still works. Other tools have their own flavors too — GEMINI.md, .windsurfrules — which is exactly where the sprawl begins.

Where they overlap, and the move toward AGENTS.md

Read those descriptions back and the overlap is obvious: they're all "a Markdown file the agent reads at startup." The content is nearly interchangeable — build commands, conventions, architectural notes, a list of don'ts. The only real differences are the filename and, for Cursor's .mdc rules, the conditional loading.

That redundancy is why AGENTS.md has gained traction as a shared standard. Rather than keep CLAUDE.md, AGENTS.md, and .cursorrules in sync by hand, many teams now write the canonical instructions once in AGENTS.md and make the others thin pointers to it — a one-line CLAUDE.md that says "see AGENTS.md," or a symlink. It doesn't unify everything, but it shrinks three sources of truth back toward one.

Best practices for writing instruction files

Whatever the filename, the same habits make these files pay off:

• Keep them short. Every line is spent from the context budget on every turn. A tight file beats an exhaustive one the agent half-ignores.
• Be imperative and specific. "Run pnpm test:unit before finishing" beats "make sure tests pass." Give exact commands and paths.
• Document the non-obvious. Skip what the model already knows about your framework. Capture the gotchas: the flaky service, the directory that looks unused but isn't, the thing nobody should touch.
• Prefer examples over prose. A three-line code block showing your preferred pattern lands harder than a paragraph describing it.
• Layer by scope. Repo-wide truths at the root; package-specific rules in a nested file.
• Review it like code. These files change behavior, so put them through the same PR review as anything else.

A useful root file often looks like this:

## Commands
- Build: `npm run build`
- Test:  `npm test` (run before every commit)

## Layout
- API + data access: `src/lib`
- Never edit: `src/generated/**`

## Conventions
- TypeScript strict; no `any`
- Conventional Commits for messages

The scaling problem: sprawl and drift

One tidy CLAUDE.md is easy. The trouble starts when you have twenty repos and five teammates.

The same rules get copy-pasted into every repo, and then each copy drifts — a fix lands in one project and never reaches the other nineteen. A teammate refines their local .cursorrules, but nobody else ever sees it. Your CLAUDE.md, AGENTS.md, and .cursorrules slowly start contradicting each other. And because these files are edited inline, there's rarely any record of why a rule was added — the incident that prompted "never run migrations in parallel" is lost, so someone eventually deletes it and relearns the lesson the hard way.

In other words: instruction files are great at describing one repo to one agent, and poor at sharing knowledge across repos and people. That's not a failure of the format — it's just outside what a per-repo file is meant to do.

A shared, versioned skill layer to complement them

This is where a second layer helps. Instruction files are ambient and always-on; Agent Skills are the opposite — named, reusable capabilities an agent pulls in only when a task calls for them. "How we review a PR," "our house SQL style," "how to cut a release" don't belong in every repo's CLAUDE.md; they belong in one place every agent and teammate can reach.

That's the gap Roget fills. It keeps skills as versioned Markdown in a single shared vault, and agents read and write them directly over MCP — so a rule lives once, carries its history, and updates everywhere at once. Your AGENTS.md can then shrink to the truly repo-specific bits and point at the shared library for the rest.

Instruction files aren't going away — keep them lean and per-repo. For everything that should be shared, versioned, and read by every agent, browse the public skill directory to see what that layer looks like.