design-doc-required

开发前设计文档强制检查

核心原则

禁止在没有设计文档的情况下分析方案、讨论架构或编写任何实现代码。

这不是建议，是强制要求。无论任务看起来多简单，也无论用户是要求「分析」还是「实现」，都必须先完成设计文档检查。

所有设计文档中的架构图、流程图、模块关系图必须使用 Mermaid 语法绘制，禁止使用 ASCII art 或纯文本框图。

Do NOT analyze implementation approaches, discuss architecture, propose solutions, evaluate feasibility, or write any code until the design document check below is complete. This applies even when the user only asks for analysis or architectural discussion — design doc check comes FIRST, before any response about implementation.

Do NOT write any implementation code (Edit/Write .java, .ts, .py, etc.) until BOTH the design document AND the corresponding coding summary document (-coding.md) have been created and confirmed. The coding document is NOT optional — it is the second mandatory gate before any code change.

---

Step 0：知识图谱上下文预热

在执行设计文档检查之前，先加载项目知识图谱上下文，避免后续全量扫码。

flowchart TD
    S0(["收到开发任务"]) --> S0A{"docs/00_project_overview.md 存在?"}
    S0A -->|"是"| S0B["读取 00_project_overview.md\n获取项目全局索引"]
    S0A -->|"否"| S0SKIP["跳过预热\n兼容无知识图谱的项目"]
    S0B --> S0C["根据 AI 上下文路由表\n按任务类型加载必读文档"]
    S0C --> S0D["将上下文带入后续流程"]
    S0D --> MAIN(["进入设计文档检查"])
    S0SKIP --> MAIN

执行规则

1. 检查项目 docs/00_project_overview.md 是否存在
2. 若存在：
   • 读取该文件（约 3KB），获取项目概要 + 文档导航 + AI 上下文路由表
   • 根据路由表中的「按任务类型加载」，读取当前任务对应的必读文档（通常 2-3 份）
   • 按需文档不在此时加载，留到实施阶段碰到具体问题时再读
3. 若不存在：跳过本步骤，直接进入设计文档检查（兼容没有知识图谱的项目）

任务类型判断

用户意图	任务类型	路由表对应行
新增功能、新建接口	新功能开发	01_architecture + 02_module_map + 05_api_map
修复 Bug、处理异常	Bug 修复	08_constraints + modules/{模块}
重构、迁移、优化架构	重构/迁移	08_constraints + 09_refactor_plan + skills/{tech}
修改接口入参出参	接口变更	05_api_map + 06_frontend_backend_mapping
加表、改字段	数据库变更	04_data_model_map + 08_constraints

注意：Step 0 只负责加载上下文，不替代后续的设计文档检查。预热完成后，正常进入下方流程。

---

执行流程

flowchart TD
    A(["收到开发任务\n（Step 0 预热完成后）"]) --> TRIVIAL{"改动通过\n极简改动硬清单?"}
    TRIVIAL -->|"是\n（≤2 文件 ∧ ≤30 行 ∧\n透传补漏/局部修正等）"| TRIVIAL_SKIP["跳过文档检查\ngit commit body 即变更说明"]
    TRIVIAL_SKIP --> Z(["开始实现代码"])
    TRIVIAL -->|"否"| B["在当前项目中查找设计文档"]
    B --> C{"文档存在且已填写完整?"}
    C -->|"是"| LIGHT{"改动通过\n第四·五步硬清单?"}
    LIGHT -->|"是"| LIGHT_LOG["更新稳定/current 文档\n变更说明写入 git commit"]
    LIGHT_LOG --> Z(["开始实现代码"])
    LIGHT -->|"否"| D["读取并引用文档内容"]
    D --> E["通知用户引用了哪份文档"]
    E --> CODING_BR{"现有文档是\n轻量模版?"}
    CODING_BR -->|"是"| Z
    CODING_BR -->|"否"| CODING{"coding 文档存在?"}
    CODING -->|"是"| CODING_READ["读取 coding 文档"]
    CODING -->|"否"| CODING_GEN["按 coding-template.md 生成"]
    CODING_GEN --> CODING_READ
    CODING_READ --> Z
    C -->|"否"| F["询问用户设计文档路径或名称"]
    F --> G{"用户能提供文档?"}
    G -->|"是"| D
    G -->|"否"| PHASE_A["调用 doc-index-required Phase-A\n读 INDEX 查重 / 边界判断\n（用户目录知识库默认）"]
    PHASE_A --> WEIGHT{"第一·七步\n模版分级选择"}
    WEIGHT -->|"轻量\n通过准入清单"| H_LIGHT["生成轻量文档草稿\n输出 lightweight-template.md"]
    WEIGHT -->|"完整"| TYPE{"第一·八步\n业务 vs 技术"}
    TYPE -->|"业务/流程主导"| H_BIZ["生成业务方案草稿\n输出 template.md"]
    TYPE -->|"技术/架构主导"| H_TECH["生成技术方案草稿\n输出 template-tech.md"]
    H_BIZ --> API_DOC["如涉及对外接口\n同步生成 api-template.md"]
    H_TECH --> API_DOC
    H_LIGHT --> J_LIGHT["等待用户确认文档已填写"]
    API_DOC --> J_HEAVY["等待用户确认文档已填写"]
    J_LIGHT --> PHASE_B_L["调用 doc-index-required Phase-B\n登记 design/INDEX.md"]
    J_HEAVY --> PHASE_B_H["调用 doc-index-required Phase-B\n登记 design/INDEX.md"]
    PHASE_B_L --> POST_WEIGHT{"刚创建的是\n轻量模版?"}
    PHASE_B_H --> POST_WEIGHT
    POST_WEIGHT -->|"是"| Z
    POST_WEIGHT -->|"否"| CODING

---

文档目录结构规范

AI 生成的设计文档默认存放在用户文档目录的项目知识库 {USER_DOCUMENTS}/ai-docs/{project}/design/，不直接写入项目 docs/design/。用户确认终版后，可自行上传到项目 docs/design/ 或明确指定项目内路径让 AI 写入。

v1.20 起的关键变化： 用户目录不再是「草稿堆」。{USER_DOCUMENTS}/ai-docs/{project}/design/ 与项目 docs/design/ 享有同等的索引体系（INDEX.md + 主题目录），必须经过 doc-index-required Phase-A 查重和 Phase-B 登记。

