$ man how-to/claude-md-vs-agents-md-vs-cursorrules

CLAUDE.md is for Claude Code. AGENTS.md is a cross-tool standard. .cursorrules is for Cursor IDE. All three serve the same purpose: give the AI tool project-specific context and instructions so it produces better output. The difference is scope and format. If you only use one AI tool, use that tool's config file. If you use multiple tools - and most serious practitioners do - you need a strategy for keeping them in sync without tripling your maintenance burden.

PATTERN

CLAUDE.md is Anthropic's config file for Claude Code. It loads automatically at session start and stays in context for the entire conversation. Placement: repo root for project-level, ~/.claude/CLAUDE.md for global, and nested directories for module-level. Claude Code merges all applicable levels. Format: plain Markdown. Headers, bullets, code blocks, tables. No special syntax needed. Claude reads it like any other document. Unique features: supports @path/to/file imports that expand inline. Supports multiple levels (global, project, directory). Has a dedicated /init command that auto-generates a starter file from your codebase. Best for: coding conventions, build/test commands, safety rules, project architecture, deployment steps, and behavioral instructions like "never commit .env files" or "run tests before marking a task complete." The best CLAUDE.md files are under 200 lines. They use specific, verifiable instructions ("use 2-space indentation" not "format code properly"). They point to files instead of copying content ("see docs/ARCHITECTURE.md for the full system diagram" not pasting the diagram inline).

PATTERN

AGENTS.md is an emerging open standard intended to work across AI coding tools - not just Claude Code. It was designed by the community as a tool-agnostic config file. Placement: repo root, similar to CLAUDE.md. Format: Markdown with structured sections. Typically includes: project description, architecture overview, coding standards, testing instructions, and tool-specific configurations. Philosophy: write your instructions once, have every AI tool read them. Instead of maintaining separate files for Claude Code, Cursor, Copilot, and Windsurf, maintain one AGENTS.md and let each tool parse it. Reality check: adoption is still early. Claude Code reads CLAUDE.md natively. Cursor reads .cursorrules natively. AGENTS.md support varies. Some tools honor it, others ignore it. The standard is promising but not yet universal. Best for: teams that use multiple AI tools and want a single source of truth for project instructions.

PATTERN

.cursorrules is Cursor IDE's project-level instruction file. It loads when you open a project in Cursor. Placement: repo root as .cursorrules (single file) or .cursor/rules/ directory for multiple rule files with glob patterns. Format: plain text or Markdown. The .cursor/rules/ approach uses .mdc files with YAML frontmatter that specifies which file patterns trigger the rule. Unique features: glob-based rule activation (rules only load when you edit matching files), agent-requested rules that load on demand, and integration with Cursor's composer and chat modes. Best for: Cursor-specific workflows, file-pattern-based rules (load TypeScript conventions only when editing .ts files), and teams that standardize on Cursor as their IDE. Limitation: .cursorrules only works in Cursor. If anyone on your team uses a different tool, they get no benefit from these files.

PRO TIP

Maintaining three separate config files with the same information is a maintenance nightmare. Here is the approach that works: CLAUDE.md is your primary config. It is the most detailed because Claude Code is the most capable at following complex, multi-step instructions. Write your full project context, conventions, and workflows here. AGENTS.md is a simplified cross-reference. Link to CLAUDE.md for details. Include only the universal instructions that every tool should follow: coding standards, testing requirements, architecture overview. .cursorrules handles Cursor-specific rules. File-pattern activation, inline edit preferences, composer mode instructions. Do not duplicate what is already in CLAUDE.md. The structure: CLAUDE.md - Full project config (200 lines) AGENTS.md - Universal subset + links to CLAUDE.md (50 lines) .cursor/rules/*.mdc - Cursor-specific file-pattern rules (per-rule files) This way, when conventions change, you update CLAUDE.md. AGENTS.md points to it. .cursorrules only contains Cursor-specific behavior that does not apply elsewhere. If you use only Claude Code: just maintain CLAUDE.md. Skip the others until you need them.