osiman/git-learn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f45122dafbc38bcdc7f8a96204b71c806f366c0a
git-learn/skill-workbench/docs/sm-flow/workflow.md
T

20 KiB
Raw Blame History

增强版工作流总结

旧工作流 vs 新工作流

旧：                       新：
Phase 1  手动整理PRD        Phase 0   手动初始PRD（入口，保留人的判断）
Phase 2  openspec:explore   Phase 1    openspec:propose → research
Phase 3  grill-me           Phase 1.5  to-prd → 结构化PRD（替代初始PRD）
Phase 4  openspec:apply     Phase 2    grill-with-docs → CONTEXT.md + ADR
                            Phase 2.5  zoom-out → 架构审计
                            Phase 3    openspec:apply → 执行
                                       diagnose → bug排查
                                       tdd → 质量闭环
横切：                     横切：
       无                            git-guardrails → 安全锁

关键变化：手动 PRD 从"整个流程的全部输入"降级为"Phase 0 的启动草稿"——你仍然需要手写初始 PRD（这是人的判断力不可替代的部分），但它不再直接喂给 openspec apply，而是先经过 research → 精化 → grill → 架构审计，最终执行的是层层校验后的方案。

旧工作流的三个关键缺口

  1. 需求澄清后缺少可行性验证

    • 旧：grill-me 追问后 → 直接进入 apply。如果方案有架构问题，到了编码阶段才发现
    • 新：grill-with-docs 追问后 → zoom-out 拉高视角做架构审计。grill 问的是"需求对不对"，zoom-out 问的是"方案行不行"

  2. openspec 产出不能沉淀到长期记忆

    • 旧：openspec archive 只归档需求，项目的术语、业务规则、架构决策散落在对话中，下次新对话全丢
    • 新：grill-with-docs 的 CONTEXT.md 沉淀领域词汇表，ADR 沉淀架构决策。换会话重启 AI 也不丢失上下文

  3. apply 完成后缺少验证闭环

    • 旧：apply → 完成。功能对不对取决于人肉测试
    • 新：apply 过程中遇到 bug → diagnose（假说→验证→修复→回归测试），写代码时 → tdd（Red→Green→Refactor）

新增技能的投入产出

技能 学多久 一次省多少 什么时候用
to-prd 0 分钟（自动综合） 10-15 分钟 openspec research 结束后
grill-with-docs 替换已有 grill-me 0 额外时间 + 产出文档 需求澄清阶段
zoom-out 10 秒（一句话） 避免方向性返工 grill 完成后、apply 前
diagnose 5 分钟了解流程 每次 bug 省 20-30 分钟 apply 中遇到问题
tdd 5 分钟了解流程 减少回归 bug apply 中写代码
git-guardrails 0 分钟（被动生效） 防止灾难性操作 全程自动

为什么这套组合优于单纯依赖 openspec

openspec 管控的是"流程"——先出 proposal，再写 specs，再排 tasks。但它不解决三个问题：

  • 领域知识沉淀：openspec 归档后只剩需求文档，术语表、架构决策全丢了 → grill-with-docs 补齐
  • 质量验证：openspec 把 tasks 勾完就算完成 → diagnose + tdd 补齐验证闭环
  • 流程安全：openspec 不管 AI 误操作 → git-guardrails 补齐安全层

一句话：openspec 管"按什么步骤走"，mattpocock 技能管"每一步走得好不好"。

v2.0：devflow/ 产物聚合层

问题

v1.0 一次完整流程的产物散落在 5 个位置：

CONTEXT.md                 ← Phase 2 (根目录)
docs/adr/                  ← Phase 2 (docs/)
docs/agents/               ← Phase 1.5 (docs/)
openspec/changes/          ← Phase 1+3 (openspec/)
knowledge/entries/         ← /knowledge-absorber

三个月后想回溯"knowledge-index-panel 这个项目到底做了什么决策"，需要同时翻 4 个目录。产物按工具来源组织（openspec 写哪、grill 写哪、to-prd 写哪），而非按项目本身组织。

借鉴 CodeStable 的单一聚合根设计

CodeStable 的核心设计决策：所有产物集中在 codestable/ 一个目录下，按"软件实体类型"（需求/架构/特性/问题/知识）分子目录，而非按"哪个工具产生的"。