路径硬约束： 路径中禁止 {agent}/、{YYYY-MM-DD}/ 层；文件名禁止带日期后缀；同一需求始终更新 {需求名称}-current.md，不为日常迭代新建 -vN 快照。

用户目录知识库（默认）与项目 docs/（终版）共用结构

{ROOT}/design/                              ← {ROOT} = {USER_DOCUMENTS}/ai-docs/{project} 或 {项目根}/docs
  INDEX.md                                  ← 子索引，由 doc-index-required Phase-B 维护
  {需求名称}/                                ← 顶层需求目录
    {需求名称}-current.md                    ← 默认稳定文档（业务方案 / 技术方案）
    {需求名称}-api-current.md                ← 接口文档（如涉及对外接口）
    {需求名称}-coding.md                     ← 完整模版对应的当前编码摘要（仅完整模版需要）
    snapshots/                               ← 仅重大基线 / 发布快照 / 用户明确要求时创建
      {需求名称}-{YYYYMMDD}-v{N}.md
      {需求名称}-api-{YYYYMMDD}-v{N}.md
    {子模块名称}/                            ← 子模块目录（当本需求是更大架构的一部分时）
      {子模块名称}-current.md
      snapshots/
        {子模块名称}-{YYYYMMDD}-v{N}.md

示例：

docs/design/
  通用智能体架构/                            ← 顶层架构设计
    通用智能体架构-current.md
    多平台模型路由层/                         ← 子模块，归属于通用智能体架构
      多平台模型路由层-current.md
      多平台模型路由层-coding.md
  用户权限管理/                              ← 独立需求
    用户权限管理-current.md
    用户权限管理-coding.md

目录层级规则

规则	说明
独立需求	直接在 docs/design/ 下创建顶层目录
子模块/子功能	如果本需求属于某个已有架构设计的一部分，必须创建独立子目录（docs/design/{父需求}/{子模块名}/），禁止将子模块文件直接放在父需求目录下与父文档混在一起
最大嵌套深度	不超过 2 层（docs/design/{父需求}/{子模块}/），避免目录过深
归属判断标准	见下方「目录归属分析」步骤

命名规则

部分	规则	示例
需求名称	与需求/功能名一致，禁止缩写	用户权限管理
稳定文档	Git 管理下默认使用 {需求名称}-current.md 或用户指定的稳定文件名	用户权限管理-current.md
编码摘要	完整模版对应 {需求名称}-coding.md，随稳定文档同步	用户权限管理-coding.md
快照文档	仅重大基线/发布快照/用户明确要求/非 Git 管理场景使用 YYYYMMDD-vN	用户权限管理-20260330-v1.md

版本更新原则

• Git 管理下的项目正式文档默认直接更新稳定文档，历史由 git commit / PR diff / blame 负责，不靠不断复制 v1/v2/v3 文件留痕。
• 只有以下情况才新建版本快照：用户目录草稿尚未进入 Git、重大架构基线或发布基线、用户明确要求保留快照、文档不在 Git 管理范围内。
• 微小错别字、格式修正、普通迭代和常规需求调整均直接修改稳定文档，并在 commit body 写清楚变更原因。

---

步骤详解

第一步：查找设计文档

在以下两个根下按以下优先级查找（项目 docs/ 命中优先，未命中再查用户目录知识库）：

优先级	根	路径
1	项目终版	{项目根}/docs/design/
2	用户目录知识库	{USER_DOCUMENTS}/ai-docs/{project}/design/

每个根内按以下顺序查找：

1. 询问用户本次开发对应的需求名称
2. 在 {ROOT}/{需求名称}/ 目录下优先查找 {需求名称}-current.md 或用户指定的稳定文档
3. 若完整模版命中，同时查找 {需求名称}-coding.md
4. 若未找到稳定文档，再查找 snapshots/ 或目录内最新 YYYYMMDD-vN 快照作为参考
5. 若顶层未找到，递归搜索子目录（如 {ROOT}/{父需求}/{需求名称}/）
6. 若两个根都不存在该目录，则认为文档缺失，进入第一·五步（目录归属分析）后再进入第三步

第一·五步：目录归属分析

文档缺失需要新建时，在创建目录前必须先分析目录归属：

1. 扫描 design/ 下所有已有目录（同时读取项目 docs/design/INDEX.md 与用户目录 ai-docs/{project}/design/INDEX.md 获取各需求摘要）
2. 判断本次需求是否属于某个已有架构/系统设计的子模块，判断依据：

判断维度	归属为子模块的信号	保持独立的信号
功能依赖	本需求实现的功能是已有架构的组成部分	本需求可独立运行，无父架构
接口引用	本需求实现的接口定义在已有架构文档中	本需求自定义全部接口
文档提及	已有架构文档的「功能范围」或「后续扩展」明确提到本需求	无任何文档提及
模块归属	本需求的代码位于已有架构相同的 Maven 模块内	本需求位于独立模块

3. 判定结果处理：
   • 属于子模块 → 目录路径为 docs/design/{父需求}/{子模块名}/，告知用户归属原因
   • 独立需求 → 目录路径为 docs/design/{需求名称}/
   • 不确定 → 列出候选父目录及判断理由，让用户决定

示例： 新建「多平台模型路由层」设计文档时，扫描发现「通用智能体架构」的功能范围和后续扩展章节明确提到了模型路由，且代码位于同一个 llm-domain 模块 → 判定为子模块 → 建议路径 docs/design/通用智能体架构/多平台模型路由层/

第一·七步：模版分级选择（轻量 vs 完整）

目录确定后、输出模版前，必须先决定本次用「轻量模版」还是「完整模版」。 直接用完整模版处理小接口、或用轻量模版偷懒做大改造，都属于流程错位。

模版定位

模版	文件	适用场景	配套 coding.md	配套 api-doc
轻量	lightweight-template.md	单接口的自身流程 / 库表读写流程描述、已有架构内的接口新增/调整、入参出参微调	不需要	不需要（接口契约写在第 2 节）
完整-业务	template.md	业务/流程主导：订单状态、退款流程、审批工单、业务规则改造等	需要	涉及对外接口必填
完整-技术	template-tech.md	技术/架构主导：协议选型、中间件接入、分布式系统、复杂模块拆分、客户端架构	需要	涉及对外接口必填

