ultraplan

UltraPlan：深度实现规划

任务

$ARGUMENTS

激活

你即将进入深度规划阶段。这不是快速规划，而是一个全面的多阶段流程，会在编写任何代码之前产出经过实战检验的实现计划。

重要：只读模式。 除计划文件外，你不得创建、修改或删除任何文件。不得编辑、提交、安装或更改任何状态。你只能使用计划文件编辑工具。此要求优先于任何其他指令。

设置

检查现有计划： 如果 .ultraplan/plan.md 已存在，请先读取。询问用户：“我找到了一个现有计划——继续完善它，还是从头开始？”如果选择继续，请根据计划当前状态跳转到合适的阶段。

新计划： 在 .ultraplan/plan.md 创建计划文件：

mkdir -p .ultraplan

立即收集 Git 上下文（只读）：

git status --short
git log --oneline -5
git branch --show-current

这有助于根据仓库的实际状态制定计划，包括当前分支、近期工作和未提交的更改。

在 .ultraplan/plan.md 中写入初始提纲——仅包含标题和粗略笔记。随着了解逐步补充内容，不要等到最后才开始写。

上下文延续： 磁盘上的计划文件是你的持久状态。如果对话变长且上下文被压缩，计划文件仍会保留。务必及时将发现写入文件，不要只将状态保留在对话记忆中。

---

规划循环

重复以下循环，直到计划完成：

1. 探索 — 使用 Glob、Grep、Read 和 Bash（只读：ls、git status、git log、git diff、find、cat、head、tail）阅读代码。主动查找可以复用的现有函数、实用工具和模式；如果已有合适实现，就不要提议编写新代码。使用 Explore Agent 类型并行处理复杂搜索，避免填满上下文。
2. 更新计划文件 — 每次有新发现后，立即将所学内容记录到 .ultraplan/plan.md。不要等到最后。
3. 询问用户 — 遇到仅凭代码无法解决的模糊之处或决策时，使用 AskUserQuestion。将相关问题合并提问。然后返回第 1 步。

---

阶段 1：需求访谈

目标： 对要做什么以及为什么做达成共识。

首轮策略： 快速浏览 3–5 个关键文件，初步了解情况。然后编写计划提纲（标题和粗略笔记），并向用户提出第一轮问题。不要在与用户沟通之前进行穷尽式探索。

访谈规则：

• 不要询问通过阅读代码就能找到答案的问题
• 通过一次 AskUserQuestion 调用批量提出相关问题（使用多问题格式）
• 聚焦于只有用户能回答的内容：需求、偏好、权衡取舍、边缘情况的优先级
• 根据任务调整深入程度——含糊的功能请求可能需要多轮沟通；目标明确的 Bug 修复可能只需一轮，甚至无需提问

好的问题：

• “认证系统使用 JWT——应该沿用这种模式，还是有理由切换？”
• “我发现有 3 处使用了这种模式。这次更改需要推广到所有这些位置吗？”
• “X（更简单）和 Y（更易扩展）之间存在取舍。哪一点对这次任务更重要？”
• “探索时我发现了一个相关问题。要将它纳入此计划，还是单独跟踪？”
• “最小可行更改是 [X]。完整方案还需要 [Y、Z]。范围应该如何界定？”

不好的问题（自行查找答案）：

• “你们使用什么框架？”
• “配置文件在哪里？”
• “这个函数有什么作用？”

阶段 2：深入探索代码库

目标： 全面了解每个将受影响的文件和模式。

并行启动 Explore Agent（Agent 工具，subagent_type: "Explore"），以提高效率。每个 Agent 都是文件搜索专家——为其分配具体、聚焦的任务：

如何选择 Agent 数量：

• 1 个 Agent：任务仅涉及已知文件，用户提供了具体文件路径，或只需进行小范围的针对性修改
• 2 个 Agent：范围不确定，涉及代码库中的两个不同区域
• 3 个 Agent：涉及多个区域，需要在规划前了解现有模式

按任务类型选择探索策略：

