plankit

plankit

将一个粗略想法（功能、项目、规范、PRD）转化为一份可执行的结构化计划文档。plankit 具有生成能力：它会集思广益，确定形成连贯草稿所需的决策，并根据真实代码库（而非猜测）编写 NNNN-plan-<slug>-YYYY-MM-DD.md。它是工作流的第一步：对于通过 GitHub Issues 跟踪工作的项目，工作流是 plankit 起草 → grillkit 完善 → issuekit 创建工单；对于不通过 GitHub Issues 跟踪工作的项目，工作流是 plankit 起草 → grillkit 完善 → implementkit 实现。无论哪种情况，它编写的计划都是下一步所需的确切输入。plankit 只做计划：它绝不编写应用代码，也绝不创建工单。

何时触发

用户想在开始构建之前理清一项工作：“规划这个功能”“集思广益，制定计划／PRD／规范”“编写计划文档”“先帮我理清 X”“/plankit”。有一个重要区别：

• 它不是对抗式提问者。 那是 grillkit。plankit 会提出足够的问题来起草连贯的计划，并将薄弱之处记录为待解决问题；grillkit 则会一次针对一个决策进行压力测试。

流程

1. 收集想法

了解概念、要解决的问题、目标用户，以及代表成功的结果。成功结果是请求背后的目标，也就是说，这项工作的目的，而不只是它要构建什么（“让应用保持无崩溃运行”，而不是“修复这个崩溃”），并且还要有一个目标值：用于证明工作有效的数字。如果输入只有一句话，请提出几个范围界定问题（如有 AskUserQuestion，请使用）。这些问题应是生成式的“我们要构建什么，为什么”，而不是对抗式的“你漏掉了什么”。最多只问一轮，而且只针对输入中未明确的四项内容。

询问目标值；只有依据基线时才提出建议值。 先询问用户的数字目标。如果用户没有目标值，只能根据用户提供的基线，或你能读取的文件（CI 报告、基准测试输出、仪表板导出）提出建议值，并同时标明两项信息：Target: p95 load under 200 ms (proposed; baseline 4.8 s from ci/bench.json)。此技能没有 shell，因此绝不自行测量基线。如果没有基线，请写入 Target: open, no baseline，并将这一行带入待解决问题，让 grillkit 确定目标，而不是凭空捏造数字。如果这项工作不适合用数字衡量，请说明原因，并明确指出能证明工作有效的依据（“仅修改文档，因此以 lint 检查通过为准”）；“不适用”没有说明依据，不符合要求。

完成条件： 概念、问题、用户和成功结果各有一句话说明，内容来自输入或用户提供的信息；成功结果还必须包含目标值、Target: open, no baseline，或说明为何不适合用数字衡量并指出能证明工作有效的依据。

2. 以实际情况为依据

先研究，再提出方案，让计划复用现有内容，而不是重新发明。

• 在现有仓库中： 阅读相关代码、文档和配置，找出计划应基于的模式、工具和约定。自行查找事实（Read、Grep、Glob）；只有真正需要用户决策时才提问。绝不在已有合适实现的情况下提出新代码；应在计划中指出现有实现。
• 从零开始（尚无仓库）： 跳过代码研究；以用户陈述的目标和约束为依据。

完成条件： 工作涉及的系统各部分，都已按路径指出现有模块、工具或约定，或记录为不存在；对于 UI 变更，还已找到团队规范和视觉参考，或记录为缺失（UI 计划）。从零开始时，则须写明所有已陈述的目标和约束。

3. 发散，探索不同方案

集思广益，找出真正可行的方案，并推荐一个具体方案，供用户接受或调整，而不是只列出选项。这是发散思考的部分：不要止步于第一个想法；在缩小到实际可行的方案之前，先考虑不受约束时的做法。

如果存在多个可信的路径，默认给出真正不同的方案，而不是同一想法的不同变体：最小可行方案（能交付且有用的最小改动）、理想方案（如果有时间妥善完成，你会选择的方案），以及在适用时提供一个另辟蹊径的方案（通过重新定义问题来消除问题，而不是解决问题）。说明每个方案会复用上述研究中的哪些内容，让计划立足于你刚读过的代码。如果工作需要，收敛到单一方案也没问题，因为“没有可信的替代方案”胜过凭空捏造选项 B。

**完成标准：**推荐一个方案；每个替代方案都必须在明确指出的维度上与推荐方案不同，或者用一句话说明为何不存在可信的替代方案。

要避免的失败模式，是那些看起来选择很多的方案：

**变体（避免）：**缓存响应 · 缩短 TTL 后缓存响应 · 加个标志位缓存响应，以后再调整。一个想法换了三种说法，因此并没有真正的选择。

**不同方案（目标）：**缓存响应（改动最小，本周即可交付，但写入后会变陈旧）· 对读取路径做反规范化，从而无需缓存（需要迁移，但可以彻底消除整类陈旧问题）· 完全不在这里修复，因为只有在循环中调用时才会变慢，所以在上游批处理，让端点不再成为问题。

