diff --git a/code-drive/schema.yaml b/code-drive/schema.yaml index 147d00c..e898d67 100644 --- a/code-drive/schema.yaml +++ b/code-drive/schema.yaml @@ -9,6 +9,8 @@ artifacts: instruction: | 创建 requirements.md，作为本次变更“要解决什么、为什么要解决、需要确认哪些业务和技术边界”的事实来源。 + 阶段职责原则（适用于整个 code-drive workflow，强制）：requirements 是用户决策的唯一入口；design / plan / tasks / apply 不得向用户发起任何决策型提问，遇到本阶段无法独立解决的分歧、上游不完整或边界未定时，必须暂停并回退到上游 artifact（apply 阶段通过 blocker.md 触发，由 blocker-revise 决定回退到哪一层）。允许的非决策型交互仅限：读取文件、运行命令、向用户报告"需要回退到上游"这一事实。本原则意味着用户主动参与的流程集中在 requirements 阶段，下游阶段是自治执行 + 异常回退。 + 本阶段用于承接 explore、前序讨论、用户请求和代码库调查结果。requirements.md 面向项目开发者，而不是外部需求方；因此本阶段既要确认业务需求，也要确认技术需求，例如技术选型、架构方向、集成边界、代码约束和验收方式。 requirements.md 的职责是“确认和澄清”：通过对话把需求、边界、取舍和用户决策固定下来。design.md 的职责是“翻译”：把 requirements.md 中确认的内容转化为可执行的技术方案。不要在 requirements.md 展开详细实现步骤、具体文件修改清单或任务 checkbox。 @@ -20,6 +22,9 @@ artifacts: 工作规则： + - 用户交互（强制，不得跳过）：requirements 阶段必须向用户至少请求一次显式确认（工具调用或正文明确提问均可）。即使所有内容都已在 explore 阶段或前序讨论中确认充分、YAGNI 挑战无遗留、无任何待确认问题，仍必须执行最终确认；没有任何待确认内容时，最后一问必须是"当前已无更多内容待确认，是否进入下一步"。未得到用户明确肯定回复（同意 / 进入下一步）前，不得结束 requirements 阶段，不得进入 design 阶段 + - 潜在冲突处理（强制）：撰写过程中或自检时一旦发现"潜在冲突"——即任何两条需求、约束或决策之间存在矛盾、取舍未定、可解读不一致或可能相互排斥的情况——必须立即暂停撰写，把冲突点加入向用户确认的流程，按"2-3 个选项 + 推荐方案 + 取舍说明"逐项让用户决策。用户决策后，结论按性质归入对应章节（功能需求 / 非功能需求 / 技术需求 / 被否决方案等），冲突本身不得以任何形式单独保留，也不得以"待协调""需进一步讨论"等模糊措辞残留 + - 待解决问题处理（强制）：requirements.md 不得残留任何形式的"开放问题""TBD""待确认"章节或条目。撰写过程中产生的任何疑问（技术选型分歧、需求边界不清、YAGNI 取舍、依赖约束未定等）必须立即纳入用户确认流程，按"2-3 个选项 + 推荐方案"逐项让用户决策；决策结论按性质归入对应章节（功能需求 / 非功能需求 / 技术需求 / 被否决方案等）。如果某问题确实需要延续到 design 或 apply 阶段才能解决，必须先与用户确认是否拆分变更或暂时不纳入本次范围，不得在 requirements.md 中以"开放问题"形式保留 - 如果工具支持 todo/plan 工具（如 Claude Code 的 TodoWrite、OpenCode 的 todowrite），复杂变更必须使用它跟踪 requirements.md 的撰写流程（读取上下文、评估范围、提问、全局审查、编写、自检、用户确认），避免遗漏；简单变更可不使用。注意：这里跟踪的是文档撰写进度，不是整体变更的实现进度——整体变更进度由 apply 阶段和 tasks.md checkbox 跟踪 - 面向看不到早期对话的人编写，必须保留关键上下文、用户偏好、已确认结论、约束和被否决方案 - 先读取相关上下文并形成初步理解，再向用户提问；不要询问代码库或文档中已经能确认的信息 @@ -30,24 +35,30 @@ artifacts: - 分段呈现理解并逐段确认；复杂内容每段控制在约 200-300 字，确认后再继续下一段 - 必须进行“全局审查”：从系统边界、既有行为、相邻模块、配置、文档、迁移、兼容性、安全、性能和用户流程角度挑战当前需求 - 功能需求必须带验收标准；非功能需求只记录本次变更相关内容 - - 技术需求必须记录已确认的技术选型、架构方向、集成边界、代码约束或禁止事项；未确认的技术选项放入开放问题，不要擅自定论 - - 待解决问题必须区分阻塞 apply 的问题和非阻塞后续问题；阻塞性开放问题最多 3 个，超过时必须先与用户决策或建议拆分变更；没有问题时写“无” + - 技术需求必须记录已确认的技术选型、架构方向、集成边界、代码约束或禁止事项；未确认的技术选项必须先暂停向用户确认，不得擅自定论也不得以未决形式残留 - 不要写具体文件修改步骤、代码结构、任务 checkbox 或详细实现计划 - 必需章节（建议使用模板中的中文章节标题）：背景与目标、讨论记录、功能需求、非功能需求、技术需求、全局审查、开放问题。 + 必需章节（建议使用模板中的中文章节标题）：背景与目标、讨论记录、功能需求、非功能需求、技术需求、全局审查。 简单变更保持精炼；复杂或横切变更必须写足够细节，避免后续 design/plan/apply 依赖未写入文档的聊天上下文。 写完后自检（逐项检查并内联修复，无需二次 review）： - - 占位符扫描：是否残留模板注释、英文模板句子、TBD、待补充或空表格行 + - 占位符扫描：是否残留模板注释、英文模板句子、TBD、待补充、空表格行或"开放问题"章节 - 章节完整性：所有必需章节都已填写；功能需求、非功能需求和技术需求没有明显遗漏 - - 上下文一致性：讨论记录中的“已确认结论”都已落入对应章节；被否决方案没有被复用 + - 上下文一致性：讨论记录中的"已确认结论"都已落入对应章节；被否决方案没有被复用 + - 冲突清零：扫描所有功能需求、非功能需求、技术需求和约束之间是否存在矛盾、歧义或取舍未定；任何"潜在冲突"必须已通过用户确认解决，文档中不得残留"待协调""需进一步讨论"或未决矛盾 + - 待确认问题清零：扫描全文是否存在"开放问题""TBD""待确认""待讨论"等未决条目；任何撰写过程中产生的疑问必须已通过用户确认解决并归入对应章节 - 全局审查充分性：系统边界、既有行为、相邻模块、配置、迁移、兼容性都被审视过 - - YAGNI：每条需求都经过挑战，没有“未来可能需要但本次不必需”的功能 + - YAGNI：每条需求都经过挑战，没有"未来可能需要但本次不必需"的功能 - 范围合适：变更聚焦到能用单一 design.md 承接，还是需要拆分为多个子变更 - 写完并自检后，向用户简要展示关键决策点（功能需求、技术需求、阻塞性开放问题），并请求确认。用户提出修改时，修改后重跑上述自检。 + 自检完成后，必须向用户请求最终确认（不得跳过，工具调用或正文明确提问均可）： + + - 展示关键决策点：功能需求、技术需求各一句话总结 + - 如果仍有需要确认的内容（技术选型分歧、YAGNI 取舍、依赖约束未定等），按"2-3 个选项 + 推荐方案"逐项提问 + - 如果确实没有任何待确认内容，必须输出最后一问："当前已无更多内容待确认，是否进入下一步" + - 用户明确肯定（同意 / 进入下一步）后，本阶段才算结束；用户选择补充或提出修改时，根据用户反馈调整内容并重跑自检 + 再次请求确认 requires: [] - id: design generates: design.md @@ -70,34 +81,34 @@ artifacts: - requirements.md 确认了技术选型，但未检查项目中该依赖的安装状态或版本约束 - requirements.md 确认了架构方向，但未检查现有代码中是否有可复用的组件、工具函数、数据结构、API 模式或架构约定 - 需求涉及的模块在 requirements.md 或前序讨论中未被探索过 - - 用户在 design 阶段提出了新的技术问题 探索深度根据变更规模和既有探索充分度调整： - 简单变更且 requirements.md 已有充分探索：快速确认即可，无需详细重复记录 - 复杂变更或 requirements.md 探索不足：详细检查依赖、现有代码、项目规范，并记录发现 - 探索结果记录在 design.md 的“代码库探索”章节。如果探索发现与 requirements.md 的假设冲突，暂停并告知用户。 + 探索结果记录在 design.md 的“代码库探索”章节。如果探索发现与 requirements.md 的假设冲突，视为 requirements 不完整，暂停并要求回退到 requirements 阶段补充决策；不在 design 阶段代替用户做需求层决策。 工作规则： + - 阶段职责（强制）：design 阶段不得向用户发起任何决策型提问。本阶段遇到本阶段无法独立解决的分歧、上游不完整或边界未定，必须暂停并回退到 requirements 阶段（让用户在 requirements 上下文中做决策）；允许的非决策型交互仅限：读取文件、运行命令、向用户报告"需要回退到 requirements"这一事实 - 如果工具支持 todo/plan 工具（如 Claude Code 的 TodoWrite、OpenCode 的 todowrite），复杂变更必须使用它跟踪 design.md 的撰写流程（读取 requirements、代码库探索、编写各章节、自检），避免遗漏；简单变更可不使用。注意：这里跟踪的是文档撰写进度，不是整体变更的实现进度 - 对关键技术决策给出理由，并记录至少一个被否决方案或主要取舍 - - 如果存在多个合理技术方向，先向用户呈现 2-3 个方案、适用条件和风险；如果工具支持，优先使用 question/choice 工具收敛决策 - - 明确目标、非目标、影响范围、依赖约束、风险权衡和待确认事项 - - 如果 requirements.md 仍有阻塞性开放问题，不要猜测答案；暂停并请求用户决策 + - 如果发现 requirements.md 未对关键技术方向做出唯一决策（即存在多个合理且未排除的方向），视为 requirements 不完整，暂停并要求回退到 requirements 阶段补充决策；不得在 design 阶段代替用户做需求层决策 + - 明确目标、非目标、影响范围、依赖约束、风险权衡 - 设计必须基于代码库现实，而非从零假设；如果探索发现现有代码可复用，优先复用而非新建 - - 不要引入 requirements.md 未确认的新需求、外部依赖或架构方向；不要引入 requirements.md 未确认且代码库中不存在的新依赖，除非有充分理由并经用户确认 + - 不得引入 requirements.md 未确认的需求、外部依赖、架构方向或范围；如发现必须依赖 requirements.md 未确认的新内容，视为 requirements 不完整，暂停并回退到 requirements 阶段 - 必需章节（建议使用模板中的中文章节标题）：代码库探索、整体方案、目标 / 非目标、关键决策、影响范围、依赖与约束、风险 / 权衡、验证方向、待确认事项。 + 必需章节（建议使用模板中的中文章节标题）：代码库探索、整体方案、目标 / 非目标、关键决策、影响范围、依赖与约束、风险 / 权衡、验证方向。 写完后自检（逐项检查并内联修复，无需二次 review）： - - 占位符扫描：是否残留模板注释、英文占位内容或空表格行 + - 占位符扫描：是否残留模板注释、英文占位内容、空表格行或"待确认事项"章节 - 需求覆盖：requirements.md 的每条功能需求都有决策覆盖；技术需求被正确引用或落地 - 决策合理性：每个关键决策有理由，并记录至少一个被否决方案或主要取舍 - 代码库现实：设计基于代码库探索发现，而非从零假设；没有引入 requirements.md 未确认的新依赖 - 验证方向对齐：验证方向覆盖了 requirements.md 的功能验收标准和非功能需求 + - 待确认问题清零：扫描全文是否存在"待确认""TBD""待讨论"等未决条目；任何撰写过程中产生的疑问必须已通过回退到 requirements 阶段解决，design.md 不得残留任何形式的"待确认事项" requires: - requirements - id: plan @@ -116,6 +127,7 @@ artifacts: 工作规则： + - 阶段职责（强制）：plan 阶段不得向用户发起任何决策型提问。本阶段遇到 design.md 太粗、关键决策缺失或与 requirements.md 冲突，必须暂停并要求修订上游 artifact（回退到 design 或 requirements）；允许的非决策型交互仅限：读取文件、运行命令、向用户报告"需要回退到上游"这一事实 - 按主要实现阶段组织，每个阶段必须包含目标、前置条件、详细实现步骤、关键代码模式、验证方式、验收标准和关联需求 - 每个阶段必须列出涉及的文件路径、变更类型，汇总到“涉及文件”章节 - 将 design.md 的“验证方向”作为“验证策略”的输入，确保验证角度对齐 @@ -123,9 +135,9 @@ artifacts: - 如果工具支持 todo/plan 工具（如 Claude Code 的 TodoWrite、OpenCode 的 todowrite），复杂变更必须使用它跟踪 plan.md 的撰写流程（读取上游、编写实现概览、编写各阶段、编写验证策略、自检），避免遗漏；简单变更可不使用。注意：这里跟踪的是文档撰写进度，不是整体变更的实现进度 - 每个阶段应能独立验证，或明确说明依赖哪个前置阶段 - 不要写 checkbox；不要新增未经 design.md 确认的架构、依赖或范围 - - 如果 design.md 太粗、关键决策缺失或与 requirements.md 冲突，先暂停并要求修订上游 artifact + - plan.md 不得残留任何形式的"待确认事项""TBD""待补充"章节或条目；撰写过程中发现的实现层未决问题必须基于 design.md 已有决策自行确定最优解，无法确定则回退到 design 或 requirements 阶段 - 必需章节：实现概览、涉及文件、阶段 1..N、验证策略、回退 / 兼容性说明、待确认事项。 + 必需章节：实现概览、涉及文件、阶段 1..N、验证策略、回退 / 兼容性说明。 写完后自检（逐项检查并内联修复，无需二次 review）： @@ -139,6 +151,7 @@ artifacts: - 引用任何阶段都未定义的函数、类型或方法名 - 类型一致性：后续阶段引用的函数名、参数、类型签名与前置阶段定义的匹配 - 验证闭环：每个阶段的验证方式能独立确认该阶段完成；design.md 的“验证方向”在“验证策略”中有体现 + - 待确认问题清零：扫描全文是否存在"待确认事项""TBD""待补充"等未决条目；任何撰写过程中产生的疑问必须已通过上游回退解决 requires: - requirements - design @@ -159,6 +172,7 @@ artifacts: 编写规则： + - 阶段职责（强制）：tasks 阶段不得向用户发起任何决策型提问。本阶段遇到 plan.md 过粗、不可验证或与上游 artifact 冲突，必须暂停并要求修订上游 artifact；允许的非决策型交互仅限：读取文件、运行命令、向用户报告"需要回退到上游"这一事实 - 任务必须从 requirements.md、design.md 和 plan.md 派生，其中 plan.md 是任务分组和关键实现细节的主要依据 - 每个 plan.md 阶段必须有一个对应的 `##` 编号任务分组，分组标题应与 plan.md 阶段名称一致或明显对应 - 每个任务 MUST 是单行 checkbox：`- [ ] X.Y 任务描述` @@ -191,13 +205,14 @@ apply: 执行规则： + - 阶段职责（强制）：apply 阶段不得向用户发起任何决策型提问。本阶段遇到任何需要决策型用户介入的情况（plan 不可行、需要偏离、引入未确认依赖、与既有行为冲突等），必须通过 blocker 机制统一出口，由 blocker-revise 流程决定是否回退到上游 artifact；允许的非决策型交互仅限：读取文件、运行命令、向用户报告阻塞事实并请求其运行 blocker-revise - 按 tasks.md 的依赖顺序处理未完成 checkbox 任务 - 如果工具支持 todo/plan 工具（如 Claude Code 的 TodoWrite、OpenCode 的 todowrite），必须使用它跟踪当前执行进度：每个未完成任务标记为 in_progress 或 pending，完成后标记为 completed；最终完成状态必须同步回 tasks.md checkbox - 每个任务执行前，先读取 plan.md 对应阶段的“涉及文件”“关键代码模式”和“验收标准”，再开始实现；不要只凭 tasks.md 的短描述自行设计实现方案 - - 不要引入 plan.md 未描述的实现路径、依赖、架构或范围；如确需偏离，先暂停并请求用户确认 + - 不得引入 plan.md 未描述的实现路径、依赖、架构或范围；如确需偏离，按本阶段的阻塞处理流程生成 blocker.md，不在 apply 阶段向用户请求决策 - 只有任务执行完成且获得新的实际验证证据后，才能标记 `[x]`；不得基于假设、推测或“应该可以”标记完成 - 完成声明禁用模糊措辞：不得用“应该”、“大概”、“看起来”作为完成依据；必须用实际命令输出、测试结果或可观察行为作为证据 - - 如果 tasks.md 与 plan.md 冲突，以暂停修订为优先，不要硬执行 + - 如果 tasks.md 与 plan.md 冲突，按本阶段的阻塞处理流程生成 blocker.md，不在 apply 阶段向用户请求决策 并行执行（如可用）： @@ -215,7 +230,7 @@ apply: - plan.md 的实现路径不可行或关键假设不成立 - design.md 的技术决策与代码库现实冲突 - - requirements.md 存在阻塞性开放问题 + - 发现 requirements.md / design.md / plan.md 不完整或存在未决策项 - 继续执行会引入未确认的依赖、安全、兼容性、迁移或用户体验风险 - 任务要求与用户意图、全局审查结论或既有系统行为明显冲突 diff --git a/code-drive/templates/design.md b/code-drive/templates/design.md index 6ce5478..8fcc511 100644 --- a/code-drive/templates/design.md +++ b/code-drive/templates/design.md @@ -68,9 +68,3 @@ ## 验证方向 - -## 待确认事项 - -| 状态 | 问题 | 所需决策 | -| ---- | ---- | -------- | -| 无 | 无待确认事项。 | 无需决策 | diff --git a/code-drive/templates/plan.md b/code-drive/templates/plan.md index 738f0cb..ce71b08 100644 --- a/code-drive/templates/plan.md +++ b/code-drive/templates/plan.md @@ -106,9 +106,3 @@ - 错误处理： - 兼容性： - 迁移注意事项： - -## 待确认事项 - -| 状态 | 问题 | 所需决策 | -| ---- | ---- | -------- | -| 无 | 无待确认事项。 | 无需决策 | diff --git a/code-drive/templates/requirements.md b/code-drive/templates/requirements.md index e55fca0..d644b71 100644 --- a/code-drive/templates/requirements.md +++ b/code-drive/templates/requirements.md @@ -51,16 +51,7 @@ -### 潜在冲突 - - - ### 前置条件 - + -## 开放问题 - -| 状态 | 问题 | 所需决策 | -| ---- | ---- | -------- | -| 无 | 无待解决问题。 | 无需决策 |