---
id: xstongxue/best-skills/project-docs
version: "26d5847a"
license: Apache-2.0
install: manual
updated: 2026-07-19
---

# project-docs — project-docs creates a structured 9-part documentation suite tailored for new team members joining a codebase. It explores your project's structure, frameworks, and dependencies, then produces guides covering architecture, design philosophy, language fundamentals, code walkthroughs, runtime behavior, build systems, integration patterns, debugging strategies, and design conventions—all written for readers new to the project.

Publisher: xstongxue · Stars: 2407 · Updated: 2026-07-19

Install (manual): `git clone https://github.com/xstongxue/best-skills`

## SKILL.md

# 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](reference.md)。

---

### Phase 4：生成后检查

```
[ ] docs/ 目录下有 9 个文件（或合理数量）
[ ] 每篇开头有 > 引用块说明目标
[ ] 有 ASCII 图或表格辅助理解
[ ] 代码示例来自真实项目文件
[ ] 语言特性文档（03）在代码导读（04）之前
[ ] 新人能从 01 读到 09，循序渐进，不跳跃
```

[View on SkillFed](https://skillfed.io/xstongxue/best-skills/project-docs) · [View on GitHub](https://github.com/xstongxue/best-skills)