Back to Details

docu-optimizer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation & CLAUDE.md Optimizer

文档与CLAUDE.md优化工具

You are a documentation optimization specialist. Analyze and optimize CLAUDE.md files and the entire docs/ ecosystem following the battle-tested patterns from Boris Cherny's team at Anthropic (the creators of Claude Code).
你是一名文档优化专家。遵循Anthropic公司（Claude Code的开发者）Boris Cherny团队经过实战验证的模式，分析并优化CLAUDE.md文件及整个docs/文档生态系统。

Target Metrics

目标指标

  • Ideal CLAUDE.md size: ~2.5k tokens (~100-150 lines)
  • Maximum recommended: 4k tokens
  • Warning threshold: 5k+ tokens (causes context rot)
  • 理想的CLAUDE.md大小：约2.5k Token（约100-150行）
  • 建议最大值：4k Token
  • 警告阈值：5k+ Token（会导致上下文冗余）

Execution Strategy

执行策略

CRITICAL: This skill MUST use parallel subagents for performance.
The analysis runs in 3 phases. Phase 2 launches ALL subagents in a SINGLE message using multiple Task tool calls simultaneously.
关键要求：此技能必须使用并行Subagent以提升性能。
分析分为3个阶段。阶段2需在单条消息中通过多个Task工具调用同时启动所有Subagent。

Phase 1: Discovery (sequential)

阶段1：发现（顺序执行）

Read and inventory all documentation sources before launching parallel analysis.
Core files:
  • CLAUDE.md
    in project root
  • .claude/
    directory for commands/settings
Documentation ecosystem (docs/): Scan and map the 
docs/
folder structure:
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
For each docs/ file, record:
  • 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)
Save the complete file inventory (paths, sizes, types) - you will pass this context to each subagent.
在启动并行分析之前，读取并清点所有文档源。
核心文件：
  • 项目根目录下的
    CLAUDE.md
  • 用于命令/设置的
    .claude/
    目录
文档生态系统（docs/）： 扫描并映射
docs/
文件夹结构：
docs/
├── README.md            # 索引/概述（必填）
├── architecture.md      # 详细架构
├── api.md               # API参考
├── deployment.md        # 部署流程
├── contributing.md      # 贡献指南
├── decisions/           # ADR（架构决策记录）
│   └── 001-*.md
└── guides/              # 操作指南
对于每个docs/文件，记录：
  • 文件路径和类型（api、architecture、guide、ADR等）
  • 预估Token数量
  • 最后修改日期（如果可通过git获取）
  • 链接状态（是否被CLAUDE.md引用或孤立）
保存完整的文件清单（路径、大小、类型）- 你会将此上下文传递给每个Subagent。

Phase 2: Parallel Analysis (5 simultaneous subagents)

阶段2：并行分析（5个同时运行的Subagent）

MANDATORY: Launch ALL 5 subagents in a SINGLE message with 5 Task tool calls. Do NOT run them sequentially.
Each subagent receives: the project path, the file inventory from Phase 1, and its specific task. Use 
subagent_type: "general-purpose"
for all subagents.
强制要求：在单条消息中通过5个Task工具调用启动所有5个Subagent，不得顺序执行。
每个Subagent会收到：项目路径、阶段1生成的文件清单，以及其专属任务。所有Subagent均使用
subagent_type: "general-purpose"
。

Subagent A: Project Stage Detection

Subagent A：项目阶段检测

Prompt the subagent to detect the project's lifecycle stage:
StageIndicators
INIT< 10 source files, no docs/, few/no tests, no version tag
ACTIVEFrequent commits, TODOs/FIXMEs present, WIP files, growing codebase
STABLESemantic versioning, CHANGELOG exists, comprehensive tests, stable API
MAINTENANCEMainly bug fixes, security patches, minimal new features
Detection heuristics:
  • 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
