subagent-driven-development

子代理驱动开发

通过 task 工具为每项任务派发一个全新的子代理来执行计划，先进行规范符合性审查，再进行代码质量审查；当任务涉及安全相关代码时，还要进行阻断式安全审查。

**为什么使用子代理：**你可以将任务委派给上下文相互隔离的专业代理。通过精心编写指令并提供恰当的上下文，确保它们专注于任务并顺利完成。它们绝不应继承你的会话上下文或历史记录——你需要准确构建它们所需的信息。这样也能保留你自己的上下文，用于协调工作。

**核心原则：**每项任务都使用全新的子代理 + 先进行规范审查，再进行质量审查，任务涉及安全相关代码时再进行安全审查 = 高质量、快速迭代

何时使用

digraph when_to_use {
    "Have implementation plan?" [shape=diamond];
    "Tasks mostly independent?" [shape=diamond];
    "Stay in this session?" [shape=diamond];
    "subagent-driven-development" [shape=box];
    "executing-plans" [shape=box];
    "Manual execution or brainstorm first" [shape=box];

    "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
    "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
    "Tasks mostly independent?" -> "Stay in this session?" [label="yes"];
    "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
    "Stay in this session?" -> "subagent-driven-development" [label="yes"];
    "Stay in this session?" -> "executing-plans" [label="no - parallel session"];
}

与执行计划（并行会话）的对比：

• 同一会话（无需切换上下文）
• 每项任务使用全新的子代理（不会污染上下文）
• 每项任务完成后都进行审查：先检查规范符合性，再检查代码质量；当任务涉及安全相关代码时，还要进行安全审查
• 迭代更快（任务之间无需人工介入）

流程

digraph process {
    rankdir=TB;

    subgraph cluster_per_task {
        label="Per Task";
        "Dispatch implementer sub-agent (@implementer)" [shape=box];
        "Implementer sub-agent asks questions?" [shape=diamond];
        "Answer questions, provide context" [shape=box];
        "Implementer sub-agent implements, tests, commits, self-reviews" [shape=box];
        "Dispatch spec reviewer sub-agent (@spec-reviewer)" [shape=box];
        "Spec reviewer sub-agent confirms code matches spec?" [shape=diamond];
        "Implementer sub-agent fixes spec gaps" [shape=box];
        "Dispatch code quality reviewer sub-agent (@code-quality-reviewer)" [shape=box];
        "Code quality reviewer sub-agent approves?" [shape=diamond];
        "Implementer sub-agent fixes quality issues" [shape=box];
        "Task touches security-relevant code?" [shape=diamond];
        "Dispatch security reviewer sub-agent (@security-reviewer)" [shape=box];
        "Security reviewer sub-agent: no Critical or High open?" [shape=diamond];
        "Implementer sub-agent fixes security findings" [shape=box];
        "Mark task complete in `todowrite`" [shape=box];
    }

    "Read plan, extract all tasks with full text, note context, create `todowrite` list" [shape=box];
    "More tasks remain?" [shape=diamond];
    "Dispatch final code reviewer sub-agent for entire implementation" [shape=box];
    "Use finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];

    "Read plan, extract all tasks with full text, note context, create `todowrite` list" -> "Dispatch implementer sub-agent (@implementer)";
    "Dispatch implementer sub-agent (@implementer)" -> "Implementer sub-agent asks questions?";
    "Implementer sub-agent asks questions?" -> "Answer questions, provide context" [label="yes"];
    "Answer questions, provide context" -> "Dispatch implementer sub-agent (@implementer)";
    "Implementer sub-agent asks questions?" -> "Implementer sub-agent implements, tests, commits, self-reviews" [label="no"];
    "Implementer sub-agent implements, tests, commits, self-reviews" -> "Dispatch spec reviewer sub-agent (@spec-reviewer)";
    "Dispatch spec reviewer sub-agent (@spec-reviewer)" -> "Spec reviewer sub-agent confirms code matches spec?";
    "Spec reviewer sub-agent confirms code matches spec?" -> "Implementer sub-agent fixes spec gaps" [label="no"];
    "Implementer sub-agent fixes spec gaps" -> "Dispatch spec reviewer sub-agent (@spec-reviewer)" [label="re-review"];
    "Spec reviewer sub-agent confirms code matches spec?" -> "Dispatch code quality reviewer sub-agent (@code-quality-reviewer)" [label="yes"];
    "Dispatch code quality reviewer sub-agent (@code-quality-reviewer)" -> "Code quality reviewer sub-agent approves?";
    "Code quality reviewer sub-agent approves?" -> "Implementer sub-agent fixes quality issues" [label="no"];
    "Implementer sub-agent fixes quality issues" -> "Dispatch code quality reviewer sub-agent (@code-quality-reviewer)" [label="re-review"];
    "Code quality reviewer sub-agent approves?" -> "Task touches security-relevant code?" [label="yes"];
    "Task touches security-relevant code?" -> "Dispatch security reviewer sub-agent (@security-reviewer)" [label="yes"];
    "Task touches security-relevant code?" -> "Mark task complete in `todowrite`" [label="no"];
    "Dispatch security reviewer sub-agent (@security-reviewer)" -> "Security reviewer sub-agent: no Critical or High open?";
    "Security reviewer sub-agent: no Critical or High open?" -> "Implementer sub-agent fixes security findings" [label="no"];
    "Implementer sub-agent fixes security findings" -> "Dispatch security reviewer sub-agent (@security-reviewer)" [label="re-review"];
    "Security reviewer sub-agent: no Critical or High open?" -> "Mark task complete in `todowrite`" [label="yes"];
    "Mark task complete in `todowrite`" -> "More tasks remain?";
    "More tasks remain?" -> "Dispatch implementer sub-agent (@implementer)" [label="yes"];
    "More tasks remain?" -> "Dispatch final code reviewer sub-agent for entire implementation" [label="no"];
    "Dispatch final code reviewer sub-agent for entire implementation" -> "Use finishing-a-development-branch";
}

