# 实现子智能体提示词模板

分派实现子智能体时使用此模板。

```
Subagent (general-purpose):
  description: "实现任务 N：[任务名称]"
  model: [模型 —— 必填：按 SKILL.md 的"模型选择"来选；省略模型会默默
         继承会话里最贵的那个]
  prompt: |
    你正在实现任务 N：[任务名称]

    ## 任务描述

    先读你的任务简报：[BRIEF_FILE]
    它包含计划中该任务的完整文本。

    ## 上下文

    [场景铺设：这个任务在哪个环节、依赖关系、架构上下文]

    ## 开始之前

    如果你对以下内容有疑问：
    - 需求或验收标准
    - 方案或实现策略
    - 依赖或假设
    - 任务描述中任何不清楚的地方

    **现在就问。** 在开始工作之前提出任何疑虑。

    ## 你的工作

    当你确认需求清晰后：
    1. 严格按照任务指定的内容实现
    2. 编写测试（如果任务要求则遵循 TDD）
    3. 验证实现是否正常工作
    4. 提交你的工作
    5. 自审（见下文）
    6. 汇报

    工作目录：[directory]

    **工作过程中：** 如果遇到意料之外或不清楚的情况，**提问**。
    随时可以暂停并澄清。不要猜测或做假设。

    迭代过程中，只跑你正在改动的那部分的聚焦测试；在提交前跑一次
    完整测试套件，而不是每次编辑后都跑。

    ## 代码组织

    你在能一次性放入上下文的代码上推理效果最好，文件聚焦时你的编辑也更可靠。
    请牢记：
    - 遵循计划中定义的文件结构
    - 每个文件应有单一明确的职责和定义清晰的接口
    - 如果你正在创建的文件超出了计划的意图规模，停下来并以
      DONE_WITH_CONCERNS 状态报告——不要在没有计划指导的情况下自行拆分文件
    - 如果你正在修改的现有文件已经很大或很混乱，小心操作，
      并在报告中将其标注为疑虑
    - 在已有代码库中，遵循已建立的模式。像一个好的开发者那样
      改善你接触到的代码，但不要重构你任务范围之外的东西。

    ## 当你力不从心时

    随时可以停下来说"这对我来说太难了"。劣质的工作比不做更糟。
    上报不会受到惩罚。

    **遇到以下情况时停下来上报：**
    - 任务需要在多个有效方案之间做架构决策
    - 你需要理解提供内容之外的代码但找不到清晰答案
    - 你对自己的方案是否正确感到不确定
    - 任务涉及计划未预期的现有代码重构
    - 你一直在逐个读文件试图理解系统但没有进展

    **如何上报：** 以 BLOCKED 或 NEEDS_CONTEXT 状态汇报。具体描述
    你卡在哪里、尝试了什么、需要什么样的帮助。
    控制者可以提供更多上下文、用更强的模型重新分派，
    或将任务拆分为更小的部分。

    ## 汇报前：自审

    用全新的视角审查你的工作。问自己：

    **完整性：**
    - 我是否完全实现了规格中的所有内容？
    - 我是否遗漏了任何需求？
    - 是否有我没处理的边界情况？

    **质量：**
    - 这是我最好的工作吗？
    - 命名是否清晰准确（匹配事物做什么，而非怎么做）？
    - 代码是否整洁且可维护？

    **纪律：**
    - 我是否避免了过度构建（YAGNI）？
    - 我是否只构建了被要求的内容？
    - 我是否遵循了代码库中的已有模式？

    **测试：**
    - 测试是否真正验证了行为（而非只是 mock 行为）？
    - 如果要求了 TDD，我是否遵循了？
    - 测试是否全面？
    - 测试输出是否干净（没有零散的告警或噪声）？

    如果在自审中发现问题，在汇报前就修复。

    ## 审查发现之后

    如果审查者发现了问题、你也修复了，就重跑覆盖被改动代码的测试，
    并把结果追加到你的报告文件里。审查者不会替你重跑测试——
    你的报告就是测试证据。

    ## 报告格式

    把你的完整报告写到 [REPORT_FILE]：
    - 你实现了什么（如果被阻塞，则是你尝试了什么）
    - 你测试了什么以及测试结果
    - **TDD 证据**（如果本任务要求了 TDD）：
      - RED：跑的命令、实现前相关的失败输出、以及为什么这个失败是预期的
      - GREEN：跑的命令、以及实现后相关的通过输出
    - 修改了哪些文件
    - 自审发现（如果有）
    - 任何问题或疑虑

    然后只汇报以下内容（不超过 15 行——细节都在报告文件里）：
    - **状态：** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
    - 创建的提交（短 SHA + 标题）
    - 一行测试小结（例如"14/14 通过，输出干净"）
    - 你的疑虑，如果有
    - 报告文件路径

    如果是 BLOCKED 或 NEEDS_CONTEXT，把具体细节放进最终消息本身——
    控制者会直接据此行动。

    如果你完成了工作但对正确性有疑虑，使用 DONE_WITH_CONCERNS。
    如果你无法完成任务，使用 BLOCKED。如果你需要未提供的信息，
    使用 NEEDS_CONTEXT。绝不默默产出你不确定的工作。
```
</content>

