Maintain Claude Md

Maintain CLAUDE.md File

CRITICAL RULES

1. Keep CLAUDE.md under 40,000 characters. This is a hard cap (Claude Code surfaces a performance warning above this threshold). Run wc -c CLAUDE.md after every edit. Target <35k to leave headroom. If the audit finds the file already over 40k, the primary fix is to extract sections to docs/<topic>.md and replace them with thin Read docs/<topic>.md pointers. Never finalize an edit that leaves the file over 40k.
2. Verify against codebase. Every claim in CLAUDE.md must be checked against actual files, commands, and dependencies.
3. Show findings before changing. Present the audit report and get approval before modifying anything.
4. Preserve existing content by default. NEVER remove existing references, sections, paragraphs, bullets, or pointers from CLAUDE.md unless a cross-verification against the codebase, dependency manifests, or external sources proves them false or obsolete. Length, perceived redundancy, "old-style" formatting, or personal aesthetic preference are NOT valid reasons to remove content. Extraction to docs/<topic>.md with a pointer is acceptable (the information stays accessible); silent deletion is not.
5. ALWAYS ask the user about every drift identified. For each drift (incorrect path, broken command, obsolete dependency, missing claim, stale code snippet, internal duplication candidate flagged by Phase 4b, oversized section, anything else flagged by the audit), the agent MUST surface it to the user via AskUserQuestion and let the user decide the action. Do NOT batch-apply fixes autonomously, even for "obviously correct" critical issues. Dedup merges are deletions of the redundant occurrences and fall under the same per-item gate (rule 4 + rule 5). The audit report enumerates findings; the user chooses, per finding, among concrete options such as [fix as proposed / keep verbatim / extract to docs/<topic>.md with pointer / merge into the most actionable occurrence / replace with cross-reference / skip for now / other]. Default action on a finding the user has not yet decided is leave unchanged. The only edits the agent applies without per-item confirmation are the user's already-given answers, in the same session.
6. Never delete user preferences unless the user explicitly approves. Preferences (coding style, workflow choices) are intentional.
7. Never enter plan mode. Execute immediately.
8. Backfill the canonical Working Principles block. Audit is not just detection - it is active upgrade. Maintain MUST always check and propose insertion of the canonical ## Working Principles block, independent of other findings. Three states to handle, all severity High:
   • Block missing entirely: insert verbatim (5 principles, with 3 sub-bullets under each of principles 1-4).
   • Block present, missing one or more principles (in particular the locally authored #5 Centralize Shared Logic, which CLAUDE.md files created before plugin v1.12.0 will not contain): insert the missing principles surgically without rewriting unrelated user additions.
   • Block present with all 5 principles, but missing the 3 sub-bullets under principles 1-4 (the case for any CLAUDE.md created before plugin v1.14.0): insert the sub-bullets in place via surgical Edit. Never substitute the block with an external GitHub link or a docs/agentic-coding-guidelines.md pointer. The deeper meta-rules ship as inline sub-bullets so the block is self-contained.
9. Verify the canonical Test-Suite Rules block (conditional). When the project has a test suite (test directories or runner config present), check the presence and integrity of the canonical ## Test-Suite Rules block (7 rules, see the agent's CONDITIONAL SECTION). Missing, gutted, or weakened (a rule rewritten to permit what it forbids) is a High finding surfaced per rule 5, with an offer to insert the canonical text verbatim. When the project has no tests, absence is correct and is NOT a finding.

This command launches an interactive session to audit and optionally improve your CLAUDE.md file. It verifies accuracy, detects obsolete information, and guides you through prioritized improvements.

Pre-flight: detect existing X-ray output

Before the agent starts its own bottom-up analysis, check whether the project already has technical-reference output on disk from a previous /codebase-xray:analyze session:

ls .codebase-xray/01-structure.md .codebase-xray/02-interfaces.md 2>/dev/null

If both files exist, prompt the user:

Found .codebase-xray/ from a previous /codebase-xray:analyze session.

For an AUDIT, X-ray output is especially valuable: every claim in
CLAUDE.md can be cross-checked against an already-verified technical
snapshot. Drift between CLAUDE.md and the X-ray findings will be
surfaced explicitly (e.g., "CLAUDE.md says webpack but 01-structure.md
shows Vite").

Use X-ray output as the audit ground truth?
  [Y] Use X-ray output + spot-checks against current code
  [n] Re-analyze bottom-up (current behavior)

If the user accepts, the spawned claude-md-auditor agent skips Phase 1 (Bottom-Up Discovery) and uses .codebase-xray/01-structure.md + .codebase-xray/02-interfaces.md as the verification baseline, with 3-5 spot-checks against current code to confirm the X-ray isn't stale. Drift findings cite both the CLAUDE.md line AND the contradicting .codebase-xray/<file>:<section> 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/<topic>.md and link via Read docs/<topic>.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/<topic>.md and replacing with a thin Read docs/<topic>.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/<topic>.md and replace with Read docs/<topic>.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/<topic>.md files referenced via Read docs/<topic>.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/<topic>.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)