upgrade sm-flow v3.1 workflow
This commit is contained in:
zhuyongxin
@@ -378,6 +378,98 @@ Phase 4 回填 devflow，并确认是否 archive
|
||||
|
||||
`sm-flow` 不是 OpenSpec 的替代品，而是 OpenSpec 的上下文增强层和归档闭环层。
|
||||
|
||||
## v3.1：可执行 gate 与使用摩擦修正
|
||||
|
||||
v3.1 来自一次真实使用复盘：接口变更文档粒度、propose 后再 grill 的返工感、devflow 增长后的检索成本、子 skill 路径兼容，以及 Phase 3 中用户质疑和代码发现与原设计冲突时的处理方式，都需要变成可执行规则。
|
||||
|
||||
v3.1 不改变 v3 的主轴：
|
||||
|
||||
> `devflow/` 提供上下文，OpenSpec 提供执行依据，代码只是实现结果。
|
||||
|
||||
### Draft / Committed OpenSpec
|
||||
|
||||
Phase 1 产出的 OpenSpec 统一视为 **Draft OpenSpec**。它是后续 PRD 对齐、grill 和架构审计的讨论对象，不是实现许可。
|
||||
|
||||
Phase 2 和 Phase 2.5 的结论必须回写 OpenSpec。随后新增 Phase 2.9：
|
||||
|
||||
```text
|
||||
Phase 2.9 Commit OpenSpec
|
||||
```
|
||||
|
||||
Phase 2.9 检查：
|
||||
|
||||
- proposal 是否说明范围、非目标和原因。
|
||||
- design 是否记录关键约束、架构风险和接口影响。
|
||||
- specs 是否覆盖可观察行为和验收口径。
|
||||
- tasks 是否是可执行的纵向切片。
|
||||
- 是否还有未确认的 user-interview、未汇报的 evidence-driven 结论、未判级接口影响或 devflow/OpenSpec 冲突。
|
||||
|
||||
只有通过 Phase 2.9 的 OpenSpec 才是 **Committed OpenSpec**，Phase 3 只能执行 Committed OpenSpec。
|
||||
|
||||
### Grill 必须人工确认
|
||||
|
||||
Phase 2 的 `grill-with-docs` 不是代理自问自答。`user-interview` 问题必须一次只问一个，等待用户显式回答，并记录到 `decisions.md`。未获得用户确认的问题不能视为已解决，也不能进入 Phase 2.9 或 Phase 3。
|
||||
|
||||
`evidence-driven` 问题可以由代理先查证，但也必须汇报证据、结论和是否需要用户确认。
|
||||
|
||||
单个 grill 决策确认不等于 Phase 3 apply 授权。用户在 Phase 2 回答“可以”只表示该问题已确认；代理必须先回写 OpenSpec/devflow，停在 Phase 2.9，报告 Committed OpenSpec 检查结果，并等待用户明确要求进入 apply、开始实现、执行修改或继续 Phase 3。
|
||||
|
||||
### 接口影响分级
|
||||
|
||||
v3.1 区分“接口影响记录”和“独立接口文档”：
|
||||
|
||||
- 所有接口变更都必须记录影响范围。
|
||||
- 只有 L3/L4 才强制独立接口文档或等价独立章节。
|
||||
|
||||
分级规则：
|
||||
|
||||
| 级别 | 判断条件 | 产物要求 |
|
||||
| --- | --- | --- |
|
||||
| L1 内部实现 | 不改变调用方可观察行为 | tasks / acceptance 记录验证 |
|
||||
| L2 内部接口 | 内部 DTO、service 方法、内部事件、内部判断逻辑变化，消费者仍在同一实现范围内 | 内联接口影响记录 |
|
||||
| L3 协作接口 | 影响前端、其他模块/服务、跨团队消费者、数据库契约、事件、回调或 SDK | 独立接口文档或独立章节 |
|
||||
| L4 破坏性接口 | 旧调用方可能失败、数据/状态/错误码不同，或需要迁移/灰度/回滚 | 独立接口文档 + 迁移/回滚说明，必要时 ADR |
|
||||
|
||||
接口内部判断逻辑也按可观察行为评估。即使签名和字段不变，只要返回数据、错误码、状态、权限结果、排序/过滤、幂等性、时序或副作用变化，也属于接口影响。
|
||||
|
||||
### Devflow Index
|
||||
|
||||
`devflow/index.md` 成为 Phase 0.5 的默认入口。上下文查找顺序为：
|
||||
|
||||
```text
|
||||
devflow/index.md
|
||||
devflow/glossary/CONTEXT.md
|
||||
相关项目 brief / acceptance / ADR
|
||||
devflow/compound/
|
||||
```
|
||||
|
||||
Phase 4 回填项目档案时必须更新 `devflow/index.md`。最小字段为日期、slug、领域、关键词、关联 OpenSpec 和状态。
|
||||
|
||||
### 实现期冲突处理
|
||||
|
||||
Phase 3 中，如果用户质疑、用户修改、代码发现、测试失败或运行行为与 Committed OpenSpec 冲突，必须先分类：
|
||||
|
||||
| 分类 | 含义 | 处理 |
|
||||
| --- | --- | --- |
|
||||
| 实现偏差 | OpenSpec 正确，代码没有按规格做 | 修代码，不改 OpenSpec |
|
||||
| 规格遗漏 | OpenSpec 没覆盖真实边界、接口影响、验收或外部行为 | 暂停 apply，修正 OpenSpec，重新 commit |
|
||||
| 设计冲突 | OpenSpec 与架构、ADR、历史验收、数据所有权或模块边界冲突 | 暂停并请用户确认设计方向 |
|
||||
| 用户变更 | 用户改变目标、范围、验收或风险接受度 | 更新 proposal/specs/tasks 后继续 |
|
||||
|
||||
冲突分类、证据、用户确认和 OpenSpec 回写状态必须进入 `decisions.md` 或 `acceptance.md`。
|
||||
|
||||
### 子 skill 兼容
|
||||
|
||||
v3.1 将子 skill 从“路径绑定”改为“能力绑定”。例如 `openspec-propose`、`openspec-apply-change`、`to-prd`、`grill-with-docs` 都是能力契约。
|
||||
|
||||
调用优先级：
|
||||
|
||||
1. 平台原生 skill。
|
||||
2. 本地 `SKILL.md`，例如 `.claude/skills/...` 或 `.agents/skills/...`。
|
||||
3. `sm-flow` 的 fallback 协议。
|
||||
|
||||
这样 `sm-flow` 可以在 Claude、Codex 或其他代理环境中迁移，而不会被某个固定目录锁死。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,8 @@
|
||||
1. 如果涉及接口，需要额外产出一份影响接口范围文档
|
||||
1. ❯ 只要涉及到接口里的变更，不管是新增字段还是内部变更，都需要添加到接口影响范围中
|
||||
2. 涉及接口变更，需要产出一份接口文档
|
||||
3. 顺序问题，目前的顺序是propose之后在，生成了task、design之后，再用grill去澄清需求，这样当澄清完需求后，又得回去更新task、design、proposal等文档，现在的流程，是propose之后，再通过to-prd，生成devflow的产物，然后再grill来更新，哪种设计更合理？
|
||||
4. 如果devflow数量多了，如何快速定位需要的上下文
|
||||
5. 子skill现在是固定了claude，要考虑兼容情况
|
||||
6. 当在开发阶段，我发起质疑或者修改，和原来设计冲突时，不要全部接收代码建议，而是向我确认是设计冲突，还是没有考虑到，要提出反馈
|
||||
1. 可能需要加多一个步骤，apply实施过程中的沟通？
|
||||
@@ -1,4 +1,4 @@
|
||||
---
|
||||
---
|
||||
name: sm-flow
|
||||
description: OpenSpec-first、Devflow-assisted 的结构化工程开发元工作流。用户想把粗略想法、issue、PRD 或已有 research 推进为准确 OpenSpec change，并通过 OpenSpec apply 实现、验证、归档时使用；也适用于标准化开发流程、增强 OpenSpec 产物质量、沉淀工程决策和为未来代理保留上下文。
|
||||
---
|
||||
@@ -17,6 +17,8 @@ SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作
|
||||
- `openspec/changes/<change>/` 是执行真理源：当前变更的 proposal、design、specs 和 tasks。
|
||||
- 代码是实现结果：只能在执行真理源足够明确后修改。
|
||||
- 如果 `devflow/` 和 OpenSpec 冲突，不要直接写代码；先汇报冲突、让用户确认，并修正 OpenSpec。
|
||||
- Phase 1 产出的 OpenSpec 默认为 **Draft OpenSpec**：它是澄清和审计对象，不是 Phase 3 的执行许可。
|
||||
- 只有通过 Phase 2.9 提交检查后的 OpenSpec 才是 **Committed OpenSpec**；Phase 3 只能执行 Committed OpenSpec。
|
||||
|
||||
## 核心规则
|
||||
|
||||
@@ -25,16 +27,39 @@ SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作
|
||||
- devflow 默认采用分层产物：只强制保留人类理解和 OpenSpec 校准所必需的档案，避免重复 OpenSpec 的 proposal/design/tasks。
|
||||
- 不得跳过 Phase 0.5：生成或修正 OpenSpec 前，必须读取相关 devflow 上下文。
|
||||
- 不得跳过 Phase 2。即使需求看起来很清楚，也至少解决三个高价值澄清或验证问题。
|
||||
- 不得跳过 Phase 2.9：进入 Phase 3 前，必须确认 Draft OpenSpec 已提交为 Committed OpenSpec。
|
||||
- `evidence-driven` 不是自动通过：凡是通过证据确认的结论，也必须向用户汇报证据、结论和是否需要确认。
|
||||
- `user-interview` 问题必须等待用户确认；涉及范围、偏好、验收口径、风险接受度时不能擅自决定。
|
||||
- grill 过程必须显式 human-in-the-loop：每个 `user-interview` 问题一次只问一个，必须等用户回答并记录确认后才能继续；未确认的问题不能视为已解决。
|
||||
- 单个 grill 决策确认不等于 Phase 3 apply 授权；Phase 2/2.5 回写 OpenSpec 后必须停在 Phase 2.9，报告 Committed OpenSpec 检查结果，并等待用户明确要求进入 apply / 开始实现 / 执行修改 / 继续 Phase 3。
|
||||
- 接口影响按 L1-L4 分级处理；接口内部判断逻辑如果改变调用方可观察行为，也属于接口影响，不能因签名未变而降级。
|
||||
- Phase 3 实现期冲突必须先分类再处理：实现偏差修代码；规格遗漏修 OpenSpec；设计冲突暂停并请用户确认；用户变更更新 proposal/specs/tasks 后再继续。
|
||||
- 架构审计、澄清、ADR 或上下文发现如果影响实现，必须先回写 OpenSpec design/specs/tasks，再进入 Phase 3。
|
||||
- 不得猜测式修 bug。实现失败或行为不明时，先进入 diagnose 闭环；如果根因是规格不准，先修 OpenSpec，再继续 apply。
|
||||
- 默认采用 human-in-the-loop：Phase 1 后、Phase 2.5 后、Phase 3 前必须给用户一个简短检查点，除非用户明确要求“全自动执行”。
|
||||
- 默认采用 human-in-the-loop：Phase 1 后、Phase 2.5 后、Phase 2.9 后、Phase 3 前必须给用户一个简短检查点；除非用户在启动时明确要求“全自动执行”，否则不得把单个决策确认推断为执行授权。
|
||||
- Phase 4 结束前必须询问用户是否归档 OpenSpec change；不要默认执行归档。
|
||||
- 子 skill 必须显式调用或显式降级：进入 Phase 1、1.5、2、2.5、3、4 时，先说明“本阶段调用/加载的 skill 是 X”；如果不能调用，必须说明“降级为 fallback”，并记录降级原因。
|
||||
- 显式调用优先级：优先使用平台原生 Skill 调用；如果平台没有 Skill 工具，则读取对应 `SKILL.md` 并按其协议执行；只有文件不存在或协议不可执行时，才使用 `references/fallbacks.md`。
|
||||
- 子 skill 绑定能力契约，不绑定单一平台路径。显式调用优先级：优先使用平台原生 Skill 调用；如果平台没有 Skill 工具，则读取对应能力的本地 `SKILL.md` 并按其协议执行；只有文件不存在或协议不可执行时，才使用 `references/fallbacks.md`。
|
||||
- fallback 产物必须标注为降级执行，不能伪装成真实子 skill 调用。
|
||||
|
||||
## 接口影响分级
|
||||
|
||||
接口影响分级判断的是“记录在哪里、是否需要独立文档”，不是判断“是否需要关注”。凡涉及字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约、跨模块调用语义或接口内部判断逻辑变化，都必须先判断接口影响。
|
||||
|
||||
| 级别 | 判断条件 | 产物要求 |
|
||||
| --- | --- | --- |
|
||||
| L1 内部实现 | 不改变任何调用方可观察的接口、字段、状态、错误码、数据范围、排序、过滤、权限结果、状态流转、副作用或文档承诺 | 不需要接口影响文档，只在 OpenSpec tasks 或 acceptance 记录验证 |
|
||||
| L2 内部接口 | 改 DTO、service 方法、内部事件、内部 RPC 或内部判断逻辑，且所有消费者都在同一实现范围内 | 必须记录接口影响范围，可内联到 OpenSpec design/specs/tasks 或 devflow evidence/decisions |
|
||||
| L3 协作接口 | 影响其他模块、其他服务、前端、外部系统、跨团队消费者、数据库契约、消息事件、回调或 SDK | 必须产出独立接口文档或等价独立章节 |
|
||||
| L4 破坏性接口 | 删除字段、改字段语义、改状态机、改错误码、破坏兼容、旧调用方可能失败，或需要迁移、灰度、回滚 | 独立接口文档 + 迁移/回滚说明；必要时创建 ADR |
|
||||
|
||||
判断策略：
|
||||
|
||||
- 如果只是修复 bug，让接口回到原 OpenSpec 或原文档承诺，通常是 L1/L2。
|
||||
- 如果判断逻辑改变了返回数据、错误码、状态、权限结果、排序/过滤、幂等性、时序或副作用，至少按 L3 检查。
|
||||
- 如果旧调用方不改代码会失败、少数据、多数据、状态不同或错误码不同，按 L4 处理。
|
||||
- 如果无法确定调用方边界或兼容性，默认提高一级并作为 `user-interview` 问题等待确认。
|
||||
|
||||
## 首次加载
|
||||
|
||||
执行前只读取当前任务需要的 reference 文件：
|
||||
@@ -59,8 +84,8 @@ SM Flow 是一套 **OpenSpec-first / Devflow-assisted** 的软件交付元工作
|
||||
- `devflow/reference/`
|
||||
3. 如果根目录存在旧 `CONTEXT.md`，且 `devflow/glossary/CONTEXT.md` 不存在或为空，询问用户是迁移还是合并。
|
||||
4. 检查 OpenSpec 和子 skill 是否可用：
|
||||
- OpenSpec：`.claude/skills/openspec-propose/SKILL.md`、`.claude/skills/openspec-apply-change/SKILL.md`、`.claude/skills/openspec-archive-change/SKILL.md`。
|
||||
- 辅助技能：`.agents/skills/to-prd/SKILL.md`、`.agents/skills/grill-with-docs/SKILL.md`、`.agents/skills/diagnose/SKILL.md`、`.agents/skills/tdd/SKILL.md`、`.agents/skills/zoom-out/SKILL.md`。
|
||||
- OpenSpec 能力：`openspec-propose`、`openspec-apply-change`、`openspec-archive-change`。可由平台原生 skill、`.claude/skills/.../SKILL.md` 或 fallback 协议提供。
|
||||
- 辅助能力：`to-prd`、`grill-with-docs`、`diagnose`、`tdd`、`zoom-out`。可由平台原生 skill、`.agents/skills/.../SKILL.md` 或 fallback 协议提供。
|
||||
5. 如果 OpenSpec skill 不可用，不要直接绕过执行；先使用 fallback 生成/修正 OpenSpec 产物，并在 Phase 3 前向用户说明执行入口降级风险。
|
||||
|
||||
## 项目标识
|
||||
@@ -101,13 +126,14 @@ devflow 是辅助 OpenSpec 和人类阅读的档案层，不复制 OpenSpec 的
|
||||
## 阶段总览
|
||||
|
||||
1. Phase 0 — 入口澄清：接收初始 PRD、粗略想法或已有 research，澄清到可生成 OpenSpec。
|
||||
2. Phase 0.5 — Devflow 上下文收集：读取 glossary、相关 PRD、ADR、acceptance、compound knowledge。
|
||||
3. Phase 1 — OpenSpec propose：基于需求 + devflow 上下文生成或修正 OpenSpec proposal/design/specs/tasks。
|
||||
2. Phase 0.5 — Devflow 上下文收集：先查 `devflow/index.md`，再读取 glossary、相关 PRD、ADR、acceptance、compound knowledge。
|
||||
3. Phase 1 — OpenSpec propose：基于需求 + devflow 上下文生成或修正 Draft OpenSpec proposal/design/specs/tasks。
|
||||
4. Phase 1.5 — PRD / OpenSpec 对齐：检查 OpenSpec 是否覆盖 PRD、遵守 ADR、使用正确术语、具备可验收 specs。
|
||||
5. Phase 2 — Human-in-the-loop 澄清：声明 `evidence-driven` / `user-interview`，所有结论都汇报，确认后回写 OpenSpec。
|
||||
6. Phase 2.5 — 架构审计：审计结果如果影响实现，必须回写 OpenSpec design/tasks。
|
||||
7. Phase 3 — OpenSpec apply：默认依赖 OpenSpec 执行；devflow 只作为上下文参考。
|
||||
8. Phase 4 — 回填 Devflow：从 OpenSpec、实现结果和验证结果提炼长期档案，并询问是否 archive OpenSpec change。
|
||||
7. Phase 2.9 — Commit OpenSpec：检查 Draft OpenSpec 是否达到可执行状态，提交为 Committed OpenSpec。
|
||||
8. Phase 3 — OpenSpec apply：默认依赖 Committed OpenSpec 执行；devflow 只作为上下文参考。
|
||||
9. Phase 4 — 回填 Devflow：从 OpenSpec、实现结果和验证结果提炼长期档案，更新 `devflow/index.md`，并询问是否 archive OpenSpec change。
|
||||
|
||||
每个阶段的进入条件、动作、输出和退出标准见 `references/phase-contracts.md`。
|
||||
|
||||
@@ -117,6 +143,7 @@ devflow 是辅助 OpenSpec 和人类阅读的档案层，不复制 OpenSpec 的
|
||||
|
||||
- Phase 0.5 最小上下文检查：至少检查 glossary 和相关 ADR。
|
||||
- Phase 2 最小澄清：至少一个术语问题、一个边界问题、一个验收问题；evidence-driven 结论也要汇报。
|
||||
- Phase 2.9 提交检查：即使快速模式也必须确认没有未解决用户问题、接口影响已记录、OpenSpec tasks/specs 可执行。
|
||||
- Phase 3 仍以 OpenSpec tasks/specs 为执行依据。
|
||||
- Phase 4 轻量归档：记录验收结果、OpenSpec 产物链接和是否归档。
|
||||
|
||||
|
||||
@@ -17,6 +17,10 @@ devflow/projects/YYYY-MM-DD-{slug}/
|
||||
- `decisions.md`
|
||||
- `acceptance.md`
|
||||
|
||||
同时维护仓库级索引：
|
||||
|
||||
- `devflow/index.md`
|
||||
|
||||
按需创建以下扩展文件：
|
||||
|
||||
- `prd.md`
|
||||
@@ -49,6 +53,24 @@ devflow/projects/YYYY-MM-DD-{slug}/
|
||||
| diagnose 记录 | 根因、修复、回归验证 | `acceptance.md` |
|
||||
| 词汇表更新 | 术语和业务规则 | `devflow/glossary/CONTEXT.md` |
|
||||
| 可复用经验 | 持久工程知识 | `devflow/compound/YYYY-MM-DD-{type}-{slug}.md` |
|
||||
| 项目索引 | 日期、slug、领域、关键词、关联 OpenSpec、状态 | `devflow/index.md` |
|
||||
|
||||
## 索引维护规则
|
||||
|
||||
`devflow/index.md` 是 Phase 0.5 的默认入口，Phase 4 回填时必须维护。
|
||||
|
||||
最小字段：
|
||||
|
||||
| 日期 | slug | 领域 | 关键词 | 关联 OpenSpec | 状态 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
|
||||
规则：
|
||||
|
||||
- 每个 `devflow/projects/YYYY-MM-DD-{slug}/` 默认对应一行索引。
|
||||
- Phase 4 新建或更新项目档案时，必须新增或更新对应行。
|
||||
- 如果项目仍在进行，状态写 `active`；已验收但未 archive 写 `accepted-unarchived`；已 archive 写 `archived`；暂停写 `paused`。
|
||||
- 关键词只放能帮助 Phase 0.5 定位的术语，不复制 brief 内容。
|
||||
- 如果无法准确判断领域或状态，写 `unknown`，并在 `acceptance.md` 记录待补。
|
||||
|
||||
## 验收记录规则
|
||||
|
||||
@@ -99,6 +121,7 @@ OpenSpec archive 是显式 human-in-the-loop 动作。archive 前必须确认 de
|
||||
Phase 4 结束时告诉用户：
|
||||
|
||||
- 创建或更新了哪些档案文件。
|
||||
- `devflow/index.md` 是否已更新。
|
||||
- 运行了哪些验证，并按静态验证、脚本验证、浏览器/人工验证、未验证分类。
|
||||
- 还剩哪些风险或后续事项。
|
||||
- 明确询问：是否现在 archive OpenSpec change？
|
||||
|
||||
@@ -34,12 +34,20 @@
|
||||
|
||||
1. 阅读 `proposal.md`、`design.md`、`specs/**/*.md` 和 `tasks.md`。
|
||||
2. 确认 OpenSpec 与 devflow 上下文没有未解决冲突。
|
||||
3. 修改前先检查现有代码。
|
||||
4. 一次实现一个 OpenSpec task 的纵向切片。
|
||||
5. 用最窄但有效的命令验证每个切片。
|
||||
6. 只有验证通过或明确记录原因后，才更新 task 状态。
|
||||
7. 如果失败原因不确定，停止并进入 diagnose。
|
||||
8. 如果 diagnose 证明规格不准，先修正 OpenSpec，再继续执行。
|
||||
3. 确认没有未解决的 user-interview 问题、未判级接口影响或未提交的 Draft OpenSpec。
|
||||
4. 确认 Phase 2.9 后已经获得用户明确的 Phase 3 apply 授权；单个 grill 决策确认不能替代 apply 授权。
|
||||
5. 修改前先检查现有代码。
|
||||
6. 一次实现一个 OpenSpec task 的纵向切片。
|
||||
7. 如果用户质疑、代码发现、测试失败或运行行为与 OpenSpec 冲突，先分类：
|
||||
- 实现偏差：OpenSpec 正确，代码偏离；修代码。
|
||||
- 规格遗漏：OpenSpec 未覆盖真实边界、接口影响或验收；暂停执行，修正 OpenSpec 并重新提交后继续。
|
||||
- 设计冲突：OpenSpec 与架构、ADR、历史验收或模块边界冲突；暂停并等待用户确认。
|
||||
- 用户变更：用户改变目标、范围、验收或风险接受度；更新 proposal/specs/tasks 后继续。
|
||||
8. 冲突分类、证据、用户确认和 OpenSpec 回写状态必须记录到 `decisions.md` 或 `acceptance.md`。
|
||||
9. 用最窄但有效的命令验证每个切片。
|
||||
10. 只有验证通过或明确记录原因后，才更新 task 状态。
|
||||
11. 如果失败原因不确定，停止并进入 diagnose。
|
||||
12. 如果 diagnose 证明规格不准，先修正 OpenSpec，再继续执行。
|
||||
|
||||
## PRD fallback
|
||||
|
||||
|
||||
@@ -28,6 +28,8 @@
|
||||
**进入条件**：Phase 0 已经有足够信息定位领域、项目或变更方向。
|
||||
|
||||
**动作**：
|
||||
- 优先读取 `devflow/index.md`，按日期、slug、领域、关键词和关联 OpenSpec 定位候选项目。
|
||||
- 如果 `devflow/index.md` 不存在，先从 `devflow/projects/` 现有目录初始化轻量索引，再继续本次上下文收集。
|
||||
- 读取 `devflow/glossary/CONTEXT.md`，提取相关术语和业务规则。
|
||||
- 搜索 `devflow/projects/` 中相关 PRD、design、tasks、acceptance 和 ADR。
|
||||
- 搜索 `devflow/compound/` 中可复用 learning、trick、decision、explore。
|
||||
@@ -36,6 +38,7 @@
|
||||
|
||||
**退出条件**：
|
||||
- 已形成“OpenSpec 输入上下文摘要”。
|
||||
- 已记录 `devflow/index.md` 的使用状态：已命中 / 已初始化 / 无相关条目。
|
||||
- 已列出相关 ADR 和不能违反的历史决策。
|
||||
- 已列出需要写入或修正 OpenSpec 的上下文点。
|
||||
|
||||
@@ -46,7 +49,7 @@
|
||||
|
||||
**进入条件**：Phase 0 + Phase 0.5 已经足够生成或修正 OpenSpec change。
|
||||
|
||||
**显式子 skill**：`openspec-propose`。进入本阶段必须先声明调用方式：原生 Skill 调用 / 读取 `.claude/skills/openspec-propose/SKILL.md` / fallback 降级。
|
||||
**显式子 skill**：`openspec-propose`。进入本阶段必须先声明调用方式：原生 Skill 调用 / 读取本地 `openspec-propose` 的 `SKILL.md` / fallback 降级。
|
||||
|
||||
**动作**：
|
||||
- 优先调用 `openspec-propose`。
|
||||
@@ -64,7 +67,7 @@
|
||||
- 关键假设已显式记录在 OpenSpec 或 research 中。
|
||||
|
||||
**输出**：
|
||||
- OpenSpec proposal、design、specs 和 task list。
|
||||
- Draft OpenSpec proposal、design、specs 和 task list。
|
||||
|
||||
**Human checkpoint**：
|
||||
- 向用户简要说明 OpenSpec scope、关键假设、主要风险、devflow 上下文如何影响 OpenSpec。
|
||||
@@ -85,11 +88,16 @@
|
||||
- OpenSpec 是否遵守相关 ADR。
|
||||
- specs 是否能表达可观察行为。
|
||||
- tasks 是否能驱动实现，而不是泛泛描述。
|
||||
- 检查是否涉及接口影响：
|
||||
- 是否改变字段、DTO、service 方法、API、事件、回调、数据库契约、命令契约或跨模块调用语义。
|
||||
- 接口内部判断逻辑是否改变调用方可观察行为，例如返回数据、状态、错误码、权限结果、过滤/排序、幂等性、时序或副作用。
|
||||
- 按 L1/L2/L3/L4 记录接口影响等级；不确定时标记为 Phase 2 的 `user-interview` 问题。
|
||||
- 如果发现不一致，优先修正 OpenSpec，而不是只修改 devflow 文档。
|
||||
|
||||
**退出条件**：
|
||||
- `brief.md` 已覆盖背景、目标、范围和非目标；复杂需求存在独立 `prd.md` 或用户明确不需要 PRD。
|
||||
- OpenSpec 与 PRD/devflow 上下文没有已知冲突。
|
||||
- 涉及接口变更时，已记录接口影响等级和产物要求；不确定项已进入 Phase 2。
|
||||
- 所有已知冲突已修正或等待用户决策。
|
||||
|
||||
**输出**：
|
||||
@@ -110,6 +118,10 @@
|
||||
- `user-interview`：问题涉及产品偏好、范围边界、验收口径、风险接受度或价值取舍；必须问用户并等待确认。
|
||||
- 至少覆盖三个维度：术语、边界、验收。
|
||||
- 一次只问一个 `user-interview` 问题。
|
||||
- 每个 `user-interview` 问题必须等待用户显式回答，并把回答、决策和 OpenSpec 回写状态记录到 `decisions.md`；不能由代理代替用户确认。
|
||||
- 未获得用户确认的 `user-interview` 问题必须保持未解决状态，不能进入 Phase 2.9 或 Phase 3。
|
||||
- 单个 `user-interview` 的确认只能解除该问题本身的阻塞，不能被解释为进入 Phase 3 或修改执行目标文件的授权。
|
||||
- 对接口影响等级、消费者边界或兼容性存在不确定时，必须作为 `user-interview` 问题等待用户确认。
|
||||
- 如果澄清结果影响实现，必须回写 OpenSpec proposal/design/specs/tasks。
|
||||
- 术语一旦确认，更新 `devflow/glossary/CONTEXT.md`。
|
||||
- 对难以逆转、依赖上下文、源自真实权衡的决策创建 ADR。
|
||||
@@ -118,6 +130,8 @@
|
||||
- 至少解决三个高价值澄清或验证问题，并记录每个问题属于 `evidence-driven` 还是 `user-interview`。
|
||||
- 所有 evidence-driven 结论已向用户汇报。
|
||||
- 所有 user-interview 决策已获得用户确认。
|
||||
- 没有未解决或代理代确认的 user-interview 问题。
|
||||
- 没有未判级或未确认的接口影响问题。
|
||||
- 影响实现的结论已回写 OpenSpec。
|
||||
|
||||
**输出**：
|
||||
@@ -148,14 +162,46 @@
|
||||
|
||||
**Human checkpoint**：
|
||||
- 用不超过五句话向用户说明架构风险、OpenSpec 修正点和实现计划。
|
||||
- 询问是否进入 Phase 3 OpenSpec apply；用户明确要求“全自动执行”时可跳过等待。
|
||||
- 询问是否进入 Phase 2.9 Commit OpenSpec；用户明确要求“全自动执行”时可跳过等待。
|
||||
|
||||
## Phase 2.9 — Commit OpenSpec
|
||||
|
||||
**进入条件**：
|
||||
- Phase 2 已解决术语、边界、验收三个维度的高价值问题。
|
||||
- 所有 `user-interview` 问题都已获得用户显式确认。
|
||||
- Phase 2.5 架构审计已经完成，或快速模式下已记录跳过原因。
|
||||
- Draft OpenSpec 已回写所有会影响实现的澄清、接口影响和架构审计结论。
|
||||
|
||||
**动作**：
|
||||
- 检查 proposal 是否说明为什么做、做什么、范围和非目标。
|
||||
- 检查 design 是否记录上下文约束、关键技术决策、架构风险和接口影响。
|
||||
- 检查 specs 是否表达外部可观察行为，并覆盖验收口径。
|
||||
- 检查 tasks 是否是可执行的纵向切片，而不是泛泛描述。
|
||||
- 检查接口影响是否已按 L1/L2/L3/L4 判级；L3/L4 是否有独立接口文档或等价独立章节。
|
||||
- 检查没有未汇报的 evidence-driven 结论，没有未确认的 user-interview 问题，没有 devflow/OpenSpec 冲突。
|
||||
- 如果检查失败，返回 Phase 1、Phase 2 或 Phase 2.5 修正 Draft OpenSpec。
|
||||
|
||||
**退出条件**：
|
||||
- Draft OpenSpec 已达到可执行状态，并记录为 Committed OpenSpec。
|
||||
- Phase 3 所需的 proposal、design、specs 和 tasks 均存在且一致。
|
||||
- 所有 Phase 3 preflight 风险已消除或明确记录为已接受。
|
||||
|
||||
**输出**：
|
||||
- Committed OpenSpec 状态说明。
|
||||
- Phase 3 preflight 检查结果，默认写入 `decisions.md` 或 `acceptance.md`。
|
||||
|
||||
**Human checkpoint**：
|
||||
- 用不超过五句话说明 Committed OpenSpec 的范围、接口影响、剩余风险和执行计划。
|
||||
- 询问是否进入 Phase 3 OpenSpec apply；除非用户在启动时明确要求“全自动执行”，必须等待用户明确说出进入 apply、开始实现、执行修改、继续 Phase 3 或等价授权。
|
||||
- 不得把 Phase 2 的单个 grill 决策确认当作本 checkpoint 的授权。
|
||||
|
||||
## Phase 3 — OpenSpec apply
|
||||
|
||||
**进入条件**：
|
||||
- `openspec/changes/<slug>/` 中 proposal/design/specs/tasks 已达到可执行状态。
|
||||
- Phase 2.5 后已获得用户继续实现的确认，除非用户要求“全自动执行”。
|
||||
- `openspec/changes/<slug>/` 中 proposal/design/specs/tasks 已通过 Phase 2.9，成为 Committed OpenSpec。
|
||||
- Phase 2.9 后已获得用户明确的 Phase 3 apply 授权，除非用户在启动时要求“全自动执行”。
|
||||
- devflow 与 OpenSpec 没有未解决冲突。
|
||||
- 没有未解决的 user-interview 问题、未判级接口影响、未汇报 evidence-driven 结论或未接受架构风险。
|
||||
|
||||
**显式子 skill**：`openspec-apply-change`；遇到 bug/不确定行为时显式调用 `diagnose`；需要测试驱动时显式调用 `tdd`。进入本阶段必须先声明调用方式，不能静默 fallback。
|
||||
|
||||
@@ -163,6 +209,12 @@
|
||||
- 优先调用 `openspec-apply-change`。
|
||||
- 执行依据是 OpenSpec specs/tasks；devflow 只能作为上下文参考。
|
||||
- 按 OpenSpec tasks 的纵向切片实现。
|
||||
- 当用户质疑、用户要求修改、代码检查、测试失败或运行行为与 OpenSpec 冲突时，先分类再继续：
|
||||
- 实现偏差：Committed OpenSpec 正确，代码没有按规格做；修代码，不改 OpenSpec。
|
||||
- 规格遗漏：OpenSpec 没覆盖真实边界、接口影响、验收口径或外部可见行为；暂停 apply，修正 OpenSpec 后重新提交。
|
||||
- 设计冲突：OpenSpec 与架构、ADR、历史验收、数据所有权或模块边界冲突；暂停并向用户确认设计方向。
|
||||
- 用户变更：用户改变目标、范围、优先级、验收或风险接受度；更新 proposal/specs/tasks 后再继续。
|
||||
- 冲突分类、证据、用户确认和 OpenSpec 回写状态必须记录到 `decisions.md` 或 `acceptance.md`。
|
||||
- 当用户要求、行为复杂或回归风险高时使用 TDD。
|
||||
- 当测试失败、行为意外或原因不确定时使用 diagnose。
|
||||
- 如果 diagnose 发现根因是 OpenSpec 不准确，先修正 OpenSpec，再继续 apply。
|
||||
@@ -170,6 +222,7 @@
|
||||
|
||||
**退出条件**：
|
||||
- OpenSpec tasks 已完成，或剩余 tasks 已明确记录。
|
||||
- 所有实现期冲突已分类并处理；没有未确认的规格遗漏、设计冲突或用户变更。
|
||||
- 已运行验证，或记录了未验证原因。
|
||||
- 已列出已知限制。
|
||||
|
||||
@@ -188,10 +241,12 @@
|
||||
- 从 OpenSpec、实现结果和验证结果提炼 brief、evidence、decisions 和 acceptance；只在复杂场景按需拆出 PRD/research/design/tasks/alignment。
|
||||
- 写入或更新验收记录，并区分静态验证、脚本验证、浏览器/人工验证、未验证。
|
||||
- 如果本次流程产生可复用经验，写入 compound knowledge。
|
||||
- 更新 `devflow/index.md`，记录日期、slug、领域、关键词、关联 OpenSpec 和状态。
|
||||
- 询问用户是否要 archive OpenSpec change；不要默认执行归档。
|
||||
|
||||
**退出条件**：
|
||||
- `devflow/projects/YYYY-MM-DD-{slug}/` 能说明做了什么、为什么做、OpenSpec 如何指导执行、还剩什么、如何验证。
|
||||
- `devflow/index.md` 已包含或更新本项目条目。
|
||||
- 用户已被询问是否 archive OpenSpec change。
|
||||
|
||||
**输出**：
|
||||
|
||||
@@ -65,6 +65,68 @@
|
||||
- 风险接受：{accepted by whom/when}
|
||||
```
|
||||
|
||||
## 接口影响记录模板
|
||||
|
||||
```markdown
|
||||
# {标题} 接口影响记录
|
||||
|
||||
## 分级
|
||||
|
||||
- 级别：L1 内部实现 / L2 内部接口 / L3 协作接口 / L4 破坏性接口
|
||||
- 判级原因：{why this level}
|
||||
- 是否需要独立接口文档：是 / 否
|
||||
|
||||
## 变更对象
|
||||
|
||||
- 接口/字段/DTO/事件/回调/数据库契约：
|
||||
- 判断逻辑变化：
|
||||
- 可观察行为变化：返回数据 / 状态 / 错误码 / 权限结果 / 过滤排序 / 幂等性 / 时序 / 副作用 / 无
|
||||
|
||||
## 影响范围
|
||||
|
||||
- 调用方/消费者：
|
||||
- 是否跨模块/跨服务/跨团队：
|
||||
- 旧调用方是否需要改动：
|
||||
|
||||
## 兼容与迁移
|
||||
|
||||
- 是否向后兼容：
|
||||
- 迁移/灰度/回滚要求：
|
||||
- 风险接受：
|
||||
|
||||
## 验收方式
|
||||
|
||||
- 如何证明新行为正确：
|
||||
- 如何证明旧行为未破坏：
|
||||
- 需要用户确认的问题：
|
||||
```
|
||||
|
||||
## 实现期冲突记录模板
|
||||
|
||||
```markdown
|
||||
# {标题} 实现期冲突记录
|
||||
|
||||
## 冲突摘要
|
||||
|
||||
- 触发来源：用户质疑 / 用户变更 / 代码发现 / 测试失败 / 运行行为
|
||||
- 冲突对象：proposal / design / specs / tasks / ADR / 代码行为
|
||||
- 分类：实现偏差 / 规格遗漏 / 设计冲突 / 用户变更
|
||||
|
||||
## 证据
|
||||
|
||||
- OpenSpec 依据：
|
||||
- 代码或测试证据：
|
||||
- 用户反馈：
|
||||
|
||||
## 处理
|
||||
|
||||
- 决策：
|
||||
- 是否需要用户确认：是 / 否
|
||||
- OpenSpec 回写：不需要 / 已回写 / 待回写
|
||||
- 代码处理：
|
||||
- 验证方式：
|
||||
```
|
||||
|
||||
## PRD 模板
|
||||
|
||||
```markdown
|
||||
|
||||
Reference in New Issue
Block a user