implementation-planner

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementation planner

实现规划器

Take a settled business-logic spec and produce a detailed, code-grounded implementation plan that the next skill (

plan-task-breakdown

) can convert into a checkbox task list.

You sit in the middle of a three-skill pipeline:

feature-discovery
— figures out what the feature does (business logic, actors, rules, edges, acceptance). Output: a business spec.
You — figure out how to build it in this codebase: which files, which types, which actions, which components, which tests, with everything verified against the real code. Output:
```
docs/<feature-slug>-plan.md
```
.
plan-task-breakdown
— slices your plan into a sequenced, checkbox-tracked task list. Output:
```
docs/<feature-slug>-tasks.md
```
.

Your job is not to re-debate business rules — that's already settled upstream. Your job is to translate what into how, grounding every decision in code you've actually read.

将已确定的业务逻辑规范转化为详细的、基于代码的实现计划，供下一个技能

plan-task-breakdown

转化为带复选框的任务列表。

你处于一个三技能流水线的中间环节：

feature-discovery
—— 明确功能的「是什么」（业务逻辑、参与者、规则、边界、验收标准）。输出：业务规范。
你 —— 明确在当前代码库中「如何构建」：涉及哪些文件、类型、操作、组件、测试，所有决策均基于实际读取的代码。输出：
```
docs/<feature-slug>-plan.md
```
。
plan-task-breakdown
—— 将你的计划拆分为有序的、带复选框跟踪的任务列表。输出：
```
docs/<feature-slug>-tasks.md
```
。

你的职责不是重新讨论业务规则——这在上游已经确定。你的任务是将「是什么」转化为「如何做」，让每一个决策都基于你实际读取的代码。

What goes in

输入内容

The skill activates with one of these inputs:

A business spec doc (typical output from
```
feature-discovery
```
) — usually at
```
docs/<slug>-business-logic.md
```
.
A conversational description the user just typed — no spec doc, just words in chat.
An existing plan the user wants improved or extended (rare; treat as a starting point, not a constraint).

Read whatever's available, then proceed. If the input is a conversational sketch, you'll need to compensate by asking more clarifying questions later — but don't pause now. Start exploring the codebase first; the questions get sharper once you've seen the code.

该技能在以下任一输入触发：

业务规范文档（
```
feature-discovery
```
的典型输出）——通常位于
```
docs/<slug>-business-logic.md
```
。
用户刚输入的对话式描述——没有规范文档，仅聊天中的文字内容。
用户想要改进或扩展的现有计划（少见；仅作为起点，而非约束）。

读取所有可用内容后继续执行。如果输入是对话式草稿，后续你需要补充更多澄清问题——但现在无需暂停。先开始探索代码库；查看代码后，你的问题会更精准。

How to run

执行流程

The work is roughly four phases, and they overlap — feel free to loop back. Move through them quickly, in parallel where the tools allow.

工作大致分为四个阶段，各阶段可重叠——请随时回溯。尽快推进，在工具允许的情况下并行处理。

Phase 1 — Read the input and the relevant code

阶段1 —— 读取输入内容和相关代码

Read the spec doc (or scroll back the chat) and form a working hypothesis about which parts of the codebase the feature touches: which routes, which actions, which components, which schemas, which tests. Then read those files. Don't grep blindly — start from the spec's nouns (the entities), follow the routes that already serve them, and trace from there.

What you're looking for, concretely:

Existing primitives to reuse. Tables, dialogs, form patterns, hooks, util functions, formatters, i18n helpers. The good plans in this repo (see
```
docs/budgets-page-plan.md
```
) include a "Reusable primitives to lean on" section — that's not optional decoration, it's the difference between a plan that drifts and a plan that lands. List them by file path.
The closest existing analogue. Almost every feature in a healthy codebase has a sibling already shipped (the manage-budgets page mirrored the manage-categories page). Find that sibling, read it, and let it shape your plan. Naming, layout, error handling, i18n keys — all get cheaper when the new code mirrors the old.
Conflicts and surprises. Does the schema already have the field the spec needs? Is there an action with the same name that does something different? Is there a workaround in existing code (like the
```
b.id.startsWith(id)
```
hack in the budgets detail page) that this feature is a chance to fix? Note these — they become callouts in the plan's "Context" section.
Test files for the touched code. Note which
```
*.test.ts
```
files exist for the modules you'll change; those tests may need updating, and their existence (or absence) tells you the project's test culture for that area.

