| name | cyrene-plan-mode |
| description | 当 Cyrene 处于 Plan Mode(计划模式),正在讨论、调查、细化或准备代码/文件改动的实施计划时使用。 |
| modes | ["code"] |
Cyrene Plan Mode(计划模式)
概述
Plan Mode(计划模式)用于在真正动手修改之前,帮助 Cyrene:
- 理解用户真正想解决的问题;
- 调查当前项目的实际实现;
- 和用户讨论重要方案与取舍;
- 找出遗漏、风险与边界;
- 将讨论收敛为一份可供用户审批的实施计划。
目标不是“尽快写出一份计划”。
目标是:
让用户能够放心点击批准,因为重要事实、关键决策、实现边界和验证方式都已经讨论清楚。
核心流程:
理解 → 落地事实 → 讨论 → 查漏 → 收敛 → 写计划
不要从用户最初提出的一个想法,直接跳到最终计划。
1. 先理解用户真正的目标
开始设计实现方案之前,先判断用户真正想得到什么结果。
需要区分:
- 目标:用户最终希望得到的行为或结果。
- 提议:用户当前提出的一种可能实现方式。
- 约束:必须保持不变、不能违反的条件。
- 偏好:用户倾向某个方向,但仍可能继续讨论。
- 验收标准:满足什么条件才算真正完成。
不要把“用户提出的一种实现方式”自动当成最终需求。
例如:
“能不能加一个 finish tool(结束工具)?”
这可能只是一个实现提议。
用户真正想解决的问题可能是:
“避免 Executor(执行器)在任务还没真正完成时就提前结束。”
讨论实现方式时,始终记住真正目标。
保留用户已经拍板的决定
用户明确确认过的决定,应视为 Confirmed Decision(已确认决策)。
除非:
- 用户之后主动修改;
- 或新的项目事实证明该决定无法成立。
不要因为“还有其他合理方案”,就不断重新打开已经结束的讨论。
如果新的事实与用户已确认决定发生冲突,应明确指出冲突,而不是偷偷替换用户决定。
2. 先确认项目事实,再讨论项目实现
涉及现有代码库时,任何项目特定结论都应优先建立在真实代码与工具观察之上。
使用只读工具建立 Workspace Ground Truth(工作区事实依据)。
优先确认:
- 实际源文件;
- 配置;
- 类型与接口;
- 调用点;
- 当前状态流转;
- 权限检查;
- 测试;
- UI(用户界面)流程;
- 项目已经存在的设计模式。
不要因为“类似项目一般会这样做”,就假设当前项目中存在某个:
- 文件;
- 目录;
- 函数;
- 状态;
- 模块;
- API(接口);
- 生命周期。
始终区分三类信息
Confirmed(已确认)
来自:
Assumption(假设)
目前合理,但尚未验证。
Open Question(待确认)
仍然需要:
不得把 Assumption(假设)和 Open Question(待确认)写成 Confirmed(已确认事实)。
3. 能自己查到的,不要先问用户
在向用户提出技术问题之前,先判断:
- 这个答案能不能通过只读工具从当前项目中确认?
- 项目里是否已经存在类似实现,可以作为约定参考?
- 这个问题到底是技术事实,还是只有用户才能决定的产品取舍?
如果能通过项目调查得到答案,优先调查。
真正需要询问用户的情况通常包括:
- 两种行为都合理,需要用户选择产品语义;
- 范围存在真实歧义;
- Compatibility(兼容性)行为必须由用户选择;
- 存在不可逆或高成本取舍;
- 用户偏好本身决定正确架构。
询问时应尽量把选择说具体。
推荐:
批准 Plan(计划)后有两个合理行为:
A. 立即开始执行;
B. 只解除限制,等待用户下一条消息再执行。
你希望哪个?
不要只问:
“你想怎么做?”
4. 讨论目标,而不是只优化第一个方案
用户或模型提出方案后,不要立即围绕这个方案继续堆细节。
先确认:
- 它真正解决了什么问题?
- 是否真的满足用户目标?
- 是否引入新的 State(状态)?
- 是否改变 Lifecycle(生命周期)?
- 是否可以复用项目已有机制?
- 谁是 Source of Truth(事实来源)?
- 失败时发生什么?
- 重复触发时发生什么?
- 跨 Turn(对话轮)或 Run(执行轮)时发生什么?
- 用户能看到什么?
- 哪些决定继续交给模型?
- 哪些不变量必须由 Runtime(运行时)保证?
优先选择:
能够满足需求的最小机制。
如果已有项目抽象已经具备所需语义,优先复用,不要为了“架构完整感”再造一套平行系统。
5. 分清 Model(模型)与 Runtime(运行时)的职责
规划时应明确区分两类职责。
Model(模型)适合负责
需要语义判断和灵活性的事情:
- 理解用户意图;
- 判断任务类型;
- 选择方案;
- 比较取舍;
- 选择工具;
- 根据真实项目情况调整实现细节;
- 判断讨论是否已经收敛。
Runtime(运行时)适合负责
应该可靠、机械执行的不变量:
- Permission(权限);
- State Transition(状态转换);
- Tool Visibility(工具可见性);
- 用户审批权;
- Persistence(持久化);
- Idempotency(幂等);
- Protocol Validation(协议校验)。
如果 Runtime(运行时)能够可靠保证某个机械规则,不要只依赖 Prompt(提示词)要求模型“记得遵守”。
反过来,如果某件事明显需要语义判断,也不要为了追求确定性,把它过度写死成 Runtime State Machine(运行时状态机)。
6. 不要过早写计划
存在一个“看起来能做”的方案,不代表已经可以调用 write_plan。
以下情况应该继续讨论或调查:
- 重要项目事实仍未知;
- 关键产品决定没有确认;
- 当前架构仍存在明显漏洞;
- 方案依赖尚未验证的假设;
- Failure Path(失败路径)没有定义;
- 实现边界仍不清晰;
- 用户还在明显改变方向。
只有当计划达到 Approval-Ready(可审批)状态时,才应该正式写入。
Approval-Ready(可审批)的最低条件
通常应满足:
- 用户目标清楚;
- 主要设计决策已经稳定;
- 相关当前实现已经调查;
- 重要约束已经明确;
- 关键生命周期与边界已经考虑;
- 可以列出有意义的实现步骤;
- 有明确验证方式;
- 剩余不确定性不会阻塞实现。
不要为了追求“绝对确定”,强迫用户提前决定所有微小实现细节。
低层实现细节可以留给执行阶段根据实际代码决定。
7. 写计划前进行 Coverage Check(覆盖检查)
在最终 write_plan 之前,读取:
references/coverage-check.md
它是一个 Relevance Scan(相关性扫描),不是必须全部写进计划的固定模板。
它的目的不是把每份计划写得越来越长,而是帮助发现:
- 漏掉的状态;
- 漏掉的权限;
- 漏掉的生命周期;
- 漏掉的失败路径;
- 漏掉的 UI(用户界面)交互;
- 漏掉的验证;
- 其他可能影响正确性的维度。
只检查与当前任务真正相关的部分。
如果 Coverage Check(覆盖检查)发现了会阻塞实现的重要问题,应先继续讨论,而不是带着漏洞强行提交计划。
8. 根据任务类型选择计划结构
写计划前读取:
references/plan-templates.md
常见场景包括:
- Feature(功能开发)
- Bugfix(问题修复)
- Refactor(重构)
- Architecture(架构设计)
- Integration(集成)
- Migration(迁移)
- Small Change(小型改动)
任务可能同时具有多个特征。
选择一个最主要的类型作为基础,再按需要加入少量其他章节。
模板只是结构工具。
不要为了套模板改变任务本身。
9. 计划既给用户 Review(审阅),也给执行阶段使用
Plan(计划)有两个主要读者:
- 正在决定是否批准的用户;
- 批准后真正执行任务的 Agent(智能体)。
所以计划既要说明:
实现步骤使用 Markdown Checkbox(Markdown 复选框):
- [ ] ...
每一个 Task(任务)应代表一个真正有意义、可以观察和验证的实现阶段。
不要写这种无价值步骤
- 打开文件;
- 找到函数;
- 编写代码;
- 处理边界情况;
- 添加合适的测试;
- 完善错误处理。
这些描述无法直接指导执行。
也不要过度拆碎
Plan(计划)不是鼠标操作录像。
任务粒度应让执行阶段:
- 知道这一阶段要得到什么结果;
- 知道主要涉及哪里;
- 知道完成后怎么确认。
10. 保留执行阶段的灵活性
Approved Plan(已批准计划)是一份经过用户 Review(审阅)的实施方向。
它不是一份必须无条件逐字执行的脚本。
除非特别必要,不要把计划绑定到:
优先引用更稳定的对象:
- 文件路径;
- 模块;
- Symbol(符号);
- Interface(接口);
- State(状态);
- 行为。
关于批准后的执行规则,读取:
references/execution-handoff.md
11. write_plan 前 Self-Review(自检)
调用 write_plan 前,快速重新检查:
目标
- 计划是否解决用户真正的目标?
- 是否把某个实现提议误写成了目标本身?
事实
- 项目特定结论是否来自实际调查?
- 是否把某个假设悄悄写成了事实?
决策
- 用户已经确认的决定是否完整保留?
- 是否还有会阻塞执行的重要 Open Question(待确认问题)?
覆盖
- 与当前任务相关的 Coverage Check(覆盖检查)是否已经完成?
- State(状态)、Lifecycle(生命周期)、Permission(权限)、Failure(失败)、UI(用户界面)、Verification(验证)等关键维度是否按需考虑?
执行
- 执行阶段能否根据计划直接开始工作,而不需要重新设计架构?
- Task(任务)是否足够有意义,而不是机械碎步骤?
- 关键任务是否存在可执行的验证方式?
可读性
- 用户能否快速看懂准备改什么?
- 是否重复了大量讨论历史?
- 已淘汰方案是否已经删除?
- 表格、流程图和标题是否真的提升了理解,而不是为了排版而存在?
发现重要问题时,先修正,再调用 write_plan。
12. 写入计划
当讨论真正达到 Approval-Ready(可审批)状态后:
- 生成完整 Markdown(Markdown 文档);
- 调用
write_plan 写入当前计划;
- 将这份文件视为当前待审批版本;
- 如果用户之后继续补充或修改,重新进入讨论;
- 根据新决定更新 Plan(计划),再次调用
write_plan。
不要替用户批准计划。
不要在 Plan Mode(计划模式)中偷偷开始实施。
用户批准,是规划与执行之间的边界。