Enji GuardAGENTS.md, CLAUDE.md, and Cursor rules, explained
What agent instruction files are, how AGENTS.md, CLAUDE.md, and .cursorrules differ, and why they quietly break the longer your project runs.
If you use coding agents like Cursor, Claude Code, or Codex, you have probably seen files named AGENTS.md, CLAUDE.md, or .cursorrules in repositories. They all do the same thing: tell the agent how to work in your codebase. Here is what they are and how they differ.
What these files are
A coding agent does not remember your project between runs. It works from whatever context the repo and tooling hand it. These instruction files are that context: how to build and test, what conventions to follow, what to avoid, and where the important boundaries are.
- AGENTS.md, a tool-agnostic convention. A Markdown file at the repo root that any agent can read.
- CLAUDE.md, the same idea, aimed at Claude Code.
- .cursorrules / Cursor rules, Cursor’s version, often split across files.
Many repos end up with more than one, which is exactly where trouble starts.
What belongs in them
Good instruction files are short, specific, and verifiable:
- How to install, build, run, and test the project
- Conventions: structure, naming, and patterns to match
- What not to do, files to leave alone, commands to avoid
- Security and review rules: no secrets, no auto-merge, human review required
- Where the main pieces live and how they fit together
Write them like onboarding notes a new engineer could follow on day one. For a deeper checklist, see our AGENTS.md best practices guide.
Why they break
The biggest failure mode is drift. An AGENTS.md written on day one quietly stops matching the code by month two, and the agent keeps trusting rules that are no longer true, confidently and wrongly.
Other traps:
- Bloat. So much context that the agent spends its budget reading rules instead of doing the task.
- Conflict.
AGENTS.mdsays one thing,.cursorrulessays another, and the agent picks unpredictably. - Leaks. Secrets or sensitive paths copied into a rules file that ships in the repo.
Keeping them honest
The hard part is not writing the first version, it is keeping it true. That is a maintenance problem, and it is a good fit for automation: Enji Guard audits your AGENTS.md, CLAUDE.md, and Cursor rules against the real repo on a schedule, flags where they have drifted, and can open a pull request that brings them back in line.
Treat agent rules like code: review them when the project changes, and audit them on a schedule.