You create and update subdirectory CLAUDE.md files. These are small domain files that stack ON TOP of the root CLAUDE.md — both active at once. They make the same agent behave differently depending on which folder it’s in.
NEVER repeat anything from the root CLAUDE.md. Read it first. If a rule already exists in root, don’t put it here. Nested files add domain-specific context only. Duplication wastes tokens and creates contradictions when one copy gets updated and the other doesn’t.
This is the key insight most people miss: nested CLAUDE.md files aren’t just extra rules. They’re behavior routers. The same agent changes HOW it works based on which directory it enters.
Examples of behavior-shifting:
/frontend/CLAUDE.md → “Prioritize UX. Visual changes need screenshots.”/backend/CLAUDE.md → “Prioritize correctness. Every endpoint needs tests.”/tests/CLAUDE.md → “Be thorough. Test edge cases, not just happy paths.”/creative/CLAUDE.md → “Be experimental. Try unconventional approaches.”/infrastructure/CLAUDE.md → “Be cautious. Changes here affect everything.”The behavior shift is more valuable than the rules. Write HOW the agent should think in this area, not just what it should do.
Both add domain-specific context. Choose based on the trigger:
| Use | When |
|---|---|
| Nested CLAUDE.md | The domain maps to a folder AND needs behavior change, key decisions, pitfalls — contextual guidance |
Path-scoped rules .claude/rules/*.md |
The rule is about a file pattern (e.g., all *.test.ts files) or a convention that doesn’t need context, just enforcement |
Path-scoped rules use YAML frontmatter with glob patterns:
---
paths:
- "**/*.test.ts"
- "**/*.spec.ts"
---
Always use vitest. Mock external APIs. Never test implementation details.
When a folder needs BOTH contextual guidance AND pattern rules, use a
nested CLAUDE.md for the guidance and .claude/rules/ for the enforcement.
Read the root CLAUDE.md first. Then check the target folder:
No nested file exists → Create mode. Scan the folder (files, patterns, test setup, any README). Ask the user what’s specific about this area if not obvious. Write a focused file following the template.
File exists but bad (repeats root info, too long, missing WHY, generic) → Remake mode. Strip out anything that duplicates root. Keep only what’s domain-specific. Restructure to meet quality bar.
File exists and good → Update mode. Surgical edits only. Same generalize/deduplicate/expire/promote rules as the root skill.
# [Domain Name]
[One sentence: what this part of the codebase does and what tech it uses.]
## How to Work Here
[2-3 sentences that shift agent behavior. Not rules — mindset. What
matters most in this area? What's the thinking approach?]
## Patterns
- [How code is written HERE, not project-wide] — because [why]
- NEVER [anti-pattern specific to this domain] — because [consequence]
## Key Decisions
[WHY the architecture is this way. Prevents the agent from "improving"
things that were deliberately chosen.]
- We use [X] instead of [Y] — because [trade-off]
- [This thing] is structured this way — because [reason]
## Key Files
- `[path]` — [what it does, why it matters]
- `[path]` — golden example, follow this pattern
## Domain Testing
- [How to test THIS area specifically]
- [What to mock here vs. what to test e2e]
## Pitfalls
| Mistake | Fix |
|---------|-----|
| (real mistakes only) | |
50-100 lines max. If it’s longer, you’re probably repeating root info.
These patterns from production repos show what good nesting looks like:
Per-module depth (open-notebook): lib/api/CLAUDE.md for Axios/interceptors,
lib/hooks/CLAUDE.md for TanStack Query wrappers, lib/stores/CLAUDE.md
for Zustand state. Each file ~30-50 lines, laser focused.
Monorepo @imports (AutoGPT): Root CLAUDE.md uses @backend/CLAUDE.md
and @frontend/CLAUDE.md so both load proactively, not just on-demand.
Error tables (WooCommerce): Nested files per plugin AND per test dir,
each with | Error | Wrong | Correct | quick-reference tables.
Use these as inspiration, not templates. Adapt to THIS project.
After writing, re-read the full file and check:
Before saving, check:
Same discipline as root — NEVER just append:
Create a nested file when:
DON’T create one when:
.claude/rules/ would serve better (pure enforcement,
no context needed)references/example-output.md for what great nested output looks like.