claude-context-improver

# Claude Context Improver Audit and improve the context Claude Code loads before it sees a prompt: `CLAUDE.md` guidance files, `.claude/rules/` path-scoped rules, and the companion `code_map.md` navigation map. The goal is a context layer that is concise, current, conflict-free, and progressively disclosed — sized for Claude 5 generation models rather than for the weaker models most existing guidance was written against. **Default mode is report-first.** Output a quality report and proposed diff before writing. If the user explicitly asks to implement an approved plan, continue directly to targeted edits and verification. **Relationship to `/doctor`.** Claude Code's bundled `/doctor` is Anthropic's automated rightsizer for skills and CLAUDE.md. This skill is the repo-tailored, report-first companion: it scores against a rubric, verifies claims against the actual codebase, covers `code_map.md` and `.claude/rules/`, and shows diffs before editing. Recommending a `/doctor` run alongside the report is reasonable; neither replaces the other. **Trivial edit fast path.** If the request is a single scoped edit the user has already specified (add or fix one line or one small section in an identified file), skip the scope question and the full workflow: apply the edit directly, checking only that hook marker blocks stay intact, the file stays under the 200-line target, and no `@code_map.md` import is introduced. Everything below applies to audit and optimization requests. ## Context Engineering Principles (Claude 5) Anthropic removed over 80% of Claude Code's system prompt for Claude Opus 5 and Fable 5 with no measurable loss on coding evals. The same over-constraining that hobbled the system prompt hobbles most `CLAUDE.md` files. Audit against these shifts: | Then | Now | | --------------------- | ----------------------------------------------------------------------------------------------- | | Give Claude rules | Let Claude use judgement — phrase intent, reserve absolutes for expensive mistakes | | Give Claude examples | Design interfaces — expressive parameters and contracts beat example walls that narrow the space | | Put it all upfront | Progressive disclosure — a tree of files loaded at the right time, not one central repository | | Repeat yourself | Say it once, in the layer that owns it | | Memory in `CLAUDE.md` | Auto-memory — session facts and decisions are saved automatically, not pasted into guidance | | Simple specs | Rich references — specs-as-code, test suites, HTML artifacts, and rubrics beat restated prose | The one-line summary from the official guidance: keep `CLAUDE.md` lightweight, briefly say what the repo is for, and spend most of the tokens on **gotchas** — never on what Claude can see by reading the file tree. See `references/context-engineering-claude5.md` for the full rules, sources, and how each shift maps to a concrete audit check. ## Core Semantics Claude Code memory files use **additive layering**, not directory-scoped override. This is the most common point of confusion when migrating instructions from Codex `AGENTS.md` or other agents. - Claude Code walks up the directory tree from the current working directory; every `CLAUDE.md` and `CLAUDE.local.md` found along the way is loaded at session start and concatenated into context, ordered from filesystem root to working directory. - `CLAUDE.md` files in **descendant** directories are loaded **lazily** when Claude reads files in those directories during the session. - `CLAUDE.md` files in **sibling** directories are never loaded for the current session. - Files load additively: all layers contribute to context simultaneously. There is no "deeper file overrides parent" semantic; more specific guidance simply sits later in the prompt. This is why a cross-layer contradiction is a real defect, not a resolution order. - Precedence chain at session start: managed policy → user (`~/.claude/CLAUDE.md`) → project (`./CLAUDE.md` or `./.claude/CLAUDE.md`) → `CLAUDE.local.md` per layer. - `@path` imports expand at launch (recursive, max depth 4). They do not save context; they only organize files. - Block-level HTML comments (`<!-- ... -->`) are stripped before injection. Use them for human-maintainer notes that should not consume tokens. - `.claude/rules/*.md` with a `paths:` frontmatter glob loads only when Claude reads files matching that glob. Rules without `paths:` load unconditionally. - `CLAUDE.md` carries durable behavioral constraints, commands, and project conventions. `code_map.md` carries navigational structure, search anchors, entry points, and generated/ignored directory notes. - Every created or updated `CLAUDE.md` should name the relative `code_map.md` path agents must read before broad grep, for example `Before broad grep, read ./code_map.md`. - When the repository also uses Codex (`AGENTS.md` present), `code_map.md` is a shared artifact maintained by both this skill and `codex-context-improver`. Use the canonical code map wording from `references/templates.md` (it names both guidance files), never remove the other tool's mention from an existing map, and prefer the `@AGENTS.md` import bridge over duplicating shared instructions. - The [official memory documentation](https://code.claude.com/docs/en/memory) recommends keeping each `CLAUDE.md` **under 200 lines**; longer files reduce adherence and inflate every session's startup tokens. - Preserve hook-managed marker blocks such as `<!-- OMX:RUNTIME:START --> ... <!-- OMX:RUNTIME:END -->` and `<!-- OMX:TEAM:WORKER:START --> ... <!-- OMX:TEAM:WORKER:END -->`. These are stripped at injection but are still meaningful to hook tooling and must survive edits intact. See `references/claude-md-loading.md` for the full loading model, including edge cases around `--add-dir`, `claudeMdExcludes`, and auto memory boundaries. ## Workflow ### Phase 0: Choose Scope Ask which context layer to work on before touching anything, using `AskUserQuestion` with header `优化范围`: - **当前仓库 (Recommended)** — the repository's `CLAUDE.md` tree, `.claude/rules/`, and `code_map.md`. This is the default. - **全局** — the user-level context: `~/.claude/CLAUDE.md`, `~/.claude/rules/*.md`, and files they `@`-import. Skip the question when the user already named a scope ("audit my global CLAUDE.md", "check this repo's rules"), named concrete files, or the trivial-edit fast path applies. If `AskUserQuestion` is unavailable on the host platform, ask the same two options in plain text and wait; treat "no preference" as 当前仓库. The answer is the authorization boundary. Choosing 全局 authorizes reading and editing files under `~/.claude/`; choosing 当前仓库 leaves them untouched and only notes them as context. Managed policy files are never edited under either scope. How the scope changes each phase: | Phase | 当前仓库 (default) | 全局 | | ------------ | -------------------------------------------------- | -------------------------------------------------------------------------------------- | | Discovery | repo-root `find` commands below | `~/.claude/CLAUDE.md`, `~/.claude/rules/*.md`, resolved `@` imports (depth ≤ 4) | | Evidence | verify claims against repo manifests and file tree | verify claims are machine-portable — no single repo's paths or commands stated globally | | Assessment | full rubric | full rubric, plus: does this belong in a project `CLAUDE.md` instead of everyone's? | | Updates | edit repo files | edit `~/.claude/**` (authorized by this scope); managed policy stays read-only | | Verification | `git diff --check` plus the manual checks | manual checks only — `~/.claude` is usually not a git repository | ### Phase 1: Discovery Find every context file in scope. For 当前仓库: ```bash find . \( -name CLAUDE.md -o -name CLAUDE.local.md -o -name code_map.md \) \ -not -path './.git/*' \ -not -path './node_modules/*' \ -not -path './target/*' \ -not -path './dist/*' \ -not -path './build/*' \ -not -path './vendor/*' \ -not -path './.omx/state/*' find . -path '*/.claude/rules/*.md' -not -path './.git/*' -not -path './node_modules/*' ``` For 全局: ```bash find "$HOME/.claude" -maxdepth 1 \( -name 'CLAUDE.md' -o -name 'CLAUDE.local.md' \) find "$HOME/.claude/rules" -name '*.md' ``` The commands above are a starting set; the full exclusion list below governs. Exclude generated, vendored, dependency, cache, and build-output directories from creation scans: `.git/`, `node_modules/`, `target/`, `dist/`, `build/`, `.omx/state/`, `vendor/`, coverage output, generated docs/site output, and language-specific package caches. Managed policy files are noted but never edited under any scope: ```text /Library/Application Support/ClaudeCode/CLAUDE.md # macOS managed policy /etc/claude-code/CLAUDE.md # Linux/WSL managed policy C:\Program Files\ClaudeCode\CLAUDE.md # Windows managed policy ``` Under 当前仓库, discover candidate subtrees for new nested `CLAUDE.md` (and possibly local `code_map.md`) before proposing writes. Score only real source subtrees that show one or more of: distinct stack or framework, independent manifest/command surface, divergent conventions, frequent agent work in that area, local safety boundary, or pressure to relieve a bloated root `CLAUDE.md`. Classify each file: | Type | Location | Purpose | | ----------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------- | | project root guidance | `./CLAUDE.md` or `./.claude/CLAUDE.md` | repo-wide pointers, gotchas, conventions, top-level commands | | nested project guidance | `./<subtree>/CLAUDE.md` (or `<subtree>/.claude/CLAUDE.md`) | local stack, commands, safety, conventions distinct from parent | | path-scoped rules | `./.claude/rules/*.md` (optional `paths:` frontmatter) | conditional or always-on rules organized by topic | | personal override | `./CLAUDE.local.md` | gitignored per-developer preferences; never read content, only confirm it is gitignored | | root code map | `./code_map.md` | repo navigation, top-level routing, search anchors, ignored/generated paths | | nested code map | `./<subtree>/code_map.md` | subtree entry points, internal routing, upstream/downstream boundaries | | user global guidance | `~/.claude/CLAUDE.md`, `~/.claude/rules/` | cross-project personal preference; in scope only when the user chose 全局 | | managed policy guidance | OS-managed path above | IT/DevOps controlled; never edit from this skill | ### Phase 2: Evidence Collection For every in-scope file, verify claims against the repository (or, under 全局, against portability): - commands referenced in `package.json`, `justfile`, `Cargo.toml`, `pyproject.toml`, `Makefile`, CI workflows - actual directory structure and entry points named in the file - `@import` targets: every `@path/to/file` must resolve relative to the file containing it; recursion depth ≤ 4 - `code_map.md` existence and whether each `CLAUDE.md` map pointer uses an explicit relative path - `.claude/rules/*.md` frontmatter: `paths:` globs are valid, file globs match real source files, conditional rules are not duplicating root content - alignment with `.claude/settings.json` — do not duplicate hard `permissions.deny` constraints as soft prose; if the setting already blocks an action, do not also rephrase it as a rule - `claudeMdExcludes` settings (in `.claude/settings.json`, `.claude/settings.local.json`, or managed) and whether they conflict with the files you are auditing - bloat signals: total line count vs the 200-line target, repeated content across nested files, code restatement that belongs in `code_map.md` - conflict signals: instructions that contradict each other across layers, or contradict what the user's own prompts routinely ask for - obvious-content signals: statements Claude would derive from one `ls`, one manifest read, or the file names themselves - preserved hook marker blocks; flag any unbalanced `OMX:...:START` / `END` pairs - `CLAUDE.local.md` presence — confirm it is listed in `.gitignore`; do not read its content ### Phase 3: Quality Assessment Use `references/quality-criteria.md` for detailed scoring, including the nested `CLAUDE.md` creation scorecard. Quick checklist (100 points total): | Criterion | Weight | Check | | ---------------------------------- | -----: | ------------------------------------------------------------------------------------------------------------------------------------------- | | judgement fit and conflict-freedom | 20 | no contradictions across layers, no absolute-rule walls outside expensive-mistake areas, no content Claude derives from the file tree | | additive layering clarity | 15 | file states which layer it occupies and what it adds, without restating parent content | | executable commands and gates | 15 | install/build/test/lint/typecheck/dev commands are real and scoped to the file's layer | | progressive disclosure | 15 | multi-step procedures live in skills, navigation in `code_map.md`, path rules in `.claude/rules/`; the entry file points rather than holds | | architecture and routing | 10 | points to `./code_map.md` with an explicit relative path; does not duplicate directory indexes |