Superpowers 子代理驱动开发：Implementer 子代理提示词模板全解

Superpowers 的 subagent-driven-development（下称 SDD）技能通过"每任务派发一个全新 implementer 子代理 + 逐任务审查 + 最终整分支审查"的方式执行实现计划。本文以 implementer-prompt.md 这份 implementer 子代理派发模板为主体，完整保留其原文，并逐段解析模板中每一处措辞背后的工程意图，再结合 SKILL.md 的控制器流程与 scripts/ 目录下的辅助脚本，讲清楚这套"任务简报 → 实施 → 报告 → 审查 → 修复回路"机制是如何落地的。读完后你将能够：正确填充模板占位符派发 implementer 子代理、理解四态状态契约（DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT）的判定与处理路径，并复现配套的 brief/report/review-package 工作流。

一、模板在 SDD 流程中的位置

SDD 的核心原则（见 SKILL.md）是：每个任务派发一个全新子代理，子代理绝不继承控制器的会话上下文——控制器只精确构造它所需的最小上下文。这带来两个直接后果：

1. 任务需求必须通过文件传递，而不是粘贴。控制器在派发前运行 scripts/task-brief PLAN_FILE N 从计划文件抽取该任务的全文到 task-N-brief.md，implementer 只需"读这一个文件"；精确数值（数字、魔法字符串、签名、测试用例）只出现在 brief 中，避免被子代理"改写"。
2. 子代理的产出也必须落盘。implementer 把完整报告写入 task-N-report.md，只回传不超过 15 行的状态摘要——因为"你粘进派发提示的每一样东西、以及子代理回印的每一样东西，都会在整个会话期间驻留在你的上下文里"（SKILL.md The Task Loop 一节）。

implementer-prompt.md 正是这一机制的提示词载体：它定义了 implementer 的角色边界（实现什么、何时发问、何时升级）、执行纪律（测试策略、代码组织）、自我审查清单，以及向控制器回传的格式契约。

二、完整模板原文

以下是 implementer-prompt.md 的完整模板。方括号内容为占位符，由控制器在派发前替换：

