CLAUDE.md vs AGENTS.md: Which should you use?
The Quick Verdict
Use CLAUDE.md if you are using Anthropic's terminal-based Claude Code client, as it specifically reads the file at startup and parses its build and test commands to run validations. Use AGENTS.md if you are configuring editor-integrated agents (like Cursor, Windsurf, or custom workspace integrations). Since they target different runtime contexts, you can safely use both in the same repository.
Comparison Table
Understanding where these rules apply is the key to preventing rule clashes:
| Feature | CLAUDE.md | AGENTS.md |
|---|---|---|
| Primary Target | Claude Code (Terminal CLI) | Editor Extensions (Cursor, Windsurf, etc.) |
| Command Parsing | Yes (explicitly parses build, test, and dev scripts) | No (primarily reads layout rules and guidelines) |
| Nesting Support | Yes (hierarchical subdirectory rules) | Varies by editor/tooling integration |
| Format | Standard Markdown (with optional frontmatter) | Markdown (sometimes styled as custom rulesets) |
Key Structural Differences
Workflow Validation
Because Claude Code has execution rights to run local terminal commands, its configuration file requires build, test, and quality check parameters. This allows the CLI client to verify its modifications by executing your test suite locally before marking a task as done.
Conversely, editor extensions (which use AGENTS.md or .cursorrules) focus primarily on formatting guidelines and project guidelines. They assist the developer as they write code inside an editor window, leaving test execution to the user.
Can I use both?
Yes. You can use both configurations in harmony within the same workspace:
- Create a
CLAUDE.mdcontaining terminal commands (build, test, check) and core folder maps. - Create an
AGENTS.mdor.cursorrulesfile containing editor-specific templates, code snippets, and fine-grained UI guidelines.
To prevent rule duplication and maintain a single source of truth, you can write the core guidelines in one file and use import directives in the other.
What Anthropic has hinted about the future
As AI developer tooling evolves, Anthropic is actively refining how Claude Code handles project layouts. Hints from the product roadmap suggest future support for:
- Autonomous MCP discovery: Letting CLAUDE.md declare which MCP servers to initialize for the workspace.
- Fine-grained permission rings: Letting developers configure strict command whitelists inside CLAUDE.md.
- Unified Schema Standards: Collaboration with other tooling providers to establish a unified configuration layout.