satisficing-dev-workflow

name	satisficing-dev-workflow
description	满意解标准化软件开发流程。基于第一性原理的工程化开发方法论。 适用场景: 1. 构建任何新功能或应用 —— 触发 头脑风暴 → 计划 → 子代理执行循环 2. 调试 Bug 或测试失败 —— 触发系统化根因分析流程 3. 用户说"开发""添加功能""修复问题" 不适用: 单行修复(直接编辑)、只读代码、非编码任务 要求: exec工具、sessions_spawn工具

满意解开发流程 —— Satisficing Dev Workflow

基于 obra/superpowers 改编 | 适配 OpenClaw 环境 | 第一性原理工程化

---

核心理念

不是写代码，是解决问题。

Vibe Coding 能出原型，但生产系统需要工程化。 原型占软件工程的 1%，剩下 99% 在边界情况、竞态条件、错误处理。

本流程确保:

• 需求清晰再动手
• 设计评审再编码
• 测试先行再实现
• 双重审查再合并

---

五阶段流程

想法 → 头脑风暴 → 写作计划 → 子代理构建(TDD) → 代码审查 → 完成分支

每个编码任务必须经过此流程。 "太简单不需要设计" —— 永远是错的。

---

Phase 1: 头脑风暴 (Brainstorming)

触发: 用户想构建某物。触碰任何代码前激活。

执行步骤:

1. 探索项目上下文

   • 检查现有文件、文档、近期提交
   • 理解项目结构和约束

2. 澄清问题 —— 每次只问一个，优先选择题

   • 你真正想做什么？(目的)
   • 有什么约束？(时间、技术栈、依赖)
   • 成功是什么样子？(成功标准)
   • 不应该做什么？(范围边界)

3. 提出 2-3 种方案 —— 带权衡分析和推荐

   • 方案A: [简述]
   • 方案B: [简述]
   • 方案C: [简述]
   • 推荐: [方案X]，因为...

4. 分阶段呈现设计 —— 按复杂度逐步展开，每阶段获得批准

   • 架构概览
   • 组件及职责
   • 数据流
   • 错误处理策略
   • 测试策略

5. 写入设计文档

   • 路径: docs/plans/YYYY-MM-DD-<主题>-design.md
   • 提交 commit

6. 移交 Phase 2

   • 调用写作计划阶段

硬门槛: 设计批准前禁止写代码、搭脚手架、实现任何功能。

---

Phase 2: 写作计划 (Writing Plans)

触发: 设计已批准。由头脑风暴阶段激活。

执行步骤:

1. 编写详细任务计划

   • 每个任务 = 一个动作，2-5分钟
   • 格式: 写测试 → 看失败 → 实现 → 看通过 → 提交

2. 保存计划文档

   • 路径: docs/plans/YYYY-MM-DD-<功能>.md
   • 开头说明:

     # [功能名] 实现计划
     
     > **给实现者**: 全程 TDD。先写失败测试。看失败。再实现。
     
     **目标**: [一句话描述]
     **架构**: [2-3句方法说明]
     **技术栈**: [关键技术/库]
     

3. 提供两种执行模式

   • 子代理驱动: 我调度子代理逐任务执行
   • 手动执行: 你自己运行任务

任务格式示例:

### Task 1: [组件名]

**文件**:
- 创建: `exact/path/to/file.py`
- 修改: `exact/path/to/existing.py`
- 测试: `tests/exact/path/to/test_file.py`

**Step 1: 写失败测试**
[粘贴完整测试代码]

**Step 2: 运行测试 —— 确认失败**
命令: `pytest tests/path/test.py::test_name -v`
预期: FAIL —— "function not defined" 或类似

**Step 3: 写最小实现**
[粘贴完整实现代码]

**Step 4: 运行测试 —— 确认通过**
命令: `pytest tests/path/test.py::test_name -v`
预期: PASS

**Step 5: 提交**
`git add <files> && git commit -m "feat: <描述>"`

---

Phase 3: 子代理驱动开发 (Subagent-Driven Development)

触发: 计划存在，用户选择子代理驱动。

核心原则: 新子代理每个任务 + 两阶段审查 = 高质量，快速迭代。

每任务循环

Step 1: 调度实现者子代理 (sessions_spawn)

Prompt 模板:

目标: 实现编码任务，严格遵循 TDD

计划文件: [路径]
任务: [任务N原文]

约束:
- 先写失败测试。运行。确认失败。再实现
- 最小实现 —— YAGNI
- 每次绿测试后提交: git add <files> && git commit -m "..."
- 禁止修改任务范围外的文件
- 禁止添加任务外的功能

验证:
- 运行: [测试命令]
- 预期: [预期输出]

完成后报告: 实现了什么、测试结果、commit SHA

Step 2: 调度规格审查子代理 (sessions_spawn)

Prompt 模板:

目标: 仅审查规格合规性

计划文件: [路径]
被审查任务: [任务N原文]
Git 范围: [base_sha..head_sha]

仅审查实现是否符合规格。
报告:
- PASS 或 FAIL
- 任何规格缺口(指定了但未实现的内容)
- 不评论代码风格或质量

Step 3: 调度代码质量审查子代理 (sessions_spawn)

Prompt 模板:

目标: 仅审查代码质量(非规格合规)

Git 范围: [base_sha..head_sha]
描述: [实现了什么]

审查:
- DRY 违规
- 死代码
- YAGNI 违规(不必要功能)
- 命名不佳
- 缺失错误处理

