write-plan

编写计划

输出语言： 使用用户自己的语言回答并编写产物（匹配用户的消息，而不是仓库的历史记录）。

概述

将已批准的设计转化为实施计划，让容易遗忘的 Agent 能够执行，而不自行扩展范围。

核心原则：每项任务都可独立测试；每个步骤耗时 2–5 分钟；默认采用 TDD 微循环。

**必需的上游步骤：**write-spec（或经 grill 批准的书面／口头设计）。对于非平凡边界，使用 solid。产品决策尚未敲定时，不要制定计划。

宣布：“正在使用 write-plan 来……”

适用场景

• write-spec（或获准的口头设计）通过后、开始编码前
• 涉及多个文件或多个步骤的功能
• 用户要求制定实施计划／任务拆解

**不适用场景：**产品范围尚未敲定 → 先使用 grill／write-spec；显而易见且只需一个测试循环的单行修复（直接进入 tdd）；纯探索任务。

铁律

NO CODING FROM A VAGUE PLAN.
Every task lists exact files, a failing-test step, a verify-red step, minimal impl, verify-green, and a commit step (or explicit why commit is deferred).

工作流

1. 范围检查——是否涉及多个独立子系统？拆分为多个计划（每个计划包含一个可交付的切片）。
2. 文件映射——确定路径前，先获取结构指引：通过 solid 明确边界（端口／适配器／依赖箭头）。如果该切片没有新增边界，请说明并继续。文件映射需记录结果。
3. 任务拆解——拆分为小块；将脚手架工作并入需要它的任务。编写每项任务的 RED 步骤前，先获取验证指引：通过 test-design 列出用例——每个用例都用用户／产品语言描述（目标／条件／参数），让非作者也能看懂验证了什么以及为什么验证。这些用例就是任务的 RED 测试。
4. 编写计划文件——默认路径为 docs/creed/plans/YYYY-MM-DD-<feature>.md（用户指定的路径优先）。
5. 自我审查——不留 TBD；任务须包含接口和验证命令；遵循 YAGNI。
6. 用户确认——请用户快速审阅计划，再开始执行。
7. 交接——使用 tdd + test-design 执行（可选使用 Superpowers subagent-driven-development／executing-plans）。

这两个指引是建议经过的步骤，不是强制关卡：没有新增边界时可以跳过 solid；test-design 是用例的来源。在这里提及它们，是为了避免悄然跳过——或过度应用。

计划头部（必需）

# <Feature> Implementation Plan

> **For agents:** Use Creed **tdd** + **test-design** per task. Optional: Superpowers subagent-driven-development / executing-plans.

**Goal:** <one sentence>

**Architecture:** <2–3 sentences — the boundaries settled with **solid**; if no new boundary, say "no new boundary">

**Tech Stack:** <key libs>

**Cases (from test-design):** <the "when …, it should …" list, each with goal / conditions / parameters in reader-facing words>

## Global Constraints

- <verbatim constraints from spec: versions, naming, platforms, …>

---

任务模板

### Task N: <Name>

**Files:**
- Create: `path/to/file.ts`
- Modify: `path/to/existing.ts`
- Test: `path/to/file.test.ts`

**Interfaces:**
- Consumes: <signatures from earlier tasks>
- Produces: <names/types later tasks rely on>

- [ ] **Step 1: Write the failing test** (apply **test-design**)
- [ ] **Step 2: Run it — expect FAIL for the right reason**
- [ ] **Step 3: Minimal implementation** (**tdd** GREEN; **solid** boundaries)
- [ ] **Step 4: Run tests — expect PASS**
- [ ] **Step 5: Commit** (or defer with reason; ship later via **commit-and-push**)

在关键测试／实现片段有助于阐明 API 时，将其内联；不要长篇大论。

粒度

好的任务	不好的任务
一个行为及其测试循环	“实现身份验证”
明确的路径	“更新服务器相关内容”
可独立审查	必须完成任务 5 才知道任务 2 是否有效

理由对照表

借口	事实
“编码时再确定路径”	这会导致范围不断扩大。请在计划中锁定文件。
“一个大任务就够了”	审查者无法否决其中一半内容。请拆分。
“跳过测试步骤——之后再做 TDD”	“之后”就等于永远不做。步骤必须包含 RED／GREEN。
“计划就是设计文档”	规范（write-spec）说明做什么／为什么；计划说明谁在何时改动哪个文件。
“在计划中确定产品范围”	产品决策尚未敲定 → 返回 grill，然后使用 write-spec。
“Solid 只是形式，可以跳过”	那就说明“没有新增边界”，然后继续——问题不在于跳过，而在于没有说明就跳过。
“test-design 是之后在 tdd 中做的”	用例决定了任务的 RED 步骤。在计划中确定用例，才能让每项任务都可独立测试。

检查清单

• 规范已获批准（write-spec），或口头设计已获批准并豁免
• 已获取结构指引（solid）——或明确说明“没有新增边界”
• 已获取验证指引（test-design）——用例以用户／产品语言描述（目标／条件／参数）
• 已编写包含头部和任务的计划文件
• 每项任务均包含：文件、接口、RED→GREEN→提交
• 计划不会重新开启产品决策
• 用户已审阅计划（或明确豁免）
• 已准备好通过 tdd 执行

交接

阶段转换门槛——在将计划交给执行或进入下一阶段之前，询问用户（使用一个 AskUserQuestion；绝不自动推进）：

A) Recommended: Proceed → tdd (+ test-design)
B) Review first — run **review** on this plan (`references/plan.md`; upstream = the spec it narrows), then return to this gate
C) Adjust — revise the plan, then return to this gate
D) Something else (I will type it)

• 产品仍不明确 → grill / write-spec
• 执行 → tdd + test-design
• 卡在结构上 → solid
• 发布完成 → review，然后 commit-and-push