planning

按垂直切片进行规划

尽可能按垂直切片规划。 每个切片都交付真实参与者可观察到的最小端到端行为，同时让代码库保持在已知良好的状态，确保所有测试都通过。

只有在某项横向工作能够明确解除下一个垂直切片的阻碍，且可独立验证；或该工作属于一个明确选定的精简计划，其最终状态会在保持行为不变的前提下淘汰一个完整机制时，才允许开展横向工作。

在有相应功能的 Claude Code 环境中，使用 /plan 制定计划，并在独立 PR 合并后或推进并同步当前活动堆栈时使用 /continue。否则，直接创建或更新计划文档，并通过当前使用的工具链或代码库工作流继续推进。

与 story-splitting 的关系

story-splitting 决定有哪些能够创造用户价值的小型故事。planning 决定如何安全地实现选定的故事。

如果请求仍是一个史诗级需求、大型故事、功能构想、路线图事项，或有多种可能客户成果的待办事项，请先使用 story-splitting，再使用此技能。选定子故事或范围明确的能力后，使用此技能创建或更新仓库的规划文档，为每个切片制定实现分步方案、验收标准、验证路径和交付形式。

区分以下三个单位：

单位	含义	默认关系
待办故事	来自 story-splitting 的固定产品能力和验收范围	计划可以推进一个选定故事
实现切片	最小的垂直增量，或明确的缩减过渡／终止状态；声明的前置条件就绪后，即可安全合并和发布	默认对应一个 PR
PR 边界	覆盖整个切片的审查单元；特殊情况下，也可以是单个切片内的依赖层	可以独立存在，也可以纳入有意构建的堆栈

序列表示工作顺序；堆栈表示分支拓扑。默认让每个切片使用基于主干的 PR。如果多个切片可以按任意顺序合并且不会阻塞或重复工作，或者后续分支仅在前序分支合并后才开始，则保持切片 PR 相互独立。如果某个切片需要分层审查，或者后续切片应在早期 PR 尚未合并时基于同一持续演进的基线开始，则加载 stack-pull-requests。存在硬依赖即可构成理由，但并非必要；有意保持流程沿袭也可能适合采用堆栈。仅仅是推测可能需要回退，则不足以构成理由。

如果计划开始产生仅涉及数据库、仅涉及 API、仅涉及 UI 或“先完成所有基础设施工作”的切片，请暂停并返回 story-splitting；例外情况是，这些横向工作明确地通过独立验证解锁下一个垂直切片，或推动一个明确选定的缩减计划，直至达到其指定的机制移除终止状态。

如果已安装 grill-me，在规划前，当选定故事仍包含未解决的产品或设计决策时，请使用它。否则，每次只问一个重点问题，并给出推荐答案及其权衡。如果缺少或无法验证验收标准、故障模式、角色、状态或发布限制，请在起草计划前或之后使用 find-gaps。

在确定引入重要通用机制或持久性新依赖的切片前，请按适当程度执行 evaluate-existing-solutions 的预检、尽职调查或完整比较。如果某项选择此前尚未解决，请链接由决策负责人认可的结果。规划负责排列所选解决方案的实施顺序；它不会悄然将第一个看似可行的库或定制草图变成计划。

输入状态	使用工具	输出
模糊的决策树	已安装时使用 grill-me；否则每次只问一个问题进行访谈	已解决的决策或明确列出的待解决问题
有多种成果的宽泛需求	story-splitting	子故事
存在缺漏的现有故事／计划／AC／模拟稿	find-gaps	已确认的文档更新
已准备好安排交付顺序的选定子故事	planning	带有交付形式的实现切片
某个切片可能需要分层审查，或后续切片可能在较低层 PR 合并前开始	stack-pull-requests + planning	独立 PR，或明确采用硬依赖／流程沿袭的堆栈

计划目录

使用仓库声明的规划工作流和存放位置。仓库可以将计划纳入文档、议题或其他指定系统。如果没有指定的存放位置，且适合使用文件来管理计划，则在项目根目录下使用 plans/，并为文件取一个描述性名称（例如： plans/gift-tracking.md）。

通过该工作流查找有效计划。对于备用目录布局，使用 ls plans/。

