project-docs

1# project-docs：项目深度文档生成
2 
3输出到项目的 `docs/` 目录。核心约束：文档里的代码、类名、路径都必须来自真实文件，见 Phase 3。
4 
5## Step 0：判断要做哪种
6 
7| 用户表述 | 做什么 |
8|---|---|
9| 生成项目文档 / 新人文档 / 深入理解项目（没指定篇目） | 全部生成，Phase 1 → 2 → 3 → 4 |
10| 帮我写架构文档 / 只要代码导读 / 写构建和调试 | 只写指定的几篇，读项目的范围可相应缩小 |
11| 代码改了，更新文档 / 文档过期了 | 读 `docs/.project-map.md`，比对现在的代码，只重写受影响的篇目 |
12 
13**`docs/` 已经有内容时**：先列出已有文件，问用户是覆盖、跳过已存在的、还是备份到 `docs.bak/`。不要直接盖掉。
14 
15**不该用这个 skill 的情况**：用户要的是论文章节、项目梳理、重点问题清单、简历项目描述——也就是给导师、评委、HR、领导看，且格式由对方指定的东西，用 **codegen-doc**。这个 skill 只管给新同事看、要能照着上手的文档。
16 
17---
18 
19## Phase 1：先读项目，把结果记下来
20 
21记到 `docs/.project-map.md`。后面每一篇要用的路径、类名、代码，都从这个文件取。
22 
23分三步读，**不要试图把所有源文件都读完**：
24 
251. **看轮廓** —— 目录树、构建和依赖文件、README，判断用什么语言、属于哪类项目
262. **看骨架** —— 入口文件读全文、接口和类型定义、列出每个模块干什么
273. **跟一个完整例子走一遍** —— 挑一个有代表性的示例或功能，从入口追到结束
28 
29怎么读、记成什么格式、什么时候可以停，见 [reference/explore.md](reference/explore.md)。把那份模板填完再进 Phase 2，其中术语表至少 5 条。
30 
31---
32 
33## Phase 2：按项目类型决定写哪几篇
34 
35```
3601_architecture.md        → 架构：项目长什么样
3702_philosophy.md          → 思想：为什么这样设计
3803_lang_concepts.md       → 语言特性：读代码前的准备
3904_code_walkthrough.md    → 代码导读：跟着真实流程走一遍
4005_runtime_model.md       → 运行时：并发和生命周期
4106_build_guide.md         → 构建：怎么编译运行
4207_integration_guide.md   → 对接：怎么写新功能
4308_debug_guide.md         → 调试：出问题怎么查
4409_design_conventions.md  → 规范：怎么设计得更好
45```
46 
47默认模板偏向 C++ 那类"要编译、有多线程、有进程间通信"的项目。**前端、数据脚本、库这类项目必须按对照表替换或跳过对应篇目**，见 [reference/project-types.md](reference/project-types.md)。
48 
49**编号固定，跳过的留空号，不要往前挪。** 跳过 05 就是 `01,02,03,04,06,07,08,09`，原因见 project-types.md。
50 
51---
52 
53## Phase 3：写
54 
55### 贴代码前先读那个文件
56…