upgrade sm-flow v3.1 workflow
This commit is contained in:
zhuyongxin
@@ -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