完整模版的二级判定见第一·八步。

准入硬清单（命中所有项才允许走轻量分支）

只要任意一项 ❌，立即升级到完整模版。严禁口头判定「差不多就走轻量」。

• 不新增数据库表
• 不新增字段（仅读取现有字段）或字段变更属于纯枚举值扩充
• 不新增对外服务契约入口（HTTP 路径 / Feign 方法）
• 不改既有对外接口的入参/出参语义（字段重命名、含义变化）
• 不跨服务、不跨模块协作（只在当前模块内）
• 不引入新的中间件/消息队列/分布式锁/补偿事务
• 不新增 ≥3 个类（顶多 1-2 个新类）
• 不重新设计实体状态机（在已有状态机内增减状态算扩充，不算重设计）
• 改动核心可由「核心流程图 + 库表过滤规则表 + 失败行为表」完整描述

判定边界示例

✅ 走轻量：

• 给「获取可退商品」接口加一个 includeMergeTable 入参，控制是否聚合联台兄弟订单
• 把订单查询的 WHERE 条件多加一个过滤项，剔除某种特殊状态
• 在已有 Service 加一个查询方法，本质是按新条件读现有表

❌ 必须用完整模版：

• 新建「积分账户」表 + 配套接口（新增表）
• 把「订单创建」从同步改为消息异步推送（引入消息队列）
• 引入分布式锁防止重复退款（新增分布式锁）
• 设计三方对账的全新接口契约（新增对外契约）

决策动作

1. 对照硬清单逐项判定
2. 轻量分支：输出 lightweight-template.md，告知用户填写要点 + 升级触发条件
3. 完整分支：进入下方第一·八步选择业务 vs 技术，再输出对应模版

决策必须显式告知用户： 必须先回复"判定为【轻量/完整】模版，原因：xxx"，再输出模版。不允许默默选择。

---

第一·八步：完整模版的二级判定（业务 vs 技术）

仅在完整分支触发。决定用 template.md（业务）还是 template-tech.md（技术）。

关键词触发

信号词出现	倾向模版
订单 / 状态机 / 审批 / 工单 / 退款 / 业务规则 / 流程改造 / 校验逻辑	业务（template.md）
协议 / WebRTC / WebSocket / 消息队列 / 缓存 / 分布式锁 / 网关 / SSO / 路由层 / 客户端架构 / 中间件 / SDK 接入 / P2P	技术（template-tech.md）

本质区别

维度	业务方案	技术方案
核心载体	一张主流程图（线性、有判断分支）	一张架构图 + 多张交互小图（拓扑）
关键章节	核心流程、核心业务规则	整体架构、模块拆分与职责、关键交互
阅读视角	业务流程怎么走	模块怎么拆、对象怎么协作
失败信号	流程图节点超过 12 个仍线性走完	把所有交互合并成一张大 sequenceDiagram

决策动作

1. 提取用户描述中的关键词，匹配上方信号词表
2. 不确定时不允许默默选择——列出"业务/技术"两种倾向 + 各自后续章节差异，让用户拍板
3. 拍板后回复"判定为【完整-业务】或【完整-技术】模版，原因：xxx"，再输出对应模版

---

第二步：文档存在时

先识别文档类型（看文件头部声明 / 目录结构）：

• 轻量文档（基于 lightweight-template.md）：直接读取该文档作为编码依据，不需要 coding.md
• 完整文档（基于 template.md 业务方案 或 template-tech.md 技术方案）：检查是否同时存在对应的编码摘要文档（-coding.md）和接口文档（-api-current.md）

完整文档的 coding.md 处理：

• 存在 {需求名称}-coding.md 或对应 -coding.md：优先读取编码摘要文档，以节省 token、降低幻觉风险
• 不存在 -coding.md：读取完整文档，并在读取后自动生成对应的编码摘要文档

在开始编码前明确告知用户：

"已读取编码摘要：docs/design/{需求名称}/{文件名}-coding.md 本次实现依据：

• 核心业务规则：XXX
• 涉及类（全类名）：XXX
• 关键约束：XXX 如有不符，请告知我，我将先更新稳定设计文档；只有重大基线或非 Git 管理场景才创建版本快照。"

第三步：文档不存在时

禁止直接开始编码。 执行以下步骤：

1. 告知用户未找到对应需求的设计文档
2. 询问是否有已有文档需要手动指定路径
3. 若无文档，确定输出根（默认用户目录知识库 {USER_DOCUMENTS}/ai-docs/{project}/design/；用户明确指定 docs/... 时用项目 docs/design/），并执行 doc-index-required 的输出路径回显
4. 调用 doc-index-required Phase-A（读取顶层 INDEX + design/INDEX，分析内容边界，判断是新建主题目录还是补充到已有 -current.md）；用户目录与项目 docs/ 同等执行
5. 执行第一·七步模版分级选择
6. 按对应模版生成稳定文档（{需求名称}-current.md）；不为首次创建动作建带日期的 v1 快照

---

轻量分支引导（命中第一·七步轻量准入清单）

本次改动判定为【轻量级】，按接口级模版处理。

请按以下步骤操作：

1. 默认创建到用户目录知识库：{USER_DOCUMENTS}/ai-docs/{project}/design/{需求名称}/
2. 创建/更新文件：{需求名称}-current.md（首次创建即用 -current 命名，不带日期后缀、不建 v1）
3. 参考 lightweight-template.md，至少完成以下章节：
   • 第 1 节：代码入口（先写"待实现"也可以）
   • 第 2 节：接口契约（核心入参/出参）
   • 第 3 节：核心流程图（接口自身流程 / 库表读写顺序，必填 1 张 Mermaid flowchart 或 sequenceDiagram）
   • 第 4 节：关键过滤/写入规则
   • 第 5 节：失败行为
4. 文档写完后调用 doc-index-required Phase-B 登记到 {USER_DOCUMENTS}/ai-docs/{project}/design/INDEX.md
5. 草稿确认后告知我文件路径，我将读取后开始实现；终版是否上传到项目 docs/ 由用户自行决定
6. 本分支无需生成 -coding.md