可以同时存在多个计划——每个计划相互独立，文件名各不相同，因此不会在不同分支或工作树之间冲突。

**计划完成后：**遵循仓库的生命周期规则。对于备用目录布局，删除计划文件；如果 plans/ 目录为空，也删除该目录。

优先选择小而易于审查的 PR

默认选择规模最小、确认可行的垂直切片，每个切片使用一个基于主干的 PR。当上层切片存在硬依赖或有意设计的流程继承关系、会在下层切片合并前进入开发，且审查、交付周期或修正分流方面的收益足以抵消级联成本时，使用跨切片堆叠。当一个固定切片仍需要聚焦的依赖审查层时，使用切片内堆叠。

**为什么这很重要：**小型 PR 更易审查、更易回退，也更易理解。出现问题时，原因一目了然。PR 处于审查阶段时，不会阻塞无关工作。目标是始终尽可能贴近 main。

**PR 过大时：**审查者需要同时记住多个互不相关的概念才能理解它，或者你很难用 1-3 句话清楚概括它的作用。

也会有例外。请自行判断：先明确划分合理的垂直切片，再决定让它们保持独立、采用跨切片的硬依赖／流程堆叠，还是让某个切片采用切片内审查层。

垂直切片的构成

垂直切片并非“因为只涉及一个层而规模小”。它之所以小，是因为它通过真实的生产路径交付了一项可观察的行为。

每个切片都必须注明：

• 参与者：谁获得了价值（用户、管理员、API 客户端、定时任务、支持人员）
• 触发条件：是什么启动了该行为（点击、请求、事件、命令、计时器）
• 可观察结果：什么能够证明该行为已发生
• 生产路径：涉及的真实界面、用例、领域逻辑、持久化及外部适配器
• 最小可部署价值：能够安全发布的最精简且有用的版本

好的切片通常精简但完整：

• 一个表单通过真实 API 提交一个有效字段并将其持久化
• 一个后台任务处理一种事件类型并生成预期的审计结果
• 一个 CLI 命令支持一种输入形式，并返回稳定的 stdout/stderr
• 一个只读界面使用生产数据加载逻辑展示一种真实状态

如何选择切片

在编写计划切片前：

1. 明确结果——用一句话描述用户或系统可见的结果。
2. 梳理路径——列出真实入口、业务流程、状态变更、输出和可观测性。
3. 选定行走骨架——选择最精简的端到端版本，以证明该路径可行。
4. 每次只添加一种行为或状态——验证、权限、错误状态、空状态、重试、分析和润色都留到后续切片。
5. 检查可逆性——每个切片都应易于回退或禁用，且无需撤销无关工作。

先问“我们能发布的最小真实行为是什么？”，再问“需要修改哪些文件？” 如果答案仍包含多个客户结果、角色、工作流分支或质量级别，请加载 story-splitting，并在编写计划前拆分父项。

横向工作的例外情况

避免先把所有数据库、API、UI 或基础设施工作都做完。只有在所有适用条件均满足时，横向工作才能单独作为一个切片：

• 明确指出其解锁的下一个纵向切片，或属于已明确选定、以最终移除机制为结果的精简计划
• 完成后代码库仍可部署
• 有可观察的验证方式（测试、命令输出、迁移试运行或运行时检查）
• 工作量小于在纵向切片中完成该工作的成本
• 不会引入未使用的抽象或推测性的灵活性

有效的横向工作例外包括依赖项升级、迁移、测试工具框架搭建、基础设施接线、机械式重构、安全修复，以及已选定的 reduce-system-complexity 计划；该计划的最终状态须在保持行为不变的同时，退役一个完整机制。此类工作应少而明确。过渡性的精简步骤可以暂时添加桥接机制，前提是它可独立验证，且同一计划明确列出最终切片以及行为／机制门槛；为任何桥接机制记录负责人、移除条件和有限期限；若没有，则记录 N/A。

优质切片的标准

每个切片都必须：

• 确保所有测试通过
• 可独立部署
• 有明确的完成标准
• 默认可在单个 PR 中完成，否则须有获批的 stack-pull-requests 交付映射
• 能用一句话描述
• 交付可观察的行为，或直接解锁该行为；也可以安全推进已明确选定的精简计划，朝其最终行为／机制门槛迈进

