subagent-driven-development

子 Agent 驱动的开发

概述

通过为每项任务分派全新的子 Agent，并进行系统化的两阶段审查，来执行实现计划。

核心原则： 每项任务使用全新的子 Agent + 两阶段审查（先审查规范，再审查质量）＝高质量、快速迭代。

适用场景

在以下情况下使用此技能：

• 你有一份实现计划（来自 plan 技能或用户需求）
• 各项任务大多相互独立
• 质量和规范合规性很重要
• 你希望在任务之间进行自动化审查

与手动执行相比：

• 每项任务都有全新的上下文（不会因状态累积而混淆）
• 自动化审查流程可及早发现问题
• 所有任务都执行一致的质量检查
• 子 Agent 可以在开始工作前提问

流程

1. 阅读并解析计划

阅读计划文件。预先提取所有任务的完整内容和上下文。创建待办事项列表：

# Read the plan
read_file("docs/plans/feature-plan.md")

# Create todo list with all tasks
todo([
    {"id": "task-1", "content": "Create User model with email field", "status": "pending"},
    {"id": "task-2", "content": "Add password hashing utility", "status": "pending"},
    {"id": "task-3", "content": "Create login endpoint", "status": "pending"},
])

要点： 只阅读一次计划。提取所有内容。不要让子 Agent 阅读计划文件——直接在上下文中提供完整任务内容。

2. 逐项处理任务

对于计划中的每项任务：

步骤 1：分派实现子 Agent

使用 delegate_task 提供完整上下文：

delegate_task(
    goal="Implement Task 1: Create User model with email and password_hash fields",
    context="""
    TASK FROM PLAN:
    - Create: src/models/user.py
    - Add User class with email (str) and password_hash (str) fields
    - Use bcrypt for password hashing
    - Include __repr__ for debugging

    FOLLOW TDD:
    1. Write failing test in tests/models/test_user.py
    2. Run: pytest tests/models/test_user.py -v (verify FAIL)
    3. Write minimal implementation
    4. Run: pytest tests/models/test_user.py -v (verify PASS)
    5. Run: pytest tests/ -q (verify no regressions)
    6. Commit: git add -A && git commit -m "feat: add User model with password hashing"

    PROJECT CONTEXT:
    - Python 3.11, Flask app in src/app.py
    - Existing models in src/models/
    - Tests use pytest, run from project root
    - bcrypt already in requirements.txt
    """,
    toolsets=['terminal', 'file']
)

步骤 2：分派规范合规性审查员

实现者完成后，根据原始规范进行核验：

delegate_task(
    goal="Review if implementation matches the spec from the plan",
    context="""
    ORIGINAL TASK SPEC:
    - Create src/models/user.py with User class
    - Fields: email (str), password_hash (str)
    - Use bcrypt for password hashing
    - Include __repr__

    CHECK:
    - [ ] All requirements from spec implemented?
    - [ ] File paths match spec?
    - [ ] Function signatures match spec?
    - [ ] Behavior matches expected?
    - [ ] Nothing extra added (no scope creep)?

    OUTPUT: PASS or list of specific spec gaps to fix.
    """,
    toolsets=['file']
)

如果发现规范问题： 修复差距，然后重新进行规范审查。只有符合规范后才能继续。

步骤 3：分派代码质量审查员

通过规范合规性审查后：

delegate_task(
    goal="Review code quality for Task 1 implementation",
    context="""
    FILES TO REVIEW:
    - src/models/user.py
    - tests/models/test_user.py

    CHECK:
    - [ ] Follows project conventions and style?
    - [ ] Proper error handling?
    - [ ] Clear variable/function names?
    - [ ] Adequate test coverage?
    - [ ] No obvious bugs or missed edge cases?
    - [ ] No security issues?

    OUTPUT FORMAT:
    - Critical Issues: [must fix before proceeding]
    - Important Issues: [should fix]
    - Minor Issues: [optional]
    - Verdict: APPROVED or REQUEST_CHANGES
    """,
    toolsets=['file']
)

如果发现质量问题： 修复问题并重新审查。只有获得批准后才能继续。

步骤 4：标记完成

todo([{"id": "task-1", "content": "Create User model with email field", "status": "completed"}], merge=True)

3. 最终审查

所有任务完成后，分派一名最终集成审查员：

delegate_task(
    goal="Review the entire implementation for consistency and integration issues",
    context="""
    All tasks from the plan are complete. Review the full implementation:
    - Do all components work together?
    - Any inconsistencies between tasks?
    - All tests passing?
    - Ready for merge?
    """,
    toolsets=['terminal', 'file']
)

4. 验证并提交

# Run full test suite
pytest tests/ -q

# Review all changes
git diff --stat

# Final commit if needed
git add -A && git commit -m "feat: complete [feature name] implementation"

任务粒度

每项任务应聚焦完成，用时 2–5 分钟。

过大的任务：

• “实现用户身份验证系统”

合适的任务：

• “创建包含电子邮件和密码字段的 User 模型”
• “添加密码哈希函数”
• “创建登录端点”
• “添加 JWT 令牌生成”
• “创建注册端点”