模型选择

为每个角色选用能够胜任的最低能力模型，以节省成本并提高速度。

机械式实现任务（独立函数、规范明确、涉及 1-2 个文件）：使用快速、低成本的模型。计划规范明确时，大多数实现任务都是机械式的。

集成和判断类任务（多文件协作、模式匹配、调试）：使用标准模型。

架构、设计和审查任务：使用当前最强大的可用模型。

任务复杂度信号：

• 涉及 1-2 个文件且规范完整 → 低成本模型
• 涉及多个文件且存在集成问题 → 标准模型
• 需要设计判断或广泛理解代码库 → 最强大的可用模型

处理实现者状态

实现者子代理会报告以下四种状态之一。请分别妥善处理：

**DONE：**继续进行规范符合性审查。

**DONE_WITH_CONCERNS：**实现者已完成工作，但提出了疑虑。继续之前先阅读这些疑虑。如果涉及正确性或范围，请在审查前处理。如果只是观察（例如“这个文件越来越大”），请记录后继续审查。

**NEEDS_CONTEXT：**实现者需要未提供的信息。补充缺失的上下文，然后重新派发。

**BLOCKED：**实现者无法完成任务。评估阻碍：

1. 如果是上下文问题，补充更多上下文，并使用相同模型重新派发
2. 如果任务需要更多推理，使用能力更强的模型重新派发
3. 如果任务规模过大，将其拆分为更小的部分
4. 如果计划本身有误，向人工升级处理

绝不忽视升级请求，也不要在不做任何调整的情况下强迫同一模型重试。如果实现者表示受阻，就需要做出改变。

Agent 参考

• implementer（全局 Agent）- 派发实现者子代理
• spec-reviewer（全局 Agent）- 派发规范符合性审查者子代理
• code-quality-reviewer（全局 Agent）- 派发代码质量审查者子代理
• security-reviewer（全局 Agent）- 派发安全审查者子代理（当任务涉及安全相关代码时）

工作流示例

You: I'm using Subagent-Driven Development to execute this plan.

[Read plan file once: docs/plans/feature-plan.md]
[Extract all 5 tasks with full text and context]
[Create `todowrite` list with all tasks]

Task 1: Hook installation script

[Get Task 1 text and context (already extracted)]
[Dispatch implementation sub-agent using the `task` tool with full task text + context]

Implementer: "Before I begin - should the hook be installed at user or system level?"

You: "User level (~/.config/opencode/hooks/)"

Implementer: "Got it. Implementing now..."
[Later] Implementer:
  - Implemented install-hook command
  - Added tests, 5/5 passing
  - Self-review: Found I missed --force flag, added it
  - Committed

[Dispatch spec compliance reviewer]
Spec reviewer: APPROVED - Spec compliant - all requirements met, nothing extra

[Get git SHAs, dispatch code quality reviewer]
Code reviewer: Strengths: Good test coverage, clean. Issues: None. Approved.

[Mark Task 1 complete]

Task 2: Recovery modes

[Get Task 2 text and context (already extracted)]
[Dispatch implementation sub-agent using the `task` tool with full task text + context]

Implementer: [No questions, proceeds]
Implementer:
  - Added verify/repair modes
  - 8/8 tests passing
  - Self-review: All good
  - Committed