Use parallel tool calls — fire off

Read

on the candidate files in one go, not serially. If the surface is broad, dispatch the

Explore

subagent for the "where does X live?" lookups so you don't burn the main context.

阅读规范文档（或回溯聊天记录），初步假设该功能会涉及代码库的哪些部分：哪些路由、操作、组件、模式、测试。然后读取这些文件。不要盲目使用grep——从规范中的名词（实体）入手，找到已有的相关路由，再逐步追踪。

具体需要查找：

可复用的现有基础组件。表格、对话框、表单模式、hooks、工具函数、格式化器、i18n助手。本仓库中的优秀计划（如
```
docs/budgets-page-plan.md
```
）包含「可依赖的复用基础组件」部分——这不是可选的装饰，而是决定计划能否落地的关键。按文件路径列出这些组件。
最接近的现有同类功能。健康的代码库中，几乎每个功能都有已上线的同类功能（如预算管理页面参考了分类管理页面）。找到这个同类功能，阅读其代码，并以此指导你的计划。命名、布局、错误处理、i18n键——当新代码与旧代码保持一致时，开发成本会大幅降低。
冲突与意外情况。规范所需的字段是否已存在于模式中？是否有同名但功能不同的操作？现有代码中是否有需要通过此功能修复的临时解决方案（如预算详情页中的
```
b.id.startsWith(id)
```
hack）？记录这些内容——它们会成为计划「背景」部分的重点说明。
涉及代码的测试文件。记录你将修改的模块对应的
```
*.test.ts
```
文件；这些测试可能需要更新，它们的存在（或缺失）能反映项目在该领域的测试文化。

使用并行工具调用——一次性对候选文件发起

Read

调用，而非串行调用。如果涉及范围较广，可调度

Explore

子代理来查找「X在哪里？」，避免占用主上下文资源。

Phase 2 — Identify implementation-level open questions

阶段2 —— 识别实现层面的待澄清问题

A good plan locks in implementation decisions that the spec didn't pin down. Common forks:

Route placement. New top-level route, nested under an existing one, or extending an existing page?
Schema changes. New table, new column, repurpose existing, or compute on the fly? (Migration cost matters.)
Reuse vs. fork. A near-identical component already exists — extend it with a prop, or build a sibling?
Server vs. client component. Default to server; flip to client only when you've named the interactive surface.
Action shape. Single fat action with branching, or several narrow actions? Where does revalidation hit?
Error semantics. Throw vs. return discriminated union, error codes vs. i18n keys, 404 vs. toast.
Test depth. Unit tests for pure functions are obvious; do we need integration tests for the action? E2E for the flow?
Scope cuts. The spec might be larger than one PR's worth. Where would you draw the line and defer the rest?

Anything you can answer from the spec or the code, answer yourself and proceed. The user trusted the upstream skill to settle business logic; they trust you to make reasonable implementation calls. Only ask when:

There's a real fork with non-obvious tradeoffs the user is best placed to decide.
The spec is silent on an implementation choice that would visibly change the result.
The code reveals a constraint the user couldn't have known when writing the spec (e.g., "your idea works, but it'd require a schema migration — is that on the table?").

When you do ask, batch related questions in a single

AskUserQuestion

call (up to 4) with options spelled out — by this stage the forks are usually concrete enough that multiple-choice works. For genuinely open-ended things, fall back to prose. Never ask a question already answered by the spec or visible in the code.

优秀的计划会锁定规范未明确的实现决策。常见的分支选择：

