From b05ce81e66cf8ad732252e90ed81015561c0f32d Mon Sep 17 00:00:00 2001 From: Florian BRUNIAUX Date: Mon, 19 Jan 2026 09:14:06 +0100 Subject: [PATCH] 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 --- guide/ultimate-guide.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/guide/ultimate-guide.md b/guide/ultimate-guide.md index 81267de..f2068b8 100644 --- a/guide/ultimate-guide.md +++ b/guide/ultimate-guide.md @@ -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