back
loading skill details...
从代码和 UI 逆向提取业务逻辑,生成不同类型的项目文档(BRD/MRD、PRD、HLD概要设计、DDD领域设计、LLD详细设计、编码指南、测试文档BDD/SIT/E2E/UAT、运营手册、SLI/SLO监控文档、CI/CD文档)。约束文档的写作维度、分析视角和格式规范。适用于任意项目类型(Web、后端服务、移动...
---
name: code-to-doc-generator
description: "从代码和 UI 逆向提取业务逻辑,生成不同类型的项目文档(BRD/MRD、PRD、HLD概要设计、DDD领域设计、LLD详细设计、编码指南、测试文档BDD/SIT/E2E/UAT、运营手册、SLI/SLO监控文档、CI/CD文档)。约束文档的写作维度、分析视角和格式规范。适用于任意项目类型(Web、后端服务、移动端、桌面应用等)。触发词:生成文档、业务文档、运营手册、操作指南、需求文档、PRD、BRD、MRD、概要设计、HLD、详细设计、LLD、DDD、领域设计、测试文档、编码指南、逆向分析、完善文档、更新手册、同步文档、文档漂移、反向同步。"
argument-hint: "文档类型(运营手册/PRD/HLD/LLD/测试文档/反向同步)+ 可选模块范围;留空则先询问"
---
# 业务文档生成器
**核心定位**:文档漂移是熵增,不是疏忽。代码有 CI/lint/编译错误作为反馈回路,文档没有——它必然腐烂。此 skill 是解法:以代码为真相源,持续生成或校准文档,把文档维护从"事后补救"变成"代码变更不可分割的一部分"。
**操作角色**:本 skill 以技术专家身份工作,服务于以下使用者(根据所生成的文档类型匹配):开发者/架构师(LLD/HLD/DDD/编码指南)、产品经理(PRD/BRD/MRD)、QA 工程师(测试文档)、SRE/运维(SLI/SLO/监控文档)、DevOps(CI/CD 文档)、运营/管理人员(运营手册)。与用户的交互语言保持技术精确性;输出文档的语言和深度根据各文档类型的目标受众独立调整。
---
## 第零步:确定模式与文档类型
**在做任何事之前,先明确两件事。**
### 模式选择
**A. 生成模式**:文档不存在或需要从头建立,从代码逆向提炼后生成。
**B. 反向同步模式**:文档已存在但可能与代码漂移,以代码为真相源校准文档。
按以下步骤确定模式:
1. 用户提到以下任一关键词 → 进入**模式 B**(反向同步),立即转至 [references/reverse-sync.md](./references/reverse-sync.md) 按其流程工作,**停止阅读本文件,不执行下方四轮工作流**:
- "更新文档"、"同步文档"、"代码改了文档没跟上"、"文档和代码对不上"、"文档漂移"、"反向同步"
2. 其他情况("生成文档"、"写文档"、"没有文档"、"帮我写个 HLD/PRD/LLD"、"整理架构文档"、"出测试用例"等)→ 进入**模式 A**(生成),继续下方流程。
---
### 文档类型选择(模式 A 必须确认)
> ⛔ **硬阻断规则:文档类型必须来自用户的明确表述,不得从上下文推断或自主选择。** 分析或生成步骤在类型确认前禁止启动。
按以下顺序判断:
1. **用户已明确写出文档类型**(如"帮我写 HLD"、"生成 PRD")→ 直接确认并继续,无需提问。
2. **用户未明确说明文档类型** → 立即向用户提问并等待回答,不得根据上下文猜测后自行开始:
```
要生成哪种文档?(对应软件交付链路的哪个阶段)
立项阶段
A. BRD/MRD — 商业需求/市场需求文档,面向决策层,说明做这件事的价值与边界
需求阶段
B. PRD — 产品需求文档,面向产品/研发,描述功能需求与验收标准
架构阶段
C. HLD — 概要设计,面向架构师/技术负责人,描述模块划分与关键设计决策
D. DDD/领域设计 — 领域模型文档,描述核心域、聚合、领域事件
实现阶段
E. LLD — 详细设计,面向开发者,描述接口、数据结构、流程逻辑
F. 编码指南 — 面向贡献者,描述实现约定、禁忌、常见陷阱
验证阶段
G. 测试文档(BDD/TDD/SIT/E2E/UAT)— 面向 QA/开发,描述测试场景与验收标准
运维阶段
H. 运营手册 — 面向操作/管理人员,说明如何使用与配置系统
I. SLI/SLO/监控文档 — 面向 SRE/运维,描述可观测性指标与告警策略
其他
J. CI/CD 流水线文档 — 面向 DevOps/开发,描述发布流程与自动化配置
K. 管理员速查手册 — 面向系统管理员,Q&A 格式,覆盖所有管理功能的操作步骤与业务影响,支持按章节独立速查
需要说明的模块范围或特别关注点?(留空则覆盖整个项目)
```
> ⛔ 收到用户回答后,才能进入第一轮。在此之前:不读代码、不分析结构、不建 todo 列表。
---
## 四轮工作流(模式 A 通用骨架)
> 每轮的**关注重点**由文档类型决定。
> `references/` 中的文件均为**按需扩展材料**,不是必读——只在需要完整模板或脚本片段时才打开。
---
### 第一轮:识别项目类型与入口
1. 读根目录(不递归),识别技术栈:
- `package.json` / `bun.lock` → Web 前端或 Node 服务
- `go.mod` / `Cargo.toml` / `pom.xml` / `*.csproj` / `requirements.txt` → 后端服务
- `*.xcodeproj` / `AndroidManifest.xml` / `pubspec.yaml` → 移动端
- `*.sln` + XAML → 桌面(WPF/WinForms);`CMakeLists.txt` / `*.pro` → Qt/C++
- `electron.js` / `main.js` + `renderer/` → Electron 桌面
- 多种并存 → 多端项目,分别处理
2. 找程序入口(`main.*` / `index.*` / `App.*` / `Program.*`)。
3. 先读现有文档(`README.md`、`docs/`、`wiki/`)——最快的模块清单来源。
4. **输出**:项目类型 + 技术栈摘要 + 初始模块清单,写入 todo 工具。
---
### 第二轮:结构扫描与信息骨架提取
**按文档类型关注不同的高信息密度位置:**
| 信息类型 | 在哪里找 | 重要的文档类型 |
|---------|---------|--------------|
| 功能入口/导航 | 路由表、菜单配置、命令注册表 | 运营手册、PRD |
| 界面文案 | i18n 文件、字符串资源 | 运营手册、PRD |
| 数据模型 | 数据库实体、Schema、DTO、聚合根 | HLD、LLD、DDD、PRD |
| 模块/包边界 | 目录结构、命名空间划分、包依赖 | HLD、DDD |
| 接口契约 | 函数签名、接口定义 | LLD |
| 业务规则 | Service/UseCase/BLL 层、公式、状态机 | PRD、LLD、DDD、运营手册 |
| 权限规则 | 中间件、角色枚举、权限常量 | 运营手册、PRD |
| 异常/错误边界 | 错误码、异常处理分支、校验规则 | LLD、测试文档 |
| 代码约定 | 注释规范、命名模式、Lint 配置 | 编码指南 |
| 可观测性/CI配置 | 日志埋点、`workflows/`、`Makefile` | SLI/SLO、CI/CD |
**可写脚本加速**(脚本模板见 [references/exploration-strategy.md](./references/exploration-strategy.md)):
- 批量提取路由/菜单列表 → 功能清单骨架
- 搜索中文字符串 → UI 实际文案
- 统计目录代码量 → 定位核心模块
---
### 第三轮:逐模块深度分析
**按文档类型决定分析重点:**
- **运营手册**:对每个功能点逐一提炼七个维度——
1. **操作基础**:功能入口、权限要求、操作步骤、表单字段含义
2. **状态影响**:操作后哪些数据变化、生效时机(立即/下次请求/下次同步)、是否可撤销
3. **危险等级**:不可逆操作 → `⚠️ 危险`;影响范围广 → `📌 注意`;可随时撤销 → 不标注
4. **设计背景**:为什么有这个功能?没有它会遇到什么真实问题?(推断不出则省略)
5. **业务规则**:公式、条件判断、上下限;触发的底层策略必须**命名**(如"负载均衡路由算法"),不能只写"影响路由"
6. **关联影响**:改此配置后哪些其他模块/用户受影响(表格:影响范围 | 具体变化)
7. **已知局限**:当前版本做不到的事,有无 workaround(每章 3-5 条)
每章开头还须收集两个固定节的素材(质检会核查):
- **🔗 前置依赖链路**:完整的 `上游模块 ➔ 上游模块 ➔ **当前** ➔ 下游模块` 链路(数清楚深度N),以及每个前置条件的两种情况(有/无、开/关)
- **📊 影响追踪矩阵**:本模块每个配置项 → 影响的对象 → 影响的功能 → **触发的策略(必须命名+说机制)**
> 格式模板见 [references/document-structure.md](./references/document-structure.md),深度说明见 [references/analysis-dimensions.md](./references/analysis-dimensions.md)。
- **BRD/MRD**:提炼业务问题 + 市场背景 + 目标指标 + 范围边界
- **PRD**:提炼用户故事 + 验收标准(必须可测试)+ 业务规则 + 约束条件
- **HLD / DDD**:提炼模块/域职责 + 依赖关系 + 关键设计决策(含 trade-off)+ 领域事件
- **LLD**:提炼接口签名 + 数据结构 + 流程逻辑(含异常路径)+ 错误码
- **编码指南**:提炼实现模式(正例+反例+原因)+ 约定规范 + 常见陷阱
- **测试文档**:提炼输入/输出边界 + 业务规则 + 状态转换 + 异常场景
- **SLI/SLO**:提炼服务目标 + 指标定义 + 告警阈值 + 降级策略
- **CI/CD**:提炼流水线阶段 + 触发条件 + 环境矩阵 + 回滚策略
- **管理员速查手册**:面向有系统权限的管理员,Q&A 格式组织,分析重点:
1. **系统定位**:用一句话 + 一张 Mermaid 架构图说明系统在业务中的角色("用户→网关→上游"链路)
2. **设计理念**:整理 3-7 条核心设计决策(分层权限/预扣计费/路由策略等),每条说明"这样设计解决了什么问题"
3. **读者路径图**:用 Mermaid flowchart 画出「第一次部署 / 运营提升 / 遇到问题」三类读者的推荐阅读路径
4. **功能章节**:每章以 🔗前置依赖链路 + 📊影响追踪矩阵 开头,正文全部以"如何…?"/"什么是…?"/"为什么…?"等问句作子标题,答案含操作步骤 + 危险等级 + 业务影响
5. **附录体系**:根据项目的管理目的自行设计,不强制固定数量和名称。常见附录类型供参考(按需取用):
- 权限快速对比表(各角色能做/不能做的矩阵)
- 业务场景解决方案(按"我遇到的问题"索引到解决步骤)
- 财务与计费精细化手册(计费公式、倍率逻辑、对账方法)
- 运营最佳实践(可分入门/进阶/高级三级)
- 配置速查索引、常见报错排查、术语表等(视项目需要增减)
6. **无技术术语**(同运营手册规则,完整替换表见 [references/document-structure.md](./references/document-structure.md))
通用原则:
- 遇到看不懂的逻辑,先搜索**调用方**推断语义
- 枚举值找**定义处+使用处**,理解每个值的含义
- 无法确定的细节标注 `〔INFER〕`,不猜测
- 每模块分析完立即整理,不攒到最后
---
### 第四轮:生成文档
按文档类型读取 [references/document-types.md](./references/document-types.md) 中**对应类型的章节结构模板**(定位到具体类型节,不需要读整个文件)。
通用生成策略:
- **先生成骨架**(所有章节标题),再填充内容,避免遗漏章节
- Mermaid 图先用文字描述逻辑,再转为图语法
- 章节间交叉引用用"参见第X章",不重复内容
- 所有 AI 推断内容用 `〔INFER〕` 标注,直接从代码验证的事实用 `〔FACT|文件:行号〕` 标注
---
### 完成后:保存、同步检查与汇报
1. **保存**:新建存到 `docs/[项目名]/[文档全称]-[系统名].md`;文件名使用与用户对话相同的语言,不使用缩写。缩写对应全称:
| 缩写 | 中文全称 | 英文全称 |
|------|---------|---------|
| BRD | 商业需求文档 | Business Requirements Document |
| MRD | 市场需求文档 | Market Requirements Document |
| PRD | 产品需求文档 | Product Requirements Document |
| HLD | 概要设计 | High-Level Design |
| DDD | 领域设计 | Domain-Driven Design |
| LLD | 详细设计 | Low-Level Design |
| SLI/SLO | 监控文档 | Monitoring Document |
| CI/CD | 流水线文档 | Pipeline Document |
| 编码指南 | 编码指南 | Coding Guide |
| 测试文档 | 测试文档 | Test Document |
| 运营手册 | 运营手册 | Operations Manual |
| 管理员速查手册 | 管理员速查手册 | Admin Quick Reference |
更新则在原文件增量修改
2. **文档同步铁律**(每次新建/更新文档后必须执行,不可跳过):
| 步骤 | 操作 |
|------|------|
| 评估影响范围 | 以本次新建/更新文档涉及的模块名为关键词,搜索 `docs/[项目名]/` 全文 |
| 强制三选一 | ①文档与实现一致 → 无需变更 ②文档落后 → 立即更新 ③实现偏离设计意图 → 告知用户请求裁决 |
| 禁止"待定" | 不允许输出"文档待后续更新"—— "后续"是文档腐烂的最大单一来源 |
> 完整反向同步任务(模式 B)额外执行六项收尾清单,详见 [references/reverse-sync.md §任务收尾强制清单](./references/reverse-sync.md)。
3. **汇报**:覆盖了几个模块、发现哪些关键信息、哪些地方打了 `〔INFER〕` 标注
---
## 通用质量检查
| 检查项 | 标准 |
|--------|------|
| 受众匹配 | 语言和深度符合目标读者(运营≠开发≠测试) |
| 流程图 | 多步操作或决策分支有 Mermaid 图 |
| 标注完整 | AI 推断内容有 `〔INFER〕`, 代码验证事实有 `〔FACT|文件:行号〕`。生成完成后检查:若某份文档零标注, 视为执行失误——任何有业务规则推断的文档都不可能一处标注都没有, 须回头补充 |
| 无歧义术语 | 技术词有解释,或已转为目标受众语言 |
| 无"待定"承诺 | 所有不确定项已三选一处理 |
**运营手册**额外检查:
| 检查项 | 标准 |
|--------|------|
| 前置依赖节 | 每章有 `🔗 功能前置条件与依赖链路`,含最多3层深度标注(逐层列出上下游依赖方向)|
| 影响矩阵节 | 每章有 `📊 影响追踪矩阵`,含第4列「影响的算法/策略」 |
| 设计痛点 | 可推断处有 `💡 设计背景` 提示块 |
| 危险标注 | 不可逆操作有 `⚠️ 危险` 警告块 |
| 无技术术语 | 无 API/Token/JSON/HTTP 等词汇;常见替换:API→接入方式、Token→令牌、JSON→配置内容、Webhook→回调通知、正则→匹配规则(完整替换表见 [references/document-structure.md](./references/document-structure.md)) |
**管理员速查手册**额外检查:
| 检查项 | 标准 |
|--------|------|
| 系统定位节 | 文档开头有"系统是什么"说明 + Mermaid 架构图 |
| 设计理念节 | 开头有 3-7 条设计理念,每条说明解决了什么问题 |
| 读者路径图 | 有 Mermaid flowchart 引导不同类型读者 |
| Q&A 格式 | 所有正文子标题均为问句("如何…?"/"什么是…?"/"为什么…?")|
| 前置依赖节 | 每章有 `🔗 功能前置条件与依赖链路` |
| 影响矩阵节 | 每章有 `📊 影响追踪矩阵`,含第4列「影响的算法/策略」 |
| 附录体系 | 至少有1个附录,内容与项目管理目的匹配;各附录有明确的使用场景说明 |
| 危险标注 | 不可逆操作有 🔴 危险 / 🟡 谨慎 / 🟢 安全 三级标注 |
| 无技术术语 | 同运营手册规则 |
don't have the plugin yet? install it then click "run inline in claude" again.