路由位置。新的顶级路由、嵌套在现有路由下，还是扩展现有页面？
模式变更。新增表、新增列、复用现有列，还是动态计算？（迁移成本很重要。）
复用还是分叉。已有近乎相同的组件——通过添加props扩展它，还是构建一个同类组件？
服务端还是客户端组件。默认使用服务端组件；仅当明确需要交互界面时才切换为客户端组件。
操作结构。单个包含分支逻辑的复杂操作，还是多个单一功能的操作？重新验证的触发点在哪里？
错误语义。抛出异常还是返回区分联合类型、错误码还是i18n键、404提示还是toast弹窗？
测试深度。纯函数的单元测试是必需的；操作是否需要集成测试？流程是否需要端到端测试？
范围裁剪。规范的内容可能超出单个PR的承载范围。你会在哪里划分界限，将剩余部分延后？

任何可通过规范或代码得出答案的问题，自行回答并继续执行。用户信任上游技能已确定业务逻辑；他们也信任你能做出合理的实现决策。仅在以下情况提问：

存在真正的分支选择，且权衡利弊不明显，需要用户决定。
规范未明确某个实现选择，而该选择会显著改变最终结果。
代码揭示了用户编写规范时无法预知的约束（例如：「你的想法可行，但需要模式迁移——是否可以接受？」）。

提问时，将相关问题批量整合到一个

AskUserQuestion

调用中（最多4个），并列出选项——此时分支选择通常足够具体，适合使用选择题。对于真正开放式的问题，再使用散文式描述。绝不提问已被规范或代码明确回答的问题。

Phase 3 — Identify the test cases

阶段3 —— 识别测试用例

This isn't optional. The downstream skill (

plan-task-breakdown

) bakes a non-negotiable test-coverage rule into every task — your plan needs to be specific enough about tests that those task lines have substance.

For every meaningful change, name:

What new tests to add. Be concrete: "Add
```
src/actions/budgets.test.ts
```
cases for
```
updateBudget
```
: happy path, missing id throws
```
NOT_FOUND
```
, empty categories throws
```
noCategories
```
."
What existing tests need updating. If a function's signature or return shape changes, the test file for it needs updates. Name the file and the assertions that shift.
What level of test fits. Pure functions → unit. Server actions → integration with the DB if the project does that, else unit with mocks. UI behavior → component test or manual smoke if the project doesn't do component tests. Match the project's existing patterns; don't invent a test layer the codebase doesn't use.
Playwright happy-path e2e. For any feature with a user-visible flow (new page, dialog, multi-step interaction), name one Playwright spec that walks the happy path end-to-end — the same clicks a user would make, asserting the visible outcome. One per feature, not one per branch; edge cases stay in unit/integration. Be specific:
```
e2e/budgets.spec.ts
```
— create budget → assert it appears in the list → open detail → assert period totals render. If the project has no Playwright setup yet, say so explicitly and flag adding it as a setup decision the user should confirm; don't silently invent an
```
e2e/
```
directory the codebase doesn't have.
Manual smoke checks that close the loop on user-visible behavior the automated tests don't cover (locale rendering, period changes, dialog flows). These land in the "Verification" section of the plan.

If the project has no tests for an area you're touching, say so explicitly — "no existing tests for X; the verification phase relies on manual smoke." That's a judgment call, but it's a named one.

这是必需步骤。下游技能

plan-task-breakdown

会为每个任务制定不可协商的测试覆盖规则——你的计划需要足够具体地说明测试内容，才能让任务条目有实际意义。

对于每一项有意义的变更，明确：

