subagent-driven-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Subagent-Driven Development

子代理驱动开发（Subagent-Driven Development）

Dispatch fresh subagent per task with two-stage review after each.

Core principle: Fresh subagent per task + two-stage review (spec then quality) + diff-based validation = high quality, fast iteration

为每个任务分配全新的子代理，且每个任务完成后进行两阶段审核。

核心原则： 每个任务分配全新子代理 + 两阶段审核（先规格审核再质量审核） + 基于差异的验证 = 高质量、快速迭代

Quick Reference

快速参考

Phase	Actor	Action	Exit Condition
1	Controller	Read plan, extract tasks, capture BASE_SHA, create task list	All tasks tracked with BASE_SHA
2	Subagent	Implement (templates/implementer.md)	Commit exists + tests pass + report includes HEAD_SHA
3	Subagent	Spec review (templates/spec-reviewer.md)	Reviewer checked diff(BASE..HEAD) and returned ✅ or file:line issues
4	Subagent	Quality review (templates/code-quality-reviewer.md)	Reviewer approved diff or returned severity-tagged issues
5	Controller	Update state, mark complete, loop to step 2	All tasks done
6	Subagent	Final review of entire implementation	Approved
7	Controller	Use finishing-a-development-branch	Branch complete

阶段	执行者	操作	退出条件
1	控制器	读取计划、提取任务、记录BASE_SHA、创建任务列表	所有任务已关联BASE_SHA进行跟踪
2	子代理	实现功能（参考templates/implementer.md）	提交已创建 + 测试通过 + 报告包含HEAD_SHA
3	子代理	规格审核（参考templates/spec-reviewer.md）	审核人员已检查diff(BASE..HEAD)并返回✅或标注file:line格式的问题
4	子代理	质量审核（参考templates/code-quality-reviewer.md）	审核人员已批准差异内容或返回带严重程度标签的问题
5	控制器	更新状态、标记任务完成、循环至步骤2	所有任务已完成
6	子代理	对整个实现进行最终审核	审核通过
7	控制器	调用finishing-a-development-branch技能	开发分支已完成

Task Contract

任务契约

Every task must satisfy these constraints:

Scope:

One task = one commit (or tight commit stack)
No drive-by refactors; no formatting churn
No unrelated file changes

Verification:

All tests pass (run full suite or affected subset)
Lint/typecheck pass (if applicable)
Commands actually executed (not assumed)

Report must include:

BASE_SHA (from controller)
HEAD_SHA (after commit)
Commands run (exact, copy-pasteable)
Test output summary (pass/fail + counts)
Files changed (list)
Scope confirmation ("No unrelated changes")

每个任务必须满足以下约束：

范围：

一个任务 = 一次提交（或紧密关联的提交序列）
禁止附带重构操作；禁止无意义的格式变更
禁止无关文件修改

验证要求：

所有测试通过（运行完整测试套件或受影响的子集）
代码检查/类型检查通过（如适用）
必须实际执行命令（不可假设已执行）

报告必须包含：

BASE_SHA（来自控制器）
HEAD_SHA（提交后的值）
执行的命令（精确可复制的内容）
测试输出摘要（通过/失败 + 数量统计）
修改的文件列表
范围确认（“无无关修改”）

State Tracking

状态跟踪

Controller maintains per-task record:

{
  task_id: string,
  base_sha: string,      # Captured before implementer starts
  head_sha: string,      # From implementer report after commit
  status: pending|in_progress|spec_review|quality_review|complete,
  spec_review_cycles: number,
  quality_review_cycles: number
}

Update state after each phase transition.

控制器维护每个任务的记录：

{
  task_id: string,
  base_sha: string,      # 子代理开始前记录
  head_sha: string,      # 来自子代理提交后的报告
  status: pending|in_progress|spec_review|quality_review|complete,
  spec_review_cycles: number,
  quality_review_cycles: number
}

每次阶段转换后更新状态。

Process

流程

Setup (Once)

初始化（仅执行一次）

Read plan file once
Extract all tasks with full text and context
Capture current HEAD as BASE_SHA for first task
Create task list with all tasks (status: pending)

读取计划文件
提取所有任务的完整文本和上下文
记录当前HEAD作为第一个任务的BASE_SHA
创建包含所有任务的任务列表（状态：pending）

Per Task Loop

单任务循环

Record BASE_SHA for this task (current HEAD)
Dispatch implementer with full task text + context + BASE_SHA
If questions: Answer completely, re-dispatch with answers
Implementer completes: implements, tests, commits, reports HEAD_SHA
Update state: Record HEAD_SHA, set status to spec_review
Dispatch spec reviewer with task requirements + diff(BASE_SHA..HEAD_SHA)
If spec issues: Implementer fixes → spec reviewer re-reviews → increment cycle count → repeat until ✅
Update state: Set status to quality_review
Dispatch code quality reviewer with BASE_SHA, HEAD_SHA
If quality issues: Implementer fixes → quality reviewer re-reviews → increment cycle count → repeat until ✅
Update state: Set status to complete, BASE_SHA for next task = current HEAD_SHA