模板文件位于：skills/design-doc-required/lightweight-template.md

---

完整-业务分支引导（第一·八步判定为业务/流程主导）

本次改动判定为【完整-业务】，按 template.md 处理。

请按以下步骤操作：

1. 默认创建到用户目录知识库：{USER_DOCUMENTS}/ai-docs/{project}/design/{需求名称}/
2. 创建/更新文件：{需求名称}-current.md（首次创建即用 -current 命名）
3. 参考模板填写内容（至少完成以下章节）：
   • 第 1 节：目标与边界
   • 第 2 节：核心流程（必填 1 张 Mermaid 核心图）
   • 第 3 节：核心业务规则
   • 第 4 节：编码落点（目录树结构）
   • 第 6 节：风险与待确认
4. 如涉及对外接口：同步生成 {需求名称}-api-current.md，按 api-template.md 填写字段级契约
5. 文档写完后调用 doc-index-required Phase-B 登记到 {USER_DOCUMENTS}/ai-docs/{project}/design/INDEX.md
6. 草稿确认后告知我文件路径，我将读取后开始实现；终版是否上传到项目 docs/ 由用户自行决定

模板文件位于：skills/design-doc-required/template.md（业务方案）+ api-template.md（接口文档）

---

完整-技术分支引导（第一·八步判定为技术/架构主导）

本次改动判定为【完整-技术】，按 template-tech.md 处理。

请按以下步骤操作：

1. 默认创建到用户目录知识库：{USER_DOCUMENTS}/ai-docs/{project}/design/{需求名称}/
2. 创建/更新文件：{需求名称}-current.md（首次创建即用 -current 命名）
3. 参考模板填写内容（至少完成以下章节）：
   • 第 1 节：目标与边界
   • 第 2 节：整体架构（必填 1 张架构图，subgraph 分组）
   • 第 3 节：模块拆分与职责（每模块独立小节）
   • 第 4 节：关键交互（多张小时序图，禁合并大图）
   • 第 5 节：核心业务规则
   • 第 6 节：编码落点（目录树结构）
   • 第 8 节：风险与待确认
4. 如涉及对外接口：同步生成 {需求名称}-api-current.md，按 api-template.md 填写字段级契约
5. 文档写完后调用 doc-index-required Phase-B 登记到 {USER_DOCUMENTS}/ai-docs/{project}/design/INDEX.md
6. 草稿确认后告知我文件路径，我将读取后开始实现；终版是否上传到项目 docs/ 由用户自行决定

模板文件位于：skills/design-doc-required/template-tech.md（技术方案）+ api-template.md（接口文档）

第三·五步：文档写完后更新索引

文档写完后必须调用 doc-index-required Phase-B 登记/更新索引，用户目录知识库与项目 docs/ 同等执行：

• 默认目标：{USER_DOCUMENTS}/ai-docs/{project}/design/INDEX.md
• 用户指定项目内路径时：{项目根}/docs/design/INDEX.md

新建主题目录时，Phase-B 还会检查并更新顶层 INDEX.md（确保 design/ 子目录条目存在）。

---

第四步：生成编码摘要文档（编码前第二道门禁）

本步仅适用于完整模版（基于 template.md 业务方案 或 template-tech.md 技术方案）。 轻量模版（基于 lightweight-template.md）不需要 coding.md，核心流程图 + 规则表已经覆盖编码所需信息，跳过本步直接进入实现。

编码摘要文档是完整文档编码前的第二道强制门禁。 设计文档确认后、第一行实现代码之前，必须确保 -coding.md 存在。若不存在，立即按 coding-template.md 生成。

禁止在 -coding.md 缺失的情况下开始编码（完整模版分支）。 即使用户催促"直接写代码"，也必须先完成本步。

文件命名：

• Git 管理下的稳定文档默认使用 {需求名称}-coding.md
• 版本快照场景才使用 {需求名称}-{YYYYMMDD}-v{N}-coding.md（与快照文档对应）

三类文档的职责边界

内容	设计文档（业务/技术方案）	接口文档（api-template.md）	编码文档（coding-template.md）
目标、边界、设计结论	保留	不写	摘要引用
核心流程图 / 架构图 / 交互图	保留	不写	不重复
接口入口列表	不写	保留接口清单	保留接口入口指针（指向 api-doc）
接口字段级契约 / 错误码 / 示例	不写	保留（唯一权威载体）	不重复
核心业务规则	保留	不写	保留并可展开实现约束
编码落点 + 一句话职责	保留（目录树）	不写	展开方法签名和操作步骤
数据/依赖变化	只写本次变化	不写	展开字段级、调用级细节
风险与验证要点	保留	不写	转换为测试/异常处理要点

原则：

• 设计文档回答"为什么这样做、核心流程/架构是什么、风险在哪里、代码大概落哪"
• 接口文档回答"每个对外接口的契约长什么样"
• 编码文档回答"每个方法怎么写"

生成规则

从完整文档中提取以下内容填入编码文档（章节号按业务模版 template.md / 技术模版 template-tech.md 各自实际章节定位）：

• 变更记录 → 精简为一行摘要
• 目标与边界 → 精简为设计结论和不做什么
• 核心流程（业务）/ 整体架构 + 模块拆分 + 关键交互（技术） → 提取关键步骤、模块职责、关键交互摘要
• 核心业务规则 → 原文提取
• 编码落点 → 提取全路径填入「涉及类清单」，补充方法签名和职责
• 数据与依赖变更 → 提取本次变化的关键字段、事务、下游调用
• 风险与验证 → 提取异常处理、边界条件和测试要点
• 接口入口 → 仅列「方法 + 路径 + 实现类#方法」指针；字段级契约不复制，留给 api-doc 承担

全路径要求： 编码落点中所有类/文件必须使用完整路径（包路径或文件路径），禁止只写短类名，以便精准定位代码文件。

---

第四·五步：轻量修订（小修直接更新稳定文档）

适用场景： 设计文档已存在、本次改动属于该文档覆盖范围内的修正/对齐/删冗余，引入"新建快照 + coding.md"的成本明显大于收益。Git 管理下这类改动默认直接更新稳定/current 文档，变更原因写入 commit body；不再为了留痕在文档末尾追加流水，也不新建版本号、不新建 coding.md。