需要新增的测试。具体说明：「在
```
src/actions/budgets.test.ts
```
中为
```
updateBudget
```
添加测试用例：正常流程、缺失id抛出
```
NOT_FOUND
```
、空分类抛出
```
noCategories
```
。」
需要更新的现有测试。如果函数的签名或返回结构发生变化，其对应的测试文件需要更新。明确文件名和需要调整的断言。
适合的测试层级。纯函数→单元测试。服务端操作→如果项目支持，结合数据库进行集成测试，否则使用模拟进行单元测试。UI行为→组件测试；如果项目不做组件测试，则进行手动冒烟测试。匹配项目现有的模式；不要引入代码库未使用的测试层级。
Playwright happy-path端到端测试。对于任何包含用户可见流程的功能（新页面、对话框、多步骤交互），明确一个Playwright测试用例，模拟用户的操作流程并断言可见结果——每个功能一个，而非每个分支一个；边缘情况留在单元/集成测试中。具体说明：
```
e2e/budgets.spec.ts
```
——创建预算→断言其出现在列表中→打开详情页→断言周期总计已渲染。如果项目尚未设置Playwright，请明确说明，并将添加Playwright标记为需要用户确认的设置决策；不要凭空创建代码库中不存在的
```
e2e/
```
目录。
手动冒烟测试，覆盖自动化测试未涵盖的用户可见行为（本地化渲染、周期变更、对话框流程）。这些内容会放在计划的「验证」部分。

如果你涉及的代码领域没有现有测试，请明确说明——「X没有现有测试；验证阶段依赖手动冒烟测试。」这是一个判断性决策，但需要明确指出。

Phase 4 — Write the plan

阶段4 —— 编写计划

When the picture is clear, write the plan to

docs/<feature-slug>-plan.md

. Use the template below. Inside Claude Code plan mode, present it inline instead — file writes are blocked and the user will save it after exiting plan mode.

当整体情况清晰后，将计划写入

docs/<feature-slug>-plan.md

。在Claude Code计划模式下，直接在对话中展示计划——此时无法写入文件，用户会在退出计划模式后保存。

Plan template

计划模板

Use this structure. It mirrors the conventions established in

docs/budgets-page-plan.md

docs/selectable-transactions-plan.md

, and

docs/transaction-description-plan.md

in this codebase. Section order matters because

plan-task-breakdown

walks the plan top to bottom when generating tasks.

markdown

undefined

使用以下结构。它与本代码库中

docs/budgets-page-plan.md

、

docs/selectable-transactions-plan.md

和

docs/transaction-description-plan.md

的约定一致。章节顺序很重要，因为

plan-task-breakdown

会按从上到下的顺序生成任务。

markdown

undefined

<Feature name> — implementation plan

<功能名称> —— 实现计划

Context

背景

<2–4 paragraphs covering:

What already exists in the codebase that's relevant (with file paths).
What's missing or broken that this feature changes.
The user decisions made during this planning round (if you asked clarifying questions, capture the chosen answers here so the rationale survives).
The pointer to the source business spec, if there is one: e.g. "Business logic:
```
docs/<slug>-business-logic.md
```
.">

<2-4段内容，包括：

代码库中已有的相关内容（带文件路径）。
此功能需要改变的缺失或不完善之处。
本次规划过程中用户做出的决策（如果你询问了澄清问题，请在此记录选择的答案，以便保留决策依据）。
源业务规范的链接（如果存在）：例如「业务逻辑：
```
docs/<slug>-business-logic.md
```
」。>

<Subfeature N — name> (omit subfeature headings if the feature is small enough to be one block)

<子功能N —— 名称> （如果功能足够小，可省略子功能标题）

Server actions / data (

<path>.ts

)

服务端操作 / 数据 (

<path>.ts

)

Add
```
<actionName>(<args>)
```
— <one sentence describing inputs, behavior, error codes, revalidation paths>. Reference the zod schema shape and any non-obvious branches.
Update
```
<existingAction>
```
— <what changes and why>.

添加
```
<actionName>(<args>)
```
—— <一句话描述输入、行为、错误码、重新验证路径>。参考zod模式结构和任何非明显分支逻辑。
更新
```
<existingAction>
```
—— <变更内容及原因>。

Types (

src/lib/types.ts

or wherever this project keeps DTOs)

类型定义 (

src/lib/types.ts

或项目存放DTO的其他位置)

Add
```
<TypeName>
```
with fields
```
<list>
```
. Show the interface block if non-trivial.