dev-flow v2.0 借鉴这一点，在不改变 openspec 工作区的前提下，增加一个人类可读的档案层：

devflow/                              ← 单一入口
├── projects/YYYY-MM-DD-{slug}/       ← 一个 PRD→实现 闭环
│   ├── {slug}-prd.md                 # Phase 0+1.5 需求文档
│   ├── {slug}-research.md            # Phase 1 技术方案（从 openspec 提取）
│   ├── {slug}-design.md              # Phase 1+2.5 设计 + 架构审计
│   ├── {slug}-tasks.md               # Phase 1 任务清单（从 openspec 提取）
│   ├── {slug}-acceptance.md          # Phase 3+4 验收报告
│   └── adr/                          # Phase 2 架构决策
├── glossary/
│   └── CONTEXT.md                    # 跨项目领域词汇表
├── compound/                         # 跨项目知识沉淀
│   └── YYYY-MM-DD-{type}-{slug}.md   # type ∈ {learning, trick, decision, explore}
└── reference/                        # 共享模板/规范

两层架构

openspec/changes/ devflow/projects/
角色 工具工作区（WAL） 人类档案层（Tables）
谁读 机器 人
生命周期 活跃变更期 → Archive 后清空 永久保留
组织方式 按变更名 按日期 + 项目

关键：openspec archive 后 openspec/changes/ 清空，但 devflow/projects/ 不受影响。Phase 4 收尾时从 openspec 提取关键内容到 devflow。

各 Phase 产物路径变化

Phase v1.0 v2.0
1.5 PRD docs/agents/<name>-prd.md devflow/projects/{date}-{slug}/{slug}-prd.md
2 CONTEXT 根目录 CONTEXT.md devflow/glossary/CONTEXT.md
2 ADR docs/adr/ devflow/projects/{slug}/adr/
2.5 架构审计 对话中，丢失 devflow/projects/{slug}/{slug}-design.md
4 验收 docs/agents/lessons/ devflow/projects/{slug}/{slug}-acceptance.md
4 经验沉淀 无 devflow/compound/YYYY-MM-DD-{type}-{slug}.md
4 从 openspec 提取 无 提炼到 {slug}-research.md + {slug}-tasks.md

一键启动

已固化为 skill：/dev-flow

/dev-flow                     # Phase 0 开始：粘贴初始 PRD 草稿 → 走完后续全流程
/dev-flow --prd docs/my-idea.md  # 跳过 Phase 0，直接用已有 PRD 文件 → Phase 1
/dev-flow --from phase2       # 已有 research，从 grill 开始
/dev-flow --from apply        # 已有 PRD + 文档，直接执行
/dev-flow --quick             # 小需求，跳 PRD 精化 + zoom-out

Skill 位置：.claude/skills/dev-flow/SKILL.md

Skill 评估结论（2026-05-19）

详细评估报告见：devflow/projects/2026-05-19-dev-flow-skill-evaluation/dev-flow-skill-evaluation.md。

总体判断

dev-flow 的方向是正确的：它没有试图替代 openspec，而是在 openspec 的流程控制之上增加需求精化、架构审计、质量闭环和长期知识沉淀。

最有价值的设计是 devflow/ 产物聚合层：

  • openspec/changes/ 负责机器可执行的变更工作区。
  • devflow/projects/ 负责人类可回溯的项目档案。
  • devflow/glossary/CONTEXT.md 负责跨项目领域词汇。
  • devflow/compound/ 负责沉淀可复用工程知识。

评估中发现的核心问题是：早期 SKILL.md 更像设计说明书，而不是代理可稳定执行的运行手册。它解释了很多理念，但缺少执行时必需的检查点、模板、分支规则和 fallback 策略。

