The 3 Files Every AI Coding Agent Reads

Every serious AI coding setup eventually grows the same three files: CLAUDE.md, AGENTS.md, and .cursor/rules. The names vary by tool, but the job is the same. These files tell agents what world they are operating in before they touch code. They are the repo's harness layer in prose form.

The mistake is treating them as documentation. They are not documentation in the normal sense. They are executable-adjacent context. They shape tool behavior, session boot, rule loading, file edits, command choices, and review expectations. A stale README annoys a human. A stale agent instruction file changes what the agent does.

My opinion is blunt: if your repo has more than one AI coding agent, you should review CLAUDE.md, AGENTS.md, and .cursor/rules as one unit. Do not let each tool grow its own private truth. The files can be separate adapters, but the project policy underneath them should be one harness layer.

File one: AGENTS.md

AGENTS.md is the best candidate for canonical project policy. It is tool-neutral by name, Codex treats it as a project instruction surface, and the convention is broad enough to make sense outside one vendor.

AGENTS.md should answer durable project questions:

- What is this repo?
- Where does source code live?
- Which package manager is canonical?
- How do we build, lint, test, and typecheck?
- What files are generated?
- What branch and PR policy applies?
- Where are deeper docs?
- What security rules are hard?

It should not be a dumping ground. If AGENTS.md becomes a 900-line manual, it stops being a useful boot layer. The right shape is a short map with hard rules and pointers:

# AGENTS.md

## Project facts
This is a TypeScript monorepo for a developer tool.
Apps live in apps/. Shared packages live in packages/.

## Commands
- Install: npm ci
- Build: npm run build
- Test: npm test
- Lint: npm run lint

## Working rules
- Use npm only. package-lock.json is canonical.
- Branch from main and open a PR.
- Do not edit generated output by hand.
- Never print secret values.

## References
- package.json owns scripts.
- .github/workflows/ci.yml owns CI behavior.
- docs/release.md owns release procedure.

That is enough to prevent many bad guesses. It is also short enough that an agent can read it without losing the task.

File two: CLAUDE.md

CLAUDE.md is the Claude Code adapter. In a Claude-only repo, it may contain the project policy directly. In a multi-agent repo, it should usually point to AGENTS.md and then add Claude Code-specific behavior.

The clean version:

# CLAUDE.md

AGENTS.md is the canonical project instruction file.
Read AGENTS.md before making changes.

## Claude Code-specific behavior
- Hooks are configured in .claude/settings.json.
- Workflow-specific instructions live in .claude/skills/.
- If this file and AGENTS.md conflict on project rules, AGENTS.md wins.

This feels almost too small. That is why it works. CLAUDE.md should not become a second source of package-manager policy, branch policy, generated-file policy, and security policy if AGENTS.md already owns those. It should adapt the canonical policy into Claude Code's harness and explain Claude-only mechanics.

Claude Code has real mechanics worth documenting: hooks, skills, slash commands, MCP permissions, and local workflow conventions. Those do not belong in Cursor rules or generic AGENTS.md sections unless every tool needs to know them.

The boundary is simple. Project rule? AGENTS.md. Claude Code loading or workflow rule? CLAUDE.md or .claude/.

File three: .cursor/rules

Cursor rules are not one file. They are a directory of .mdc files with frontmatter and markdown content. They can be always applied, attached by glob, requested by the agent, or invoked manually. That makes them the scoped adapter in the three-file model.

A root Cursor rule should point to canonical policy:

---
description: Canonical project rules
globs:
alwaysApply: true
---

Project rules live in AGENTS.md. Treat AGENTS.md as canonical for package manager,
commands, branch policy, generated files, security rules, and architecture boundaries.

Scoped Cursor rules should add local behavior:

---
description: Frontend implementation rules
globs: "src/**/*.{ts,tsx,css}"
alwaysApply: false
---

- Use existing UI primitives before adding new visual primitives.
- Do not introduce a new color scale without updating tailwind.config.ts.
- Above-the-fold images need width/height or aspect-ratio.

This is where Cursor rules are stronger than one global markdown file. You can attach frontend rules to frontend files, backend rules to backend files, and generated-client rules to generated-client paths. Do not throw that away by putting every rule in one always-applied .mdc file.

