` anchor. See the agent's "Phase 0: X-Ray Detection" for the full protocol. If the user declines (or `.codebase-xray/` is absent), the agent does its own bottom-up analysis as in step 1 below. ## What This Does The agent will: 1. Analyze your codebase bottom-up (dependencies, entry points, source, config, tests, docs) -- OR ingest `.codebase-xray/` if the pre-flight check accepted that shortcut 2. Read your `CLAUDE.md` last and verify every claim against established ground truth 3. Detect obsolete file paths, dependencies, or commands -- with explicit `.codebase-xray/` anchor citations when applicable 4. Identify gaps - undocumented commands, dependencies, configs, or patterns 5. Check for best practices (conciseness, progressive disclosure, instruction economy) 6. Present findings with prioritized recommendations 7. Ask if you want to apply improvements 8. If yes: Guide you through interactive improvement workflow 9. If no: Provide detailed audit report only ## When to Use - After major refactoring or restructuring - When you suspect `CLAUDE.md` is outdated - Periodic maintenance (quarterly recommended) - Before onboarding new team members - After significant dependency updates - When Claude seems to be working from wrong assumptions - After team discussion about what Claude should know - After learning what works/doesn't work with Claude - Want to modernize CLAUDE.md based on best practices ## Example Interactive Flow ### Scenario 1: Audit with Improvements ``` Agent: I've audited CLAUDE.md. Found 3 critical issues, 5 high priority, 4 medium priority. Critical Issues: 1. File path src/api/ doesn't exist (actual: src/routes/api/) 2. References webpack but project uses Vite 3. Command "npm run build:prod" not found in package.json Would you like me to fix these issues? You: Yes Agent: Should I fix all critical issues? (Recommended: Yes) You: Yes Agent: Done. High priority issues: 1. File is 450 lines (recommend <300) 2. Duplicates code from README 3. Contains style rules (should delegate to biome.json) 4. Missing info about Vite build system 5. Obsolete Redux docs (project uses Zustand) Which should I prioritize? A) All of them B) Just reduce length and remove duplicates C) Let me choose individually You: B Agent: I can reduce from 450 to ~180 lines by: - Moving detailed guides to docs/development.md - Removing code samples (replace with file references) - Removing README duplicates I also found gaps in your CLAUDE.md: - "npm run lint" exists in package.json but not documented - Prisma ORM is a key dependency but not mentioned - docker-compose.yml not referenced I found these patterns to potentially document: - Custom hooks usage (src/hooks/) - API conventions with React Query - Feature-based folder structure Should I include these? You: Yes for hooks and API conventions, skip folder structure Agent: I see both REST and GraphQL endpoints. Which should Claude prioritize? You: GraphQL - REST is legacy Agent: Here's the improved version (185 lines): [Shows diff] Apply these changes? You: Yes Agent: Applied! Your CLAUDE.md is now: - 185 lines (was 450) - All paths verified - No code duplication - Focuses on hooks, API conventions, GraphQL - References docs/development.md for details ``` ### Scenario 1b: Working Principles Backfill on an Otherwise-Clean CLAUDE.md ``` Agent: I've audited CLAUDE.md. No critical issues, no obsolete claims, all paths verified. However, two Working Principles backfills are pending: [HIGH] Working Principles block is missing the locally authored principle #5 "Centralize Shared Logic" (DRY / Single Source of Truth). CLAUDE.md files generated before plugin v1.12.0 do not include it. Proposed Edit: insert principle #5 verbatim between #4 and the next ## section, preserving the existing 4 rules. [HIGH] Principles 1-4 are present but lack the 3 deeper-meta-rule sub-bullets under each. CLAUDE.md files generated before plugin v1.14.0 only have the lead sentences. Proposed Edit: insert the canonical sub-bullets in place under each principle (12 lines total), preserving the existing lead sentences. Apply both? You: Yes both Agent: Applied. CLAUDE.md is now aligned with v1.14.0 conventions. Diff: +16 lines (principle #5: 4 lines; sub-bullets for 1-4: 12 lines). ``` ### Scenario 1c: Duplication Detection Pass ``` Agent: I've audited CLAUDE.md. All claims verified, Working Principles block intact. Phase 4b found one internal duplication candidate: [MED] docs/wire-payload.md is referenced 3 times: - line 41 (PROJECT CONTEXT pointers block): path + scope tag "Mandatory reference before adding or renaming any wire field" - line 155 (CODE STANDARDS rule #6): path + scope + full rule (Pydantic name = wire JSON key, anti-pattern example) - line 312 (CONTRIBUTING checklist): one-line bullet "see wire-payload.md" Peer comparison: SEARCH_INDEX, ADR README, JUPITER_CONTEXT each appear 1x in the PROJECT CONTEXT block; docs/wire-payload.md is the only outlier. Self-sufficiency test: the line 155 occurrence already contains path + scope + rule + anti-pattern. Line 41 repeats path + scope with different wording. Line 312 is a thin pointer. Options: (a) Keep all 3 - each carries a distinct directive (b) Merge: remove line 41 (line 155 is self-sufficient), keep 312 (c) Replace line 41 with cross-reference: "see CODE STANDARDS #6" (d) Skip / decide later You: b Agent: Removed line 41. Diff: - 1 line removed (PROJECT CONTEXT pointer) - 0 lines changed at line 155 (rule already self-sufficient) - 0 lines changed at line 312 (thin pointer kept) ``` ### Scenario 2: Audit Only (No Changes) ``` Agent: I've audited CLAUDE.md. Found 2 critical issues, 3 high priority, 5 medium priority. Critical Issues: 1. File path src/components/old/ doesn't exist 2. Command "npm test:ci" not found in package.json Would you like me to fix these issues? You: No Agent: Understood. Here's the complete audit report: ✅ Verified Claims (23 items) - Package manager: npm - Test framework: Jest - Build system: Vite ... ❌ Critical Issues (2) 1. File path src/components/old/ doesn't exist → Actual path: src/components/legacy/ 2. Command "npm test:ci" not found → Available: npm test, npm run test:watch [HIGH] High Priority (3) 1. File length: 380 lines (recommend <300) 2. Duplicates content from README.md 3. Missing documentation for new GraphQL API [MED] Medium Priority (5) ... Audit complete. Run /maintain-claude-md again when ready to apply fixes. ``` ## Audit Verification The agent verifies: - **File size <40k characters**: Runs `wc -c CLAUDE.md`. Any value over 40,000 is a Critical finding (Claude Code performance warning threshold); 35,000-40,000 is High (no headroom). Primary fix: extract sections to `docs/.md` and link via `Read docs/.md` pointers - **File paths**: Checks all referenced files and directories exist - **Commands**: Validates npm scripts, build commands, test commands - **Dependencies**: Confirms packages mentioned are actually installed - **Tech stack**: Verifies frameworks, libraries, and tools referenced - **Code patterns**: Checks that documented patterns exist in codebase - **Architecture**: Validates architectural claims against actual structure - **Uncertainty**: Flags claims that cannot be verified from codebase alone - **Gaps**: Identifies undocumented commands, dependencies, configs, and patterns - **Transient state**: Flags any passage recording runtime or temporary state (in-progress task lists, "currently"/"pending"/"for now"/"as of " phrasing, open branches or PR numbers, scratch and temp paths, one-run benchmark numbers, backlog items). Critical when already stale, High when still accurate but time-bound. The proposed fix is deletion or relocation to an issue, a commit message, or `docs/` - never a refresh of the value, since it will go stale again - **Project structure shape (evergreen, not exhaustive)**: Verifies the top-level layout, repeating structural patterns, and role of each top-level category are documented. Does NOT require file-by-file annotation - that level of detail is justified only where names alone are ambiguous, where a file is itself a key entry point, or to disambiguate sibling names. Flags missing whole categories (an entire top-level dir undocumented) as a gap, and flags overly exhaustive file-by-file trees as a Medium consolidation candidate (high decay risk, tokens without evergreen value) - **Working Principles block**: Checks presence of the canonical `## Working Principles` section (5 principles: 4 inspired by upstream agentic-coding meta-rules plus Centralize Shared Logic for DRY / Single Source of Truth), AND the presence of 3 deeper-meta-rule sub-bullets under each of principles 1-4. Flags as High if the block is missing, gutted, or stripped of sub-bullets, and offers to insert what's missing via surgical Edit. Centralize Shared Logic (#5) and the sub-bullets are locally authored and easy to lose on paraphrase - audit each explicitly. Never substitute with an external link or `docs/` pointer - **Test-Suite Rules block (conditional)**: When the project has a test suite, checks presence and integrity of the canonical `## Test-Suite Rules` block (7 rules). Flags missing, gutted, or weakened rules as High and offers verbatim insertion or surgical repair. When the project has no tests, verifies nothing and raises nothing - **External reference fix pattern**: For any OTHER section that bloats CLAUDE.md or duplicates other docs, proposes extracting to `docs/.md` and replacing with a thin `Read docs/.md` pointer. The Working Principles block itself is exempt - it always stays inline - **Internal duplication detection (Phase 4b)**: Counts how often each file path, pointer, and external resource appears in CLAUDE.md. Flags outliers (a reference appearing N>1 times while peer references in the same block appear once), conceptual restatements of the same fact across sections, and cases where the only justification for keeping a duplicate is a weak argument (e.g., "scannability for readers who jump"). Each candidate is surfaced as its own per-drift question with all N occurrences, line numbers, peer-group comparison, and concrete options (keep all / merge / cross-reference / extract to docs/ / skip). Dedup is treated as deletion: no occurrence is removed without explicit per-item user approval - **Best practices**: Assesses proportional sizing, progressive disclosure, structure detail ## Improvement Categories ### Critical (Auto-fix Recommended) - File size over 40,000 characters (Claude Code performance warning threshold) - extract sections to `docs/.md` and replace with `Read docs/.md` pointers until the file is back under the cap - Factually incorrect information - Non-existent file paths - Broken commands - Obsolete dependencies - Transient or runtime state already gone stale (see the Transient state check above) ### High Priority (Usually Should Fix) - Excessive length without substance (padding, duplication, pasted code snippets) - Code duplication - Missing important context - Transient or runtime state that is still accurate but time-bound - relocate it out of CLAUDE.md before it decays - Missing structural categories (a top-level directory or repeating structural pattern is entirely undocumented in the structure section). File-by-file omissions are NOT flagged here - they belong in Medium as consolidation candidates only when the existing map is already exhaustive - Missing or gutted `## Working Principles` block (insert the canonical 5 meta-rules: 4 inspired by upstream agentic-coding meta-rules plus Centralize Shared Logic; preserve any coexisting project-specific principles) - Missing 3 deeper-meta-rule sub-bullets under any of Working Principles 1-4 (the case for any CLAUDE.md created before plugin v1.14.0) - insert the sub-bullets in place via surgical Edit; the block is always delivered inline, never as an external link - Missing or gutted `## Test-Suite Rules` block in a project that has a test suite (any CLAUDE.md created before plugin v1.18.0 will not contain it) - offer the canonical 7-rule block verbatim; weakened rules count as gutted. Not a finding in projects without tests ### Medium Priority (Consider Based on Goals) - Organizational improvements - Better progressive disclosure - Condensing verbose sections - Adding helpful pointers - Extracting bloated sections (OTHER than the Working Principles block, which always stays inline) to `docs/.md` files referenced via `Read docs/.md` pointers - the primary fix for an oversized CLAUDE.md - Internal duplication candidates flagged by Phase 4b (reference outliers, conceptual restatements). Escalate to High if the two occurrences have already drifted out of sync and state contradictory facts - **Exhaustive file-by-file project-structure tree (consolidation candidate)**: the structure section enumerates every file with a per-file description and requires an update on every add/rename. High decay risk, tokens without evergreen value. Proposes consolidation into categorical shape (top-level layout + structural pattern + role per category), keeping file-level annotation only where names alone are ambiguous, where a file is itself a key entry point, or to disambiguate siblings. Per GOLDEN RULE 6, the agent NEVER collapses an exhaustive map autonomously: surfaces it as a per-finding question with options [consolidate as proposed / extract full map to `docs/.md` with pointer / keep verbatim / skip]. Default on unanswered = leave unchanged ### Low Priority (Nice to Have) - Formatting consistency - Minor wording improvements - Additional examples ## Output Depending on your choice: **Audit Only:** - Comprehensive audit report - List of verified vs incorrect claims - Obsolete information flagged - Best practices assessment - Prioritized recommendations - Verification commands to confirm findings **Audit + Improvements:** - Updated `CLAUDE.md` based on your priorities - All critical issues fixed - User-approved improvements applied - Diff showing what changed - Verification commands - Maintenance recommendations ## Tips for Best Results 1. **Start with audit**: Review findings before committing to improvements 2. **Be specific about priorities**: Tell the agent what matters most to your team 3. **Answer pattern questions**: Help agent understand preferred approaches when multiple exist 4. **Review diffs carefully**: Agent shows changes before applying 5. **Provide context**: Explain decisions so agent understands your preferences 6. **Iterate**: It's okay to try improvements and adjust 7. **Run quarterly**: Keep CLAUDE.md fresh with regular maintenance ## Related Commands - `/create-claude-md` - Create new CLAUDE.md from scratch (interactive)