准入硬清单（必须全部 ✅ 才能走本分支）

只要任意一项 ❌，立即退回[第五步：需求变更时更新稳定文档]。严禁口头判定"差不多就走轻量"。

• 设计文档已存在（优先 docs/design/{需求}/{需求}-current.md，兼容历史 ...vN.md）
• 改动不新增对外接口、不修改入参/出参字段
• 改动不新增数据库表、不新增/重命名/删除字段
• 改动不新增类、不新增/删除/重命名公开方法
• 改动不改变方法签名（参数/返回值/异常）
• 改动不引入新的外部依赖（pub/maven/npm 等）
• 改动范围 ≤ 单文件、≤ 30 行净变更
• 改动性质属于以下一种：
  • 修正与上游/云端/规范的不一致（对齐）
  • 删除冗余、错误或被强制覆盖的逻辑
  • 修复明确的 bug 且不改变文档已声明的业务规则方向
  • 补充注释、日志、错误信息文案

判定边界示例： ✅ 走轻量：删除 _calculateRefundPriceRaw 中强制覆盖 selectedServices 的 6 行 if 块（与云端 calculateRefundPrice 对齐） ❌ 必须进入需求变更处理：把 selectedServices 改成支持半选的全新数据结构（改了入参语义） ❌ 必须进入需求变更处理：从 selectedServices 派生出新的 selectedServiceTypeFlag 字段（新增字段）

处理动作

1. 若稳定文档中的业务规则、接口描述、代码入口或表操作说明会失真，直接更新 {需求名称}-current.md；若文档内容仍准确，则不必为本次小修强行改文档
2. 不新建快照文档、不新建/更新 -coding.md
3. 跳过 doc-index-required Phase-B（INDEX 摘要无需更新）
4. 进入代码改动时必须遵循 bugfix-coding-style（v1.17 起方向反转）：直接改写或新增；禁止在源码中保留 [DEPRECATED] / [ADDED] / [BUGFIX 日期] 等变更日志标记，禁止注释保留旧代码段；变更原因写进 commit message body，源码内只保留 WHY 注释且优先上提到方法 / 类 doc comment
5. commit 信息按 git-commit-standards 规范，在 body 写清楚本次为什么改；若同步更新了设计文档，在 body 引用文档路径

红线

想法	正确处理
"这次只改 5 行，但顺手删个无用方法"	删方法即破清单第 4 项，必须进入需求变更处理
"顺便把入参字段名规范一下"	改入参字段即破清单第 2 项，必须进入需求变更处理
"走轻量分支就不用写 commit body 了"	错。Git commit body 是默认变更日志，必须写清楚为什么改

---

第五步：需求变更时更新稳定文档

若改动未通过 [第四·五步硬清单]（任意一项 ❌），即视为需求变更：

• 项目内 Git 管理的正式文档：直接更新 {需求名称}-current.md 或用户指定的稳定文档，并同步更新 {需求名称}-coding.md（完整模版）
• 用户目录草稿 / 非 Git 管理文档 / 重大基线 / 用户明确要求快照：才引导创建 {需求名称}-{今日日期}-v{N+1}.md

对用户提示：

"检测到需求变更。若这是项目内 Git 管理的正式文档，我会先更新稳定设计文档并依赖 git commit 留痕；若你需要保留基线快照，请明确要求我创建 {需求名称}-{今日日期}-v{N+1}.md。"

---

第六步：修改设计文档后同步 coding 文档

本步仅适用于完整模版。 轻量模版没有配套 coding.md，跳过本步。

每次对完整设计文档进行实质性内容变更后（包括直接修改稳定文档和创建快照），必须同步更新对应的 -coding.md。

按以下映射关系更新对应章节：

设计文档变更内容	需同步更新的文档/章节
接口清单增删 / 入参出参字段调整 / 错误码变更	api-doc 文档（不通过 coding.md，由 api-doc 唯一承载）
接口实现类/方法路径变更	coding 文档第 2 节：接口入口指针
类清单增删	coding 文档第 3 节：涉及类清单（同步增删类条目，补充方法签名）
核心业务规则变更	coding 文档第 1 节：核心业务规则
数据库字段/DDL/Mapper 变更	coding 文档第 4 节：数据结构
约束、事务、边界说明变更	coding 文档第 5 节：重要约束与边界

注意：设计文档的类清单只有一句话职责，coding 文档需自行补充方法签名和详细操作说明。设计文档新增一个类时，coding 文档不只是复制一行，而要展开该类的方法级细节。

若文档使用稳定命名，coding 文档直接同步覆盖；若文档是快照命名，coding 文档与快照版本号保持一致。

若以上章节均未涉及，则跳过 coding 文档更新。

---

Mermaid 图表要求

Mermaid 语法规范由 markdown-writing-standards Skill 统一管控。 本章节只定义设计文档中「哪些场景适合画哪些图」，具体「图怎么画不出错」请遵循 markdown-writing-standards。 生成 Mermaid 代码块前，必须先调用 markdown-writing-standards 进行语法自检。

最小图原则

设计文档的图表目标是清晰明了地表达业务与实现边界，不是凑齐图表类型。

1. 能用一张图表达清楚，就只画一张图。 禁止为了满足模板形式重复画功能图、能力图、流程图和依赖图。
2. 图随场景选，不随章节凑。 单个后端接口优先画接口自身流程；跨模块协作才画模块/依赖；状态变化明显才画状态图。
3. 同一事实不要多图重复表达。 如果核心流程图已经同时表达了模块、调用、库表读写和异常分支，不再额外拆模块图或类调用图。
4. 复杂才拆图。 当一张图超过 12 个节点、分支超过 4 个、或同时混入业务流程与系统依赖导致难读时，才拆成多张图。

场景选图表