已确认的亮点

  1. 产物聚合层设计清晰

    • devflow/projects/YYYY-MM-DD-{slug}/ 解决了 openspec archive 后上下文难以回溯的问题。
    • 工具工作区和人类档案层分离，职责边界明确。

  2. 阶段顺序合理

    • Phase 0 → Phase 1 → Phase 1.5 → Phase 2 → Phase 2.5 → Phase 3 → Phase 4 的顺序能有效避免“需求没想清楚就开始编码”。

  3. Phase 4 很有价值

    • 从 openspec 提炼 research、design、tasks、acceptance、ADR 和 compound knowledge。
    • 这是区别于普通 openspec 流程和普通编码 skill 的核心优势。

  4. 文档化追问方向正确

    • Phase 2 要求一次只问一个问题，并即时更新 CONTEXT.md / ADR。
    • 这符合“边澄清边沉淀”的工作方式。

  5. 质量闭环意识强

    • Phase 3 明确要求 bug 不允许猜测式修复，必须走 diagnose 协议。
    • TDD 被设计为可选增强，避免对所有任务强制套用重流程。

主要改进点

问题 改进方向
触发描述不够完整 明确覆盖需求到实现、规划 feature、执行 openspec change、沉淀工程文档、规范化开发流程等场景
Claude 工具耦合较强 保留 Claude 版本兼容，同时在 skill 正文中提供环境无关 fallback
依赖安装状态写死 改为启动时检查 required / optional / fallback
子 skill 调用方式不稳 优先调用子 skill；不可调用时读取对应 SKILL.md；不存在时执行最小协议
缺少初始化算法 明确 devflow/ 目录骨架、slug 生成、重名处理和旧 CONTEXT.md 迁移规则
缺少模板 拆出 PRD、research、design、tasks、acceptance、CONTEXT、ADR、compound knowledge 模板
quick 模式与约束冲突 quick 只能跳 Phase 1.5 和 2.5，不能跳 Phase 2 最小澄清和 Phase 4 轻量归档
Phase 退出条件不足 为每个 Phase 增加进入条件、动作、输出、退出条件和失败回退路径

产品化方向

评估结论不是继续增加理念，而是把 workflow 产品化为“代理稳定执行协议”：

  • SKILL.md 保持短而硬：角色、触发场景、阶段总览、核心规则、关键分支。
  • references/ 承载长内容：Phase 契约、模板、归档规则、fallback 协议。
  • 每个 Phase 都要有明确的进入条件和退出条件。
  • quick 模式、fallback、归档确认、人类检查点必须写成硬规则。
  • devflow/ 只做长期记忆和上下文增强，不应与 openspec 抢执行真理源。

后续演进：sm-flow 产品化

基于这次评估，dev-flow 的设计被重构为 .agents/skills/sm-flow/。这一步仍属于 v2 产品化：目标不是改变 v2 的“devflow 聚合层”定位，而是把早期设计说明书拆成代理可执行的 skill 结构。

.agents/skills/sm-flow/
├── SKILL.md                         # 短执行协议
└── references/
    ├── phase-contracts.md           # Phase 输入/动作/输出/退出条件
    ├── templates.md                 # PRD/ADR/验收等模板
    ├── archive-rules.md             # 从 openspec 提取到 devflow 的规则
    └── fallbacks.md                 # 子 skill 不可用时的最小协议

v2 的核心仍然是：在不改变 openspec 工作区的前提下，增加 devflow/ 作为人类可读档案层，并让 Phase 4 把 openspec、实现、验证结果提炼回长期记忆。

v3.0：OpenSpec-first / Devflow-assisted

背景

v2 跑通后暴露出一个更深的问题：devflow/ 产物越来越完整，容易让代理在执行阶段直接依赖 PRD、design、tasks、acceptance 等档案写代码，从而弱化 openspec 的执行真理源地位。

这会导致两套“执行依据”并存：

devflow/projects/{slug}/...     # 人类档案层，也包含 PRD/design/tasks
openspec/changes/{change}/...    # 工具工作区，也包含 proposal/design/specs/tasks

如果没有主从关系，Phase 3 执行时代理可能不知道到底听 devflow tasks，还是听 openspec tasks。文档越多，不一定越准确；没有唯一执行真理源时，反而更容易漂移。

v3 的核心判断

v3 不重新设计一套替代 openspec 的工作流，而是明确：

devflow 辅助 OpenSpec，OpenSpec 指挥执行，执行结果回填 devflow。

职责分层变为：

层 角色 负责回答
devflow/ 上下文真理源 / 长期记忆 为什么这样做？术语是什么？历史决策是什么？之前怎么验收？
openspec/changes/ 执行真理源 / 当前变更规格 这次到底改什么？验收标准是什么？任务是否完成？
code 实现结果 OpenSpec apply 后实际落地的代码

