Two CLAUDE.md Files, Two Scopes

Claude Rules Workflow

Chapter 2 · Two CLAUDE.md Files, Two Scopes

Chapter 1 talked about "CLAUDE.md" as if it were one file. In practice, there are two — one living at ~/.claude/CLAUDE.md, the other living inside this repository itself — and they answer two genuinely different questions. The global file asks "how should Claude behave with this particular user, no matter which project they're in?" The project file asks "what does this specific codebase need Claude to know?" Confusing the two, or putting the wrong instruction in the wrong one, is a real and easy mistake to make.

The Global File — Cross-Project Preferences

~/.claude/CLAUDE.md lives outside any one project, in the user's own home directory — which is exactly why its own first line states plainly that it "applies across every project, regardless of which directory Claude Code is started in." Whatever's written here follows the user around, not the codebase.

A few real examples from this project's own global file:

  • Explanation Style for Mistakes & Corrections — when explaining a bug or a correction, state what went wrong and how to avoid it next time. This has nothing to do with any one codebase; it's about how this specific user wants any mistake explained to them, everywhere.
  • Prompting-Style Feedback Is Welcome — if a prompt could have been phrased more efficiently, say so directly. Again, a preference about the working relationship itself, not about a project.
  • Utility Scripts Folder — a standing instruction that general-purpose, non-project-specific scripts get saved to one particular folder. The folder itself sits outside any single project, and the instruction only makes sense read that way.
  • The "conversation" command — a reusable convention (save a readable transcript to a predictable location) meant to work the same way in this project and in any other one the user might be working in.

The Project File — What This Codebase Needs

This repository's own CLAUDE.md, by contrast, opens with a plain description of what this specific project actually is — a personal educational website, PHP/MySQL, no build system — information that is meaningless outside this one repository. Its real payload is the @rules/ include block from Chapter 1, plus a Key Paths table mapping every content type (course HTML, language lessons, kanji pages, sidebar pages) to its exact folder inside this repo's own Folder-Structure/ tree.

Global — ~/.claude/CLAUDE.md
Lives in the user's home directory
  • Explanation style for corrections
  • Prompting-style feedback preference
  • The utility-scripts folder location
  • The "conversation" transcript command
Project — this repo's own CLAUDE.md
Lives at this repository's own root
  • What this specific project is (PHP/MySQL learning blog)
  • The full @rules/ include list (Chapter 1)
  • The Key Paths table (course/lesson/kanji/sidebar folders)
  • The R1-supersession note from Chapter 1

How the Two Actually Stack

Inside this repository, both files are in effect at once — the global preferences apply and this project's own rules apply, layered together rather than one replacing the other. Outside this repository, in some completely different project, only the global file would still apply; this repo's own @rules/ include block and Key Paths table would be entirely irrelevant there, since they only make sense in the context of this specific codebase's own folder structure.

QuestionGlobal CLAUDE.mdProject CLAUDE.md
Where it lives~/.claude/CLAUDE.mdThis repository's own root
Applies whereEvery project, everywhereOnly inside this repository
What it holdsPreferences about working WITH the userFacts and rules ABOUT this codebase
A rule that belongs here"Explain corrections with what-went-wrong + how-to-avoid""Course chapters live at content/<subject>/<course>/"
Putting a project-specific rule in the global file would leak it everywhere
The @rules/ include list and the Key Paths table are meaningless — worse, actively misleading — in any project that isn't this one. If a rule like "course HTML goes in content/<subject>/" were written into the global file instead of the project file, every other unrelated project the user ever works in would start seeing an instruction that makes no sense there at all. The split isn't just tidy organization; it's what stops one project's own conventions from bleeding into every other one.
A quick test for which file a new rule belongs in
Ask: "would this instruction still make sense if pasted into a completely different, unrelated project?" If yes — a communication style, a general habit, a location for scratch files — it belongs in the global file. If the instruction only makes sense because of something specific to this codebase's own folder structure or content type, it belongs in this project's own rules files instead (and, per Chapter 1, still needs its own @rules/ line to actually take effect).

Hands-On Exercises

Exercise 1

A new instruction says: "Whenever generating a chart, use a colorblind-safe palette." Using this chapter's own test, decide which CLAUDE.md file it belongs in, and explain your reasoning.

📄 View solution
Exercise 2

Explain what would actually go wrong, concretely, if this repository's own Key Paths table were moved into the global ~/.claude/CLAUDE.md file instead of staying in the project's own file.

📄 View solution
Exercise 3

A user works on this website project in the morning and on a completely unrelated Node.js API project in the afternoon. Which of this chapter's own four global-file examples (explanation style, prompting feedback, utility scripts folder, "conversation" command) would still be in effect during the afternoon session, and why?

📄 View solution

Chapter 2 Quick Reference

  • ~/.claude/CLAUDE.md — global, applies across every project, holds preferences about working WITH this user
  • This repo's own CLAUDE.md — project-local, holds facts and rules ABOUT this specific codebase
  • Inside this repository, both files apply at once, layered together — not one replacing the other
  • Outside this repository, only the global file is still relevant
  • Quick test: would this instruction still make sense in a totally different project? Yes → global. No → project-local
  • Putting a project-specific rule in the global file lets it leak into every other unrelated project
  • Next chapter: a full tour of the project file's own biggest include — the Permanent Rules file, P1 through P13