Subagent (general-purpose):
  description: "Implement Task N: [task name]"
  model: [MODEL — REQUIRED: choose per SKILL.md Model Selection; an omitted
         model silently inherits the session's most expensive one]
  prompt: |
    You are implementing Task N: [task name]

    ## Task Description

    Read your task brief first: [BRIEF_FILE]
    It contains the full task text from the plan.

    ## Context

    [Scene-setting: where this fits, dependencies, architectural context]

    ## Before You Begin

    If you have questions about:
    - The requirements or acceptance criteria
    - The approach or implementation strategy
    - Dependencies or assumptions
    - Anything unclear in the task description

    **Ask them now.** Raise any concerns before starting work.

    ## Your Job

    Once you're clear on requirements:
    1. Implement exactly what the task specifies
    2. Write tests (following TDD if task says to)
    3. Verify implementation works
    4. Commit your work
    5. Self-review (see below)
    6. Report back

    Work from: [directory]

    **While you work:** If you encounter something unexpected or unclear, **ask questions**.
    It's always OK to pause and clarify. Don't guess or make assumptions.

    While iterating, run the focused test for what you're changing; run the
    full suite once before committing, not after every edit.

    ## Code Organization

    You reason best about code you can hold in context at once, and your edits are more
    reliable when files are focused. Keep this in mind:
    - Follow the file structure defined in the plan
    - Each file should have one clear responsibility with a well-defined interface
    - If a file you're creating is growing beyond the plan's intent, stop and report
      it as DONE_WITH_CONCERNS — don't split files on your own without plan guidance
    - If an existing file you're modifying is already large or tangled, work carefully
      and note it as a concern in your report
    - In existing codebases, follow established patterns. Improve code you're touching
      the way a good developer would, but don't restructure things outside your task.

    ## When You're in Over Your Head

    It is always OK to stop and say "this is too hard for me." Bad work is worse than
    no work. You will not be penalized for escalating.

    **STOP and escalate when:**
    - The task requires architectural decisions with multiple valid approaches
    - You need to understand code beyond what was provided and can't find clarity
    - You feel uncertain about whether your approach is correct
    - The task involves restructuring existing code in ways the plan didn't anticipate
    - You've been reading file after file trying to understand the system without progress

    **How to escalate:** Report back with status BLOCKED or NEEDS_CONTEXT. Describe
    specifically what you're stuck on, what you've tried, and what kind of help you need.
    The controller can provide more context, re-dispatch with a more capable model,
    or break the task into smaller pieces.

    ## Before Reporting Back: Self-Review

    Review your work with fresh eyes. Ask yourself:

    **Completeness:**
    - Did I fully implement everything in the spec?
    - Did I miss any requirements?
    - Are there edge cases I didn't handle?

    **Quality:**
    - Is this my best work?
    - Are names clear and accurate (match what things do, not how they work)?
    - Is the code clean and maintainable?

    **Discipline:**
    - Did I avoid overbuilding (YAGNI)?
    - Did I only build what was requested?
    - Did I follow existing patterns in the codebase?

    **Testing:**
    - Do tests actually verify behavior (not just mock behavior)?
    - Did I follow TDD if required?
    - Are tests comprehensive?
    - Is the test output pristine (no stray warnings or noise)?

    If you find issues during self-review, fix them now before reporting.

    ## After Review Findings

    If the task review finds issues, you will be resumed with the findings.
    Fix them, re-run the tests that cover the amended code, and append a fix
    report to your report file: what you changed, the covering tests you
    ran, the command, and the output. Reviewers will not re-run tests for
    you — your report is the test evidence. Then reply with the same short
    status contract as your first report.

    ## Report Format

    Write your full report to [REPORT_FILE]:
    - What you implemented (or what you attempted, if blocked)
    - What you tested and test results
    - **TDD Evidence** (if TDD was required for this task):
      - RED: command run, relevant failing output before implementation, and why the failure was expected
      - GREEN: command run and relevant passing output after implementation
    - Files changed
    - Self-review findings (if any)
    - Any issues or concerns

    Then report back with ONLY (under 15 lines — the detail lives in the
    report file):
    - **Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
    - Commits created (short SHA + subject)
    - One-line test summary (e.g. "14/14 passing, output pristine")
    - Your concerns, if any
    - The report file path

    If BLOCKED or NEEDS_CONTEXT, put the specifics in the final message
    itself — the controller acts on it directly.

    Use DONE_WITH_CONCERNS if you completed the work but have doubts about correctness.
    Use BLOCKED if you cannot complete the task. Use NEEDS_CONTEXT if you need
    information that wasn't provided. Never silently produce work you're unsure about.

三、占位符与字段约定

模板中的占位符与控制器侧的来源一一对应：

占位符	含义	控制器侧的来源
[task name] / Task N	任务编号与名称，用于 description 与角色声明	计划文件中 ## Task N: ... 标题
[MODEL]	必填。子代理使用的模型	按 SKILL.md Model Selection 一节选择；省略会"静默继承会话中最贵的那个模型"
[BRIEF_FILE]	任务简报文件路径，需求的唯一来源	scripts/task-brief PLAN_FILE N 打印出的路径，默认形如 <repo>/.superpowers/sdd/<plan-basename>/task-N-brief.md
[directory]	implementer 的工作目录	通常为 SDD 约定的 git worktree 目录
[REPORT_FILE]	完整报告的落盘路径	命名与 brief 对应：task-N-brief.md → task-N-report.md，同样位于该计划的 workspace 目录
Context 段	场景铺垫：任务在整体中的位置、依赖、架构上下文	控制器手工撰写，并附上此前任务遗留的接口约定、简报中歧义的裁定结果

关于 model 字段，模板特意加了一句警告：omitted model "silently inherits the session's most expensive one"（静默继承会话中最贵的模型）。这与 SKILL.md Model Selection 一节的规则呼应——"Always specify the model explicitly when dispatching a subagent"。该节的选型准则值得在填模板前重读一遍：

• 机械实现任务（1-2 个文件、规格完整）→ 快速便宜的模型；若计划文本里已含完整代码，实现即"转录+测试"，用最低档；
• 集成/判断任务（多文件协调、模式匹配、调试）→ 标准档；
• 架构/设计任务与最终整分支审查 → 最强可用模型；
• 修复回路第 4-5 轮 → 至少比卡住的 implementer 高一档；
• 关键经验："Turn count beats token price"——轮次成本胜过 token 单价，最便宜的模型在多步工作上常常要 2-3 倍的轮次，总成本反而更高。

四、模板逐段设计解析

4.1 任务入口：先读简报，先问后做

## Task Description 要求 implementer 先读 [BRIEF_FILE]，"It contains the full task text from the plan"。配合 SKILL.md 的派发约定，简报被介绍为 "read this first — it is your requirements, with the exact values to use verbatim"（先读——这就是你的需求，其中的精确值必须逐字使用）。这是上下文工程的关键：子代理只拿到单个任务，从不会读整个计划文件。

## Before You Begin 列出四类应该开工前提出问题的情况：需求/验收标准、方案/实现策略、依赖/假设、任务描述中任何不清晰处。## While you work 再次强调中途遇到意外或不明确时暂停澄清、"Don't guess or make assumptions"（不要猜测或做假设）。这种"把提问合法化"的双次强调，是为了对抗子代理常见的"默默做出错误假设"失败模式。

4.2 工作纪律：六步作业流程与测试策略

## Your Job 给出固定六步：按规格实现 → 写测试（任务要求时遵循 TDD）→ 验证实现 → 提交 → 自我审查 → 回报。其中测试策略是一条明确的性能/效率规则：

While iterating, run the focused test for what you're changing; run the full suite once before committing, not after every edit.

即迭代期间只跑与改动相关的聚焦测试，提交前完整跑一次全量套件，而不是每次编辑后都全量跑。

4.3 代码组织：受计划约束的克制

## Code Organization 的五条规则围绕一个前提——"你能一次放进上下文的代码才是你能可靠推理的代码"：

1. 遵循计划定义的文件结构；
2. 每个文件单一职责、接口清晰；
3. 新建文件超出计划意图时，停下来以 DONE_WITH_CONCERNS 报告，而不是擅自拆文件（拆分的决定权在计划/控制器）；
4. 修改的既有文件若已很大或很乱，谨慎处理并在报告中记为 concern；
5. 遵循既有代码库模式；改善你碰到的代码（"the way a good developer would"），但不重构任务范围之外的东西。

这组规则与模板后文的状态契约形成闭环：文件膨胀这类"范围外"的结构性问题，被设计为走 DONE_WITH_CONCERNS 通道而不是被 implementer 自行吞掉。

4.4 升级机制："能力不足"是被制度性允许的

## When You're in Over Your Head 是全模板最具防御性的段落。它先给出总原则——"Bad work is worse than no work. You will not be penalized for escalating"（坏工作比没有工作更糟，升级不会受罚），然后列出五个必须停下升级的信号：任务需要多方案并存的架构决策；需要理解远超所给上下文的代码且找不到清晰线索；不确定自己方案是否正确；任务涉及计划未预料的既有代码重构；翻了很多文件仍无进展。

升级方式是回传 BLOCKED 或 NEEDS_CONTEXT 状态，并具体描述：卡在哪、试过什么、需要什么帮助。模板还预告了控制器的三种应对："provide more context, re-dispatch with a more capable model, or break the task into smaller pieces"。SKILL.md 侧的对应处理更严格："Never ignore an escalation or force the same model to retry without changes"（绝不忽略升级，也绝不让同一模型不做任何改变地硬试）。

4.5 自我审查：回报前的四象限清单

## Before Reporting Back: Self-Review 要求用"新眼睛"过四个维度：

• Completeness（完整性）：规格是否全部实现、有无遗漏需求、边界情形是否处理；
• Quality（质量）：是否是自己最好的工作、命名是否准确（"match what things do, not how they work"）、代码是否整洁可维护；
• Discipline（纪律）：是否避免了过度建设（YAGNI）、是否只做了被要求的事、是否遵循代码库既有模式；
• Testing（测试）：测试是否验证真实行为（而非 mock 行为）、是否遵循 TDD（如要求）、覆盖是否充分、测试输出是否 pristine（无杂散警告或噪音）。

"fix them now before reporting"（发现问题当场修复，然后再回报）把自我审查定位成第一道质量门。但注意 SKILL.md 的明确边界："Implementer self-review never replaces the task review; both are needed"——自审不能替代随后的任务审查。

4.6 审查发现的处理：报告即测试证据

## After Review Findings 定义了修复回路的 implementer 侧协议：被"resume"（恢复）并收到 findings 后，修复 → 重跑覆盖被改代码的测试 → 把修复报告追加到同一个报告文件（写清改了什么、跑了哪些覆盖测试、命令、输出）→ 用与首次报告相同的简短状态契约回复。

关键一句："Reviewers will not re-run tests for you — your report is the test evidence"（审查者不会替你重跑测试——你的报告就是测试证据）。这与 task-reviewer-prompt.md 中 "Do Not Trust the Report / Do not re-run the suite to confirm their report" 的规则互为镜像：审查方把报告视为"未经验证的声称"，只与 diff 交叉验证，且"only a focused test, never a package-wide suite"。SKILL.md 修复回路一节也要求控制器在派发再审查前确认三要素齐备："the fix report contains the covering tests, the command run, and the output"。

4.7 报告格式与四态状态契约

## Report Format 定义了双层输出：

层一：落盘的完整报告（写入 [REPORT_FILE]），内容包括：实现了什么（若被阻塞则写了尝试了什么）、测试了什么及结果、TDD Evidence（如任务要求 TDD：RED——实现前运行的命令、相关失败输出、为何该失败是预期的；GREEN——实现后的命令与通过输出）、变更文件清单、自审发现、问题与顾虑。

层二：回传给控制器的短消息（不超过 15 行，细节都在报告文件里）：

• Status: DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
• 创建的提交（短 SHA + 主题）
• 一行测试摘要（如 "14/14 passing, output pristine"）
• 顾虑（如有）
• 报告文件路径

四态语义与控制器侧的处理路径（模板末段 + SKILL.md "Handle the report" 一节）：

状态	语义	控制器动作
DONE	完成	生成审查包并派发任务审查者
DONE_WITH_CONCERNS	完成但对正确性有疑虑	先读顾虑：涉及正确性/范围则先处理再审查；仅观察性（如"某文件在变大"）则记录后继续
NEEDS_CONTEXT	缺信息	补齐上下文后重新派发
BLOCKED	无法完成	四选一路：补上下文重派同模型 / 换更强模型重派 / 拆小任务 / 计划本身错误则升级给人

模板特别规定：BLOCKED 或 NEEDS_CONTEXT 时，具体细节必须直接写在最终消息里（"the controller acts on it directly"）——因为这两态下控制器要立即行动，不会去翻报告文件。最后一句是全模板的收尾纪律："Never silently produce work you're unsure about"（绝不默默交出不确定的工作）。

五、配套脚本：模板占位符背后的工程实现

模板能成立，依赖控制器侧三个脚本（均在 skills/subagent-driven-development/scripts/ 下），它们共同把"文件交接"落到实处。

1. task-brief PLAN_FILE N [OUTFILE] — scripts/task-brief

用 awk 从计划文件中抽取匹配 ^#+[ \t]+Task[ \t]+N 标题的任务全文（跳过代码围栏内的干扰标题），写入默认路径 <repo-root>/.superpowers/sdd/<plan-basename>/task-N-brief.md，并打印 wrote <path>: <n> lines。参数不足/过多退出码 2，任务标题未找到退出码 3。这就是模板中 [BRIEF_FILE] 的生成方式。

2. sdd-workspace PLAN_FILE — scripts/sdd-workspace

解析并确保该计划专属的 workspace 目录（.superpowers/sdd/<plan-basename>/），打印其绝对路径，并写入一个内容为 * 的自忽略 .gitignore 于 .superpowers/sdd/。脚本注释解释了两个关键设计决策：一是每计划一个目录，让后续计划不可能误读别的计划的 ledger（"A stale ledger misread as current progress makes controllers skip whole task sequences"）；二是 workspace 放在工作树而非 .git/ 下，因为 Claude Code 把 .git/ 当作受保护路径、拒绝代理写入——那会直接阻塞 implementer 写它的报告文件。它同时是 task-brief 与 review-package 目录解析的单一事实源。

3. review-package PLAN_FILE BASE HEAD [OUTFILE] — scripts/review-package

生成审查包文件：git log --oneline 提交列表 + git diff --stat 摘要 + git diff -U10 全量 diff（扩展 10 行上下文），写入 review-<base7>..<head7>.diff，审查者一次 Read 即可看全。它强制要求先给计划文件参数（否则无法落到正确的计划目录），并对 BASE/HEAD 做 git rev-parse --verify 校验。SKILL.md 反复强调 BASE 必须是派发 implementer 前记录的 git rev-parse HEAD——"never HEAD~1, which silently drops all but the last commit of a multi-commit task"（绝不用 HEAD~1，它会静默丢掉多提交任务中除最后一个以外的所有提交）。

这些脚本的行为有专门的 shell 测试覆盖：tests/claude-code/test-sdd-workspace.sh 验证了参数校验（退出码 2）、双计划解析到互异目录、.gitignore 内容恰为 *、workspace 对 git status 与 git add -A 不可见、task-brief/review-package 的产出落在各自计划的目录下、显式 OUTFILE 被尊重，以及linked worktree 解析出各自独立的 workspace（配合 SDD 的"在隔离 worktree 中实现"约定）。

六、把模板放进完整回路：一次典型派发

综合 SKILL.md 的任务循环，模板在真实会话中的生命周期是：

1. 派发前：创建/恢复该计划的 workspace（sdd-workspace）；运行 task-brief PLAN N 得到 [BRIEF_FILE]；记录 BASE=$(git rev-parse HEAD)；按 Model Selection 选定 [MODEL]；报告文件定名 task-N-report.md。
2. 派发：用本文第二节模板填充占位符，Context 段写入"任务在整体中的一行定位 + 简报路径 + 先前任务遗留接口 + 歧义裁定 + 报告契约"。禁止把累积的前序任务总结粘进后续派发（SKILL.md 记录了一个真实会话中 42k 字符的派发，99% 是粘贴的历史）。
3. 交互：implementer 可能先问问题（模板 "Before You Begin"）——控制器"clearly and completely"作答并补充上下文，不催促其进入实现。
4. 回报：收到 ≤15 行状态消息。DONE → 运行 review-package PLAN BASE HEAD，把打印的路径连同 brief 路径、报告文件路径一起交给任务审查者（task-reviewer-prompt.md）。
5. 修复回路（最多 5 轮）：第 1-3 轮 resume 原 implementer（模板 "After Review Findings" 即为此设计，报告文件是"persistent memory"）；第 4-5 轮换新 implementer + 更高档模型。每轮以一次范围受限的再审查收尾（re-review-prompt.md 只判每条 finding 是否 ADDRESSED、只查修复 diff 是否引入新问题）。第 5 轮仍有 open findings 时触发断路器：控制器逐条裁决——可争议的/不影响下游的 park 进 ledger 并写明 ruling；"real and load-bearing"（后续任务依赖它或暴露计划缺陷）的则 STOP，向人报告 BLOCKED。
6. 完成：ledger 记 Task N: complete (commits <base7>..<head7>, review clean)，进入下一任务；全部任务完成后做一次整分支最终审查。

七、小结

implementer-prompt.md 的价值不在于它是一张"填空题"，而在于把子代理协作中一系列反复出现的失败模式都写进了契约：用 brief 文件隔离需求（防转述失真）、用报告文件隔离细节（防上下文膨胀）、用"先问后做 + 明确升级通道"替代猜测（防静默错误假设）、用四态状态契约强制不确定性显性化（防"默默交出不确定的工作"）、用"报告即测试证据"约定打通 implementer 与 reviewer 的职责边界。模板与其控制器流程（SKILL.md）、辅助脚本（task-brief / sdd-workspace / review-package）和测试（test-sdd-workspace.sh）构成一个自洽的整体——理解模板每个小节的"为什么"，是把它移植到自己的多代理开发流程中的前提。