v2 vs v3

维度 v2：devflow 聚合层 v3：OpenSpec-first / Devflow-assisted
核心目标 防止 openspec archive 后上下文丢失 防止 devflow 与 openspec 成为并列执行源
devflow 角色 人类可读档案层 上下文增强层 + 归档层
openspec 角色 工具工作区 当前变更的唯一默认执行真理源
Phase 1 openspec propose 产出 research 基于 devflow 上下文生成/修正 OpenSpec 产物
Phase 2 grill-with-docs 更新 glossary/ADR human-in-the-loop 澄清后必须回写 OpenSpec
Phase 2.5 zoom-out 产出架构审计 架构审计若影响实现，必须回写 OpenSpec design/tasks
Phase 3 openspec apply + diagnose/tdd 默认只能依赖 OpenSpec apply；devflow 只作参考上下文
Phase 4 从 openspec 提炼到 devflow 轻量回填 devflow 必要档案，避免重复 OpenSpec

v3.1：Devflow 产物瘦身

v3 继续跑完整流程后，又暴露出一个实践问题：devflow 作为辅助和人类阅读层时，如果默认生成 PRD、research、design、tasks、alignment、clarifications、acceptance，会和 OpenSpec 的 proposal、design、specs、tasks 大量重叠。

因此 v3.1 明确：devflow 不复制 OpenSpec，只保存 OpenSpec 不擅长表达的人类上下文、证据、决策和验收归档。

默认必要产物收敛为：

devflow/projects/YYYY-MM-DD-{slug}/
├── brief.md        # 背景、目标、范围、非目标、关联 OpenSpec
├── evidence.md     # 代码/文档证据、evidence-driven 结论和汇报状态
├── decisions.md    # user-interview 确认、关键取舍、OpenSpec 回写记录
└── acceptance.md   # 实现结果、验证、未验证项、archive 状态

扩展产物只在有明确理由时创建：

  • prd.md：复杂需求、对外协作或用户明确要求。
  • research.md：真实调研、代码考古、竞品/API 对比或复杂方案比较。
  • design.md：长期架构背景、架构审计摘要或决策索引；实现设计仍以 OpenSpec design 为准。
  • tasks.md：跨轮次人类复盘任务；执行任务仍以 OpenSpec tasks 为准。
  • alignment.md / clarifications.md：冲突或澄清问题很多时拆出；否则并入 decisions.md。

规模分档：

分档 适用场景 devflow 默认产物
micro 小改动、低风险、需求明确 brief.md、decisions.md、acceptance.md；证据少时并入 brief.md
standard 默认模式 brief.md、evidence.md、decisions.md、acceptance.md
complex 高风险、跨模块、需求不清、多人协作 standard + 按需 PRD/research/design/tasks/alignment

v3 新增 Phase 0.5

v3 在 Phase 0 和 Phase 1 之间增加：

Phase 0.5  Devflow Context Harvest

读取：

  • devflow/glossary/CONTEXT.md
  • 相关项目 PRD/design/tasks/acceptance
  • 相关 ADR
  • devflow/compound/ 中的 learning、trick、decision、explore

目的不是直接指导编码，而是给 Phase 1 的 OpenSpec propose 提供更准确的上下文输入。读取旧项目时可以参考历史 PRD/design/tasks，但新项目不再默认生成这些重复产物。

v3 中各 skill 的参与方式

这些 skill 仍然参与，但职责从“并列执行流程”调整为“服务 OpenSpec 产物质量”：

