| name | generate-docs |
| description | 分析项目代码结构并生成分层的 CLAUDE.md 文档体系。采用渐进式披露策略， 从项目全局架构到各模块设计理念逐层展开，每个 CLAUDE.md 控制在 200 行以内。 重点包含架构设计、关键 API 索引和模块间依赖关系。 使用文件 MD5 增量检测，只重新分析有变更的模块，通过并行 sub-agent 加速。 当用户要求生成文档、更新 CLAUDE.md、整理项目说明、或说"帮我写 CLAUDE.md"时触发此 skill。 也适用于用户提到"文档生成"、"代码文档化"、"项目文档整理"、"generate docs"、 "update project docs"等场景。即使用户只是说"帮我整理下项目结构"或 "我想让 Claude 更好地理解这个项目"，也应使用此 skill。
|
| allowed-tools | Bash, Read, Write, Edit, Glob, Grep, Task |
generate-docs Skill
分析项目代码结构，生成分层 CLAUDE.md 文档体系。AI 生成完整文档，用户直接编辑修改。
增量模式：通过文件 MD5 追踪变更，只重新分析自上次生成以来有修改的模块。
首次运行全量扫描，后续运行自动走增量路径。
使用方式
/generate-docs — 增量更新（仅处理有变更的模块）/generate-docs --full — 强制全量重新生成所有文档/generate-docs server/app/api — 仅为指定目录生成/更新文档- 自然语言："帮我生成 CLAUDE.md"、"更新项目文档"、"整理模块文档"
根据 $ARGUMENTS 决定范围：
- 空 → 增量（整个项目中有变更的模块）
--full → 全量重新生成- 指定路径 → 仅该目录及其子目录（忽略缓存，始终重新分析）
核心理念
每个包目录都有 CLAUDE.md
不按文件数量设门槛。只要是一个有意义的代码目录（有 __init__.py、package.json、
或明确的职责分组），就应该有 CLAUDE.md。小目录文档更简洁（15-30 行）。
基于文件 MD5 的增量更新
不需要每次全量扫描所有文件。缓存文件记录每个目录下各文件的 MD5 值，
下次运行时只重新分析有文件变更的目录。这样即使项目很大，更新也很快。
这种方式不依赖 git，对未纳入版本控制的项目也同样适用。
缓存机制
缓存目录
.claude/cache/generate-docs/
└── md5_map.json # 记录每个文件的 MD5，按目录分组
md5_map.json 格式
{
"server/app/api/agents.py": {
"md5": "a1b2c3d4e5f6...",
"last_analyzed": "2026-03-19T10:30:00"
},
"server/app/models/edict.py": {
"md5": "f6e5d4c3b2a1...",
"last_analyzed": "2026-03-19T10:30:00"
}
}
- key = 文件相对于项目根的路径
- value.md5 = 上次分析时该文件的 MD5 值
- value.last_analyzed = 上次分析时间（ISO 格式）
缓存操作
读取缓存：Phase 1 开始时读取 .claude/cache/generate-docs/md5_map.json（不存在则视为首次运行）
判断变更：对目录内的每个代码文件计算当前 MD5 并与缓存对比：
md5 -q <file>
md5sum <file> | awk '{print $1}'
- MD5 一致 → 文件未变更
- MD5 不一致或缓存中不存在 → 文件有变更
- 某个目录下任何一个文件有变更 → 该目录标记为"需更新"
写入缓存：Phase 4 每生成/更新一个 CLAUDE.md 后，将该目录下所有文件的当前 MD5 写入缓存。
全部完成后将 md5_map.json 写回 .claude/cache/generate-docs/。只更新本次涉及的文件条目，不清除其他条目。
特殊情况
--full 参数 → 忽略缓存，全量分析- 指定路径 → 忽略缓存，该路径始终重新分析
- 新文件（缓存中无记录）→ 视为有变更
- 文件被删除（缓存中有但磁盘上不存在）→ 该目录标记为需更新，清除已删除文件的缓存条目
依赖传播
某个模块变更时，其父级 CLAUDE.md 也可能需要更新（比如模块索引表需要刷新）。
传播规则：
- 子目录有变更 → 父目录的 CLAUDE.md 也标记为需更新
- 根目录 CLAUDE.md 在任何子模块有变更时都需更新（因为它包含模块索引）
执行流程
Phase 1 — Diff（检测变更）
目标：确定哪些目录需要重新生成文档。
- 读取缓存：读取
.claude/cache/generate-docs/md5_map.json，不存在则标记为首次运行
- 扫描代码文件：用 Glob 扫描项目代码文件，识别包边界
- 如果首次运行或
--full：
- 如果增量运行：
- 对每个包目录下的代码文件计算 MD5，与缓存对比
- 目录下有任何文件 MD5 变更 → 标记该目录为"需更新"
- 检查是否有新包目录（有代码文件但缓存中无任何条目）→ 标记为"需新建"
- 应用依赖传播：子目录有变更 → 父目录也标记为"需更新"
- 找到已有 CLAUDE.md：对需更新的目录，读取现有 CLAUDE.md
输出：
- 需更新的目录列表 + 变更文件摘要
- 无变更的目录列表（跳过）
Phase 2 — Plan（规划）
目标：呈现更新计划给用户确认。
将计划以表格形式呈现，标明每个目录的操作和变更原因：
| 路径 | 操作 | 原因 | 变更文件数 |
|------|------|------|-----------|
| ./CLAUDE.md | 更新 | 子模块变更 | — |
| server/app/api/CLAUDE.md | 更新 | agents.py, edicts.py 修改 | 2 |
| server/app/models/CLAUDE.md | 跳过 | 无变更 | 0 |
| web/src/components/CLAUDE.md | 新建 | 新目录 | — |
等待用户确认后进入 Phase 3。
Phase 3 — Analyze（自底向上分析）
目标：从叶子目录向上逐层分析，上层目录直接根据子目录的 CLAUDE.md 总结，不重复读代码。
核心原则：自底向上。 先处理最深层的叶子目录（直接分析代码），再处理它们的父目录（只读子目录的 CLAUDE.md，不看代码）。
步骤
- 按深度分层：将所有需更新的目录按路径深度从深到浅排列，分为多个层级
- 例如：Level 2 =
server/app/api/agents/，Level 1 = server/app/api/，Level 0 = server/app/，Root = .
- 从最深层开始，同层并行：
- 同一层级的目录互相独立，在同一条消息中发出所有 Task 调用并行执行
- 每层完成后再处理上一层
- 叶子目录（无子级 CLAUDE.md 的目录）：
- 使用 Explore sub-agent 分析代码
- prompt 包含：目标目录路径、变更文件列表、已有 CLAUDE.md 内容
- 提取：架构、关键 API、依赖关系
- 非叶子目录（有子级 CLAUDE.md 的目录）：
- 不分析代码，只读取子目录的最终 CLAUDE.md
- 使用 sub-agent 读取所有子级 CLAUDE.md + 该目录自身的入口文件（如
__init__.py），综合总结
- 生成模块概述、子模块索引表、依赖关系汇总
- 项目根 CLAUDE.md（
.）最后处理：
- 读取所有一级子目录的 CLAUDE.md
- 综合为项目全局架构、模块索引表、核心入口表、全局依赖关系
并行分组策略：
- 同一深度层级内的目录放在同一批并行
- 如果同层目录数 > 7，分批执行（避免同时 agent 过多）
- 严格按深度顺序：深层先完成 → 浅层才开始
参考 references/analysis-guide.md 获取叶子目录的代码分析方法。
Phase 4 — Write（生成文档 + 更新缓存）
目标：将分析结果写入 CLAUDE.md，更新缓存。
参考 references/templates.md 获取各层级的模板结构。
-
生成/重写每个 CLAUDE.md（按自底向上的顺序，与 Phase 3 同步进行）
- 叶子目录：按模板生成，基于 sub-agent 的代码分析结果
- 非叶子目录：读取子目录已写好的 CLAUDE.md，综合总结
- 重写时整合已有内容中用户补充的部分
-
更新缓存
- 每写完一个 CLAUDE.md，将该目录下所有代码文件的当前 MD5 写入
md5_map.json
- 全部完成后写回
.claude/cache/generate-docs/md5_map.json
-
输出汇总
更新: 4 个文件
跳过: 7 个文件（无变更）
新建: 1 个文件
已更新:
CLAUDE.md (子模块变更)
server/app/api/CLAUDE.md (agents.py, edicts.py)
server/app/services/CLAUDE.md (edict_service.py)
web/src/components/CLAUDE.md (新增 AgentCard.tsx)
已跳过:
server/app/models/CLAUDE.md (无变更)
...
重要约束
- 重写时保留用户补充内容：已有 CLAUDE.md 中的约定、注意事项、经验知识要整合保留
- 自底向上：叶子目录分析代码，上层目录只读子目录的 CLAUDE.md 来总结
- 遵守目录安全规则：不对数据目录递归扫描
- 中文优先：文档内容使用中文，代码标识符保持原样
- 不注水：小模块就写简短文档，不要为了"看起来完整"而填充无意义内容
- 缓存目录加入 .gitignore：
.claude/cache/ 不应提交到仓库