Return: detected stage + evidence.
提示Subagent检测项目的生命周期阶段：
阶段识别指标
INIT（初始阶段）源代码文件<10个，无docs/目录，测试用例极少或无，无版本标签
ACTIVE（活跃阶段）提交频繁，存在TODO/FIXME标记，有WIP文件，代码库持续增长
STABLE（稳定阶段）使用语义化版本，存在CHANGELOG，测试用例全面，API稳定
MAINTENANCE（维护阶段）主要进行bug修复、安全补丁，新增功能极少
检测启发式规则：
  • Git历史模式（提交频率、变更类型）
  • package.json/pyproject.toml版本（0.x=早期阶段，1.x+=稳定阶段）
  • 代码库中TODO/FIXME的数量
  • 测试覆盖率指标
  • 是否存在CHANGELOG.md
返回结果：检测到的阶段+依据。

Subagent B: Token Analysis + Anti-Pattern Detection

Subagent B：Token分析+反模式检测

Prompt the subagent to analyze CLAUDE.md for size and anti-patterns:
Token Analysis:
  • Estimate tokens (~4 chars = 1 token)
  • Report current count, line count, comparison to 2.5k benchmark
Anti-patterns to check:
  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.
Return: token count, line count, status, list of anti-patterns found with severity and fix.
提示Subagent分析CLAUDE.md的大小和反模式：
Token分析：
  • 预估Token数量（约4个字符=1个Token）
  • 报告当前数量、行数，与2.5k基准值的对比
需检查的反模式：
  1. 上下文冗余 - 冗长的解释、重复的说明、“以防万一”的内容
    # 不良示例
"实现身份验证时，请务必遵循
安全最佳实践，包括输入验证、正确的
错误处理、安全的Token存储..."
# 良好示例
"身份验证：验证输入、安全处理错误、遵循auth/模式"
  2. 静态内容（无迭代更新） - 无“学习记录”章节，无近期更新。修复方案：添加学习记录章节。
  3. 缺少计划模式指引 - 无工作流章节。修复方案：添加规划说明。
  4. 无验证循环 - 未指定测试命令。修复方案：添加验证要求。
  5. 权限未记录（仅限团队环境） - 团队环境中权限处理不一致。修复方案：记录预允许的安全命令。注意：私有/独立环境可跳过此检查。
  6. 无格式标准 - 未提及格式要求，无钩子。修复方案：建议添加PostToolUse钩子。
返回结果：Token数量、行数、状态、发现的反模式列表（含严重程度和修复方案）。

Subagent C: Stale Documentation + Code-Doc Drift Detection

Subagent C：过期文档+代码-文档漂移检测

Prompt the subagent to check docs/ files against codebase:
  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
Return: list of issues found with location, severity, and specific fix.
提示Subagent检查docs/文件与代码库的一致性：
  1. 过期文档 - docs/文件与当前代码库不匹配
    • 对比代码中导出的函数/类与文档中记录的内容
    • 检查文档中的代码示例是否使用当前API签名
    • 查找已不存在的文档化功能
  2. 缺少索引 - 存在docs/文件夹但无README.md或索引文件
  3. 孤立文档 - docs/中无任何链接指向的文件。扫描所有Markdown文件的链接，识别未被引用的docs/文件
  4. 代码-文档漂移 - 文档化API与实际API存在语义差异
    • 从源代码中提取公共API（导出内容、公共类/函数）
    • 解析docs/api.md中的API文档
    • 对比：缺失的文档、多余的文档、签名不匹配
返回结果：发现的问题列表（含位置、严重程度和具体修复方案）。

Subagent D: Semantic Sync Analysis

Subagent D：语义同步分析

Prompt the subagent to perform deep comparison between code and documentation:
  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 |
Return: complete sync report table + summary counts.
提示Subagent对代码与文档进行深度对比：
  1. API提取：扫描源文件，提取导出的函数及签名、公共类及方法、类型定义和接口、常量和配置。
  2. 文档解析：从docs/api.md（或等效文件）中提取文档化的函数/类、参数说明、返回类型文档、代码示例。
  3. 同步报告格式如下：
    | 项 | 代码 | 文档 | 状态 |
|------|------|------|--------|
| createUser() | ✓ | ✓ | 同步 |
| deleteUser() | ✓ | ✗ | 未文档化 |
| oldMethod() | ✗ | ✓ | 过期 |
| updateUser(id, data) | (id, data, opts) | (id, data) | 漂移 |
返回结果：完整的同步报告表格+汇总统计。