场景	推荐图	是否必填	说明
单个后端接口 / 单个业务动作	接口自身流程图（flowchart TD）或库表读写时序图（sequenceDiagram）	必填 1 张	例如退款后端接口，一张图讲清入参校验、查询、判断、写表、返回即可
查询/写表顺序是核心	sequenceDiagram	条件必填	需要按执行顺序说明读写哪些表、哪些字段、业务含义时使用
业务分支/异常路径是核心	flowchart TD	条件必填	需要表达判断条件、失败行为、兜底策略时使用
涉及 2 个以上模块/服务协作	模块/组件关系图（graph TD）	条件必填	只在模块边界、调用关系本身需要被看清时画
涉及实体状态变化	状态流转图（stateDiagram-v2）	条件必填	只有新增/调整状态、状态迁移规则复杂时画
跨系统/外部依赖较多	依赖图（graph TD）	条件必填	只在依赖关系影响设计、部署、降级或风险时画
能力拆分复杂、多人协作开发	能力分解图（mindmap / graph TD）	不推荐	优先用文字/表格说明；除非不画就无法确认边界

完整-业务模版（template.md）图表要求

业务方案不再要求固定凑齐多张图。默认要求是：

• 至少 1 张核心图：从「接口自身流程图 / 库表读写时序图」中选择最能表达本次设计的一张。
• 其余图表按上方「场景选图表」触发；未命中场景时必须省略或写"本场景不需要"，不得画空泛示意图。

图表类型	适用章节	Mermaid 图类型	触发条件
接口自身流程图	第 2 节（核心流程）	flowchart TD	单接口、单业务动作、退款/下单/查询等自身流程
库表读写时序图	第 2 节（核心流程）	sequenceDiagram	读写表顺序、字段含义、事务边界是核心
状态流转图	第 2 节或第 3 节	stateDiagram-v2	状态迁移是本次核心风险，且用流程图表达不清
模块/依赖关系图	第 5 节（数据与依赖变更）	graph TD	新增跨系统依赖或复杂模块交互，文字/表格说不清风险

完整-技术模版（template-tech.md）图表要求

技术方案与业务方案的根本差异在图表组合：禁止用一张大流程图涵盖所有交互。

图表类型	适用章节	Mermaid 图类型	是否必填
整体架构图	第 2 节（整体架构）	flowchart TD 或 flowchart LR + subgraph 分组	必填
关键交互时序图（多张）	第 4 节（关键交互）	sequenceDiagram + box 分组	至少 2 张，每张只讲一个 critical path
状态流转图	第 4 节或第 5 节	stateDiagram-v2	仅当存在实体状态变化时

红线（技术方案）：

• ❌ 把「初始化 + 核心流程 + 异常处理」合并到一张 sequenceDiagram
• ❌ 用业务方案模板写技术方案（强行套核心流程图导致大图压缩）
• ✅ 拆 4.1 / 4.2 / 4.3 多张小图，每张只讲一件事

轻量模版（lightweight-template.md）图表要求

图表类型	适用章节	Mermaid 图类型	目的
接口自身流程图 / 库表读写时序图（二选一）	第 3 节（核心流程图）	flowchart TD / sequenceDiagram	用一张图讲清接口自己的执行路径；流程分支强用 flowchart，库表顺序强用 sequenceDiagram

轻量模版不强制要求功能模块总览图、能力分解图、类调用关系图、依赖图。所有业务规则下沉到核心流程图的节点/Note 与第 4 节规则表。

模块/依赖图要求

默认不画功能模块总览图。设计文档是某个方案/接口的编码依据，不是整个大模块的功能设计。

只有当本次新增跨系统依赖、复杂模块交互，且文字/表格无法说清风险时，才允许画模块/依赖图。该图需要：

1. 只列本次变化相关节点，不画完整系统拓扑
2. 标注真实调用/依赖关系，不要画泛泛的功能分组
3. 说明这张图解决什么风险，否则不画

Mermaid 图表分组（subgraph / box）规范

所有 Mermaid 图表中，属于同一主题、同一系统、同一职责域的节点必须用 subgraph 包裹为同一个 BOX。 这是大型项目中清晰展示模块边界和系统调用关系的关键。

分组原则：

图类型	分组维度	示例
flowchart / graph	按业务阶段、系统边界、职责层	subgraph Stage1["阶段一 前置查询"]
sequenceDiagram	用 box 包裹同一系统/层的参与者	box 本地数据层 包裹 Repository + SQLite
classDiagram	按包/模块分组	namespace Application

flowchart/graph 分组规则：

1. 同一业务阶段的模块必须放入同一 subgraph（如"前置查询阶段"包裹所有查询接口）
2. 同一系统/服务的模块必须放入同一 subgraph（如"外部服务"包裹 KPay API + POS 设备）
3. subgraph 嵌套不超过 2 层，避免视觉混乱
4. subgraph 必须使用 ID["显示名"] 格式，ID 用英文，显示名用中文

sequenceDiagram 分组规则：

1. 属于同一系统的参与者必须用 box 包裹
2. 格式：box rgba(颜色) 分组名称，包裹 participant 声明
3. 典型分组：前端层、业务编排层、数据层、外部服务

正确:
  box rgb(212, 237, 218) 本地数据层
    participant REPO as RefundLocalRepository
    participant DB as SQLite
  end

  box rgb(248, 215, 218) 外部服务
    participant KPAY as KPay Cloud
    participant POS as POS Device
  end

错误:（参与者散列，无法看出谁属于哪个系统）
  participant REPO as RefundLocalRepository
  participant KPAY as KPay Cloud
  participant DB as SQLite
  participant POS as POS Device

能力分解图要求

默认不画能力分解图。简单接口设计、单个后端动作、已有模块内的方案开发都不需要能力分解图。

只有当本次需求本身是在切分多项能力边界，且文字/表格无法确认职责边界时，才允许补充能力分解图。

检查清单

完整-业务模版（template.md）检查清单

生成或审查业务方案文档时，必须逐项确认：

• 已按「最小图原则」选择图表，能一张图讲清的场景没有拆成多张图
• 第 2 节至少包含 1 张核心图（接口自身流程图 / 库表读写时序图二选一）
• 主流程和异常流程能合并时已合并到同一张图，通过判断节点表达路径
• 未画功能模块总览图；如确实画了，已说明其解决的具体交互风险
• 未画能力分解图；如确实画了，已说明文字/表格无法确认的能力边界
• 类调用关系不涉及核心逻辑时没有画图，改用编码落点表和一句话职责
• 第 5 节数据结构、下游依赖、缓存、消息、锁、事务只写本次变化，不复写项目全集资料
• 所有图表中同一主题/系统/职责域的节点已用 subgraph（flowchart）或 box（sequenceDiagram）分组
• 文档中无任何 ASCII 框图（┌─┐、│、└─┘、→、↓ 等字符画）
• 文档不包含字段级接口契约（已分流到 api-doc）
• 所有 Mermaid 代码块已通过 markdown-writing-standards 自检清单