#!/usr/bin/env bash
# Generate a review package: commit list, stat summary, and the net
# diff with extended context, written to a file the reviewer reads in one
# call. Using the recorded per-task BASE (not HEAD~1) keeps multi-commit
# tasks intact.
#
# Usage: review-package BASE HEAD [OUTFILE]
# Default OUTFILE: <repo-root>/.superpowers/sdd/review-<base7>..<head7>.diff
# (named per range, so a re-review after fixes gets a distinct fresh file).
set -euo pipefail

if [ $# -lt 2 ] || [ $# -gt 3 ]; then
  echo "usage: review-package BASE HEAD [OUTFILE]" >&2
  exit 2
fi

base=$1
head=$2

git rev-parse --verify --quiet "$base" >/dev/null || { echo "bad BASE: $base" >&2; exit 2; }
git rev-parse --verify --quiet "$head" >/dev/null || { echo "bad HEAD: $head" >&2; exit 2; }

if [ $# -eq 3 ]; then
  out=$3
else
  dir=$("$(cd "$(dirname "$0")" && pwd)/sdd-workspace")
  out="$dir/review-$(git rev-parse --short "$base")..$(git rev-parse --short "$head").diff"
fi

{
  echo "# Review package: ${base}..${head}"
  echo
  echo "## Commits"
  git log --oneline "${base}..${head}"
  echo
  echo "## Files changed"
  git diff --stat "${base}..${head}"
  echo
  echo "## Diff"
  git diff -U10 "${base}..${head}"
} > "$out"

commits=$(git rev-list --count "${base}..${head}")
echo "wrote ${out}: ${commits} commit(s), $(wc -c < "$out" | tr -d ' ') bytes"

#!/usr/bin/env bash
# Resolve and ensure the working-tree directory SDD uses for its short-lived
# artifacts: task briefs, implementer reports, review packages, and the
# progress ledger. Print the directory's absolute path.
#
# The workspace lives in the working tree (not under .git/) because Claude Code
# treats .git/ as a protected path and denies agent writes there — which blocks
# an implementer subagent from writing its report file. A self-ignoring
# .gitignore keeps the workspace out of `git status` and out of accidental
# commits without modifying any tracked file.
#
# Single source of truth for the workspace location, so task-brief and
# review-package cannot drift to different directories.
#
# Usage: sdd-workspace
set -euo pipefail

root=$(git rev-parse --show-toplevel)
dir="$root/.superpowers/sdd"
mkdir -p "$dir"
printf '*\n' > "$dir/.gitignore"
cd "$dir" && pwd

#!/usr/bin/env bash
# Extract one task's full text from an implementation plan into a file the
# implementer reads in one call, so the task text never has to be pasted
# through the controller's context.
#
# Usage: task-brief PLAN_FILE TASK_NUMBER [OUTFILE]
# Default OUTFILE: <repo-root>/.superpowers/sdd/task-<N>-brief.md
# (per worktree; concurrent runs in the same working tree share it).
#
# 中文 fork 适配：上游只识别英文任务标题 "## Task N"，而 superpowers-zh
# 的 writing-plans 产出的是 "### 任务 N：..."。下方 awk 同时匹配
# "Task" 与 "任务"，两种计划都能抽取。
set -euo pipefail

if [ $# -lt 2 ] || [ $# -gt 3 ]; then
  echo "usage: task-brief PLAN_FILE TASK_NUMBER [OUTFILE]" >&2
  exit 2
fi

plan=$1
n=$2
[ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }

if [ $# -eq 3 ]; then
  out=$3
else
  dir=$("$(cd "$(dirname "$0")" && pwd)/sdd-workspace")
  out="$dir/task-${n}-brief.md"
fi

awk -v n="$n" '
  /^```/ { infence = !infence }
  !infence && /^#+[ \t]+(Task|任务)[ \t]*[0-9]+/ {
    intask = ($0 ~ ("^#+[ \t]+(Task|任务)[ \t]*" n "([^0-9]|$)"))
  }
  intask { print }
' "$plan" > "$out"

if [ ! -s "$out" ]; then
  echo "task ${n} not found in ${plan} (no heading matching 'Task ${n}' / '任务 ${n}')" >&2
  exit 3
fi

echo "wrote ${out}: $(wc -l < "$out" | tr -d ' ') lines"

# 任务审查者提示词模板

分派任务审查子智能体时使用此模板。审查者一次性读取该任务的 diff，
返回两个结论：规格合规性和代码质量。

**目的：** 核实一个任务的实现与其需求匹配（不多不少）且构建良好（整洁、有测试、可维护）

```
Subagent (general-purpose):
  description: "审查任务 N（规格 + 质量）"
  model: [模型 —— 必填：按 SKILL.md 的"模型选择"来选；省略模型会默默
         继承会话里最贵的那个]
  prompt: |
    你正在审查一个任务的实现：先看它是否与需求匹配，再看它是否
    构建良好。这是一个任务范围内的关卡，不是合并审查——覆盖整个
    分支的宽范围审查会在所有任务完成后另行进行。

    ## 要求的内容

    读取任务简报：[BRIEF_FILE]

    来自规格/设计、约束本任务的全局约束：
    [GLOBAL_CONSTRAINTS]

    ## 实现者声称构建了什么

    读取实现者的报告：[REPORT_FILE]

    ## 待审查的 Diff

    **Base：** [BASE_SHA]
    **Head：** [HEAD_SHA]
    **Diff 文件：** [DIFF_FILE]

    一次性读取这个 diff 文件——它包含提交列表、stat 摘要，以及
    带上下文的完整 diff，它就是你对本次改动的视图。diff 的上下文行
    **就是**那些被改动的文件：不要单独去 Read 某个被改动的文件，除非
    你必须判断的某个 hunk 在函数中途被截断——并在报告中说明这一点。
    不要重跑 git 命令。如果 diff 文件缺失，就自己取 diff：
    `git diff --stat [BASE_SHA]..[HEAD_SHA]` 和 `git diff [BASE_SHA]..[HEAD_SHA]`。
    不要爬取更广的代码库。只有为了评估一个你能点名的具体风险，才去
    查看 diff 之外的代码——每个点名的风险做一次聚焦检查，并在报告中
    同时点名这个风险和你检查了什么。横切改动是正当的、可点名的风险：
    如果 diff 改动了锁顺序、某个函数或 API 契约、或共享的可变状态，
    检查其调用点就是正确的方法。

    你的审查在这个 checkout 上是只读的。不要以任何方式改动工作树、
    索引、HEAD 或分支状态。

    ## 不要信任报告

    把实现者的报告当作关于代码的、未经核实的说法。它可能不完整、
    不准确或过于乐观。对照 diff 去核实这些说法。报告里的设计理由
    同样是说法："出于 YAGNI 留着没做""特意保持简单"或任何其他辩解，
    都是实现者在给自己的工作打分。就代码本身评判它的优劣——一句
    陈述出来的理由永远不会降低一个发现的严重度。

    ## 测试

    实现者已经跑过测试，并为正是这份代码报告了带 TDD 证据的结果。
    不要为了确认他们的报告而重跑测试套件。只有当阅读代码引出一个
    现有任何运行都无法回答的具体疑问时，才去跑测试——而且是聚焦
    测试，绝不是包级套件、竞态检测运行、或反复的/高次数的循环。
    如果看起来确实需要重度验证，就在报告里建议它，而不是自己去跑。
    如果你在这个环境里无法运行命令，就点名你会跑的那个测试。

    实现者报告的测试输出里的告警或其他噪声都是发现——测试输出
    应当是干净的。

    ## 第一部分：规格合规性

    把 diff 对照"要求的内容"来看：

    - **缺失：** 他们跳过、遗漏、或声称却未实现的需求
    - **多余：** 未被要求的功能、过度工程、不需要的"锦上添花"
    - **理解偏差：** 正确的功能却用错了方式来构建，解决了错误的问题

    如果某个需求无法仅从这份 diff 中核实（它藏在未改动的代码里、
    或横跨多个任务），就把它作为一个 ⚠️ 事项报告出来，而不是
    扩大你的搜索范围。

    ## 第二部分：代码质量

    **代码质量：**
    - 关注点分离是否干净？
    - 错误处理是否恰当？
    - 是否做到 DRY 而没有过早抽象？
    - 边界情况是否处理了？

    **测试：**
    - 新增和改动的测试是否验证了真实行为，而非 mock？
    - 本任务的边界情况是否被覆盖？

    **结构：**
    - 每个文件是否有单一明确的职责和定义清晰的接口？
    - 各单元是否拆分得足以独立理解和测试？
    - 实现是否遵循了计划中的文件结构？
    - 本次改动是否创建了已经很大的新文件，或显著增大了现有文件？
      （不要标记已有的文件大小问题——聚焦于本次改动带来的贡献。）

    你的报告应指向证据：每一个发现、以及任何你本来会用一句干巴巴的
    "是"来回答的检查，都要给出 file:line 引用。一份引用了行号的
    紧凑报告，就把控制者需要的一切都给它了。

    你的最终消息就是报告本身：直接从规格合规性结论开始。每一行
    要么是一个结论、要么是一个带 file:line 的发现、要么是你跑过的
    一个检查——没有开场白、没有流程叙述、没有结尾小结。

    ## 校准

    按实际严重度给问题分类。不是所有东西都是 关键。
    重要 意味着这个任务在修好之前不可信：不正确或脆弱的行为、
    一个漏掉的需求、或你会为之拦下合并的可维护性损害——逻辑块的
    逐字重复、被吞掉的错误、什么都不断言的测试。"覆盖面可以更广"
    和打磨类建议是 次要。
    如果计划或简报明确强制了某个本评分标准称之为缺陷的东西（一个
    什么都不断言的测试、逻辑块的逐字重复），那**就是**一个发现——
    把它报告为 重要，并标注为"计划强制"。计划的作者身份不能给它
    自己的工作打分；由人类来决定。
    在列出问题之前，先承认做得好的地方——准确的赞扬能帮实现者
    信任其余的反馈。

    ## 输出格式

    ### 规格合规性

    - ✅ 符合规格 | ❌ 发现问题：[缺失/多余/理解偏差的内容，
      附带 file:line 引用]
    - ⚠️ 无法从 diff 中核实：[你无法仅凭 diff 核实的需求，以及
      控制者应当检查什么——与你能核实的一切的 ✅/❌ 结论一起报告]

    ### 优点
    [哪些做得好？要具体。]

    ### 问题

    #### 关键（必须修复）
    #### 重要（应当修复）
    #### 次要（锦上添花）

    每个问题：file:line、哪里错了、为什么重要、如何修复（如果不明显）。

    ### 评估

    **任务质量：** [通过 | 需要修复]

    **理由：** [1-2 句技术性评估]
```

**占位符：**
- `[模型]` —— 必填：按 SKILL.md 的"模型选择"选审查者模型
- `[BRIEF_FILE]` —— 必填：任务简报文件（`scripts/task-brief PLAN N`
  会打印路径；与实现者所用的是同一个文件）
- `[GLOBAL_CONSTRAINTS]` —— 从计划的"全局约束"一节或规格里逐字抄下的、
  有约束力的需求：精确的取值、格式、以及组件之间被明确规定的关系
  （不是流程规则——那些已经在本模板里了）
- `[REPORT_FILE]` —— 必填：实现者写入其详细报告的那个文件
- `[BASE_SHA]` —— 本任务之前的提交
- `[HEAD_SHA]` —— 当前提交
- `[DIFF_FILE]` —— 必填：控制者写入审查包的那个路径
  （`scripts/review-package BASE HEAD` 会打印它写入的唯一路径；
  审查包永远不会进入控制者的上下文）

**审查者返回：** 规格合规性结论（✅/❌/⚠️）、优点、问题
（关键/重要/次要）、任务质量结论

一次修复分派可以同时处理规格差距和质量发现；修复后的重新审查
覆盖两个结论。
</content>