阶段 主要 skill / 工具 作用 产物去向
Phase 0 初始需求 / PRD / research sm-flow 收集原始需求、已有 PRD 或 research，判断启动模式 入口摘要、初步 slug
Phase 0.5 Devflow Context Harvest sm-flow 读取 devflow/ 的 glossary、ADR、历史 PRD、acceptance、compound knowledge 作为 Phase 1 的 OpenSpec 输入上下文
Phase 1 OpenSpec propose openspec-propose 生成或修正 proposal.md、design.md、specs/**/*.md、tasks.md openspec/changes/<change>/
Phase 1.5 PRD / OpenSpec 对齐 to-prd + sm-flow 检查 brief/devflow/OpenSpec 是否一致；复杂需求才生成独立 PRD brief.md / 按需 prd.md；冲突回写 OpenSpec
Phase 2 Human-in-the-loop 澄清 grill-with-docs 追问术语、边界、验收；区分 evidence-driven 和 user-interview evidence.md / decisions.md；影响实现的结论回写 OpenSpec
Phase 2.5 架构审计 zoom-out 拉高视角审查模块、数据流、耦合、架构风险 默认写入 decisions/evidence；复杂审计才拆 design.md；影响实现则回写 OpenSpec
Phase 3 OpenSpec apply openspec-apply-change 按 OpenSpec specs/tasks 执行实现 代码变更、OpenSpec task 状态
Phase 3 bug/不确定行为 diagnose 复现 → 最小化 → 假设排序 → 仪器化 → 修复 → 回归 根因若是规格问题，先修 OpenSpec；修复记录进入 acceptance
Phase 3 高风险/复杂行为 tdd 按 OpenSpec specs 做纵向切片测试驱动 测试与实现代码
Phase 4 回填 devflow sm-flow + openspec-archive-change 从 OpenSpec、实现和验证提炼长期档案，并询问是否 archive devflow/projects/、devflow/compound/；用户确认后 archive

说明：grill-me 在 v3 中不再作为主要入口，已被 grill-with-docs 替代。原因是 v3 需要把澄清结果沉淀到 glossary/ADR，并把影响实现的结论回写 OpenSpec；纯对话式 grill 容易丢失上下文。

v3 的执行规则

  1. OpenSpec 是执行真理源

    • Phase 3 默认必须依赖 openspec/changes/<change>/proposal.md、design.md、specs/**/*.md、tasks.md。
    • 不允许直接基于 devflow/projects/... 绕过 OpenSpec 写代码。

  2. Devflow 是上下文真理源

    • 术语、历史决策、项目背景、踩坑记录来自 devflow/。
    • 这些内容用于增强和修正 OpenSpec，而不是替代 OpenSpec。

  3. 冲突先修 OpenSpec

    • 如果 devflow 和 OpenSpec 冲突，不能直接执行。
    • 必须汇报冲突、让用户确认、更新 OpenSpec，再进入 apply。

  4. evidence-driven 也必须汇报

    • 证据驱动不是“AI 自己确认完就继续”。
    • 代理必须汇报查了什么、得出什么结论、是否需要用户确认。

  5. user-interview 必须等待确认

    • 涉及范围、偏好、验收口径、风险接受度时，必须问用户。

  6. 归档仍回到 devflow

    • OpenSpec 完成后，从 OpenSpec、实现结果、验证结果中提炼长期档案。
    • Phase 4 询问是否 archive OpenSpec change，不默认执行。

  7. devflow 产物按需生成

    • 默认只生成 brief、evidence、decisions、acceptance。
    • PRD、research、design、tasks、alignment、clarifications 只有在复杂度或协作需要时才生成。
    • 小需求走 micro，不能让文档成本超过实现成本。

v3 流程图

Phase 0    初始需求 / PRD / research
           skill: sm-flow
   ↓
Phase 0.5  读取 devflow 上下文
           skill: sm-flow
   ↓
Phase 1    生成或修正 OpenSpec proposal/design/specs/tasks
           skill: openspec-propose
   ↓
Phase 1.5  PRD / Devflow / OpenSpec 对齐检查
           skill: to-prd + sm-flow
   ↓
Phase 2    human-in-the-loop 澄清，并回写 OpenSpec
           skill: grill-with-docs
   ↓
Phase 2.5  架构审计；影响实现则回写 OpenSpec
           skill: zoom-out
   ↓
Phase 3    OpenSpec apply 执行
           skill: openspec-apply-change；按需 diagnose / tdd
   ↓
Phase 4    回填 devflow，并确认是否 archive
           skill: sm-flow；用户确认后 openspec-archive-change

v3 一句话定位

sm-flow 不是 OpenSpec 的替代品，而是 OpenSpec 的上下文增强层和归档闭环层。

Reference in New Issue View Git Blame Copy Permalink