Rules Hierarchy & Priority

Claude Code does not have one CLAUDE.md file. It has a priority stack. When you launch a session, Claude assembles rules from multiple sources and resolves them in a strict top-down order. The system prompt sits at the top — immutable, invisible, always in effect. Below that, your project CLAUDE.md (the one checked into your repo) carries the highest user-configurable priority. Then comes the .claude/CLAUDE.md directory-level file. Then your personal global rules at ~/.claude/CLAUDE.md. Finally, any rules injected by MCP servers or session context land at the bottom of the stack.

Why does this matter? Because when two rules conflict, the higher-priority rule wins silently. If your project CLAUDE.md says "always use single quotes" and your personal config says "always use double quotes," single quotes win — every time, without warning. Claude does not flag the conflict. It does not ask for clarification. It applies the higher-priority rule and moves on. If you are wondering why Claude keeps ignoring a rule you wrote, the answer is almost always that a higher-priority rule is overriding it.

The practical implication is that your project CLAUDE.md is the most powerful file you control. It outranks every personal preference, every global config, every MCP-injected instruction. Treat it accordingly. This is not a scratch pad for notes — it is the operating system for your AI development environment. Every rule in this file should be intentional, tested, and understood by the team.

1. 1. System Prompt (Highest Priority) Anthropic's built-in instructions. You cannot modify these. They govern safety, tool usage, and core behavior. Everything you write operates beneath this layer.
2. 2. Project CLAUDE.md (Root Directory) Checked into your repo at the project root. Shared with the team. This is your primary control surface — put your most critical rules here.
3. 3. .claude/CLAUDE.md (Directory Level) Lives inside the .claude directory. Useful for project-specific overrides that you do not want in the root-level file. Often used for environment-specific or branch-specific rules.
4. 4. ~/.claude/CLAUDE.md (Global Personal) Your personal global config. Applies to every project unless overridden. Put cross-project preferences here — editor style, communication preferences, personal workflows.
5. 5. MCP & Session Context (Lowest Priority) Rules injected by MCP servers or accumulated during a session. Lowest priority, most easily overridden. Do not rely on MCP context for critical rules.