Back to Details

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

快速参考

PhaseActorActionExit Condition
1ControllerRead plan, extract tasks, capture BASE_SHA, create task listAll tasks tracked with BASE_SHA
2SubagentImplement (templates/implementer.md)Commit exists + tests pass + report includes HEAD_SHA
3SubagentSpec review (templates/spec-reviewer.md)Reviewer checked diff(BASE..HEAD) and returned ✅ or file:line issues
4SubagentQuality review (templates/code-quality-reviewer.md)Reviewer approved diff or returned severity-tagged issues
5ControllerUpdate state, mark complete, loop to step 2All tasks done
6SubagentFinal review of entire implementationApproved
7ControllerUse finishing-a-development-branchBranch 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)

初始化（仅执行一次）

  1. Read plan file once
  2. Extract all tasks with full text and context
  3. Capture current HEAD as BASE_SHA for first task
  4. Create task list with all tasks (status: pending)
  1. 读取计划文件
  2. 提取所有任务的完整文本和上下文
  3. 记录当前HEAD作为第一个任务的BASE_SHA
  4. 创建包含所有任务的任务列表（状态：pending）

Per Task Loop

单任务循环

  1. Record BASE_SHA for this task (current HEAD)
  2. Dispatch implementer with full task text + context + BASE_SHA
  3. If questions: Answer completely, re-dispatch with answers
  4. Implementer completes: implements, tests, commits, reports HEAD_SHA
  5. Update state: Record HEAD_SHA, set status to spec_review
  6. Dispatch spec reviewer with task requirements + diff(BASE_SHA..HEAD_SHA)
  7. If spec issues: Implementer fixes → spec reviewer re-reviews → increment cycle count → repeat until ✅
  8. Update state: Set status to quality_review
  9. Dispatch code quality reviewer with BASE_SHA, HEAD_SHA
  10. If quality issues: Implementer fixes → quality reviewer re-reviews → increment cycle count → repeat until ✅
  11. Update state: Set status to complete, BASE_SHA for next task = current HEAD_SHA
  1. 记录当前任务的BASE_SHA（当前HEAD值）
  2. 分配实现子代理，提供完整任务文本、上下文和BASE_SHA
  3. 若有疑问： 清晰完整地解答后，重新分配子代理
  4. 实现子代理完成： 完成功能实现、测试、提交，并报告HEAD_SHA
  5. 更新状态： 记录HEAD_SHA，将状态设置为spec_review
  6. 分配规格审核子代理，提供任务要求和diff(BASE_SHA..HEAD_SHA)
  7. 若存在规格问题： 实现子代理修复 → 规格审核子代理重新审核 → 增加循环计数 → 重复直至审核通过✅
  8. 更新状态： 将状态设置为quality_review
  9. 分配代码质量审核子代理，提供BASE_SHA和HEAD_SHA
  10. 若存在质量问题： 实现子代理修复 → 质量审核子代理重新审核 → 增加循环计数 → 重复直至审核通过✅
  11. 更新状态： 将状态设置为complete，下一个任务的BASE_SHA = 当前HEAD_SHA

Completion

完成阶段

  1. Dispatch final code reviewer for entire implementation (first BASE_SHA to final HEAD_SHA)
  2. Use finishing-a-development-branch skill
  1. 分配最终代码审核子代理，对整个实现进行审核（从第一个BASE_SHA到最终HEAD_SHA）
  2. 调用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或同类工具）、以及分配子代理的能力。可根据实际环境调整工具名称。