| name | project-docs |
| description | 对任意代码项目生成一套面向新人的循序渐进文档集，输出到 docs/ 目录。包含架构、设计思想、代码导读、运行时模型、构建系统、对接指南、调试指南、语言特性、设计规范共 9 篇。当用户提到"生成项目文档"、"写文档"、"新人文档"、"项目理解"、"深入理解项目"时使用。 |
project-docs：项目深度文档生成
工作流程
Phase 1：探索项目（先做这步，再写任何文档）
用 Explore agent 对项目做全面探索，需要掌握：
- 目录结构全貌
- 主要语言和框架
- 入口文件（main / index / app 等）
- 构建系统（Makefile / CMake / package.json / build.gradle 等）
- 核心库/模块及其职责
- 有没有示例/演示代码（example / demo / test）
- 关键类/接口的继承和组合关系
- 进程间/模块间通信机制（IPC / RPC / 消息队列 / 事件总线等）
提示词参考：
请全面探索项目，读取所有源文件内容。需要了解：目录结构、入口文件、
核心类的继承关系、模块间通信方式、构建文件、示例代码。
Phase 2：确定文档顺序
根据探索结果，按以下顺序生成 9 篇文档，语言特性文档（第3篇）放在代码导读之前：
01_framework_architecture.md → 架构：项目长什么样
02_framework_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 → 规范：怎么设计得更好
如果某篇不适用（如项目没有多线程，跳过05），跳过即可，其余编号顺延。
Phase 3：写作要求
面向读者：刚接触项目的新同学，不假设读者了解项目背景，但假设读者有基础编程能力。
每篇文档的固定结构：
- 顶部用
> 一句话说明本篇目标 的引用块
- 从"是什么"开始，再讲"为什么"，最后讲"怎么做"
- 大量使用 ASCII 图、表格、代码注释
- 对比写法（❌ 没有框架 vs ✅ 用框架）
- 类比说明（把抽象概念比作生活中的事物）
- 结尾附速查表或检查清单
写作禁忌：
- 不用"如上所述"、"综上"等套话
- 不写读者已经知道的废话
- 代码示例必须是项目里真实存在的代码，不造假
- 专业术语首次出现时解释
详细模板见 reference.md。