切片是规划和交付已知良好价值的基本单位。默认情况下，它也是针对主干分支的一个评审 PR。在跨切片堆栈中，每个 PR 可负责一个完整切片，该切片在 PR 自底向上合并后完成。在切片内堆栈中，依赖 PR 层是聚焦的评审边界；切片在最上层 PR 合并后完成。在每个会改变行为的 PR 边界内，快速的 RED-GREEN-REFACTOR 增量可以产生多个提交；变异测试或替代证据仅在该边界已满足 PR 就绪条件时运行一次，而不是每次增量后都运行。

如果无法用一句话描述一个切片，就进一步拆分。

切片大小启发式

过大，如果：

• 需要超过一个工作时段
• 描述中有多个“并且”
• 不确定如何测试
• 需要许多无关的测试夹具、模拟对象、屏幕或端点
• 只构建一层，却无法证明结果

大小合适，如果：

• 只有一个明确的行为
• 有一个主要测试用例和聚焦的边界情况
• 能快速向别人解释清楚
• 完成状态一目了然
• 只涉及实现该行为所需的路径
• 即使后续切片都没有开展，也能留下有用的检查点

TDD 集成

**每个会改变行为的切片都采用快速的 RED-GREEN-REFACTOR 增量；当切片已具备 PR 条件时，在阶段结束时进行一次变异测试或替代证据审查。**开始实现前，加载 tdd、testing 和适用的 refactoring 指南。使用 mutation-testing 变异规则指导低成本测试设计，但将自动化测试框架的执行推迟到 PR 就绪时。真正保持行为不变的重构或 reduce-system-complexity 切片，应从通过且适度的保留性证据开始，并使用相同的阶段结束关卡。切勿伪造失败的机制计数测试或结构变异体。本节是路由约定，不能替代这些技能。

无论使用何种技术栈，每个 PR 都要以其父级审查边界为准，遵循这一节奏。在首次负责该行为的 PR 中加入测试；每个边界达到 PR 就绪状态时，运行一次变异测试或替代证据关卡；并要求最顶层证明每个纳入切片的累积验收标准或精简关卡均已满足。不要将测试或证据推迟到后续层级。

FOR EACH BEHAVIOR-CHANGING SLICE OR PR BOUNDARY:
    │
    ├─► LOAD: Required implementation skills
    │   - `tdd` for RED-GREEN-REFACTOR
    │   - `testing` for behavior-driven tests and factories
    │   - `refactoring` when restructuring is applicable; otherwise `N/A`
    │
    ├─► CONFIRM: Present acceptance criteria for this slice
    │   - Human must approve criteria before any code is written
    │   - Criteria must be specific and observable
    │   - Do NOT proceed until human confirms
    │
    ├─► RED: Write failing test FIRST
    │   - Test describes expected behavior
    │   - Test fails for the right reason
    │   - Run only the exact test/test name needed to prove RED
    │   - Test plan accounts for likely mutants from the `mutation-testing` skill's `resources/mutator-rules.md` resource
    │
    ├─► GREEN: Write MINIMUM code to pass
    │   - No extra features
    │   - No premature optimization
    │   - Just make the test pass
    │   - Follow the `tdd` skill's canonical watcher selection, lifecycle, cleanup, and live-proof policy
    │   - Prefer a proven repository-owned watcher; use diff-selected Vitest watch only under the canonical version/configuration proof
    │   - Use the affected one-shot when watch is unreliable; do not hand-pick GREEN test files
    │   - Keep watcher discovery live for new tests, or rerun the affected one-shot after creation; reject zero-test/`--passWithNoTests` results
    │   - In monorepos, run through the root project/task graph so shared-package consumers remain eligible
    │
    ├─► REFACTOR: Assess improvements
    │   - See `refactoring` skill
    │   - Only if it adds value
    │   - Focused and affected tests stay green; do not rerun the full suite after every edit
    │
    ├─► REPEAT: Continue RED-GREEN-REFACTOR as needed
    │   - Do not run the automated mutation harness after each increment, refactor, or commit
    │
    └─► STOP: Present the work and wait for commit approval
         - Show what was implemented and the ordinary verification
         - Human reviews and approves before commit

