| name | readme-wiki |
| description | 为代码库子模块/子目录建立模块级 README 文档体系，并通过 CLAUDE.md 建立导航索引。
当用户提到以下任一情况时触发：代码库太大 AI 翻代码费上下文、给子模块加文档、
创建 README 索引、模块文档化、代码库导航、子系统文档、需要理解某个文件夹的作用、
代码组织结构文档、AI 查看代码时上下文溢出。也适用于任何需要为代码库建立结构化
文档导航的场景，无论语言是 Python/JavaScript/MATLAB/C++/Go 等。
|
README-Wiki：代码库模块文档体系构建
目标
为代码库中的子模块/子目录建立标准化的 README 文档，并通过项目根目录的 CLAUDE.md
（或 AGENTS.md、README.md）建立导航索引。解决 AI 在理解代码逻辑时翻遍大量文件、
上下文溢出的问题。
核心原则
- 按需查阅：AI 被问到子系统问题时，先看对应 README，而非翻遍代码
- 聚焦接口：README 只写"这个模块做什么、对外暴露什么、输入输出是什么"，不写实现细节
- 数据流优先：每个 README 必须包含"谁调用它、它调用谁"的数据流描述
- 标注陷阱：记录常见坑、已知的 bug、过时的实现、与直觉相反的逻辑
- 适度文档：函数名自解释的简单模块不需要 README，避免过度文档化
执行流程
Step 1：扫描代码库结构
扫描当前代码库，识别所有子目录（排除 .git、.claude、node_modules、归档目录、
纯数据目录、临时目录等）。列出：
- 已有 README.md 的目录
- 没有 README.md 的目录
- 已有 README 但内容过于简陋的目录
Step 2：评估每个目录是否需要 README
判断标准（满足任一即需要）：
- 是核心业务模块，被多个其他模块依赖
- 包含复杂的算法或业务逻辑，不是一看就懂的工具函数
- 有已知的 bug、限制、或需要注意的隐含假设
- 是独立实验分支或历史遗留代码，需要标注"不要用"或"有问题"
- 是系统的配置中心、输入输出层、或运行时基础设施
不需要 README 的情况：
- 函数名和代码注释已经足够自解释（如纯配置数据、简单工具函数）
- 归档/历史目录（已在 CLAUDE.md 中标注"非当前实现"）
- 纯数据/输出/临时目录
- 仍在快速迭代、接口不稳定的实验性代码
Step 3：创建/增强 README.md
对每个需要文档的目录，创建或增强 README.md，必须包含以下章节：
# 目录名 — 一句话职责
## 简介
一句话说明这个模块是做什么的，在整个系统中的位置。
## 职责边界
- **做**：...
- **不做**：...
## 核心函数/文件清单
| 函数/文件 | 输入 | 输出 | 说明 |
|-----------|------|------|------|
| `funcA.m` | `x` (n维向量) | `y` (标量) | 核心计算入口 |
| `funcB.m` | 无 | `cfg` (结构体) | 配置读取 |
## 数据流
用 ASCII 图或文字描述谁调用这个模块、这个模块调用谁：
input/ --→ calculate/ --→ coefficient/ --→ calculate_strength/ --→ limit/
## 注意事项 / 常见坑
- 陷阱1：...
- 陷阱2：...
内容要求：
- 函数清单中的"输入/输出"列只写类型和含义，不写实现细节
- 数据流必须标注数据方向，说明模块在系统中的位置
- 注意事项必须包含"为什么这是个坑"（隐含假设、历史原因、与直觉相反的地方）
Step 4：建立根目录导航索引
在项目根目录的 CLAUDE.md（如果存在）或 README.md 中，添加"模块文档导航"章节：
## 模块文档导航
当你需要理解某个子系统的逻辑时，**优先查阅对应模块的 README.md**，
而非直接翻阅代码。
| 想了解什么 | 查阅文档 | 一句话说明 |
|-----------|---------|-----------|
| 想了解强度计算链路 | `arc/calculate_strength/README.md` | 应力计算→极限应力→安全系数 |
| 想了解约束体系 | `arc/limit/README.md` | 行星/平行/全局三级约束 |
| ... | ... | ... |
### 数据流速查
input/ --→ calculate/ --→ coefficient/ --→ calculate_strength/ --→ limit/
如果项目同时有 CLAUDE.md 和 AGENTS.md，两者必须保持同步更新。
Step 5：审查与精简
完成初稿后，重新审视每个 README：
- 是否只是重复了代码注释？如果是，删除该 README
- 是否有"数据流"和"注意事项"章节？如果没有，补充或标记为不需要
- 是否标注了已知问题和限制？
删除过度文档化的 README，只保留有真正信息增量的文档。
Step 6：添加维护规则
在 CLAUDE.md 的"工程规则"部分添加：
模块文档（README）随代码同步更新：修改模块接口、函数签名、数据流或约束逻辑时，
必须同步更新对应 README。过时的文档比没有文档更有害。
输出规范
- 所有 README 使用中文编写（与项目主要语言一致）
- 文件名统一为
README.md（首字母大写）
- 不要在 README 中复制代码实现，只描述接口和职责
- 如果某个目录已有简陋的
readme.md（小写），替换为标准的 README.md
边界与限制
- 本 skill 不处理归档目录（
archive/、legacy/ 等），这些已在 CLAUDE.md 中标注
- 本 skill 不处理纯数据/输出/临时目录
- 本 skill 假设项目根目录已有
CLAUDE.md 或 README.md 作为索引载体；如果没有，
会建议用户先创建
