claude-docu-optimizer

A Claude Code plugin for optimizing CLAUDE.md files and the docs/ documentation ecosystem following battle-tested patterns from Boris Cherny's team at Anthropic.

What it does

Analyzes and optimizes your project documentation to keep Claude Code's context efficient and your docs synchronized with code.

Key features:

• Token analysis with target benchmarks (2.5k ideal, 4k max)
• 15 anti-pattern detection (context stuffing, stale docs, orphan files, code-doc drift, cache-hostile ordering...)
• Semantic sync analysis between code and documentation
• Project stage detection (INIT / ACTIVE / STABLE / MAINTENANCE)
• Documentation ecosystem mapping and link graph analysis

Modes

Installation

Add the marketplace and install the plugin:

claude plugin marketplace add https://github.com/kojott/claude-docu-optimizer
claude plugin install docu-optimizer@claude-docu-optimizer

Updating

claude plugin marketplace update claude-docu-optimizer
claude plugin update docu-optimizer@claude-docu-optimizer

Usage

/docu-optimizer analyze     # Report issues
/docu-optimizer optimize    # Full analysis + optimized version
/docu-optimizer apply       # Directly update CLAUDE.md
/docu-optimizer compare     # Before/after comparison
/docu-optimizer create      # Generate new CLAUDE.md
/docu-optimizer sync        # Check docs ↔ code sync
/docu-optimizer audit       # Full documentation ecosystem audit
/docu-optimizer scaffold    # Generate docs/ structure
/docu-optimizer insights            # Friction-pattern analysis from git
/docu-optimizer scaffold security   # Generate claude-security-guidance.md

Target metrics

Anti-patterns detected

1. Context Stuffing - Verbose, redundant instructions
2. Static Memory (No Evolution) - No evolution/learnings section
3. Missing Plan Mode Guidance - No workflow section
4. Weak Verification Loop - Scored 0-5; low-quality verification (no test command, or "run tests" without specifics) is the anti-pattern
5. Permissions Not Documented (Teams Only) - Team environments only
6. No Format Standards - Missing formatting hooks
7. Stale Documentation - Docs don't match code
8. Missing Index - No docs/README.md
9. Orphan Docs - Unreferenced documentation files
10. Code-Doc Drift - API signatures out of sync
11. Cache-Hostile Ordering - Dynamic content above static (hurts prompt caching)
12. Instruction Overload - >150 instructions degrade adherence
13. Missing Modular Rules - Large monolithic CLAUDE.md without .claude/rules/
14. No Feedback Loop - No mechanism for iterative improvement
15. Missing Emphasis on Critical Rules - Critical rules without IMPORTANT/CRITICAL emphasis

License

MIT + Commons Clause - Free to use, modify, and share. Commercial selling requires author's approval. See LICENSE for details.