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

Mode	Description
analyze	Report issues only (default)
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. scaffold security generates <project>/.claude/claude-security-guidance.md for the security-guidance plugin
insights	Analyze friction patterns from git history; generate copy-paste-ready CLAUDE.md rules

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

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

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.