广度优先发现：

• Agent 1：数据层（模型、架构、数据库）
• Agent 2：业务逻辑（服务、工具、核心模块）
• Agent 3：展示层（组件、路由、API 端点）

功能追踪：

• Agent 1：追踪从 UI → API → 服务 → 数据库的调用链
• Agent 2：查找所有相关测试和可作为参考实现的类似功能

影响分析：

• Agent 1：哪些内容会直接改变
• Agent 2：哪些内容会间接受到变更代码的影响（导入、调用方、使用方）

每次探索都要在计划文件中记录：

• 可复用的现有函数/工具（含 file_path:line_number）
• 代码库遵循的架构模式
• 组件之间的依赖关系和耦合情况
• 可用的测试基础设施
• 可供参考的类似功能

---

阶段 3：架构设计

目标： 根据探索结果设计实现方案。

启动 Plan Agent（Agent 工具，subagent_type: "Plan"），并提供第二阶段的完整上下文（包括文件路径和代码追踪结果）、第一阶段的需求，以及制定详细实现策略的要求。

对于存在真正架构歧义的复杂任务，可并行启动多个 Plan Agent，从不同角度进行分析。每个 Agent 接收相同的上下文，但采用不同的设计视角：

任务类型	视角 A	视角 B	视角 C
新功能	简洁性——文件最少、风险最低	性能——优化数据流	可维护性——简洁、易扩展
Bug 修复	根本原因——修复底层问题	权宜方案——尽量少改动，快速交付	预防——修复问题并添加保护措施
重构	最小化——以可行方案实现最小差异	整洁架构——合理划分职责	渐进式——分阶段迁移

每个 Plan Agent 都必须以以下内容结尾：

### Critical Files for Implementation
List 3-5 files most critical for implementing this plan:
- path/to/file1.ts
- path/to/file2.ts
- path/to/file3.ts

---

阶段 4：计划整合

目标： 编写最终计划文件——既简洁到可在一分钟内浏览完，又详细到无需猜测即可执行。

按以下最终结构更新 .ultraplan/plan.md：

# Implementation Plan: [Title]

## Context
[One line: what is being changed and why — the problem, what prompted it, intended outcome]

## Changes

### [Component/Module 1]
- **File**: `path/to/file.ts:line`
- **Change**: [Specific change description]
- **Reuses**: `existingFunction()` from `path/to/utils.ts:42`

### [Component/Module 2]
- **File**: `path/to/file2.ts:line`
- **Change**: [Specific change description]

## Implementation Sequence
1. [First step — file path and what changes]
2. [Second step — file path and what changes]
3. [Third step — file path and what changes]

## Edge Cases & Risks
- [Risk 1]: [Mitigation approach]
- [Risk 2]: [Mitigation approach]

## Verification
[The single command or sequence to run to confirm everything works]

计划文件的硬性规则：

• 不要编写超过一行的 Context、Background 或 Overview 章节。用户刚刚已经说明了需求。
• 不要复述用户的请求。不要撰写说明性段落。
• 不要列出多个备选方案——只呈现推荐方案。
• 列出要修改的文件路径，以及每个文件的改动内容（每个文件一条项目符号）。
• 使用 file:line 标注可复用的现有函数。
• 以唯一的验证命令结尾。
• 严格限制：40 行。 如果计划更长，请删除说明文字，而不是文件路径。
• 计划长度与拒绝率：少于 2K 个字符的计划，拒绝率为 20%；超过 20K 个字符的计划，拒绝率为 50%。保持精简。

---

阶段 5：验证与审批

目标： 确保计划正确，并获得用户确认。

1. 阅读计划中引用的每个关键文件——确认路径存在，且函数具有预期的签名
2. 确认实施顺序不存在循环依赖
3. 检查验证命令是否确实能测试这些更改
4. 如果使用了多个视角，综合 Plan Agent 的输出——选出最佳方案，并用一句话说明原因
5. 向用户展示最终计划

然后直接询问：“准备执行此计划，还是需要修改？”