Treat them as one harness layer

These files are separate because tools discover different surfaces. They should not be separate sources of truth.

A good harness has one answer to each project-policy question:

Package manager: AGENTS.md, enforced by lockfile and CI.
Build command: AGENTS.md, backed by package.json and CI.
Branch policy: AGENTS.md, backed by branch protection.
Claude Code hooks: CLAUDE.md and .claude/settings.json.
Cursor scoped behavior: .cursor/rules/*.mdc.
Long release procedure: docs/release.md, linked from AGENTS.md.

If a reviewer asks "where do I change the test command for all agents?", the answer should be immediate. If the answer is "maybe CLAUDE.md, maybe a Cursor rule, maybe the README," the harness is already split.

The single-harness view also prevents false confidence. A clean CLAUDE.md does not help if Cursor rules still tell the editor agent to use the wrong package manager. A good Cursor glob does not help if AGENTS.md points to a deleted test script. A perfect AGENTS.md does not help if CI does not enforce the rule it names.

How drift starts

Drift rarely starts with a grand redesign. It starts with one urgent edit.

Someone adds this to CLAUDE.md:

- Small fixes can be pushed directly to main.

AGENTS.md still says:

- Branch from main and open a PR. No direct pushes to main.

Cursor rules say nothing. Now Claude Code has one process, Codex has another, and Cursor has no guidance. The next agent behavior difference will look mysterious until someone reads all three files.

Or someone adds this to .cursor/rules/frontend.mdc:

- Use pnpm dev for local frontend work.

AGENTS.md says npm. package-lock.json says npm. CI uses npm. Cursor now has a local lie that only appears during editor sessions.

Or AGENTS.md says:

- Run npm run test before opening a PR.

But package.json renamed the script to test:unit, and CI never runs it. The rule looks responsible. It is stale.

These are not writing-style problems. They are harness consistency problems.

Lint the unit, not just the files

A linter that checks only one file can catch vague prose and stale paths. That is useful, but incomplete. The real unit is the harness:

AGENTS.md
CLAUDE.md
.cursor/rules/*.mdc
package.json
.github/workflows/*
.husky/*
docs referenced by the instruction files

The linter should ask cross-file questions:

- Do all instruction files agree on package manager?
- Do referenced commands exist in package.json or the shell?
- Do referenced paths exist?
- Do branch and PR rules contradict each other?
- Are generated-file rules backed by CI or review checks?
- Do Cursor globs point at real directories?
- Does CLAUDE.md duplicate project policy instead of pointing to AGENTS.md?

That is how you catch drift before it becomes behavior. You do not wait for Cursor to write code that Claude Code would not write. You inspect the harness as a unit.

A practical review checklist

When any agent instruction file changes, review the set:

- Is this a project rule? It belongs in AGENTS.md first.
- Is this Claude Code-specific? It belongs in CLAUDE.md or .claude/.
- Is this Cursor-specific scoping? It belongs in .cursor/rules.
- Is this long procedure? It belongs in docs/ or a skill, with a pointer.
- Does CI or a hook enforce the rules that claim to be mandatory?
- Did any duplicate rule become inconsistent?

This checklist is more valuable than another paragraph of agent advice. It changes review behavior. It gives maintainers a way to say "this rule is true, but it is in the wrong layer."

The 3-file framework

Use this framework:

AGENTS.md = canonical project policy.
CLAUDE.md = Claude Code adapter.
.cursor/rules = Cursor scoped adapter.

There are exceptions. A Claude-only repo may keep CLAUDE.md canonical. A regulated team may generate all three from a policy source. A monorepo may have nested AGENTS.md files and nested Cursor rules. But the principle remains: one owner per rule at each scope.

The future will add more files, not fewer. Every agent vendor has reasons to expose its own instruction surface. That is fine. The engineering discipline is to treat those surfaces as adapters over one harness policy, not as independent notebooks.

AgentLint is built for that discipline. It checks the files together so CLAUDE.md, AGENTS.md, .cursor/rules, CI, hooks, and repo reality do not quietly drift into five different stories.