CLAUDE.md vs .cursorrules vs Custom Instructions

Format Comparison

CLAUDE.md is a Markdown file. It supports headers, code blocks, lists, and all standard Markdown formatting. Claude Code parses it as Markdown and uses the structure to understand the hierarchy of information. Headers help the model identify sections, and code blocks signal that enclosed content is technical syntax rather than natural language instructions.

.cursorrules is a plain text file. While you can use Markdown-like formatting (headers with # symbols, code blocks with backticks), Cursor does not parse the Markdown structure. The file is injected as raw text into the system prompt. The practical implication is that formatting is cosmetic rather than semantic: use it for readability, but the model treats the entire file as a single block of instructions.

.github/copilot-instructions.md is a Markdown file stored in the .github directory of your repository. Copilot reads it as part of the repository context and uses it to guide code generation. The format supports the same Markdown features as CLAUDE.md, but the file location is fixed (it must be in .github/) and there is no hierarchy beyond the single file.

Loading Behavior

CLAUDE.md has the most sophisticated loading behavior. Claude Code reads CLAUDE.md files from three locations, concatenating them in order: the user's home directory (~/.claude/CLAUDE.md), any parent directories between home and the project, and the project root. This hierarchy means you can have personal preferences at the home level, shared conventions at a parent directory level (useful for monorepos), and project-specific details at the project level. All three files are loaded into every session.

.cursorrules loads a single file from the project root. There is no hierarchy. If you need different rules for different parts of a monorepo, you need separate .cursorrules files in each package directory and open those directories as separate workspaces. Global personal preferences are configured through Cursor's settings UI rather than through a file in the file system.

Copilot's instruction file loads from a single fixed location (.github/copilot-instructions.md). Like .cursorrules, there is no file hierarchy. Personal preferences are configured through the IDE's Copilot settings rather than through a file.

Token Budget Impact

All three file types consume context window tokens when loaded. The content is injected into the system prompt, reducing the space available for code, conversation, and tool results. This is why keeping context files concise matters: a 5,000-word CLAUDE.md file consumes roughly 6,000 tokens, which is significant when the context window also needs to hold multiple files of source code and a conversation history.

CLAUDE.md's hierarchy adds a nuance: the total token cost is the sum of all loaded files. A 1,000-word home-level file plus a 1,500-word project-level file consumes 3,000 tokens total. Plan your hierarchy so that information is not duplicated across levels. The home file should contain personal preferences that the project file does not need to repeat.

.cursorrules and copilot-instructions.md each have a single file, so the token cost is straightforward. Keep each file under 2,000 words (roughly 2,500 tokens) for the best balance between context richness and remaining token budget.

Team Sharing

All three file types can be committed to version control, making them shareable across a team. This is their primary advantage over IDE-level settings: the entire team gets the same context automatically when they pull the repository.

CLAUDE.md and .cursorrules both live in the project root, so they are straightforward to commit. The team can review changes to these files through the normal pull request process, treating convention updates like any other code change. The .github/copilot-instructions.md file is equally committable but may be overlooked during reviews since it lives in a directory that developers do not check as regularly.

The personal layer differs across tools. CLAUDE.md's home-level file (~/.claude/CLAUDE.md) is inherently personal and not shared. Cursor's global rules are stored in the IDE's settings, also personal. This separation is appropriate because personal preferences (coding style, explanation depth, interaction patterns) should not override team conventions.

Which to Use When

If your team primarily uses Claude Code, invest in a well-structured CLAUDE.md file with the three-level hierarchy. The home-level file captures your personal coding preferences. The project-level file captures the team's conventions and constraints. The hierarchy ensures that every session starts with comprehensive context without duplication.

If your team primarily uses Cursor, invest in a thorough .cursorrules file supplemented by Cursor's project settings. The single-file format is less flexible than CLAUDE.md's hierarchy, but a well-organized .cursorrules file provides equivalent value. Use Cursor's global settings for personal preferences that apply across projects.

If your team uses multiple tools, maintain both CLAUDE.md and .cursorrules with similar content. The content categories are the same (conventions, constraints, architecture, anti-patterns), so the effort is minimal once you have written the content for one file. Some teams automate this by maintaining a single source-of-truth file and generating tool-specific versions through a build step or pre-commit hook.

Regardless of which tool you use, supplement the static context file with an MCP memory server for dynamic knowledge. Static files capture the stable, authoritative knowledge. Dynamic memory captures the evolving, contextual knowledge that accumulates over time. The combination provides coverage that neither approach achieves alone.

Content Strategy Across Formats

The content that works well is the same across all three formats. Document non-obvious constraints, conventions that differ from defaults, architecture decisions with reasoning, and codebase-specific anti-patterns. Omit information the assistant can determine from the code. Keep the total under 2,000 words. Use specific, actionable instructions rather than general guidelines.

The only format-specific adjustment is that CLAUDE.md benefits from clear Markdown structure (headers, code blocks, lists) because Claude Code uses the structure to navigate the content. The other formats are read as flat text, so structure is cosmetic. In practice, structured content is easier to maintain regardless of the format, so using headers and organized sections is a good practice for all three.