Every Domain-3 location question reduces to two axes:
~/.claude/…, personal) or the whole team
(.claude/… in the repo, version-controlled, arrives on clone/pull)?Exam tell: "available to every developer when they clone the repo" → it must be
in the repo (.claude/…), never ~/.claude/….
| What you need | Where it lives | Scope |
|---|---|---|
| My instructions across all projects | ~/.claude/CLAUDE.md | user — personal, not shared |
| Team instructions for this project | ./CLAUDE.md (repo root) | project — shared via git |
| Instructions for one subtree | <subdir>/CLAUDE.md | directory — supplements the parents |
| Split a huge CLAUDE.md into topics | .claude/rules/*.md (e.g. testing.md) | project; optional glob paths to scope by file |
| Slash command shared on clone | .claude/commands/ | project — version-controlled |
| My personal/experimental command | ~/.claude/commands/ | user — not in the repo |
| Context useful for one task type only | a skill, invoked via slash command | on-demand — loaded only when called |
| Run non-interactively (CI/CD) | claude -p "…" (--print) | CLI flag — prints & exits, no prompt |
You can place CLAUDE.md at the user level, the project root, and inside subdirectories. Claude reads all applicable levels and supplements — a child does not overwrite the parent's rules.
The distractor that beat you: "multiple CLAUDE.md files, each overriding the parent." Wrong on two counts — (1) they supplement, not override; (2) this feature is for scoping context to parts of the codebase, not for modularizing one project's many topics.
To modularize a 500-line CLAUDE.md into focused files → that's .claude/rules/, a different feature.
.claude/rules/ — modular, and optionally path-scopedBreak the monolith into topic files (testing.md, api-conventions.md). Each rule file
can declare a glob paths so it activates only when you're working on matching files.
Key limit: a rule with paths: api/** fires for everything you do in
that directory — generation, bug fixes, reviews alike. That's the trap in the next point.
| Path-scoped rule | Skill (slash command) | |
|---|---|---|
| Loads when | any work touching matching files | only when you invoke it |
| Best for | standards that apply to all work in a path | context useful for one task type |
| Risk | wastes context on unrelated tasks (bug fixes, reviews) | none — it's silent until called |
The distractor that beat you: exemplar endpoints help only when generating new
endpoints — not for bug fixes or reviews in the same api/ dir. A path-rule would fire for all of
those (wasteful). The on-demand skill loads the exemplars only when you
ask for a new endpoint. Useful-sometimes → skill; always-applies-in-path → rule.
-p for CI — the non-interactive flagA bare claude "…" in a pipeline hangs waiting for interactive input. claude -p "…"
(--print) processes the prompt, writes the result to stdout, and exits.
Dodge these: there is no CLAUDE_HEADLESS env var and no --batch flag;
redirecting < /dev/null is a generic Unix hack, not the documented mechanism. The answer is always
-p.
CLAUDE.md notes.