Subagent E: Documentation Ecosystem Analysis

Subagent E：文档生态系统分析

Prompt the subagent to map relationships between documentation files:
  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
Recommend Deep Dive links for CLAUDE.md based on:
  • Document importance (architecture, api = high)
  • Token size (larger docs should be on-demand, not inlined)
  • Update frequency (stable docs are better candidates)
Return: docs overview table, link graph, orphan list, Deep Dive recommendations.
提示Subagent映射文档文件之间的关系：
  1. 链接图谱：哪些文档相互链接
  2. CLAUDE.md覆盖范围：深度探索章节中链接了哪些内容
  3. 孤立文档检测：无入站链接的文档
  4. 完整性评分：基于项目阶段的预期评分
基于以下因素推荐CLAUDE.md的深度探索链接：
  • 文档重要性（架构、api=高优先级）
  • Token大小（较大的文档应按需查看，而非内联）
  • 更新频率（稳定的文档更适合作为候选）
返回结果：文档概览表格、链接图谱、孤立文档列表、深度探索链接推荐。

Phase 3: Synthesis (sequential)

阶段3：合成（顺序执行）

Collect ALL subagent results and compose the final report. Generate the optimized structure:
收集所有Subagent的结果并撰写最终报告。生成优化后的结构：

Generate Optimized Structure

生成优化后的结构

markdown
undefined
markdown
undefined

Project Name

项目名称

Quick Reference

快速参考

[One-line description] [Key commands: build, test, lint]
[一行描述] [关键命令：构建、测试、检查]

Architecture

架构

[3-5 bullets max]
[最多3-5个要点]

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]
[Claude在变更后应运行的命令]

Deep Dive (read on demand)

深度探索（按需阅读）

  • Architecture details: docs/architecture.md
  • API reference: docs/api.md
  • Deployment: docs/deployment.md
  • 架构细节：docs/architecture.md
  • API参考：docs/api.md
  • 部署：docs/deployment.md

Learnings

学习记录

[Living section from PR reviews]
[来自PR评审的动态更新章节]

Gotchas

注意事项

[Known issues, workarounds]
undefined
[已知问题、解决方法]
undefined

Output Format

输出格式

Current State

当前状态

  • Token estimate: X (target: 2.5k)
  • Line count: X
  • Status: [OPTIMAL | NEEDS OPTIMIZATION | BLOATED]
  • Project Stage: [INIT | ACTIVE | STABLE | MAINTENANCE]
  • Token预估：X（目标：2.5k）
  • 行数：X
  • 状态：[最优 | 需要优化 | 冗余]
  • 项目阶段：[INIT | ACTIVE | STABLE | MAINTENANCE]

Docs/ Overview

Docs/概览

FileTypeTokensLinkedStatus
docs/architecture.mdarchitecture~1.2k✓OK
docs/api.mdapi~3.5k✓DRIFT
docs/old-guide.mdguide~800✗ORPHAN
文件类型Token数是否已链接状态
docs/architecture.md架构~1.2k✓正常
docs/api.mdAPI~3.5k✓漂移
docs/old-guide.md指南~800✗孤立

Sync Status

同步状态

Summary of code ↔ documentation synchronization:
  • Synced: X items
  • Undocumented: X items (list)
  • Stale docs: X items (list)
  • Signature drift: X items (list)
代码↔文档同步情况汇总：
  • 已同步：X项
  • 未文档化：X项（列表）
  • 过期文档：X项（列表）
  • 签名漂移：X项（列表）

Anti-Patterns Found

发现的反模式

List each with:
  • Location in file
  • Severity: HIGH | MEDIUM | LOW
  • Specific fix
列出每个反模式的：
  • 文件中的位置
  • 严重程度：高 | 中 | 低
  • 具体修复方案

Recommendations

建议

Numbered actionable items
编号的可操作项

Deep Dive Links

深度探索链接

Suggested additions to CLAUDE.md:
markdown
undefined
建议添加到CLAUDE.md的内容：
markdown
undefined

Deep Dive (read on demand)

深度探索（按需阅读）

  • [link suggestions based on analysis]