WHEN THE CURRENT REVIEW BOUNDARY IS OTHERWISE READY FOR ITS PR:
    ├─► LOAD: `mutation-testing`
    ├─► MUTATE OR ALTERNATE EVIDENCE: Run once for the focused boundary scope, or record explicit `N/A` plus proportionate alternate evidence
    ├─► KILL MUTANTS: Address valuable survivors and re-run focused/diff mutations within the same gate
    └─► COMPLETE: Finish the remaining PR checks and present the final report

纯重构采用以下步骤：确认保留的使用方契约 → 运行适用且通过的基线测试 → 在保持绿色的同时调整结构 → 验证保留的表面 → PR 就绪时，对累积范围运行一次变异测试，或审查适度的替代证据。

精简迁移采用以下步骤：链接精简计划/台账和终端切片 → 确认保持不变的契约 → 运行适用的基线测试 → 执行可独立验证的迁移 → 通过行为关卡 → 记录任何桥接的归属/移除/有限期限（没有则填 N/A）→ 保持 mechanism gate: pending — no net-reduction claim → PR 就绪时，运行一次变异测试/替代证据关卡。

终端精简采用以下步骤：链接计划/台账（或经授权的单切片 N/A）→ 运行适用的基线测试 → 移除已被取代的机制和已过期的桥接 → 完成迁移义务 → 通过行为关卡和机制关卡 → PR 就绪时，运行一次变异测试/替代证据关卡。

不得引入未经测试的行为变更。不得说“我之后再补测试”。

提交纪律

未经用户批准，绝不提交。

完成一个实现增量后：

1. 验证适用测试均通过，和/或已批准的保留性证据仍然成立

2. 验证静态分析通过

3. 提供与类别对应的证据：行为变更须提供 RED/GREEN 证据；纯重构须证明契约得到保留；迁移须提供通过的行为关卡、独立验证，以及待完成的机制关卡/不主张净精简；终端精简须提供已链接的计划/台账、已完成的义务、两个均通过的关卡，以及已退役的机制

4. 不要要求每次提交都提供变异测试报告。当前 PR 边界已具备就绪条件时，运行一次阶段结束的变异测试关卡，并提供最终报告（或经审查的替代证据记录及 N/A 理由）。

5. 停止并询问：“准备提交 [描述]。是否批准？”

只有在获得明确批准后，才能继续提交。

为什么要等待批准？

• 用户可以掌控 Git 历史
• 用户有机会在提交前审查
• 防止意外提交未完成的工作
• 为讨论创造自然的检查点

计划文件结构

每个基于文件的计划都遵循以下结构：

# Plan: [Feature Name]

**Branch**: feat/feature-name
**Status**: Active

## Goal

[One sentence describing the outcome]

## Acceptance Criteria

[For a behavior-change delivery plan, use behavior-driven criteria that describe observable business outcomes, not implementation details. Test at the lowest level that gives confidence: prefer unit tests for logic/domain behavior, browser tests for UI interaction, and end-to-end tests only for end-to-end flows.

For a reduction program, define the conserved observable contract, terminal same-scope mechanism delta, retirement of superseded machinery and expired bridges, passing behavior/mechanism gates, and mutation results or explicit mutation `N/A` with proportionate alternate evidence. Do not invent new product behavior or tests for mechanism shape.]

- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

## Slices

Classify every slice as **behavior change**, **pure refactor**, **reduction transition**, or **terminal reduction**. Behavior-changing slices use RED-GREEN-REFACTOR increments and all classes use one end-of-phase mutation or alternate-evidence gate at PR readiness. Pure refactors start from passing preservation evidence. Every reduction transition and terminal reduction loads `reduce-system-complexity` and references the plan-level reduction program. A transition may add a bounded bridge but never claims net reduction: its mechanism gate remains explicitly pending until the terminal slice removes the old mechanism and expired bridges. Only the terminal reduction may claim net removal after both behavior and mechanism gates pass.
Read the repository's governing instructions and testing rules before writing slices.

## Reduction Program (include only when applicable)