[Dispatch spec compliance reviewer]
Spec reviewer: ISSUES:
  - Missing: Progress reporting (spec says "report every 100 items")
  - Extra: Added --json flag (not requested)

[Implementer fixes issues]
Implementer: Removed --json flag, added progress reporting

[Spec reviewer reviews again]
Spec reviewer: APPROVED - Spec compliant now

[Dispatch code quality reviewer]
Code reviewer: Strengths: Solid. Issues (Important): Magic number (100)

[Implementer fixes]
Implementer: Extracted PROGRESS_INTERVAL constant

[Code reviewer reviews again]
Code reviewer: APPROVED

[Mark Task 2 complete]

Task 3: Token signing key (touches security-relevant code)

[Spec APPROVED, quality APPROVED]

[Dispatch security reviewer]
Security reviewer: Critical open — signing key from env, no check it is
non-empty (fails open to unsigned tokens). Path traced, fix named.

[Implementer fixes, security reviewer re-reviews]
Security reviewer: APPROVED - no Critical or High open

[Mark Task 3 complete]

...

[After all tasks]
[Dispatch final code-reviewer]
Final reviewer: All requirements met, ready to merge

Done!

优势

与手动执行相比：

• 子 Agent 会自然遵循 TDD
• 每项任务都使用全新上下文（不会混淆）
• 支持并行执行，不会互相干扰
• 子 Agent 可以提问（工作开始前和进行中都可以）

与执行计划相比：

• 使用同一会话（无需交接）
• 持续推进（无需等待）
• 自动设置审核检查点

效率提升：

• 无需额外读取文件（控制器会提供完整文本）
• 控制器会精确筛选所需上下文
• 子 Agent 一开始就能获得完整信息
• 问题会在工作开始前提出（而不是事后）

质量关卡：

• 自我审查可在交接前发现问题
• 审查顺序：先检查规格符合度，再检查代码质量；对于与安全相关的任务，还要进行安全审查
• 审查循环可确保修复确实有效
• 规格符合度审查可避免实现过多或过少
• 代码质量审查可确保实现完善
• 安全审查会在代码交付前追踪攻击者路径

成本：

• 调用子 Agent 的次数更多（每项任务需要实现者和 2 位审查者；与安全相关的任务还需要安全审查者）
• 控制器需要做更多准备工作（提前提取所有任务）
• 审查循环会增加迭代次数
• 但能及早发现问题（比之后调试成本更低）

警示信号

切勿：

• 未经用户明确同意，就在 main/master 分支上开始实现
• 跳过审查（规格符合度和代码质量审查都必不可少；任务涉及与安全相关的代码时，还必须进行安全审查）
• 带着尚未修复的问题继续推进
• 跳过涉及不受信任输入、身份验证/授权、机密、注入点、子进程/插件边界或新增依赖的任务的安全审查者（参见 reviewing-security 的触发条件）
• 并行分派多个实现子 Agent（会产生冲突）
• 让子 Agent 读取计划文件（应改为提供完整文本）
• 跳过背景介绍（子 Agent 需要理解任务在整体中的位置）
• 忽视子 Agent 的问题（让他们继续之前先作出答复）
• 对规格符合度接受“差不多就行”（规格审查者发现问题，就表示任务尚未完成）
• 跳过审查循环（审查者发现问题 → 实现者修复 → 再次审查）
• 让实现者的自我审查取代实际审查（两者都必不可少）
• 在规格符合度审查通过前开始代码质量审查（顺序错误）
• 在规格符合度和代码质量审查通过前开始安全审查（顺序错误）
• 还有任何审查问题未解决时就转到下一项任务

如果子 Agent 提出问题：

• 清晰、完整地作答
• 如有需要，提供更多背景信息
• 不要催促他们开始实现

如果审查者发现问题：

• 由实现者（同一个子 Agent）修复
• 审查者再次审查
• 重复此流程，直到通过
• 不要跳过复审

如果子 Agent 未能完成任务：

• 分派修复子 Agent，并提供具体指示
• 不要尝试手动修复（以免污染上下文）

集成

必需的工作流技能：

• using-git-worktrees - 必需：开始前设置隔离工作区
• writing-plans - 创建此技能要执行的计划
• requesting-code-review - 审查者子 Agent 使用的代码审查工作流
• code-quality-reviewer - 用于代码质量审查的全局 Agent
• security-reviewer - 用于与安全相关任务的安全审查全局 Agent
• finishing-a-development-branch - 所有任务完成后结束开发

子 Agent 应使用：

• test-driven-development - 子 Agent 为每项任务遵循 TDD

替代工作流：

• executing-plans - 使用并行会话，而非在同一会话中执行