完整-技术模版（template-tech.md）检查清单

生成或审查技术方案文档时，必须逐项确认：

• 第 2 节包含 1 张整体架构图（flowchart + subgraph 分组），区分新增/已有/外部依赖
• 第 3 节每个新增模块独立一节，含定位、职责（≤3 条）、上下游、关键设计点
• 第 4 节使用多张小时序图（至少 2 张，一般 3-5 张），每张只讲一个 critical path
• 没有把所有交互合并到一张大 sequenceDiagram（这是技术方案最常见的反模式）
• 第 6 节编码落点用目录树展示，每行带 [新增/修改/不变] + 一句话职责
• 第 7 节数据/依赖变更只写本次变化
• 文档不包含字段级接口契约（已分流到 api-doc）
• 所有图表使用 subgraph / box 分组
• Mermaid 代码块通过 markdown-writing-standards 自检清单

轻量模版检查清单

生成或审查轻量设计文档时，必须逐项确认：

• 第 1 节代码入口已写明 Service / DAO 入口（编码前可写「待实现」）
• 第 3 节包含 1 张 mermaid 核心图（flowchart 或 sequenceDiagram），能讲清接口自身执行路径
• 若使用 sequenceDiagram，每条关键 SQL 后挂 Note over DB，说明字段 + 业务含义
• 第 4 节关键过滤/写入规则表已列出所有非显然的过滤条件
• 第 5 节失败行为表已覆盖入参校验 / 业务规则 / SQL 异常三类
• 文档中无任何 ASCII 框图
• Mermaid 代码块通过 markdown-writing-standards 自检清单

---

终版文档（current）

Git 管理下的项目正式文档以稳定/current 文档为主。版本快照只作为少数场景的辅助，而不是日常迭代默认动作。

文件名格式	用途	更新方式
{需求名称}-current.md	默认正式设计文档（业务方案 / 技术方案），反映当前代码的实际实现	随代码演进直接更新，历史由 Git 负责
{需求名称}-api-current.md	接口文档，与 current 配套；如涉及对外接口必须存在	接口签名变更时同步更新
{需求名称}-coding.md	完整模版对应的当前编码摘要	随 current 文档同步更新
snapshots/{需求名称}-{YYYYMMDD}-v{N}.md	重大基线、发布快照、用户明确要求或非 Git 管理场景	创建后不再修改，后续变更另建快照
snapshots/{需求名称}-api-{YYYYMMDD}-v{N}.md	接口文档对应快照	同上

终版文档规则：

• 无版本号、无日期前缀，命名固定为 {需求名称}-current.md
• 内容结构与完整设计文档模板一致，但头部注明「最后更新日期」
• 每次代码变更后同步更新，保证与代码一致
• 存在 current.md 时，AI 编码优先读取 current.md（而非历史版本快照）
• 不在 current.md 里堆“本次改了什么”的流水账；这类说明写入 git commit body

查找优先级（第一步查找文档时）：

1. {需求名称}-current.md（终版，优先）
2. {需求名称}-api-current.md（接口文档，如涉及接口）
3. {需求名称}-coding.md（当前编码摘要，完整模版需要）
4. snapshots/{需求名称}-{YYYYMMDD}-v{N}.md 或历史 {需求名称}-{YYYYMMDD}-v{N}.md（最新快照）

---

合法的例外情况

以下情况可以完全跳过设计文档检查（不需要文档、也不需要文档留痕）：

• 单元测试补充
• 配置文件修改（非业务规则相关）
• 与设计文档完全无关的纯 Bug 修复（如修字符串拼写、import 排序）
• 代码重构（不改变业务逻辑、不改变文档已声明的边界）
• 极简代码调整：满足下方[极简改动硬清单]全部条件时跳过文档，git commit body 即变更说明

极简改动硬清单（必须全部 ✅ 才能走本分支）

任意一项 ❌ 即退回正常流程（第一·七步模版分级 / 第四·五步轻量修订）。严禁口头判定"差不多就跳过"。

• ≤2 文件 且 ≤30 行净变更
• 0 新类、0 新数据库表/字段、0 新对外契约入口（HTTP 路径 / Feign 方法）
• 既有出参字段语义不变（仅新增字段，向前兼容）
• 无业务规则改动、无状态机调整、无新中间件/锁/事务
• 不跨模块/跨服务
• 改动性质属于以下一种：
  • 透传层补漏字段（BFF / Gateway / Adapter）：DTO mirror 上游 SDK 已存在的字段、Service 加 setter 透传映射
  • 局部行为修正：参数边界、空判、字符串文案、日志、调试输出
  • 简单条件分支调整（不改变方法对外语义）
  • 移除无用代码 / dead code
  • 注释、import 整理

极简分支处理动作

1. 不生成轻量草稿、不生成 coding.md、不更新设计文档
2. 代码改动遵循 bugfix-coding-style：源码内不留变更日志注释，旧逻辑由 git log 承担
3. commit body 必须承担变更说明职责，至少包含：
   • 改了什么（具体字段 / 方法 / 行号）
   • 为什么改（动因，如"上游 SDK 已存在但 BFF 漏接收"）
   • 影响范围（如"纯字段新增、向前兼容，不影响下游契约"）

极简分支判定边界示例

✅ 走极简跳过：

• BFF DataSyncPushEvent DTO 加 2 个字段 mirror 上游 SDK 已有字段 + impl 加 2 行 setter 映射（4 行净变更）
• Controller 方法加一行 trim 入参的空判
• 把魔法数字 3 替换成已有枚举 OrderState.PAID.code
• 删除 if (false) { ... } dead code 块

❌ 必须进入正常流程：

• 改动 5 行但其中 1 行重命名了入参字段 → 改语义（破第 3 项），按轻量模版处理
• 顺手抽了一个 _buildXxxKey 私有方法 → 0 新方法（破第 2 项的精神），按轻量模版处理
• BFF 端对上游字段做了过滤/聚合再返回 → 不再是纯透传（破改动性质条件）

