plan-feature

规划一项功能

有两种失败模式：擅自猜测应由用户决定的事项，以及按层拆分工作，导致直到最后阶段才有任何可见成果。先敲定决策，再切分垂直切片。完成阶段 1 后再进入阶段 2；围绕尚未敲定的决策制定的任务清单最终会被推翻。

计划存放在 plans/<feature-slug>.md，除非仓库将设计文档放在其他位置，或用户指定了目录。如果此功能已有计划，就接着完善。

阶段 1 — 敲定所有决策

先询问意图。 询问这项请求背后的最终目标或触发因素。提供你认为最可能的选项。绝不要根据请求推断 Why；看似合理的猜测仍然只是猜测。如果目标表明有更小或不同的修复方案，只说明一次，然后照此执行。

接着询问访谈深度。 将其记录为第一个 Decision。它决定两个阶段中的所有提问，但意图、界定范围的缺口和部署相关问题始终要询问。

• 仅询问关键决策（推荐）：询问难以撤销的事项；其余事项敲定为 agent。
• 全部询问： 询问每项决策，包括成本低的事项；不做任何 agent 选择。
• 由 Agent 决定： 其余事项全部敲定为 agent，并在阶段 2 前展示清单。

先阅读代码。 了解会涉及哪些文件、现有模式以及正在使用的库。只提供代码库能够支持的选项。

界定功能。 按照下方格式写出四条界定说明，其中 The Why 应来自对意图的回答。如果有任何一条写不出来，先询问相关问题。

从代码中查明答案。 库的支持情况、现有架构以及类似功能的实现方式都属于调研，而不是决策。标记为 research。不要询问你可以直接查阅的内容。

询问重要事项。 仅在只询问关键决策的模式下，询问难以撤销的事项，通常包括范围、数据模型、公共 API 或用户看到的内容；其余容易撤销的决定由你自行敲定。根据 Why 排定问题优先级：询问与之相关的事项，不相关的由你敲定。你做出的每项选择都标记为 agent。使用 AskUserQuestion，提供具体选项，将你的建议放在首位，并说明每个选项的实际取舍。每次最多合并询问四个彼此独立的问题；只有依赖某个答案的问题，才在收到该答案后继续追问。询问决策（“重试应由哪一层负责？”），不要询问工作事项（“添加重试处理程序”）。

只规划会形成约束的技术细节。 保留评审者必须确保的不变量、安全规则、代码之外的约定（webhook URL、发布时切换的标记），以及难以撤销的选择；用属性表述（例如“每种货币的价格都以最小货币单位表示”），不要列出字段。将架构字段、端点路径、枚举值、环境变量名和测试用例留给实现者和评审者；在代码尚未成形前锁定猜测，会把他们束缚在这些猜测上。

敲定演示方式。 整个功能只安排一个演示，在每个阶段合并后运行。询问用户是否需要演示，以及演示形式：用户自行执行的步骤、由你进行的演示，还是端到端检查。除非某个阶段推迟了 Verify，否则 none 也是有效选项。

边进行边写入文件。 答案一收到就记录，并将未回答的问题标记为 _open_，以便会话中断后继续。每个答案都可能引出新问题；继续询问，直到没有未解决的问题。

有异议时说明一次，然后照办。 如果你不同意此技能中的任何选择，用两行说明原因，然后记录用户的决定。

只有在没有未解决的问题、没有含糊其词的回答，并且用户已看到每项 agent 选择后，才能进入阶段 2。

阶段 2 — 将工作拆分为多个阶段

纵向切分。 按层划分阶段（Backend、Frontend、Database、Tests、Setup），会让用户直到最后才能看到成果，并把集成问题留到最后处理。

Bad — layer slices, nothing usable until the end
  Phase 1  Backend    [db][api]............  user sees nothing
  Phase 2  Frontend   ...........[ui][wire]  everything lands at once

Good — feature slices, each one usable
  Phase 1  Log in            [db][api][ui]   user has an account
  Phase 2  Generate an image [db][api][ui]   user makes an image
  Phase 3  Animate it        [db][api][ui]   user makes a clip

