docs: improve CLAUDE.md section structure & clarifications

- Restructure section 3.1: move MVP CLAUDE.md before Level 1/2/3 examples
- Replace unverified "90% of projects" claim with "most projects"
- Add Skills/Commands unification note to Section 6 (matching Section 5)
- Add cross-references between Memory Loading and Token Cost sections
- Clarify Monorepo CLAUDE.md merge/conflict resolution behavior
- Clarify Path-specific rules glob matching syntax

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX 2026-01-19 09:14:06 +01:00
parent 7a6d369512
commit b05ce81e66

View file

@ -3197,6 +3197,8 @@ monorepo/
- When you work in `packages/api/`, it merges root + api CLAUDE.md
- More specific files add to (don't replace) parent context
**Conflict resolution**: If the same instruction appears in both files, the more specific (child) file takes precedence. Instructions are merged additively—child rules don't delete parent rules, they override conflicting ones.
**What goes where**:
| Location | Content |
@ -3590,6 +3592,8 @@ Understanding when each memory method loads is critical for token optimization:
**Key insight**: `.claude/rules/` is NOT on-demand. Every `.md` file in that directory loads at session start, consuming tokens. Reserve it for always-relevant conventions, not rarely-used guidelines.
> **See also**: [Token Cost Estimation](#token-saving-techniques) for approximate token costs per file size.
### Path-Specific Rules (December 2025)
Since December 2025, rules can target specific file paths using YAML frontmatter:
@ -3612,6 +3616,11 @@ These rules only apply when working with API files:
This enables progressive context loading—rules only appear when Claude works with matching files.
**How matching works**:
- Patterns use glob syntax (same as `.gitignore`)
- Multiple rules can match the same file (all are loaded)
- Rules without `paths:` frontmatter always load
---
# 4. Agents
@ -8661,6 +8670,8 @@ You: "Implement the caching layer following the plan"
Note: These are loaded **once at session start**, not per request. A 200-line CLAUDE.md costs ~2K tokens upfront but doesn't grow during the session. The concern is the cumulative effect when combined with multiple `@includes` and all files in `.claude/rules/`.
> **See also**: [Memory Loading Comparison](#memory-loading-comparison) for when each method loads.
**1. Keep CLAUDE.md files concise:**
```markdown