sawzhang SDD — Subagent-Driven Development (Harness Engineering)
完整的 Harness Engineering 软件开发 loop。所有「执行性质的工作」都由 subagent 完成，本 Skill 只做编排。
Harness Engineering vs. Vibe Coding
核心判断标准（来自 @kasong2048）：
你有没有一个完整的环境，可以对 Agent 的行为进行约束、观测、校验、回退？
- 有 → Harness Engineering（Agent 自主完成全部编码）
- 没有 → Vibe Coding（需要人工介入）
本 Skill 就是这个「完整环境」：
| Harness 属性 | 在本 Skill 中的体现 |
|---|---|
| 约束 | Subagent 在 git worktree 中工作，任务边界由 plan 明确定义，不能触碰范围外的文件 |
| 观测 | 每个 subagent 返回 DONE/DONE_WITH_CONCERNS/NEEDS_CONTEXT/BLOCKED 状态，审查 subagent 输出结构化报告 |
| 校验 | 测试必须通过 → lint/format 必须通过 → spec compliance review → code quality review → CI 验证 |
| 回退 | 测试失败 → rollback worktree；review 3 次不过 → 上报用户；BLOCKED → 暂停等待 |
触发时机
- 用户提供 feature/bug 描述，希望 Agent 自主完成全部开发
- 用户说"自主开发"、"帮我实现"、"sdd"、"harness 开发"
- 有清晰的任务范围，不需要每步都确认
不适用场景：
- 需要频繁探索性讨论 → 先用 brainstorming
- 任务范围极不清晰 → 先澄清再启动
- 纯修改 SKILL/文档（自然语言无法完整验证）→ 人工 Vibe Coding
完整流程
Feature Spec
│
▼
Phase 1: 设计 → dispatch design-subagent
│ ← 用户确认（唯一强制人工介入点）
▼
Phase 2: 规划 → dispatch planning-subagent
│
▼
Phase 3: 建立 Worktree → git worktree + 环境初始化
│
▼
Phase 4: 实现循环 → 每个 task: impl-subagent → spec-review → quality-review
│
▼
Phase 5: 质量关卡 → 测试套件 + lint + coverage 检查
│
▼
Phase 6: PR 创建 → gh pr create，等待 CI
│
▼
Phase 7: Review 修复 → dispatch fix-subagent per review comment → push → merge
Phase 1：设计
dispatch design-subagent（最强模型）
给 subagent 的上下文：
- feature/bug 的完整描述
- 相关代码文件路径（不是内容，让 subagent 自己读）
- 项目约束（CLAUDE.md / AGENTS.md 中的规则）
- 输出路径：
docs/specs/YYYY-MM-DD-<feature>.md
设计文档应包含：
- 目标与非目标（scope 边界）
- 架构方案（2-3 个备选 + 推荐）
- 关键接口定义
- 边界情况处理
- 不做哪些事（明确排除）
人工确认：设计文档完成后，向用户展示摘要，等待确认或修改意见。这是整个流程唯一的强制人工介入点。
Phase 2：规划
dispatch planning-subagent（标准模型）
给 subagent 的上下文：
- 已确认的设计文档全文
- 项目结构（通过 glob 获取文件列表）
- 技术栈和测试框架信息
输出：docs/plans/YYYY-MM-DD-<feature>.md
规划文档格式：
## 任务列表
### Task 1: <名称>
**文件**: src/foo/bar.ts, src/foo/bar.test.ts
**描述**: ...
**验证步骤**: pnpm test src/foo/bar.test.ts
**依赖**: 无
### Task 2: <名称>
...
每个 task 要求：
- 粒度：2-5 分钟实现，单一职责
- 包含明确的测试文件路径
- 包含可执行的验证命令
- 标注依赖关系（串行 vs. 可并行）
Phase 3：建立 Worktree
# 检查 worktree 目录配置（优先 .worktrees/，其次 worktrees/）
# 验证已在 .gitignore 中
git worktree add .worktrees/<feature-name> -b feat/<feature-name>
# 自动检测并初始化环境
# Node.js: npm/pnpm/yarn install
# Python: uv sync / pip install -e .
# Rust: cargo build
# 验证干净基线：运行测试，确认全部通过
Phase 4：实现循环
对每个 task 串行执行（注意：不并行，防止文件冲突）：
Step 4a：dispatch implementation-subagent
关键原则：subagent 不继承你的上下文，你需要构造完整的任务包。
给 implementation-subagent 的 prompt 模板：
## 任务
<task 完整文本，从 plan 文件提取>
## 场景
你在实现 <feature 名称> 的一部分。
设计文档在 <路径>，你可以读取它了解整体方向。
## 工作目录
<worktree 绝对路径>
## 要求
1. 遵循 TDD：先写失败的测试，再写实现，确认测试通过
2. 完成后运行：<验证命令>
3. 提交代码（使用 conventional commit 格式）
4. 如遇到阻碍，立即上报，不要猜测
## 返回状态
完成后以下列格式回复：
STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
SUMMARY: <一句话总结>
CONCERNS: <如有，列出>
QUESTIONS: <如有，列出>
COMMIT: <commit sha>
Step 4b：处理 subagent 状态
| 状态 | 处理方式 |
|---|---|
DONE |
进入 spec compliance review |
DONE_WITH_CONCERNS |
先读 concerns，判断是否影响正确性，再决定是否先修复还是直接进 review |
NEEDS_CONTEXT |
提供缺失的上下文，重新 dispatch（同模型） |
BLOCKED |
评估原因：上下文问题→补充上下文重 dispatch；任务太大→拆分；plan 有误→上报用户 |
永远不要 ignore BLOCKED 或强迫同一 subagent 重试而不做任何改变。
Step 4c：dispatch spec-reviewer-subagent
给 reviewer 的上下文：
- 设计文档全文
- plan 中该 task 的完整文本
- commit sha 和变更的文件列表（用
git diff <base>..<commit>输出）
reviewer 检查：
- 实现是否覆盖了 spec 要求的全部功能
- 是否有多余实现（超出 spec 的功能）
- 测试是否覆盖了 spec 描述的场景
返回：✅ SPEC_PASS 或 ❌ SPEC_FAIL: <具体缺失/多余项列表>
Step 4d：dispatch quality-reviewer-subagent
只在 spec review PASS 后才启动（顺序不能错）。
给 reviewer 的上下文：
- code diff（完整内容）
- 项目的 lint/format 规则（从配置文件读取）
- 项目的 code style 样例（从同类文件读取 2-3 个）
reviewer 检查：
- 代码质量（可读性、命名、单一职责）
- 测试质量（非 mock 实现细节、测试边界情况）
- 性能和安全（明显问题）
- 格式规范（lint/format）
返回结构：
DECISION: APPROVED | CHANGES_REQUESTED
CRITICAL: <阻塞合并的问题>
IMPORTANT: <强烈建议修改的问题>
MINOR: <可选改进>
Step 4e：修复循环
如果 review 返回 CHANGES_REQUESTED：
- dispatch fix-subagent，提供：review 报告全文 + 原始 task 上下文 + diff
- fix-subagent 修复后提交
- 重新进行对应阶段的 review
- 最多 3 轮修复（spec 和 quality 各自独立计数）
- 3 轮后仍不过 → 上报用户，暂停
完成一个 task 后，更新 TodoWrite 标记该 task 完成，再进入下一个。
Phase 5：质量关卡
所有 tasks 完成后，在 worktree 中运行完整质量检查。全部通过才能进入 Phase 6。
必须通过的检查
# 1. 完整测试套件（优先运行，失败直接 rollback）
pnpm test # 或 npm test / pytest / cargo test
# 2. Lint 和格式检查
pnpm lint # 或对应命令
pnpm format:check # 或 prettier --check
# 3. 类型检查（TypeScript 项目）
pnpm tsgo # 或 tsc --noEmit
# 4. 构建验证（如有 dist 变化）
pnpm build
可选检查（项目有配置才运行）
# 测试覆盖率（如有 coverage 配置）
pnpm test:coverage
# 失败条件：新增代码的行覆盖率 < 项目配置的阈值
# 架构边界检查（如有自定义 scripts）
pnpm check:boundaries # 或等效命令
# 重复代码检测
pnpm dup:check
检查失败的处理
| 失败类型 | 处理方式 |
|---|---|
| 测试失败 | dispatch debug-subagent，根因分析后修复，重新运行全部测试 |
| Lint 失败 | dispatch fix-subagent，自动修复（通常可 lint:fix 解决） |
| 类型错误 | dispatch fix-subagent，修复类型问题，重新类型检查 |
| 覆盖率不足 | dispatch test-subagent，补充测试用例，重跑 |
| 构建失败 | 分析错误，dispatch fix-subagent，重新构建 |
Phase 6：PR 创建
# 推送分支
git push -u origin feat/<feature-name>
# 创建 PR
gh pr create \
--title "<conventional commit 风格标题，<70字符>" \
--body "$(cat <<'EOF'
## 变更摘要
<3-5 bullet points>
## 实现细节
<关键设计决策>
## 测试
- [ ] 单元测试通过
- [ ] 集成测试通过（如有）
- [ ] 覆盖率满足阈值（如有）
## 验证步骤
<人工验证的步骤（如有）>
🤖 Generated with [Claude Code](https://claude.ai/code)
EOF
)"
等待 CI 结果：
- CI 通过 → 进入 Phase 7（等待 review）或直接 merge（如无 review 要求）
- CI 失败 → 分析失败日志，dispatch fix-subagent，push fix commit
Phase 7：Review 修复循环
收到 PR review 反馈后：
对每个 reviewer comment，评估严重程度：
- CRITICAL（阻塞合并）→ 必须修复
- IMPORTANT（强烈建议）→ 评估后决定
- MINOR（可选）→ 可 defer
对需要修复的 comment，dispatch fix-subagent：
- 提供 comment 全文 + 被评论的代码上下文
- 修复后 push，reply comment 说明修改
等待 reviewer approve，merge PR。
模型选择策略
| 角色 | 推荐模型 | 原因 |
|---|---|---|
| design-subagent | 最强（opus） | 需要架构判断力 |
| planning-subagent | 标准（sonnet） | 结构化分解任务 |
| implementation-subagent（简单 task，1-2 文件） | 快速（haiku） | 机械实现 |
| implementation-subagent（复杂 task，多文件协调） | 标准（sonnet） | 集成判断 |
| spec/quality reviewer | 标准（sonnet） | 需要理解上下文 |
| debug-subagent | 最强（opus） | 根因分析 |
人工介入点
| 时机 | 原因 | 如何处理 |
|---|---|---|
| Phase 1 完成后（设计确认） | 确保方向正确，避免后续全部返工 | 展示设计摘要，等待 confirm |
| subagent 状态为 BLOCKED | 超出 subagent 能力范围 | 分析 blocker，决策后继续 |
| 质量关卡 3 次修复后仍失败 | 可能是根本性问题 | 上报，暂停，等待用户决策 |
| CI 持续失败（3 次） | 可能是环境/基础设施问题 | 上报 CI 失败详情，等待 |
Red Flags
永远不要：
- 在 main/master 分支直接工作（必须用 worktree + feature branch）
- 跳过 spec compliance review 直接做 quality review（顺序固定）
- 并行派发多个 implementation-subagent（会产生文件冲突）
- 让 subagent 继承主 session 上下文（每次构造完整任务包）
- quality review 有 CRITICAL 问题时继续创建 PR
- ignore BLOCKED 状态，强迫重试
- 3 轮修复后仍继续循环（上报用户）
- 在 Phase 5 质量关卡失败时直接创建 PR
注意：
- Subagent 问题 → 回答后重 dispatch（不是继续当前 subagent）
- 修复用 fix-subagent，不要主 session 手动改代码（context pollution）
- 每次给 subagent 的 prompt 要自包含（subagent 不会看到主 session 的历史）
与 Superpowers 的集成
如果项目已安装 superpowers：
superpowers:brainstorming→ 替代 Phase 1 的 design-subagentsuperpowers:writing-plans→ 替代 Phase 2 的 planning-subagentsuperpowers:using-git-worktrees→ Phase 3 的 worktree 创建superpowers:test-driven-development→ implementation-subagent 内部遵循superpowers:finishing-a-development-branch→ Phase 6 的 PR 创建