**Ledger/report**: [Link to the `reduce-system-complexity` diagnosis and conservation ledger.]
**Conserved contract**: [Behavior and guarantees that every transition and the terminal state preserve.]
**Superseded mechanism**: [The complete mechanism the terminal slice will retire.]
**Terminal slice**: [Slice name/number that removes the old mechanism and expired bridges.]
**Owner and removal condition**: [For each temporary bridge: accountable owner, objective removal condition, and latest acceptable removal point; otherwise `N/A — no temporary bridge`.]
**Behavior gate**: [Required evidence and fidelity.]
**Mechanism gate**: [Like-for-like whole-mechanism accounting required at the terminal slice.]

### Slice 1: [One sentence observable behaviour]

**Value**: [Behavior change: actor and observable outcome. Pure refactor: preserved consumer surface and maintenance value. Reduction transition: why this independently verifiable increment is necessary to reach the terminal state. Terminal reduction: conserved contract plus the ownership/mechanism retired.]
**Path**: [Behavior change: entry point -> business path -> state/output -> observability. Pure refactor: preserved public surface. Either reduction class: affected trigger-to-outcome path, program/terminal link, and mechanism scope.]
**Class**: Behavior change / pure refactor / reduction transition / terminal reduction.
**Delivery**: [Independent PR against trunk (default); cross-slice stack member referencing the shared `#### Delivery Shape`; or an intra-slice `#### Delivery Shape` map.]
**Required implementation skills**: For changed behavior, load `tdd`, `testing`, and applicable refactoring guidance. For a pure refactor, load only applicable testing and refactoring skills. Every reduction transition and terminal reduction loads `reduce-system-complexity` plus applicable evidence skills. At each PR boundary's readiness, load `mutation-testing` for the focused scope where meaningful or record the alternate-evidence `N/A`. Add UI/domain/architecture skills only when relevant.
**Reduction program**: [For either reduction class: reference the plan-level program and terminal slice; otherwise `N/A`.]
**Transition/terminal evidence**: [Transition: `behavior gate: pass`, independent verification, bridge owner/removal/bounded-lifetime metadata when a bridge exists (`N/A` otherwise), and `mechanism gate: pending — no net-reduction claim`. Terminal: passing behavior gate, like-for-like mechanism gate, and removal of the superseded mechanism/expired bridges. Otherwise `N/A`.]
**Acceptance criteria**: [Behavior change: specific observable outcome. Pure refactor: conserved surface plus preservation evidence. Transition: passing behavior gate, independent verification, optional bridge metadata or `N/A`, and pending mechanism gate/no net claim. Terminal: both gates pass and superseded machinery/expired bridges are gone. **Present to the human and get confirmation before writing any code.**]
**RED or preservation baseline**: For behavior change, what failing behavior test will we write? For a pure refactor/reduction, which passing oracles and proportionate non-test evidence conserve the affected behavior and guarantees? Never assert implementation shape merely to create RED.
**GREEN or preservation change**: What minimum code makes the new behavior pass, or what smallest mechanism-only change preserves the baseline?
**REFACTOR**: Assess improvements (only if they add value).
**PRE-PR MUTATION or alternate evidence**: Once the current review boundary is otherwise PR-ready, run mutation testing once for its accumulated scope. Address valuable survivors and re-run focused/diff checks inside the same gate. Otherwise mark `N/A` and name reachability, configuration, contract, integration, or operational evidence; never invent structural mutants.
**PR-ready when**: All acceptance criteria owned by the current boundary and its end-of-phase mutation/alternate-evidence obligations are met. A transition's behavior gate and independent checks pass while its mechanism gate remains truthfully pending with no net claim; a terminal reduction passes both gates and removes old machinery/expired bridges. The human approves the commit.
**Slice complete when**: Its independent or cross-slice owning PR lands, or the top PR lands for an intra-slice stack.

### Slice 2: [One sentence observable behaviour]

Use the same adaptive fields as Slice 1. Classify the slice independently; do not inherit a behavior-change workflow when this slice only preserves behavior or removes mechanism.

## Pre-PR Quality Gate