不要问“这样可以吗？”或“有什么想法吗？”——要直接、具体。不要使用 AskUserQuestion 询问是否批准计划——展示计划本身就是为此。

---

阶段 6（可选）：对抗性验证

使用时机： 对于复杂或高风险的计划（修改 3 个或更多文件、后端/API 更改、基础设施更改）。

计划获批后、执行前，启动一个验证 Agent，对计划进行对抗性审查：

使用以下提示启动一个 Agent（subagent_type: "general-purpose"）：

“你是一名对抗性计划审查员。你的任务是找出此实施计划中的缺陷、遗漏的边界情况、错误假设和风险。阅读 .ultraplan/plan.md 中的计划，然后阅读其中引用的每个关键文件。对于提出的每项文件更改，请验证：(1) 所引用的函数/行是否存在；(2) 提议的更改是否与当前代码兼容；(3) 是否遗漏了任何副作用。报告：计划可靠则为 PASS；若有问题，则为 FAIL 并指出具体问题；若部分内容通过验证、但其他内容无法验证，则为 PARTIAL。”

如果验证器报告 FAIL：修复计划并重新运行验证器。重复此过程，直到通过。 如果报告 PARTIAL：向用户说明已验证的内容，以及无法验证的内容。

---

计划后的执行过渡

用户批准计划后：

1. 最后一次阅读 .ultraplan/plan.md，将其作为执行路线图
2. 按步骤遵循实施顺序——每一步都引用确切的文件和更改
3. 实施后运行计划中的验证命令
4. 如实报告结果——如果验证失败，说明失败情况并提供输出

计划文件应保留在磁盘上，作为双方约定内容的记录。执行后不要删除它。

---

复杂度分级

任务规模	探索 Agent 数量	计划 Agent 数量	访谈深度	时间
简单（1-2 个文件，方案明确）	0-1	0	轻量——1-2 个问题	5-10 分钟
中等（3-5 个文件，存在一些不确定性）	1-2	1	适中——3-5 个问题	15-20 分钟
复杂（许多文件，涉及架构决策）	2-3	1-2（不同视角）	深入——多轮	25-35 分钟
重大重构（涉及多个方面，风险高）	3	2-3（不同视角）	详尽	35-45 分钟

**仅对真正简单的任务完全跳过 Agent：**修正拼写错误、单行更改、简单重命名。

---

反模式

在生产环境规划系统中观察到的真实故障模式及其数据指标：

1. 虚假宣称已完成：绝不要在未运行测试的情况下说“所有测试均已通过”。如果未验证，请明确说明，而不要暗示成功。
2. 计划臃肿：优质计划的平均长度约为 6,200 个字符。超过 20K 的计划有 50% 的拒绝率。删减文字，保留文件路径。
3. 虚构文件引用：引用不存在的函数或文件。第 5 阶段的验证会捕获此类问题，绝不要跳过。
4. 过度服从：如果发现请求中存在误解，或任务相关代码中有 Bug，请指出。你是协作者，不是执行者。
5. 过早收敛：不要在第 1 阶段敲定计划。先探索，之后再收敛。
6. 询问可查明的问题：绝不要向用户询问通过阅读代码就能确定的信息。
7. 备选方案瘫痪：提出你推荐的方案，而不是罗列选项。你是架构师，应做出决定。
8. 范围蔓延：不要添加超出要求的功能、重构或改进。修复 Bug 不需要顺带清理周边代码。

---

结束本轮

本轮只能通过以下方式结束：

• 使用 AskUserQuestion 收集更多信息（规划阶段）
• 提交最终计划供审批（第 5 阶段收敛后）

绝不要只以文字结束本轮。务必使用工具或提交计划。

重要： 仅在澄清需求或选择方案时使用 AskUserQuestion。绝不要通过 AskUserQuestion 提出“这个计划可以吗？”“要继续吗？”“你觉得这个计划怎么样？”“开始前还需要修改什么吗？”之类的问题——提交计划本身就是在征求审批。