根据用户能获得什么来命名阶段。 用“登录并看到一个空资料库”，而不是“身份验证层”。

为每个阶段提供一行验证说明，没有该阶段的代码就无法通过验证：命令、URL、点击路径或测试都可以。“检查通过”不算。说明具体步骤和可观察到的结果；只有在没有可见结果时，才写明查询或标志。如果你写不出验证说明，这就不是一个阶段。

注意耗时较长的验证步骤。 构建者会在每次评审修复后重新运行快速检查，但耗时较长的检查（E2E、Playwright、会启动服务或等待的集成测试）只会在 PR 前和合并前运行。只要测试能证明结果，就让验证说明中的证明方式保持快速；跨仓库运行留给 ## Demo。

**在本地验证，**使用开发服务器、测试数据库或临时账号。构建者必须能一气呵成地运行每一条验证说明。如果没有本地验证方式，就添加测试固件，而不是针对生产环境。

• 需要已部署 URL、共享数据库或生产凭据的步骤属于发布步骤。将其列在计划末尾，供用户在合并后执行。
• 需要用户自己的设备或个人账号的步骤，放在 ## Demo 中。
• 除非用户明确同意，否则不要为验证说明或 Demo 安排部署。

仅当阶段没有本地验证界面时才延后验证： **Verify:** deferred — <why>，并且 Demo 必须覆盖该项。绝不要延后尚未认真考虑的工作。连续延后两次，说明切分不合理。

**每个阶段的工作量应适合一个构建会话：**在同一上下文中完成编写、验证和评审修复。先做最小的可见成果，每个阶段都应建立在已有可运行成果之上。优先拆成 3-6 个阶段；如果功能适合在一个会话中完成，一个阶段也可以。先切分工作，再询问用户想要几个阶段，先给出你的阶段数，并说明每种选项会合并或拆分哪些内容。绝不要只为凑数而拆分。

**为每个阶段提供一行依赖项：**先合并的阶段，或 none。如果某个阶段需要其他阶段的代码、会修改相同文件，或用户选择了顺序执行，该阶段就有依赖。决定哪些工作可以并行执行的是依赖关系图，而不是计划顺序。如果两个阶段互不依赖且不共享文件，询问是否将它们作为 2a/2b 并行执行。

将任务写成未勾选的祈使句，每项可一次完成，并注明文件： - [ ] Add source_generation_id to generations (internal/db/migrations)。说明做什么，而不是怎么做：Retry failed uploads，而不是 Loop with exponential backoff, max 3。如果用户要求特定做法，将其记录为 Decision。构建者负责勾选任务。

已确定的决策必须保持不变。 如果构建结果证明某项决策有误，请明确修改 Decisions，并注明受影响的阶段。绝不要悄悄绕开用户的选择重新规划。

在末尾列出阶段 2 选择的 agent，让用户可以推翻任意选择。

计划文件格式

# <Feature>
**The Job** — <what gets built>
**The Why** — <end goal behind the ask, from the user: who needs it, what breaks or stalls without it>
**The Guardrail** — <what must not change — omit if none>
**Done means** — <observable outcome that closes the feature>

## Decisions
- **Interview depth** — <key decisions only | ask everything | agent decides>
- **<question>** — <answer, one or two lines>
- **<question>** — <answer> `agent`
- **<question>** — <answer> `research`
- **<question>** — _open_   <-- only while stage 1 is running

## Progress
Active: 1 · 0/11 tasks

### Phase 1 — <what the user gains>
<one line: what they can do now that they could not before>
**Blocked by:** <phase numbers, or `none`>
- [ ] <task>
- [ ] <task>
**Verify:** <command, URL, click path, or test — or `deferred — <why>`>

## Demo
<how the finished feature gets shown once every phase has merged — or `none`>

添加功能所需的章节，例如约束、合并后的发布步骤或已排除的方案。除此之外，不要添加其他内容。