添加
```
<TypeName>
```
，包含字段
```
<列表>
```
。如果非 trivial，展示接口代码块。

Pages / routes

页面 / 路由

```
<path/to/page.tsx>
```
— server or client, what it renders, what it fetches, parallel vs. sequential fetches.

```
<path/to/page.tsx>
```
—— 服务端或客户端组件，渲染内容、获取的数据、并行还是串行获取。

Components

组件

```
<path/to/component.tsx>
```
— new or modified, client/server, props, modes (display/edit), what primitives it composes.

```
<path/to/component.tsx>
```
—— 新增或修改，客户端/服务端组件，props，模式（展示/编辑），组合的基础组件。

i18n (

messages/en.json

messages/de.json

)

国际化 (

messages/en.json

messages/de.json

)

Keys to add, grouped by namespace. Show structure if it's a new namespace.

需要添加的键，按命名空间分组。如果是新命名空间，展示结构。

Tests

测试

New:
```
<test file>
```
— assertions to add (named).
Updated:
```
<existing test file>
```
— assertions that change.
E2E:
```
<e2e/<feature>.spec.ts>
```
— Playwright happy-path flow (the clicks + visible-outcome assertions). Omit only if there's no user-visible flow, or note "Playwright not yet set up in this project" and defer.

新增：
```
<测试文件>
```
—— 需要添加的断言（明确名称）。
更新：
```
<现有测试文件>
```
—— 需要变更的断言。
端到端：
```
<e2e/<feature>.spec.ts>
```
—— Playwright happy-path流程（操作步骤+可见结果断言）。仅当无用户可见流程时省略，或注明「项目尚未设置Playwright」并延后。

Critical files

关键文件

New

```
<path>
```
— <one-line purpose>
...

Modify

```
<path>
```
— <one-line summary of the change>
...

新增

```
<路径>
```
—— <一句话说明用途>
...

修改

```
<路径>
```
—— <一句话总结变更内容>
...

Reusable primitives to lean on

可依赖的复用基础组件

```
<component or util>
```
(
```
<path>
```
) — <why it's useful here>
...

(This section is the difference between a plan that ships and a plan that drifts. Always include it unless the feature is so isolated that nothing reusable applies — and even then, double-check.)

```
<组件或工具>
```
(
```
<路径>
```
) —— <在此处的用途>
...

（此部分是计划能否落地的关键。除非功能完全独立，无任何可复用内容，否则必须包含此部分——即使如此，也请再次检查。）

Verification

验证

Static checks
- ```
<lint command>
```
  clean.
- ```
<typecheck command>
```
  clean.
Unit / integration tests
- ```
<test command>
```
  green, including the new and updated tests above.
E2E (Playwright)
- ```
<playwright command, e.g. pnpm playwright test>
```
  green, including the new happy-path spec. Skip this step (and say so) if the project has no Playwright setup.
Manual smoke
- <One sentence per user-visible flow to click through. Cover both locales if the project is i18n'd. Cover the empty state, the happy path, and the most important edge case.>

静态检查
- ```
<lint命令>
```
  无报错。
- ```
<类型检查命令>
```
  无报错。
单元 / 集成测试
- ```
<测试命令>
```
  通过，包括上述新增和更新的测试。
端到端测试（Playwright）
- ```
<Playwright命令，如pnpm playwright test>
```
  通过，包括新增的happy-path测试用例。如果项目未设置Playwright，跳过此步骤并说明。
手动冒烟测试
- <每个用户可见流程一句话说明操作步骤。如果项目支持国际化，覆盖两种语言。覆盖空状态、正常流程和最重要的边缘情况。>

Out of scope

超出范围

<Something the spec mentioned or implied that this plan deliberately defers — and why. Helps
```
plan-task-breakdown
```
avoid inventing scope.>
...


Sections that genuinely have nothing in them can be omitted (e.g. no schema change → no migration sub-section). Don't pad with empty headings.

<规范提及或暗示但本计划故意延后的内容——及原因。帮助
```
plan-task-breakdown
```
避免额外增加范围。>
...