严重度: Critical / Important / Minor
报告: 批准或按严重度列出问题

审查严重度处理:

严重度	行动
Critical	修复后才能继续 —— 阻塞下一任务
Important	修复后才能继续
Minor	记录，稍后处理

Step 4: 标记任务完成，进入下一任务

所有任务完成后

1. 调度最终整体审查子代理(完整 diff，所有任务)
2. 修复任何 Critical/Important 问题
3. 移交 Phase 5

---

Phase 4: 系统化调试 (Systematic Debugging)

触发: Bug、测试失败、意外行为 —— 任何技术问题。

铁律: 没有根因调查，禁止修复

随机修复浪费时间并引入新 Bug。症状修复是失败。

四阶段

Phase 1: 根因调查

修复前必须:

1. 仔细阅读错误信息

   • 不停顿地扫过错误或警告
   • 完整阅读堆栈跟踪
   • 记录行号、文件路径、错误码

2. 一致复现

   • 能可靠触发吗？
   • 确切步骤是什么？
   • 如果不可复现 → 收集更多数据，不要猜测

3. 检查近期变更

   • 什么变更可能导致这个？
   • git diff、近期提交、新依赖、配置变更

4. 多组件系统收集证据

   当系统有多层(API → 服务 → 数据库):

   在提出修复前，先添加诊断埋点:

   对每个组件边界:
     - 记录进入的数据
     - 记录出去的数据
     - 验证配置/环境传播
   运行一次看在哪里中断，然后调查该层
   

5. 追踪数据流

   • 坏值起源于哪里？
   • 谁用坏值调用了这个？
   • 沿调用栈向上追踪到源头
   • 在源头修复，不在症状处

Phase 2: 模式分析

修复前找到模式:

1. 在代码库中找到类似代码的工作示例
2. 与参考对比 —— 完整阅读，不停顿
3. 列出工作和损坏之间的每个差异
4. 理解所有依赖和假设

Phase 3: 假设 + 测试

1. 形成一个清晰的假设: "我认为 X 是根因，因为 Y"
2. 明确写下来
3. 设计最小测试来证明/证伪
4. 运行测试
5. 如果证伪 → 形成新假设，重复
6. 如果证明 → 进入修复

Phase 4: 修复 + 验证

1. 在根因处修复，不在症状处
2. 写一个本应捕获此 Bug 的测试
3. 验证修复有效
4. 验证无回归(运行完整测试套件)
5. 提交，信息清晰解释根因

反模式

• "试试这个" —— 没有根因的随机修复
• "可能是 X" —— 没有证据的猜测
• "快速补丁" —— 症状修复，根因仍在
• 一次修复多个东西 —— 无法知道什么有效
• 跳过复现 —— 调试无法一致触发的东西

---

Phase 5: 完成分支 (Finishing Branch)

触发: 所有任务完成，所有测试通过。

执行步骤:

1. 验证所有测试通过

   # Python
   pytest -q
   
   # Node/TS
   pnpm test
   
   # Rust
   cargo test
   
   # Go
   go test ./...
   

   如果失败 —— 停止。不能合并/PR 直到通过。

2. 确定基础分支

   git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
   git branch --show-current
   

3. 呈现 4 个选项

   实现完成。你想做什么？
   
   1. 本地合并回 <基础分支>
   2. 推送并创建 Pull Request
   3. 保持分支原样(稍后处理)
   4. 丢弃此工作
   
   选哪个？
   

4. 执行选择

   选项 1: 本地合并

   git checkout <基础分支>
   git pull
   git merge <功能分支>
   <运行测试>
   git branch -d <功能分支>
   

   选项 2: 推送 + PR

   git push -u origin <功能分支>
   gh pr create --title "<标题>" --body "## 摘要
   - <要点1>
   - <要点2>
   
   ## 测试计划
   - [ ] <验证步骤>"
   

   选项 3: 保持原样 报告: "保持分支 <名称>。你可以稍后返回。"

   选项 4: 丢弃 先确认:

   这将永久删除:
   - 分支 <名称>
   - 自 <基础分支> 以来的所有提交
   
   输入 'discard' 确认。
   

   等待确切单词 "discard"。然后:

   git checkout <基础分支>
   git branch -D <功能分支>
   

---

关键原则

原则	说明
一次一个问题	头脑风暴时每次只问一个
TDD 永远	先写失败测试，删除测试前写的代码
YAGNI	移除设计中所有不必要功能
DRY	禁止重复
系统化优于即兴	压力下尤其要遵循流程
证据优于主张	宣称成功前先验证
频繁提交	每次绿测试后提交

---

OpenClaw 适配说明

原版基于 Claude Code 的 Task 工具，本版适配 OpenClaw:

• 使用 sessions_spawn 替代 Task 工具
• 使用 exec 执行 git 命令
• 所有文件路径相对于工作区根目录
• 子代理通过 session 完成通知返回结果

---

使用示例

用户: "帮我开发一个合伙人评估问卷系统"

我:

1. 调用本 Skill
2. 进入 Phase 1: 头脑风暴 —— 问澄清问题
3. 得到批准后，进入 Phase 2: 写作计划
4. 选择子代理驱动，进入 Phase 3
5. 逐任务调度子代理实现
6. 双重审查每个任务
7. 完成后进入 Phase 5: 完成分支
8. 用户选择合并或 PR

---

版本: 1.0.0 | 基于 obra/superpowers | 满意解研究所