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.