危险信号——绝对不要这样做

• 没有计划就开始实现
• 跳过审查（规范合规性或代码质量）
• 发现严重或重要问题后不修复就继续
• 为涉及相同文件的任务分派多个实现子 Agent
• 让子 Agent 阅读计划文件（应直接在上下文中提供完整内容）
• 跳过背景说明（子 Agent 需要了解任务所处的位置）
• 忽略子 Agent 的问题（让其继续前先回答）
• 对规范合规性接受“差不多就行”
• 跳过审查循环（审查员发现问题 → 实现者修复 → 再次审查）
• 用实现者的自我审查代替实际审查（两者都不可少）
• 在规范合规性审查通过之前开始代码质量审查（顺序错误）
• 任一审查仍有未解决问题时就转到下一项任务

问题处理

如果子 Agent 提问

• 清晰、完整地回答
• 必要时提供更多背景
• 不要催促其开始实现

如果审查员发现问题

• 由实现子 Agent（或新的子 Agent）修复
• 审查员再次审查
• 重复此过程，直到获得批准
• 不要跳过重新审查

如果子 Agent 未能完成任务

• 分派新的修复子 Agent，并具体说明问题所在
• 不要在控制器会话中手动修复（避免上下文污染）

效率说明

为什么每项任务都使用全新的子 Agent：

• 避免状态累积造成的上下文污染
• 每个子 Agent 都能获得干净、专注的上下文
• 不会被先前任务的代码或推理混淆

为什么采用两阶段审查：

• 规范审查可及早发现实现过少或过度构建的问题
• 质量审查可确保实现构建良好
• 可在问题逐项累积之前将其发现

成本权衡：

• 需要调用更多子 Agent（每项任务分别调用实现者和两名审查员）
• 但能及早发现问题（比起之后调试累积的问题，成本更低）

与其他技能的集成

配合 plan 使用

此技能会执行由 plan 技能创建的计划：

1. 用户需求 → 计划 → 实施计划
2. 实施计划 → subagent-driven-development → 可运行的代码

配合 test-driven-development 使用

实施子 Agent 应遵循 TDD：

1. 先编写失败的测试
2. 实现最少量的代码
3. 验证测试通过
4. 提交

在每个实施者的上下文中加入 TDD 指示。

配合 requesting-code-review 使用

两阶段审查流程就是代码审查。对于最终集成审查，请使用 requesting-code-review 技能的审查维度。

配合 systematic-debugging 使用

如果子 Agent 在实施过程中遇到 bug：

1. 遵循 systematic-debugging 流程
2. 修复前先找到根本原因
3. 编写回归测试
4. 恢复实施

工作流示例

[Read plan: docs/plans/auth-feature.md]
[Create todo list with 5 tasks]

--- Task 1: Create User model ---
[Dispatch implementer subagent]
  Implementer: "Should email be unique?"
  You: "Yes, email must be unique"
  Implementer: Implemented, 3/3 tests passing, committed.

[Dispatch spec reviewer]
  Spec reviewer: ✅ PASS — all requirements met

[Dispatch quality reviewer]
  Quality reviewer: ✅ APPROVED — clean code, good tests

[Mark Task 1 complete]

--- Task 2: Password hashing ---
[Dispatch implementer subagent]
  Implementer: No questions, implemented, 5/5 tests passing.

[Dispatch spec reviewer]
  Spec reviewer: ❌ Missing: password strength validation (spec says "min 8 chars")

[Implementer fixes]
  Implementer: Added validation, 7/7 tests passing.

[Dispatch spec reviewer again]
  Spec reviewer: ✅ PASS

[Dispatch quality reviewer]
  Quality reviewer: Important: Magic number 8, extract to constant
  Implementer: Extracted MIN_PASSWORD_LENGTH constant
  Quality reviewer: ✅ APPROVED

[Mark Task 2 complete]

... (continue for all tasks)

[After all tasks: dispatch final integration reviewer]
[Run full test suite: all passing]
[Done!]

请记住

Fresh subagent per task
Two-stage review every time
Spec compliance FIRST
Code quality SECOND
Never skip reviews
Catch issues early

质量并非偶然，而是系统化流程的成果。

延伸阅读（在相关时加载）

当编排涉及大量上下文使用、漫长的审查循环或复杂的验证检查点时，请加载这些针对特定领域的参考资料：

• references/context-budget-discipline.md — 四级上下文退化模型（PEAK / GOOD / DEGRADING / POOR）、随上下文窗口大小调整的阅读深度规则，以及静默退化的早期预警信号。当一次运行明显会消耗大量上下文时（多阶段计划、多个子 Agent、大型产物），请加载此资料。
• references/gates-taxonomy.md — 四种规范的门控类型（Pre-flight、Revision、Escalation、Abort），包括行为、恢复方式和示例。在设计或审查任何包含验证检查点的工作流时，请加载此资料，并明确使用这些术语，以便为每个门控定义进入条件、失败行为和恢复规则。

两份参考资料均改编自 gsd-build/get-shit-done（MIT © 2025 Lex Christopherson）。