# 文档驱动开发 (DD) 维护具有不同角色的**两种文档**的工作流程： * **Spec（规格）** : 临时的，受任务限制。以精确的验收标准指导人工智能实施。在开发之前创建，在开发之后存档。 * **Doc（文档）** ：永久的，模块绑定的。按原样描述系统 — 架构、基本原理、业务逻辑。人工智能和人类建筑师的活知识库。生命周期形成一个闭环： Doc(理解现状) → Spec(定义变更) → Dev(计划 + 实现) → Sync(更新文档 + 一致性检查) → Doc'(新的现状) ↑ 小改动在此跳过 ## 命令路由解析 `/dd` 之后的第一个参数：论证|相|行动 ---|---|--- `帮助` |帮助 |解释工作流程、检测项目状态、建议下一步 `初始化` |初始化|设置文档驱动的结构 `规格 <要求>` |规格|创建意图对齐的临时规范 `dev [规范路径|文档路径]` |开发|实现规范（使用计划模式）或文档中的代码 `同步[选项]` |同步 |更新实时文档、存档规范、审核一致性 _（无）_ |与“帮助”相同 | — ### 任务规模调整——选择正确的仪式并非每个变更都需要完整的工作流程。根据变更的性质进行选择：更改类型 |工作流程|示例 ---|---|--- 新功能/行为改变 | `规格 → 开发 → 同步` |添加退款功能多模块设计变更 | `规格 → 开发 → 同步` |重新设计身份验证流程小功能添加 | `开发 → 同步` |向现有 API 添加过滤参数错误修复 | `开发 → 同步` |修复差一错误重构（无行为改变）| `开发 → 同步` |提取函数，重命名模块配置/依赖/拼写错误 |只需代码 |更改环境变量，修复拼写错误 **经验法则**：如果变更引入**新数据模型、新接口、新状态或新业务规则** → 编写规范。如果不是→直接转到dev，但仍然先阅读相关模块文档，然后再同步。 ** ** ## 帮助解释文档驱动的开发并引导用户进行正确的下一步。 ### 工作流程 1. **通过检查检测项目状态**： * `docs/` 是否存在？ → 如果没有，推荐 `init` * `docs/.vitepress/config.mts` 是否存在？ → 如果没有，推荐 `init` * `docs/modules/` 中有模块文档吗？ → 如果为空，建议为现有代码创建文档 * `docs/specs/` 中是否有有效的规范？ → 如果是，推荐`dev` * 是否有未提交的代码更改？ → 推荐`同步` * 模块文档是否过时（上次更新远远落后于最近提交）？ → 推荐`同步` 2. **输出状态摘要** : ## DD 状态项目：[项目名称] 文档结构：[已初始化/未初始化] 模块文档：[N 个模块已记录，M 个模块未记录] 活动规格：[N 个活动，N 个已完成] ## 建议的下一步 → /dd [推荐命令] — [原因] 3. **如果用户看起来不熟悉**，请解释一下核心概念：文档驱动开发维护多个文档： Spec（规格）—临时的，开发前写，指导AI按意图实现 Doc（文档） — 持久的，按模块组织，描述系统现状和设计理由完整工作流程（显着变更）： /dd spec 写规格，单色开发（开发前） ↓ /dd dev 基于研究所进入规划模式，规划后阶段实现 ↓ /ddsync 更新模块文档，归档规范，检查一致性（开发后）轻量工作流程（小）： /dd dev 直接开发（先读模块文档） ↓ /ddsync 更新模块文档定期健康检查： /ddsync --check 只检查不修改，输出一致性报告 ** ** ## 初始化设置文档结构并配置项目以进行文档驱动的开发。 ### 目录结构 1.检查项目根目录下是否存在`docs/` 2. **如果不是（绿地）**，创建核心结构：文档/ ├── .vitepress/config.mts ├── 索引.md ├──modules/ # 实时文档——永久的、按模块的、代码对齐的 │ └── 索引.md ├── specs/ # Specs — 临时的，每个任务 │ └── 索引.md └── adr/ # 架构决策记录 ├── 索引.md └── 000-模板.md （可选）询问用户是否需要其他目录（例如“product/”、“business/”、“guide/”）来存储非代码对齐文档。 3. **如果存在（棕地）** ，分析当前结构并无损迁移： * **扫描 `docs/` 下的所有现有目录** — 切勿删除或忽略它们 * 如果 `docs/design/` 存在（旧版 DD 结构）： * 解释：应该审查设计文档并将内容迁移到“modules/”（作为实时文档）或“specs/”（作为活动规范） * 不要自动删除 `design/` — 保留它直到用户确认迁移完成 * 如果 `product/`、`business/`、`guide/` 或其他目录存在 — **保留它们**。这些是非代码对齐的文档，为不同的受众提供服务，并且是对“modules/”的补充。 * 仅添加缺少的 DD 所需目录：`modules/`、`specs/`、`adr/` 4. 生成或**更新** VitePress `config.mts`： * **在导航和侧边栏中包含所有现有目录** - 不仅仅是 DD 目录 * DD目录获得标准标签：模块、规格、ADR * 现有目录保留其当前标签（或从目录名称派生） * 图表的美人鱼插件 * 如果 `config.mts` 已经存在，**将**新条目合并到现有配置中而不是覆盖 5. 编写 ADR 模板 — 参见 [references/templates.md]() § ADR 模板 ### CLAUDE.md 集成在项目的“CLAUDE.md”中附加（或创建）“## Document-Driven Development”部分： ## 文档驱动开发本项目使用文档驱动开发，维护多个文档： ### Spec（规格） - 临时性文档，位于 `docs/specs/`，在开发前创建，开发后归档 - 定义做什么、不做什么、验收标准，指导AI按意图实现 - 命令：`/dd spec <需求>` 创建 ### Doc（模块文档） - 持久性文档，位于`docs/modules/`，描述系统现状和设计理由 - 修改任何代码前，先查找并阅读关联的模块文档 - 代码与文档冲突时，确认后更新文档或修改代码 ### 工作流程 - `/dd help` — 查看项目文档状态和下一步建议 - `/dd spec <需求>` — 创建规格（显着变更时） - `/dd dev` — 按规格或文档实现代码（基于规格时自动进入计划模式） - `/ddsync` — 开发后更新模块文档、归档规格、检查一致性 - `/ddsync --check` — 只检查不修改，输出健康报告如果 `CLAUDE.md` 已经有 DD 部分，请更新它以匹配上面的内容。 ### 确认向用户显示所做的所有更改的摘要，然后确认。 ** ** ## 规格创建临时规范以在开发前协调意图。这是**人类意图与人工智能实现之间的契约**。规范回答：**人工智能应该构建什么，不应该构建什么？** 规范没有解释原因（这是开发后文档的工作）。 ### 自规格模式代理自主起草规范，然后将其提交给用户审核。代理承担繁重的工作，人类验证意图。 **代理职责**：分析需求，阅读现有模块文档以了解上下文，起草完整的规范。 **人类责任**：验证规范是否捕获了他们的实际意图，纠正误解，提供代理缺乏的上下文。 ### 工作流程 1. **了解要求** — 如果不清楚，请询问。永远不要假设。 2. **阅读项目背景**： * `CLAUDE.md` / `AGENTS.md` 用于项目约定 * `docs/modules/` 中的现有模块文档（了解当前系统状态） * 相关规范在`docs/specs/`中（避免冲突） * 相关现有代码 3. **计划范围** — 要创建哪些规范。如果范围不明确，请与用户确认。 4. **使用 [references/templates.md]() 中的模板生成规范** § 规范模板 * 使用“status: active”保存到“docs/specs/.md” 5. **自我检查** [references/quality.md]() § 规格质量 6. **更新VitePress索引** — 添加到侧边栏`config.mts` \+更新`docs/specs/index.md` 7. **呈现给用户** — 突出显示需要确认的关键设计决策 ### 规范编写规则规则|坏|好 ---|---|--- 没有含糊的话| “应该”、“可能”、“通常”| “必须”、“当 X 然后 Y” 规格中没有任何理由| “我们选择 PostgreSQL 是因为……” |约束：`必须使用 PostgreSQL` 明确排除 | （沉默）| OUT：OAuth登录、手机注册可验证的验收标准 | “工作正常”| `AC-001：POST /api/x 返回 201 和 {id, status}` 类型化接口 | “接受用户信息” | `函数创建（输入：CreateUserInput）：用户` 编号业务规则|散文段落| `BR-001：当 [条件] 那么 [行动]` 错误处理表| “处理错误” |带有触发器+响应的错误代码表状态机优于散文| “状态随时间变化”|美人鱼状态图+转换表 ### 文档元块每个规范都必须在 frontmatter 之后以元注释开头： ** ** ## 开发按照规范或模块文档实现代码。 ### 基于规范的开发：自动计划模式当开发基于规范时，**始终先进入计划模式**，然后再编写任何代码。这利用了人工智能代理的本机规划功能——无需单独的计划文档。计划模式应该： 1. 仔细阅读规范 2. 阅读当前系统上下文的目标模块文档 3. 将规范分解为实现步骤，将规范部分映射到代码任务 4. 提出方案供用户确认 5. 然后逐步实施，根据规范验收标准验证每个步骤这比静态计划文档更有效，因为代理可以随着实施的进展调整计划。 ### 强制文档绑定在修改任何代码之前，请找到其相关文档： 1.检查代码中`// ref: docs/modules/xxx.md`或者`// ref: docs/specs/xxx.md`注释 2. 将代码模块/目录名称与“docs/modules/”中的模块文档进行匹配 3. 检查“docs/specs/”中“target-modules”引用该模块的活动规范 **如果找到相关文档→在编写任何代码之前完整阅读它。**无论是通过“/dd dev”还是任何其他编码任务调用，此规则都适用。 ### 工作流程 1. **加载上下文**： * 如果给定规格路径 → 阅读规格，则**进入计划模式**（见上文） * 如果给定文档路径 → 读取模块文档，在其文档化架构中实现 * 如果两者都不是 → 使用上面的文档绑定来查找相关文档 * **如果在没有规范的情况下进行重大更改 → 停止。首先建议`/dd spec`。** 2. **阅读相关模块文档** — 了解当前系统状态 3. **实施**遵循以下铁律 4. **实施后分歧检查** - 见下文 ### 实施过程中的铁律情况|所需采取的行动 ---|--- 规范未涵盖场景 | **停止。** 向用户报告差距。不要独立决定。规格不明确 | **停止。** 要求用户澄清。不要假设。找到了比规范更好的方法 | **首先建议更新规范。** 仅在规范更新后更改代码。规格中不包含的功能 | **切勿添加它。** 矛盾模块文档 | **标记它。** 规范在开发期间优先，但必须在同步时解决分歧。在关键业务逻辑点，在代码中添加文档引用： // 参考：docs/specs/xxx.md BR-001 // 参考：docs/modules/yyy.md#业务逻辑 ### 实施后分歧检查实施后，将实际编写的内容与规范进行比较： 1. 对于每个实现的接口/函数，将签名与规范定义进行比较 2. 对于每个接触到的数据模型，将字段与规格表进行比较 3. 对于每个业务规则 (BR-NNN)，确认代码逻辑与 WHEN/THEN 匹配 **如果发现分歧**： * 列出每个分歧以及代码位置和规范参考 * 询问用户：**更新规范**以符合现实，或**修复代码**以符合规范？ * 不要默默地继续——每个分歧都必须明确解决 ** ** ## 同步保持文档健康的单个命令。将**文档更新**（开发后）与**一致性审核**（检测漂移和腐烂）相结合。 ### 模式调用|模式|它的作用 ---|---|--- `/dd 同步` | **更新** |更新模块文档以了解最近的更改、存档规范、运行一致性检查 `/dd 同步 --check` | **仅限审核** |完整的项目健康检查——报告问题而不修改任何文件 `/dd 同步 --scope=commit` | **范围更新** |只处理受当前 git diff 影响的模块 `/dd 同步 <模块文档路径>` | **有针对性的更新** |同步特定模块文档 ### 何时同步 * **在`/dd dev`** 之后 — 总是。这是任何代码更改后自然的下一步。 * **定期** — 运行“/ddsync --check”以在漂移累积之前捕获它。 ### 更新工作流程（默认模式） 1. **确定发生了什么变化**： * 如果规范存在 → 阅读规范 + 代码差异以了解更改 * 如果没有规范 → 阅读代码 diff + git log 以了解更改 2. **阅读`docs/modules/`中的现有模块文档** * 如果更改的代码不存在模块文档 → 使用 [references/templates.md]() 创建一个 § 模块文档模板 3. **生成文档更新** — 这是核心转换： **从规范中提取并注入文档**： * 决策理由（为什么选择这种方法，考虑了哪些替代方案） * 约束现在是永久系统属性 * 新的业务规则（从 BR-NNN 格式转换为带有上下文的叙述） **从代码中，在文档中更新**： * 当前数据模型状态（现在实际存在哪些字段） * 当前的接口签名（API 现在的实际情况） * 当前状态机（实际存在什么状态和转换） * 架构变化（新模块、变化的关系） **保存在文档中**： * 历史原理仍然适用 * 架构上下文没有改变 * 已知限制和未来计划（如果相关则更新） 4. **对受影响的模块运行一致性检查**（见下文） 5. **向用户呈现结果**： * 文档更新差异（建议的更改） * 一致性报告（发现的任何问题） * 用户在撰写前评论并确认 6. **存档规范**（如果使用过）： * 更改规范 frontmatter `status: active` → `status: Completed` * 在 frontmatter 中添加 `completed: YYYY-MM-DD` * 移至“docs/specs/archive/”（或根据用户偏好删除） 7. **更新VitePress索引** - 侧边栏，父index.md 8. **更新模块文档 frontmatter 中的`last-updated`** ### 一致性检查这些检查在更新模式下自动运行，或在“--check”模式下独立运行： **1\.代码-文档一致性**（关键） * 代码匹配模块文档表中的数据模型字段 * 函数/API 签名与模块文档接口匹配 * 业务逻辑与记录的业务规则相匹配 * 错误处理涵盖所有记录的错误场景 * 状态转换与记录的状态机相匹配 **2\.未实现的内容检测**（严重） * 文档包含数据模型/接口/业务规则定义，**没有相应的代码** * 这意味着该文档具有“未来状态”内容，该内容应该是规范，而不是文档 * 操作：将未实现的部分**提取**到 `docs/specs/` 中作为新的活动规范，并将它们从模块文档中删除 * 例外：`已知限制`部分可以简要提及计划的功能（例如，“手机号注册暂未实现”），但不得包含实现细节（没有数据模型，没有接口定义，没有针对未构建功能的 BR-NNN 规则） **3\.文档与文档的一致性**（关键） * 扫描所有模块文档以查找共享实体（相同的表、接口、枚举、字段） * 当同一个实体出现在多个文档中时，比较定义 * 标记冲突的定义 * 建议：合并为一个文档并在其他地方使用交叉引用 **4\.规格卫生**（警告） * 近期没有开发活动的活跃规格（过时的规格） * 已完成的代码，其规格仍标记为“活动”（忘记同步） * 目标模块没有对应模块文档的规范 **5\.文件腐烂检测**（警告） * 没有相应模块文档的代码模块 * 已删除/更改代码的模块文档描述 * 文档之间的交叉引用链接已损坏 * `last-updated` 明显早于最近提交的代码 **6\.信息重复**（警告） * 在多个模块文档中完整定义相同的数据模型 * 多个文档中描述的相同业务规则 * 推荐：定义一次，在其他地方交叉引用 **7\.文档质量**（信息） * 缺乏设计决策的基本原理 * 缺少架构上下文或模块关系 * 没有 TL;DR 块的模块文档 * 规格中的模糊词语（应该/可能/通常）完整的质量标准：[references/quality.md]() ### 报告格式更新模式和 --check 模式都会输出一致性报告： ## DD 同步报告 ### 文档更新 - [x] `docs/modules/ payment.md` — 更新了数据模型，添加了退款业务规则 - [x] `docs/specs/refund.md` — 已存档（状态：已完成） ### 严重 — 代码文档不一致 - [ ] `src/xxx.ts:42` 与 `docs/modules/xxx.md#接口定义` 代码：`function foo(a: string): void` 文档：`function foo（a：字符串，b：数字）：结果` ### 严重 - 文档中未实现的内容 - [ ] `docs/modules/auth.md#DataModel` 定义表 `phone_verifications` — 未找到相应的代码 → 提取到 `docs/specs/phone-auth.md` 或从文档中删除 - [ ] `docs/modules/ payment.md#接口定义`定义了`refundBatch()` — 未实现 → 提取到规格或删除 ### 严重 — 文档与文档之间的冲突 - [ ] 实体 `UserStatus` 定义不同： `docs/modules/auth.md#数据模型`: enum('active','inactive') `docs/modules/membership.md#数据模型`: enum('活动','暂停','关闭') ### 警告 — 规格卫生 - [ ] `docs/specs/refund.md` 状态为 `active` 但所有代码均已实现 ### 警告 — Doc Rot - [ ] `docs/modules/ payment.md` 最后更新于 2025 年 10 月 1 日，但 `src/ payment/` 自此有 12 次提交 - [ ] `docs/modules/auth.md#DataModel` 字段 `legacy_token` 在代码中找不到 ### 警告——重复 - [ ] 表“users”在“docs/modules/auth.md”和“docs/modules/profile.md”中完全定义 → 保留`auth.md`，用交叉引用替换`profile.md` ### 信息 — 质量 - [ ] `docs/modules/ payment.md` 缺少选择 Stripe 而不是 PayPal 的理由 ### 统计数据 - 检查模块文档：N |检查规格：N |检查的代码文件：N - 更新：N |关键：N |警告：N |信息：N 在“--check”模式下，“文档更新”部分被“建议更新”替换，显示**将**更改的内容。 ### 文档写作规则（与规范不同！）文档用于**理解是什么**，而不是用于**规划将会是什么**。相应地写：规则|如何 ---|--- **仅当前状态** |文档中的每个数据模型、接口和业务规则都必须存在于代码中。没有“未来”的实施细节——这些只是规范。解释为什么 |每个设计选择都应该有理由：“使用 PostgreSQL 而不是 MongoDB，因为需要强一致性的事务支持” 描述当前状态 | "注册模块目前支持邮箱注册，手机号注册因国际化短信成本暂缓（参见ADR-003）" 显示模块关系 |美人鱼图显示了该模块如何与其他模块连接包括已知的限制 |仅简要说明：“当前不支持批量导入”——未构建功能没有实现细节保持可扫描性 | TL;DR优先，图表胜于散文，数据模型表格尺寸限制 |单个模块文档 ≤ **200 行**。如果更长，则分成子文档。 ** ** ## VitePress 索引维护在“docs/”下进行任何文档更改后，始终： 1. 阅读 `docs/.vitepress/config.mts` 2. 将新文档添加到侧边栏项目 3. 将新目录添加到侧边栏组+顶部导航 4. 使用新文档的链接更新父“index.md” 5. 验证所有侧边栏引用都指向现有文件 ** ** ## 参考文献 * **[references/templates.md]()** — 规范模板、模块文档模板、ADR 模板、frontmatter 模式。 * **[references/quality.md]()** — 规格和文档的质量检查表。自查、复习时阅读。

DD

包含技能