4. 收敛，确定结构

逐一确定形成连贯草稿所需的结构性决策（架构、阶段、范围边界，以及某个阶段需要新类型测试时的测试方案），并为每项给出推荐答案。然后停止：有意将更深入、较薄弱或仍不确定的部分留给 grillkit，而不是在此处穷尽每个边界情况。在文档的待解决问题部分记录这些内容，为后续加固步骤明确目标。

**完成标准：**架构、阶段列表和范围边界都已有确定答案，并经用户接受或调整；每个需要人工参与的阶段都已标记为 attended；其他所有尚未确定的问题都列在“待解决问题”中。

5. 编写计划文档

编写 docs/plans/NNNN-plan-<slug>-YYYY-MM-DD.md，其中 NNNN 是 docs/plans/ 中下一个四位数序号，<slug> 是简短的小写 kebab-case 功能名称，后缀是计划的 ISO 创建日期（0007-plan-sso-login-2026-07-23.md）。要确定序号，请找出当前检出和仓库所有其他工作树中 docs/plans/ 里的最大前导序号，然后加一；如果没有序号，则从 0001 开始。此技能没有 shell，因此请使用 Read 和 Glob 查找工作树：在链接工作树中，.git 是一个文件，其中记录了 <main>/.git/worktrees/<name>；<main> 是主检出，而每个 <main>/.git/worktrees/*/gitdir 都记录了另一个工作树的路径。请扫描所有工作树，否则并行工作树会使用相同的序号。序号按目录单独计数，且永不重用，在所有仓库中都适用，包括新建仓库。后续编辑时保持整个文件名不变；必要时在文档内记录更新日期。使用下方的 计划文档格式，这是 grillkit 和 issuekit 都会读取的约定，因此正文应采用阶段／任务结构。如果 docs/plans/ 不存在，请创建它。如果此项工作已有计划，请原地更新，不要另写一个文件；即使该计划没有序号，也要保留原文件名。如果计划中有 Grilled: 行，而你的更新属于实质性变更，请删除该行，并在交接说明中注明。

完成条件： 文件已存在于指定路径，格式中的每个部分都已填写或明确省略，且每个阶段都包含验收可观察项。

6. 交接

本节采用流程说明的语体：每句话只写一条指令，使用主动语态和现在时，不使用比喻。

说明计划文件的位置，以及是否删除了 Grilled: 行。然后按顺序提出下一步；只有在同级工具包已安装时才点名，否则用通俗语言描述操作：

• grillkit。 压力测试并完善草案（它可以原地更新此文件）。
• 如果项目通过 GitHub Issues 跟踪工作，则使用 issuekit。将完善后的计划转化为 issue。
• 如果不是，则使用 implementkit。直接依据计划逐阶段实施。

如果能判断适用哪一项，就只点名第二项或第三项，不要两者都点名。提示词或仓库的 Agent 指南文件会说明适用情况；仓库中已有的开放 issue 是较弱的判断依据。如果没有明确信息，就两者都点名；不要仅仅因为项目托管在 GitHub 上，就假定它会用 GitHub issue 跟踪工作。

如果规划过程中发现值得明确记录的项目术语，或难以撤销的权衡决策，且已安装 domainkit，请提出使用它；否则，提出直接记录词汇表条目或 ADR。

不要自行开始执行上述任何操作。

计划文档格式

plankit 负责维护的规范结构。保持精简，让每个部分都有存在的价值，并将正文组织为阶段／任务，以便 issuekit 将其拆分为问题：

# Plan: <title>

## Context
The problem, why it matters now, and the outcome that means success: the goal behind the request and its target line.

## Design decisions (settled)
| Decision | Resolution |
|----------|-----------|
| <the choice> | <what we picked and, briefly, why> |

## Approach
The chosen approach and what it **reuses** from the existing codebase, then the plan body as phases/milestones/tasks, each a concrete, verifiable unit of work. This is the structure issuekit reads to propose an issue breakdown. When the alternatives were close, keep the rejected ones to a line each so the choice stays legible later.

### Phase 1: <name>
Attended: <only when the phase needs a person: the pick or approval it waits on>
<the tasks>
Done when: <an observable a reviewer can check: a command and its output, a behavior in the running app, a test that passes>

## Migration and rollback
Only when the plan changes stored data (a schema, a persisted file format, existing records). How existing data moves to the new shape, in which phase, and how to undo it if the phase fails. Omit the section otherwise.

## Open questions
Unresolved or thin spots, written as targets for grillkit to interrogate.

## Non-goals
Explicit scope boundaries, meaning what this plan deliberately does not cover.

经过审查的计划还会在标题正下方包含一行 Grilled: YYYY-MM-DD。计划通过一轮 grill session 后，grillkit 会写入该行；issuekit 会将其作为将问题标记为 ready 并提交的门槛。plankit 绝不会自行写入此标记；新草稿按定义未经审查。

每个阶段都以一行 Done when: 结束，说明验收时可观察到的结果。它应描述阶段交付后某个人或某项测试可以检查的内容，而不是意图（“身份验证正常”）。它为构建设定一个可供核验的终点；没有这一行的阶段就没有终点。

如果构建能够衡量目标，最后一个阶段的 Done when: 应包含该目标，这样构建就会核验数值，而不只是记录它。只有发布后才能显示的指标应放在 Context 中，并标记为 measured after release，因为构建无法核验它。

如果某个阶段要求新增一种测试，必须在 Design decisions 中注明测试运行器和测试方法（例如“使用 vitest 和 Testing Library 编写组件测试，放在源代码旁边”）。没有这一行，构建就会停下来询问该使用哪个运行器。

需要人工参与的阶段

需要人工参与的阶段应包含一行 Attended:，注明需要等待什么：设计方案选择、模型图审批，或提交问题、部署等外部操作。将需要人工参与的阶段排在无人值守运行可执行的阶段之前，这样人工工作可以先完成，之后其余工作便可在无人操作键盘的情况下运行。无人值守运行器会读取这一行，并在构建开始前停止，而不是在构建过程中途停止。

UI 计划

修改界面的计划应在构建前确定界面外观，而不是等 PR 提交后再确定。 阅读项目的 DESIGN.md 和 Agent 指令，了解项目的 UI 规范（例如：外部链接在新标签页中打开，主题切换仅支持浅色和深色，每行卡片高度相同），并将此计划中的界面必须遵守的规则列为一行 Design decisions。规划期间用户提出但尚未记录在任何文件中的规则，也应列入该行并标记为 new，以便将其纳入 DESIGN.md。注明视觉参考（模型图路径、问题附件或参考网站），并在规划期间征求用户批准；将批准记录为一行 Design decisions，并注明日期。如果尚无参考，视觉方案选择应作为需要人工参与的阶段，并排在最前面。

Grilled: 标记过期时

该标记证明计划在审查时的状态。实质性编辑是指新增、移除或修改已确定的设计决策；新增、移除阶段或调整阶段范围；更改 Done when: 中可观察到的结果；或更改非目标或迁移部分。进行实质性编辑的人应在同一次编辑中删除 Grilled: 行，使计划恢复为未经审查的状态，直到 grillkit 再次运行。措辞修正、下文所述的阶段标题注释、更新日期行和新增待解决问题均不属于实质性编辑，不会影响该标记。

阶段标题注释槽位

阶段标题末尾可以带可选注释，下游技能会写入该注释。 plankit 会写入不带注释的标题（### Phase 2: auth），自己不会添加注释，因为新计划既未归档，也未构建。此槽位共用两种标记：

• (#41)，由 issuekit 在将该阶段登记为 issue 时写入。它说明该阶段在哪儿跟踪。
• (built YYYY-MM-DD)，由 implementkit 在完成该阶段的构建后写入。它说明该阶段已完成。

二者可以共存，因此 ### Phase 2: auth (#41) (built 2026-08-20) 表示这是一个已跟踪且已交付的阶段。将二者保存在同一槽位中，读者和调查工具就能仅凭计划回答“这个计划还剩下什么？”，无需查询任何跟踪系统；对于不登记 issue 的项目，只有这样才能回答这个问题。

是否使用标记，由每个计划自行选择。 完全没有注释的计划不会对自身作出任何声明，因此不得将其中的阶段视为尚未构建。这样一来，这项约定无需迁移即可引入：在此约定出现之前编写的计划会保持沉默且依然正确；计划第一次被添加标记时，才开始作出声明。

宽松匹配标题。 阶段标题以 Phase <n> 开头，后面的分隔符因实际计划集而异，因此任何读取这些标题的工具都接受冒号、破折号或不加分隔符。

说明

• 仅限计划。 不涉及应用代码，也不涉及 issue；它们属于单独的步骤（implementkit、issuekit）。plankit 负责移交，不会越界处理。
• 只写必要且真实的章节。 计划宁可简短精炼，也不要硬凑内容；与其用废话填满章节，不如直接删掉。文档篇幅应与实际工作范围相称。
• 把审查留到之后。 留下未解决的问题没关系，而且这是预期做法。先起草一份连贯的计划，再交给 grillkit 加以完善；不要试图两者兼顾。
• 遵循代码库的约定。 如果代码库有自己的计划、RFC 或 PRD 存放位置或模板，就遵循该约定并说明你已这样做，而不是强行使用 docs/plans。
• 如果没有文件系统或 shell（例如使用基于浏览器的 Agent），你就无法写入文件。此时，请用代码块打印最终计划文档，并提供规范的 NNNN-plan-<slug>-YYYY-MM-DD.md 文件名；如果无法列出用户的计划，则使用 0001，方便用户将其保存到存放计划的位置。