记录当前任务的BASE_SHA（当前HEAD值）
分配实现子代理，提供完整任务文本、上下文和BASE_SHA
若有疑问： 清晰完整地解答后，重新分配子代理
实现子代理完成： 完成功能实现、测试、提交，并报告HEAD_SHA
更新状态： 记录HEAD_SHA，将状态设置为spec_review
分配规格审核子代理，提供任务要求和diff(BASE_SHA..HEAD_SHA)
若存在规格问题： 实现子代理修复 → 规格审核子代理重新审核 → 增加循环计数 → 重复直至审核通过✅
更新状态： 将状态设置为quality_review
分配代码质量审核子代理，提供BASE_SHA和HEAD_SHA
若存在质量问题： 实现子代理修复 → 质量审核子代理重新审核 → 增加循环计数 → 重复直至审核通过✅
更新状态： 将状态设置为complete，下一个任务的BASE_SHA = 当前HEAD_SHA

Completion

完成阶段

Dispatch final code reviewer for entire implementation (first BASE_SHA to final HEAD_SHA)
Use finishing-a-development-branch skill

分配最终代码审核子代理，对整个实现进行审核（从第一个BASE_SHA到最终HEAD_SHA）
调用finishing-a-development-branch技能

Prompt Templates

提示词模板

```
templates/implementer.md
```
— Implementation subagent
```
templates/spec-reviewer.md
```
— Spec compliance verification (diff-based)
```
templates/code-quality-reviewer.md
```
— Code quality assessment (diff-based)

See

references/example-workflow.md

for complete walkthrough with SHA tracking.

```
templates/implementer.md
```
— 实现子代理模板
```
templates/spec-reviewer.md
```
— 规格合规性验证模板（基于差异）
```
templates/code-quality-reviewer.md
```
— 代码质量评估模板（基于差异）

完整流程示例可参考

references/example-workflow.md

，包含SHA跟踪细节。

Red Flags

注意事项（红色警示）

Never:

Skip reviews (spec compliance OR code quality)
Proceed with unfixed issues
Dispatch parallel implementers in same working tree (conflicts)
Make subagent read plan file (provide full text)
Skip BASE_SHA/HEAD_SHA tracking
Let reviewers assess "the repo" instead of the specific diff
Accept reports without required fields (SHA, commands, test output)

Parallel clarification: "Parallel sessions" (separate branches/worktrees) is fine via executing-plans. "Parallel implementers" touching same working tree is forbidden.

If subagent asks questions: Answer clearly and completely before they proceed.

If reviewer finds issues: Implementer fixes → reviewer re-reviews specific diff → repeat until approved.

If implementer discovers required refactor: Stop, report to controller, request plan amendment. Don't bulldoze.

绝对禁止：

跳过审核（规格合规性或代码质量审核）
带着未修复的问题推进
在同一工作目录中分配多个并行的实现子代理（会导致冲突）
让子代理自行读取计划文件（需提供完整文本）
跳过BASE_SHA/HEAD_SHA跟踪
让审核人员评估“整个仓库”而非特定差异
接受缺少必填字段的报告（SHA、命令、测试输出）

并行说明： 通过executing-plans实现的“并行会话”（独立分支/工作目录）是允许的。但“并行实现子代理”操作同一工作目录是严格禁止的。

若子代理提出疑问： 在其推进前清晰完整地解答。

若审核人员发现问题： 实现子代理修复 → 审核人员重新审核特定差异 → 重复直至审核通过。

若实现子代理发现需要重构： 立即停止，向控制器报告，请求修改计划。禁止擅自进行。

Dependencies

依赖项

Requires: writing-plans (creates the plan)

Subagents use: test-driven-development, requesting-code-review (template)

Completes with: finishing-a-development-branch

Alternative: executing-plans (for parallel sessions/branches, not parallel implementers)

Environment notes: This skill assumes availability of: git (for SHA tracking), a task list tool (TodoWrite or equivalent), and ability to dispatch subagents. Adapt tool names to your environment.

前置技能： writing-plans（用于创建计划）

子代理使用技能： test-driven-development, requesting-code-review（模板）

收尾技能： finishing-a-development-branch

替代方案： executing-plans（适用于并行会话/分支，而非并行实现子代理）

环境说明： 本技能假设环境中已具备：git（用于SHA跟踪）、任务列表工具（TodoWrite或同类工具）、以及分配子代理的能力。可根据实际环境调整工具名称。