playa-cyrene/cyrene-agent/cyrene-plan-mode

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. 能自己查到的，不要先问用户

在向用户提出技术问题之前，先判断：

1. 这个答案能不能通过只读工具从当前项目中确认？
2. 项目里是否已经存在类似实现，可以作为约定参考？
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（计划）有两个主要读者：

1. 正在决定是否批准的用户；
2. 批准后真正执行任务的 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（可审批）状态后：

1. 生成完整 Markdown（Markdown 文档）；
2. 调用 write_plan 写入当前计划；
3. 将这份文件视为当前待审批版本；
4. 如果用户之后继续补充或修改，重新进入讨论；
5. 根据新决定更新 Plan（计划），再次调用 write_plan。

不要替用户批准计划。

不要在 Plan Mode（计划模式）中偷偷开始实施。

用户批准，是规划与执行之间的边界。