plan

计划

必读内容

• skill: principles
  • 阅读 principles/SKILL.md。
  • 规划前，阅读所有链接的原则详情文档。
  • 将原则详情视为具有约束力的规划要求，而非可选的背景资料。

角色

Plan 是裁决者。

它负责范围、上下文加载、决策、任务排序、验证策略和已保存的计划文档。

裁决者可以直接执行工作。只有当某项范围明确的调查可以独立进行时，才进行委派，例如 API 契约发现、迁移风险、测试清单或发布约束。工作者返回原始笔记。裁决者撰写计划。

此技能适用于三级工作流：

• 路由器：选择何时运行规划、构建和审查
• 裁决者：负责规划决策和计划文档
• 工作者：回答一个范围明确的规划问题

默认直接执行。

工作流

1. DETERMINE_SCOPE
2. LOAD_CONTEXT
3. DELEGATE_INVESTIGATIONS
4. RESOLVE_DECISIONS
5. DESIGN_TEST_SIGNALS
6. DRAFT_PLAN
7. CHECK_GATES
8. WRITE_ARTIFACT

DETERMINE_SCOPE

• 确定请求的变更、受影响的产品行为、规划深度，以及计划有意排除或推迟的任何可能相关工作。
• 指明仓库根目录和计划文档路径： <repository-root>/docs/plans/YYYY-MM-DD_HH:MM_<plan-name>.md。
• 如果 docs/plans/ 不存在，则创建该目录。

LOAD_CONTEXT

• 阅读相关源代码、测试、文档、配置、AGENTS.md 和本地指南。
• 确定当前行为、受影响文件、不变量、依赖项、契约、测试接入点和验证命令。
• 对外部技能使用语义化技能名称，例如 skill: principles。
• 对本地文件使用路径。除非实现者需要确切的代码片段，否则不要将参考资料复制到计划中。
• 如果必要的读取或仓库命令在尝试明显的修复后仍失败，请停止并升级处理。缺少上下文并不是盲目规划的理由。

DELEGATE_INVESTIGATIONS

• 直接规划成本更低时，跳过此步骤。
• 仅委派可独立进行、范围明确的问题。
• 给工作者的提示必须包含问题、确切范围、需要阅读的文件或技能、预期输出格式、工作者不得编写计划文档的要求，以及工作者必须将工具故障升级给裁决者而非默默降低输出质量的要求。
• 将工作者的输出视为证据。规划前需去重并协调。

RESOLVE_DECISIONS

• 尽可能依据仓库上下文解决未知事项。
• 仅在“待解决问题”中保留尚未解决的决策。
• 不要在实施任务中列出备选方案。
• 如果某项任务依赖尚未解决的问题，请将该任务标记为受阻，并注明依赖项。

DESIGN_TEST_SIGNALS

• 规划测试变更前，重新阅读 tests are code 原则详情。
• 对每项非平凡的行为变更，在起草任务前确定自动化回归信号。
• 每项计划中的测试变更都必须说明：
  • 受保护的行为、不变量或契约
  • 所测试的公共边界
  • 应由此测试捕获的回归
• 如果不添加测试，请指出现有的自动化信号，或说明为何不存在可长期保留的信号。

DRAFT_PLAN

• 面向具备专业能力、但不了解此前聊天上下文的工程师。
• 使用准确的文件路径；必要时标明行号，并按依赖顺序安排任务。
• 每项任务完成后，在其依赖项已应用的前提下，仓库都应保持一致。不要拆分重构，导致较早的任务破坏导入、类型、测试或运行时行为，再由后续任务修复。
• 如果某项任务在依赖任务完成前无法诚实地验证，就合并这些任务。
• 将测试放在与行为变更相同的任务中，或放在依赖于该变更的测试任务中。每项测试任务都要包含 DESIGN_TEST_SIGNALS 中的测试信号。
• 用 Details 说明意图、不变量和执行顺序。将具体操作写在 Code Changes 中；不要在说明文字中重复代码片段。

计划中的代码策略：

• 默认使用差异。对于对现有文件的小幅修改，只展示补丁式代码块中的变更行，并保留少量上下文。
• 只有新文件或需要额外上下文才能理解变更时，才使用较大的代码块。新文件、新函数、新组件、新类型以及大幅重写的单元需要提供完整或近乎完整的代码。
• 小幅修改时，不要贴出整个现有文件。
• 除非生成的构件、锁文件、快照或构建输出本身就是变更对象，否则不要将其纳入。
• 不要用 ... 隐去实质性逻辑。
• 仅在不明显的不变量、边界情况、错误处理、并发、性能、安全或领域规则需要时添加注释。

CHECK_GATES

写入产物前，请确认：

• 计划无需此前的聊天上下文即可独立理解。
• 每项非平凡任务都列出准确的文件。
• 每项任务都具体明确，无需做决策。
• 每项任务的 Verify 部分在该任务及其依赖项应用后即可执行。
• Open Questions 仅包含尚未解决的决策。
• 若标记为“无则跳过”的可选章节为空，则省略该章节。
• 不要将已回答的问题留作开放问题。
• 被阻塞的任务必须注明阻塞项。
• 验证命令及预期结果都要明确。
• 每个验证命令所依赖的工具都必须能在本仓库中运行。请通过空操作（例如 --help、试运行、版本检查或不指定目标）确认工具可用。对于会运行尚未实现代码的命令，只需确认工具本身可用。如果按显而易见的方式修复后仍无法运行某个工具，请升级处理。
• 每项非平凡的行为变更都必须有自动化测试信号、现有测试信号，或明确说明为何不存在可长期保留的信号。
• 每项任务的文件列表必须与该任务中的代码片段或代码块一致。
• 计划不得包含关于此技能或计划过程的元注释。

WRITE_ARTIFACT

• 将最终计划写入： <repository-root>/docs/plans/YYYY-MM-DD_HH:MM_<plan-name>.md。
• 修改计划时，重新编写完整的最终产物。不要只写相对于上一版草稿的差异。
• 将已接受的反馈整合到相关章节中。
• 删除已被取代的范围，不要描述其已被移除。

产物模板

# Plan: <Feature Name>

## Summary
<1-3 sentences describing what this builds and why>

## Prerequisites
<Task-specific setup, dependencies, or docs; skip if none>

## Open Questions
<Unresolved decisions only; skip if none>

## Out of Scope
<Nearby work the reader might reasonably expect from this plan, but this plan rejects or defers; skip if none>

## Overview
<1-2 short paragraphs about architecture, approach, constraints, and sequencing>

## Task <n>: <name>
**Files:** `path/to/file.ts:42`, `path/to/test.ts`
**Depends on:** Task <m> or `None`
**Blocked by:** <open question or external dependency; omit if unblocked>

**Details:**
- <Intent, invariant, or sequencing note not obvious from the code>
- <Concrete step only when no code hunk carries it>

**Test Signal:** <For test tasks only: behavior protected, boundary exercised, and regression that should fail; omit otherwise>

**Code Changes:**
```ts
// Patch-style hunk for small edits; full definition only for new/rewritten code.
```

**Verify:**
- `<command>`
- Expected: <observable result>