| name | project-docs |
| description | 对任意代码项目生成一套面向新人的循序渐进文档集，输出到 docs/ 目录。含架构、设计思想、语言特性、代码导读、运行时模型、构建、对接、调试、设计规范共 9 篇，支持全部生成 / 只写几篇 / 更新已有文档。当用户提到"生成项目文档"、"新人文档"、"上手文档"、"架构文档"、"代码导读"、"项目理解"、"深入理解项目"、"onboarding 文档"、"给新同事看的文档"时使用。要按用户给的格式写论文章节、项目梳理、重点问题、简历项目描述的，用 codegen-doc。 |
project-docs：项目深度文档生成
输出到项目的 docs/ 目录。核心约束：文档里的代码、类名、路径都必须来自真实文件，见 Phase 3。
Step 0：判断要做哪种
| 用户表述 | 做什么 |
|---|
| 生成项目文档 / 新人文档 / 深入理解项目（没指定篇目） | 全部生成，Phase 1 → 2 → 3 → 4 |
| 帮我写架构文档 / 只要代码导读 / 写构建和调试 | 只写指定的几篇，读项目的范围可相应缩小 |
| 代码改了，更新文档 / 文档过期了 | 读 docs/.project-map.md，比对现在的代码，只重写受影响的篇目 |
docs/ 已经有内容时：先列出已有文件，问用户是覆盖、跳过已存在的、还是备份到 docs.bak/。不要直接盖掉。
不该用这个 skill 的情况：用户要的是论文章节、项目梳理、重点问题清单、简历项目描述——也就是给导师、评委、HR、领导看，且格式由对方指定的东西，用 codegen-doc。这个 skill 只管给新同事看、要能照着上手的文档。
Phase 1：先读项目，把结果记下来
记到 docs/.project-map.md。后面每一篇要用的路径、类名、代码，都从这个文件取。
分三步读，不要试图把所有源文件都读完：
- 看轮廓 —— 目录树、构建和依赖文件、README，判断用什么语言、属于哪类项目
- 看骨架 —— 入口文件读全文、接口和类型定义、列出每个模块干什么
- 跟一个完整例子走一遍 —— 挑一个有代表性的示例或功能，从入口追到结束
怎么读、记成什么格式、什么时候可以停，见 reference/explore.md。把那份模板填完再进 Phase 2，其中术语表至少 5 条。
Phase 2：按项目类型决定写哪几篇
01_architecture.md → 架构：项目长什么样
02_philosophy.md → 思想：为什么这样设计
03_lang_concepts.md → 语言特性：读代码前的准备
04_code_walkthrough.md → 代码导读：跟着真实流程走一遍
05_runtime_model.md → 运行时：并发和生命周期
06_build_guide.md → 构建：怎么编译运行
07_integration_guide.md → 对接：怎么写新功能
08_debug_guide.md → 调试：出问题怎么查
09_design_conventions.md → 规范：怎么设计得更好
默认模板偏向 C++ 那类"要编译、有多线程、有进程间通信"的项目。前端、数据脚本、库这类项目必须按对照表替换或跳过对应篇目，见 reference/project-types.md。
编号固定，跳过的留空号，不要往前挪。 跳过 05 就是 01,02,03,04,06,07,08,09，原因见 project-types.md。
Phase 3：写
贴代码前先读那个文件
.project-map.md 里只有路径，不是代码原文。要贴哪段代码，先 Read 那个文件确认现在的内容。引用统一带位置：src/core/channel.cpp:120-135。
不这样做，新人会照着一个不存在的类名去搜索——比没有文档更糟。
写给谁看
刚接触项目的新同学。不假设他们了解项目背景，但假设有基础编程能力。
每篇都要有的
- 开头一个
> 一句话说明这篇解决什么问题
- 先说"是什么" → 再说"为什么" → 最后说"怎么做"
- 有对比（❌ 不用框架怎么写 vs ✅ 用框架怎么写）
- 抽象的概念配一个生活里的例子
- 结尾一张速查表或检查清单
图怎么画
| 要表达什么 | 用什么 |
|---|
| 调用关系、时序、状态变化、类之间的继承 | Mermaid |
| 目录树、分层框图、内存布局 | ASCII |
ASCII 图宽度控制在 80 字符内，超了在 Typora 和网页里会折行错位。
多长
每篇 300–600 行。不到 300 说明挖得不够深；超过 600 该拆节。避免一篇两千行、另一篇三十行。
用词
同一个东西前后用同一个词，都按 .project-map.md 里的术语表来。在一篇里叫"通道"、另一篇里叫"管道"，是新人最容易卡住的地方。
不要生造名词。能用大白话说清的地方不要起一个新词让读者去记。
不要
- "如上所述"、"综上"这类套话
- 读者已经知道的废话
- 编造代码，见上面第一条
- 术语第一次出现不解释
- 命令和示例没实际跑过却不说明——跑不了的标
⚠️ 未验证
各篇模板：reference/chapters-01-04.md、reference/chapters-05-09.md。
Phase 4：写目录页，然后自查
- 写
docs/README.md，列出所有篇目，说明不同目的该读哪几篇，跳过的篇目写明原因。模板见 reference/quality.md
- 每篇对着 quality.md 里的清单过一遍
- 跟用户说清四件事：写了哪几篇各多少行、跳过哪几篇为什么、哪些内容标了
⚠️ 未验证、.project-map.md 里还剩什么没弄清。后两条最容易漏，但正是用户判断能不能直接把文档给新人看的依据
