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

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