确实无内容的章节可省略（例如：无模式变更→无迁移子章节）。不要添加空标题凑数。

Plan mode

计划模式

Inside Claude Code's plan mode (read-only):

Don't try to write the plan to disk — present it inline as the final message.
Don't call
```
ExitPlanMode
```
from this skill — leave that to the user.

Outside plan mode, write the file and tell the user where the plan lives.

在Claude Code的计划模式（只读）下：

不要尝试将计划写入磁盘——在对话中直接展示最终内容。
不要从此技能调用
```
ExitPlanMode
```
——留给用户操作。

在计划模式外，写入文件并告知用户计划的位置。

Self-check before finishing

完成前的自检

After finishing

完成后

State briefly where the plan lives and what comes next:

"Saved plan to
docs/<slug>-plan.md
. <N subfeatures, M critical files>. Ready to hand to
plan-task-breakdown
when you want a task list."

Don't dump the plan back into chat — the user will open the file. If you produced it inline (plan mode), point at where it'll be saved when plan mode lifts.

简要说明计划的位置和下一步操作：

"计划已保存至
docs/<slug>-plan.md
。包含<N个子功能，M个关键文件>。当你需要任务列表时，可交给
plan-task-breakdown
处理。"

不要将计划重新粘贴到聊天中——用户会自行打开文件。如果是在计划模式下直接展示的内容，请说明计划模式结束后会保存到哪里。

What good looks like

优秀计划的标准

Code-grounded. Every file path, every function name, every type appears in the actual codebase (or is explicitly New). A reader could
```
cmd-click
```
every path and land somewhere real.
Specific about tests. Reads like "Add
```
updateBudget
```
happy-path test + missing-id branch to
```
src/actions/budgets.test.ts
```
", not "add tests for the new action." User-visible flows get a named Playwright happy-path spec (or an explicit note that Playwright isn't wired up yet).
Mirrors the sibling. If a near-identical feature already shipped, the plan visibly leans on its patterns (file layout, naming, i18n structure, error semantics).
Honest about cuts. "Out of scope" is non-empty and specific — naming what not to build is part of the plan's value.
Lean on questions. Clarifying questions are concrete forks with options, not open-ended "what do you think?" prompts. The user spends seconds, not minutes, picking an answer.

基于代码。每个文件路径、函数名、类型要么存在于实际代码库中，要么明确标记为新增。读者可以通过
```
cmd-click
```
每个路径跳转到真实位置。
测试说明具体。例如「在
```
src/actions/budgets.test.ts
```
中添加
```
updateBudget
```
正常流程测试+缺失id分支测试」，而非「为新操作添加测试」。用户可见流程有明确的Playwright happy-path测试用例（或明确说明尚未配置Playwright）。
参考同类功能。如果已有近乎相同的功能上线，计划明显借鉴其模式（文件布局、命名、i18n结构、错误语义）。
明确范围裁剪。「超出范围」部分非空且具体——明确不构建的内容是计划价值的一部分。
澄清问题精准。澄清问题是具体的分支选择并提供选项，而非开放式的「你怎么看？」。用户只需几秒即可选择答案。

What bad looks like (avoid)

需要避免的不良情况

A plan that hallucinates files or function signatures. Verify or omit.
A plan that re-debates the spec's business rules. Push that back; don't engage.
"Add tests" with no specifics. The downstream skill will produce a useless task line.
A 20-question batch before any code has been read. Read first; then ask sharper, fewer questions.
A plan with no "Reusable primitives" section in a codebase that has obvious primitives. That's a sign the planner didn't look around.

计划中虚构文件或函数签名。要么验证，要么省略。
计划重新讨论规范中的业务规则。将问题推回上游，不要参与讨论。
仅说「添加测试」而无具体内容。下游技能会生成无用的任务条目。
未读取任何代码就批量提出20个问题。先读取代码；再提出更精准、更少的问题。
在有明显可复用基础组件的代码库中，计划缺少「可复用基础组件」部分。这表明规划者未充分探索代码库。