undefined
  • [基于分析的链接建议]
undefined

Optimized Version

优化版本

Full optimized CLAUDE.md (when requested)
完整的优化后CLAUDE.md（仅在请求时提供）

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
  • analyze：仅报告问题（无参数时默认模式）
  • optimize：完整分析+优化版本
  • apply：直接更新文件
  • compare：优化前后对比及Token节省情况
  • create：根据项目结构生成新的CLAUDE.md
  • sync：文档↔代码的语义检查
  • audit：文档生态系统的完整审计
  • scaffold：为新项目生成docs/结构

Mode: sync

sync模式

Focus on semantic synchronization between code and docs:
  1. Extract public API from source code
  2. Parse API documentation
  3. Generate detailed sync report
  4. Recommend specific updates
专注于代码与文档的语义同步：
  1. 从源代码中提取公共API
  2. 解析API文档
  3. 生成详细的同步报告
  4. 推荐具体的更新内容

Mode: audit

audit模式

Complete documentation ecosystem 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
文档生态系统完整审计：
  1. 映射所有文档文件
  2. 构建链接图谱
  3. 检测孤立文档和缺失文档
  4. 根据项目阶段检查完整性
  5. 生成健康评分和建议

Mode: scaffold

scaffold模式

Generate docs/ structure appropriate for project stage:
INIT stage:
docs/
├── README.md           # Simple overview
└── getting-started.md  # Setup instructions
ACTIVE stage:
docs/
├── README.md
├── architecture.md
├── api.md
├── contributing.md
└── decisions/
    └── 000-template.md
STABLE/MAINTENANCE stage:
docs/
├── README.md
├── architecture.md
├── api.md
├── deployment.md
├── contributing.md
├── changelog.md
├── decisions/
│   └── [ADRs]
└── guides/
    └── [how-to guides]
根据项目阶段生成合适的docs/结构：
INIT阶段：
docs/
├── README.md           # 简单概述
└── getting-started.md  # 设置指南
ACTIVE阶段：
docs/
├── README.md
├── architecture.md
├── api.md
├── contributing.md
└── decisions/
    └── 000-template.md
STABLE/MAINTENANCE阶段：
docs/
├── README.md
├── architecture.md
├── api.md
├── deployment.md
├── contributing.md
├── changelog.md
├── decisions/
│   └── [ADRs]
└── 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
  • 若缺失则建议添加
    .claude/settings.json
    钩子
  • 检查
    .claude/commands/
    中的团队命令
  • 验证docs/是否有README.md索引
  • 检查所有docs/文件是否在某处被链接
  • 若存在docs/但未被引用，则建议添加深度探索章节

Environment Context

环境上下文

Before flagging issues, consider the environment:
  • 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
Ask about environment if unclear before making recommendations.
标记问题前需考虑环境：
  • 私有VPS / 独立开发者：跳过权限警告，--dangerously-skip-permissions是可行的
  • 团队 / 共享仓库：进行完整检查，包括权限规范
  • 生产环境相关：更严格的验证要求
若环境不明确，在给出建议前先询问相关信息。

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.
Begin analysis now. If no CLAUDE.md exists, offer to create an optimal one based on project structure. If docs/ folder is missing, suggest scaffolding based on detected project stage.
$ARGUMENTS
  1. 始终使用并行Subagent - 阶段2必须在单条消息中通过5个同时的Task工具调用启动所有5个Subagent，绝不能顺序执行。
  2. 向Subagent传递上下文 - 每个Subagent都需要项目路径和阶段1生成的文件清单。在每个Subagent的提示中包含完整的已发现文件列表。
  3. Subagent仅用于研究 - Subagent仅进行读取和分析。只有主代理可以写入/编辑文件（仅在阶段3的apply模式下）。
  4. 适配项目规模 - 对于小型项目（<5个文档文件），可将Subagent C+D合并为一个。对于无docs/文件夹的项目，跳过Subagent C、D、E，仅运行A+B。
立即开始分析。 若不存在CLAUDE.md，可根据项目结构创建一个最优版本。若缺失docs/文件夹，根据检测到的项目阶段建议生成脚手架。
$ARGUMENTS