Before each PR:
1. Implementation complete — confirm applicable refactoring/reduction assessment and ordinary verification are complete
2. Mutation or alternate evidence — run `mutation-testing` once for the accumulated PR scope where meaningful; address valuable survivors within the same gate, or review the explicit `N/A` rationale and proportionate evidence
3. Typecheck and lint pass
4. DDD glossary check — if the project uses DDD, verify all domain terms match the canonical glossary
5. Complete tests — stop watchers and run the repository-defined complete non-watch PR test gate; in a monorepo include every configured project and required integration/E2E suite, not only the affected development subset
6. Evidence freshness — apply the target repository's mutation-evidence rule after later fixes. Use this distribution's model (the `panel-review` skill's `references/pr-readiness.md`) only when the repository has no stricter invalidation policy, and keep project verification current after resulting fixes

For an intra-slice stack, nest the exact `#### Delivery Shape` and whole-stack gate under that slice. For a cross-slice stack, place one shared map before the first included slice and reference it from each included slice. Never stack an entire plan by default.

---
*Complete this plan using the repository's declared lifecycle. For the
fallback `plans/` layout, delete this file and remove the directory when
empty.*

计划变更须经批准

如果计划需要变更：

1. 说明变更内容及原因
2. 提出更新后的切片
3. 等待批准后再继续

计划并非不可更改，但任何变更都必须明确提出并获得批准。

功能结束

当每个切片所属的 PR 都已合并（或每个切片内堆栈的顶部 PR 已合并）时：

1. 验证完成情况 — 所有所属 PR 均已合并；所有验收标准均已满足；适用的测试和变异／替代证据均已通过；任何缩减计划均已到达终端切片，且两道门槛均已通过，旧机制／过期桥接均已移除
2. 整合经验 — 如果获得了重要见解，且已安装 Claude Code 的 learn 或 adr Agent，请使用它们；否则，使用 expectations 技能获取项目指导，并使用仓库既定的 ADR 机制记录架构决策
3. 关闭计划 — 遵循仓库声明的生命周期；对于备用的 plans/ 布局，删除文件，并在目录为空时移除该目录

反模式

❌ 未经批准就提交

• 始终等待明确的“同意”后再提交

❌ 层层堆叠的计划

• “先构建数据库，再构建 API，最后构建 UI”会延迟获取经验，并掩盖集成故障

❌ 没有明确切片的基础工作

• 如果需要进行准备工作，请明确其解锁的纵向切片，以及如何验证这项准备工作

❌ 默认只做数据库、API 或 UI 的切片

• 这类工作通常是实现任务，并非可独立交付价值的行为

❌ 先完成所有基础设施工作

• 优先构建能够验证真实路径的行走骨架，然后逐个行为扩展

❌ 跨多个 PR 且未作交付决策的切片

• 默认每个切片对应一个基于主干开发的 PR。如果跨切片流程／硬堆栈或切片内评审层确实有助益，请加载 stack-pull-requests，说明具体拓扑结构的理由，并保留每个切片的范围和终端义务。

❌ 先编写变更行为，再编写测试

• 行为变更必须先经过 RED 阶段；真正的 REFACTOR 切片则记录已通过的保持性证据

❌ 计划悄然变更

• 所有计划变更都必须经过讨论和批准

❌ 功能完成后仍保留计划文件

• 遵循仓库的文档生命周期：完成后删除临时计划，但将长期有效的决策或指导提升到负责维护它们的文档中

快速参考

START FEATURE
│
├─► Create or update the repository-owned plan (get approval)
│
│   FOR EACH IMPLEMENTATION SLICE:
│   │
│   ├─► DELIVERY: Independent trunk-based PR by default; otherwise reference an approved intra- or cross-slice stack map
│   ├─► BEHAVIOR CHANGE: LOAD → CONFIRM → RED → GREEN → REFACTOR → REPEAT WITHOUT MUTATION HARNESS
│   ├─► OR PURE REFACTOR/REDUCTION: PASSING BASELINE → REFACTOR/REDUCE → VERIFY GATES
│   ├─► **PRESENT WORK, WAIT FOR COMMIT APPROVAL**
│   ├─► PRE-PR: Run mutation once for each current review boundary (or alternate evidence), handle survivors within the gate
│   └─► Verify focused and top-level criteria; create one PR or the planned stack
│
END FEATURE
│
├─► Verify all owning PRs landed and all criteria met
├─► Merge learnings if significant (installed learn/ADR workflow, or `expectations` plus the repository's ADR mechanism)
└─► Close the plan using the repository's declared lifecycle