code-to-doc-generator

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 按其流程工作，停止阅读本文件，不执行下方四轮工作流：

   • "更新文档"、"同步文档"、"代码改了文档没跟上"、"文档和代码对不上"、"文档漂移"、"反向同步"

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）：

• 批量提取路由/菜单列表 → 功能清单骨架
• 搜索中文字符串 → UI 实际文案
• 统计目录代码量 → 定位核心模块

---

第三轮：逐模块深度分析

按文档类型决定分析重点：

• 运营手册：对每个功能点逐一提炼七个维度——

  1. 操作基础：功能入口、权限要求、操作步骤、表单字段含义
  2. 状态影响：操作后哪些数据变化、生效时机（立即/下次请求/下次同步）、是否可撤销
  3. 危险等级：不可逆操作 → ⚠️ 危险；影响范围广 → 📌 注意；可随时撤销 → 不标注
  4. 设计背景：为什么有这个功能？没有它会遇到什么真实问题？（推断不出则省略）
  5. 业务规则：公式、条件判断、上下限；触发的底层策略必须命名（如"负载均衡路由算法"），不能只写"影响路由"
  6. 关联影响：改此配置后哪些其他模块/用户受影响（表格：影响范围 | 具体变化）
  7. 已知局限：当前版本做不到的事，有无 workaround（每章 3-5 条）

  每章开头还须收集两个固定节的素材（质检会核查）：

  • 🔗 前置依赖链路：完整的 上游模块 ➔ 上游模块 ➔ **当前** ➔ 下游模块 链路（数清楚深度N），以及每个前置条件的两种情况（有/无、开/关）
  • 📊 影响追踪矩阵：本模块每个配置项 → 影响的对象 → 影响的功能 → 触发的策略（必须命名+说机制）

  格式模板见 references/document-structure.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）

通用原则：

• 遇到看不懂的逻辑，先搜索调用方推断语义
• 枚举值找定义处+使用处，理解每个值的含义
• 无法确定的细节标注 〔INFER〕，不猜测
• 每模块分析完立即整理，不攒到最后

---

第四轮：生成文档

按文档类型读取 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 §任务收尾强制清单。

3. 汇报：覆盖了几个模块、发现哪些关键信息、哪些地方打了 〔INFER〕 标注

---

通用质量检查

检查项	标准
受众匹配	语言和深度符合目标读者（运营≠开发≠测试）
流程图	多步操作或决策分支有 Mermaid 图
标注完整	AI 推断内容有 〔INFER〕, 代码验证事实有 〔FACT｜文件:行号〕。生成完成后检查：若某份文档零标注, 视为执行失误——任何有业务规则推断的文档都不可能一处标注都没有, 须回头补充
无歧义术语	技术词有解释，或已转为目标受众语言
无"待定"承诺	所有不确定项已三选一处理

运营手册额外检查：

检查项	标准
前置依赖节	每章有 🔗 功能前置条件与依赖链路，含最多3层深度标注（逐层列出上下游依赖方向）
影响矩阵节	每章有 📊 影响追踪矩阵，含第4列「影响的算法/策略」
设计痛点	可推断处有 💡 设计背景 提示块
危险标注	不可逆操作有 ⚠️ 危险 警告块
无技术术语	无 API/Token/JSON/HTTP 等词汇；常见替换：API→接入方式、Token→令牌、JSON→配置内容、Webhook→回调通知、正则→匹配规则（完整替换表见 references/document-structure.md）

管理员速查手册额外检查：

检查项	标准
系统定位节	文档开头有"系统是什么"说明 + Mermaid 架构图
设计理念节	开头有 3-7 条设计理念，每条说明解决了什么问题
读者路径图	有 Mermaid flowchart 引导不同类型读者
Q&A 格式	所有正文子标题均为问句（"如何…？"/"什么是…？"/"为什么…？"）
前置依赖节	每章有 🔗 功能前置条件与依赖链路
影响矩阵节	每章有 📊 影响追踪矩阵，含第4列「影响的算法/策略」
附录体系	至少有1个附录，内容与项目管理目的匹配；各附录有明确的使用场景说明
危险标注	不可逆操作有 🔴 危险 / 🟡 谨慎 / 🟢 安全 三级标注
无技术术语	同运营手册规则