Documentation & CLAUDE.md Optimizer

Target Metrics

• Ideal CLAUDE.md size: ~2.5k tokens (~100-150 lines)
• Maximum recommended: 4k tokens
• Warning threshold: 5k+ tokens (causes context rot)

Execution Strategy

Phase 1: Discovery (sequential)

• CLAUDE.md

  in project root

• .claude/

  directory for commands/settings

docs/

docs/
├── README.md            # Index/overview (required)
├── architecture.md      # Detailed architecture
├── api.md               # API reference
├── deployment.md        # Deploy procedures
├── contributing.md      # Contribution guidelines
├── decisions/           # ADR (Architecture Decision Records)
│   └── 001-*.md
└── guides/              # How-to guides

• File path and type (api, architecture, guide, ADR, etc.)
• Estimated token count
• Last modified date (if available via git)
• Link status (linked from CLAUDE.md or orphaned)

Phase 2: Parallel Analysis (5 simultaneous subagents)

subagent_type: "general-purpose"

Subagent A: Project Stage Detection

• Git history patterns (commit frequency, types of changes)
• package.json/pyproject.toml version (0.x = early, 1.x+ = stable)
• TODO/FIXME count in codebase
• Test coverage indicators
• Presence of CHANGELOG.md

Subagent B: Token Analysis + Anti-Pattern Detection

• Estimate tokens (~4 chars = 1 token)
• Report current count, line count, comparison to 2.5k benchmark

1. Context Stuffing - Verbose explanations, redundant instructions, "just in case" content

   # BAD
   "When implementing authentication, always ensure you follow
   security best practices including input validation, proper
   error handling, secure token storage..."
   # GOOD
   "Auth: validate inputs, handle errors securely, follow auth/ patterns"

2. Static Memory (No Evolution) - No "Learnings" section, no recent updates. Fix: Add learnings section.
3. Missing Plan Mode Guidance - No workflow section. Fix: Add planning instructions.
4. No Verification Loop - No test commands specified. Fix: Add verification requirements.
5. Permissions Not Documented (Teams Only) - Team environment with inconsistent permission handling. Fix: Document safe pre-allowed commands. Note: Skip for private/isolated environments.
6. No Format Standards - No formatting mentioned, no hooks. Fix: Suggest PostToolUse hooks.

Subagent C: Stale Documentation + Code-Doc Drift Detection

1. Stale Documentation - docs/ files don't match current codebase
   • Compare exported functions/classes in code vs documented API
   • Check if code examples in docs use current API signatures
   • Look for documented features that no longer exist
2. Missing Index - docs/ folder exists but has no README.md or index
3. Orphan Docs - Files in docs/ that nothing links to. Scan all markdown files for links, identify unreferenced docs/
4. Code-Doc Drift - Semantic difference between documented and actual API
   • Extract public API from source code (exports, public classes/functions)
   • Parse API documentation in docs/api.md
   • Compare: missing docs, extra docs, signature mismatches

Subagent D: Semantic Sync Analysis

1. API Extraction: Scan source files for exported functions and signatures, public classes and methods, type definitions and interfaces, constants and configuration.
2. Documentation Parsing: From docs/api.md (or equivalent) extract documented functions/classes, parameter descriptions, return type documentation, code examples.
3. Sync Report in this format:

   | Item | Code | Docs | Status |
   |------|------|------|--------|
   | createUser() | ✓ | ✓ | SYNCED |
   | deleteUser() | ✓ | ✗ | UNDOCUMENTED |
   | oldMethod() | ✗ | ✓ | STALE |
   | updateUser(id, data) | (id, data, opts) | (id, data) | DRIFT |

Subagent E: Documentation Ecosystem Analysis

1. Link Graph: Which docs link to which
2. CLAUDE.md Coverage: What's linked in Deep Dive section
3. Orphan Detection: Docs with no incoming links
4. Completeness Score: Based on project stage expectations

• Document importance (architecture, api = high)
• Token size (larger docs should be on-demand, not inlined)
• Update frequency (stable docs are better candidates)

Phase 3: Synthesis (sequential)

Generate Optimized Structure

# Project Name

## Quick Reference
[One-line description]
[Key commands: build, test, lint]

## Architecture
[3-5 bullets max]

## Conventions
[Essential code style only]

## Workflow
- Start complex tasks in Plan mode
- Get approval before implementation
- Break large changes into chunks

## Verification
[Commands Claude should run after changes]

## Deep Dive (read on demand)
- Architecture details: [docs/architecture.md](docs/architecture.md)
- API reference: [docs/api.md](docs/api.md)
- Deployment: [docs/deployment.md](docs/deployment.md)

## Learnings
[Living section from PR reviews]

## Gotchas
[Known issues, workarounds]

Output Format

Current State

• Token estimate: X (target: 2.5k)
• Line count: X
• Status: [OPTIMAL | NEEDS OPTIMIZATION | BLOATED]
• Project Stage: [INIT | ACTIVE | STABLE | MAINTENANCE]

Docs/ Overview

Sync Status

• Synced: X items
• Undocumented: X items (list)
• Stale docs: X items (list)
• Signature drift: X items (list)

Anti-Patterns Found

• Location in file
• Severity: HIGH | MEDIUM | LOW
• Specific fix

Recommendations

Deep Dive Links

## Deep Dive (read on demand)
- [link suggestions based on analysis]

Optimized Version

Modes

• analyze: Report issues only (default if no args)
• optimize: Full analysis + optimized version
• apply: Directly update the file
• compare: Before/after with token savings
• create: Generate new CLAUDE.md from project structure
• sync: Semantic check of docs ↔ code synchronization
• audit: Complete audit of documentation ecosystem
• scaffold: Generate docs/ structure for new project

Mode: sync

1. Extract public API from source code
2. Parse API documentation
3. Generate detailed sync report
4. Recommend specific updates

Mode: audit

1. Map all documentation files
2. Build link graph
3. Detect orphans and missing docs
4. Check completeness for project stage
5. Generate health score and recommendations

Mode: scaffold

docs/
├── README.md           # Simple overview
└── getting-started.md  # Setup instructions

docs/
├── README.md
├── architecture.md
├── api.md
├── contributing.md
└── decisions/
    └── 000-template.md

docs/
├── README.md
├── architecture.md
├── api.md
├── deployment.md
├── contributing.md
├── changelog.md
├── decisions/
│   └── [ADRs]
└── guides/
    └── [how-to guides]

Additional Checks

• Suggest

  .claude/settings.json

  hooks if missing
• Check for team commands in

  .claude/commands/

• Verify docs/ has README.md index
• Check all docs/ files are linked somewhere
• Recommend Deep Dive section if docs/ exists but isn't referenced

Environment Context

• Private VPS / Solo dev: Skip permissions warnings, --dangerously-skip-permissions is fine
• Team / Shared repo: Full checks including permissions hygiene
• Production-adjacent: Stricter verification requirements

Execution Rules

1. ALWAYS use parallel subagents - Phase 2 MUST launch all 5 subagents in a single message with 5 simultaneous Task tool calls. Never run them sequentially.
2. Pass context to subagents - Each subagent needs the project path and file inventory from Phase 1. Include the full list of discovered files in each subagent prompt.
3. Subagents are research-only - Subagents read and analyze. Only the main agent writes/edits files (in Phase 3, apply mode only).
4. Adapt to project size - For small projects (< 5 docs files), you may combine Subagents C+D into one. For projects with no docs/ folder, skip Subagents C, D, E and only run A + B.