红线

想法	正确处理
"顺手把这个字段名也规范一下"	改字段名 = 改语义 → 退回正常流程
"顺便加个新方法吧"	0 新方法是硬阈值 → 退回正常流程
"一个文件 50 行没事吧"	≤30 行净变更是硬阈值，超了立即退回
"commit body 写一行 'fix' 就够"	错。极简分支跳过文档的代价是 commit body 必须承担变更说明，不写清楚 = 流程违反
"好像有点像极简，又有点像轻量，就走极简吧"	凡边界模糊一律按上一档处理（轻量），极简分支只接收明确命中清单的改动

与"轻量修订"和"完整流程"的区别

改动性质	处理方式
设计文档已存在，且改动会影响文档已描述的业务规则/边界	第四·五步：轻量修订（必要时更新稳定/current 文档，变更说明写 commit body）
设计文档不存在或改动引入新功能/接口/类/字段	第三/五步：创建或更新稳定文档；仅例外场景新建快照
改动满足[极简改动硬清单]	本节：极简跳过（git commit body 即变更说明，无需文档）
改动与任何设计文档都无业务关系（测试 / 配置 / 拼写 / 重构）	本节：合法例外（完全跳过）

判断标准： 是否会让设计文档与代码的描述失真。如有疑问，按"轻量修订"处理；若连设计文档都没有且改动确实只是字段透传/局部修正，再考虑[极简跳过]。不允许通过"看起来很简单"绕开模版分级。

---

与其他 Skill 的协作关系

Skill	何时调用
markdown-writing-standards	生成或修改设计文档中的 Mermaid 图表时，必须先调用进行语法自检
doc-index-required	创建设计文档前必须先执行 Phase-A（读 INDEX、查重、判断新建/补充）；写完后必须执行 Phase-B 登记索引。用户目录知识库与项目 docs/ 同等执行（v1.20 起）
backend-knowledge-graph-required	后端接口/服务需求分析与编码前，若项目存在 docs/knowledge-graph/backend/，必须先读取后端知识图谱中的能力、流程、表逻辑、原子能力、枚举、API 与外部依赖；编码后同步表读写、状态判定和原子能力变化
pre-implementation-code-orientation	设计文档确认完毕、开始写第一行实现代码前调用
dev-log	仅 team-standards 自身发生决策型规则变更时调用；业务项目设计文档的普通演进由 git commit body 记录

---

红色警告

以下想法出现时立即停止，回到文档检查流程：

理由	正确处理
"需求很简单，不需要设计文档"	简单功能的文档也可以简单，但不能没有
"用户让我快点做"	先确认文档，再快速实现
"我已经理解需求了"	理解 ≠ 文档存在，仍须检查
"只改一个方法"	判断是否属于例外情况，否则仍须检查
"直接建文件，不用查索引"	必须先执行 doc-index-required Phase-A（读 INDEX 查重）；用户目录知识库与项目 docs/ 同等待遇
"先把草稿也放到 docs/design 里"	AI 生成文档默认放用户目录知识库 ai-docs/{project}/design/；终版由用户自行上传，或用户明确指定 docs/... 路径后再写项目目录
"直接建文件，不用确认输出路径"	仍需先执行 doc-index-required 的输出路径回显 + Phase-A；不论用户目录还是项目 docs/ 都不豁免
"doc-index-required 会自动触发"	不会。必须在本流程中显式调用 Phase-A 和 Phase-B；写到用户目录也必须调用
"用户目录是草稿，可以随便写"	错（v1.20 起）。用户目录承载本项目知识图谱和 1-to-N 长期文档，与项目 docs/ 享有同等的索引规范
"同一需求每次新建 -{日期}-v1.md"	错。默认更新 -current.md；版本快照仅限重大基线/发布或用户明确要求
"路径里加 claude/ 或 codex/ 隔离一下吧"	错。{agent} 层已废除；所有 AI agent 共享同一知识库
"子功能文件放父目录就行"	子模块必须创建独立子目录，禁止将文件直接放在父需求目录下
"项目文档已经进 Git，但每次变更还要新建 vN 文件"	不需要。Git 管理下默认更新稳定/current 文档，历史由 commit 负责；只有重大基线、非 Git 文档或用户明确要求才建快照
"文档末尾追加调整流水更保险"	默认不要。流水账属于 commit body；设计文档只描述当前业务规则、接口、表操作和实现边界
"设计文档确认了，直接写代码"	还差一步：必须确认 -coding.md 存在后才能编码
"coding 文档内容简单，不用生成"	无论多简单，coding 文档是编码前的第二道强制门禁，不可跳过
"用户让我根据文档直接改代码"	有文档 ≠ 已完成设计文档检查，仍须先触发本 skill 确认文档合规，再走 coding.md 门禁
"用户只是让我帮忙改一下代码，不是新需求"	任何源码 Edit/Write 操作都必须先过本 skill，由本 skill 判断是否属于合法例外
"用户已经提供了分析文档，可以直接编码"	分析/梳理文档 ≠ 设计文档，仍须检查用户提供的设计文档路径或生成用户目录设计草稿，并确认 coding.md 门禁
"看着不大就走轻量模版吧"	必须按第一·七步硬清单逐项判定，不允许凭感觉。命中任一升级触发条件立即升级到完整模版
"轻量模版可以省略核心流程图"	核心流程图是轻量模版的核心载体，省略后等于没有设计文档。缺图直接退回让用户补全
"轻量分支没 coding.md，顺手生成一个吧"	轻量分支显式不需要 coding.md，多生成一份只会让 token 浪费 + 后续维护双份。绝对不要主动生成
"改动里要新增表，但其它都不大，走轻量算了"	新增表是硬清单第 1 项 ❌，必须升级到完整模版
"用户说简单改动不需要文档"	用户偏好不能口头放行，必须按[极简改动硬清单]逐项判定。命中所有项才能走极简跳过分支；任何一项 ❌ 都必须按轻量/完整模版走
"极简分支跳过了文档，commit body 也可以简单写"	错。极简跳过的前提是 git commit body 承担变更说明，必须写清"改了什么 + 为什么改 + 影响范围"，否则等于无文档无说明