Plan Mode

Plan Mode 是 North Coder 的内建 Agent profile，适合在执行前先让 Agent 阅读代码、理解约束、形成一份可审阅的实现计划。它不会直接修改项目文件。

Plan Mode 的目标是把“探索和规划”与“真正执行”拆开。这样你可以先确认方案，再决定是在当前会话继续，还是交接到新的执行会话。

什么时候使用

适合使用 Plan Mode：

• 需求已经基本明确，但实现路径还需要代码调研。
• 任务不小，直接让 Agent 写代码风险较高。
• 你想先看到影响范围、步骤和验证方案。
• 希望执行会话从一份精简计划开始，而不是带着完整探索历史继续。
• 只需要一次性实现计划，不需要正式 RFC 设计文档。

不建议使用 Plan Mode：

• 单文件小改动。
• 明确的文案、样式或配置调整。
• 需要正式设计记录、子任务状态和长期追踪的功能。
• 用户已经准备好让 Agent 直接实现。

这类更小的任务可以直接用 General；需要正式设计和任务拆分时使用 RFC Mode。

基本流程

1. 进入目标工作区。
2. 在会话里选择 Plan Mode Agent profile。
3. 描述任务目标、范围、限制和验证要求。
4. Plan Mode 会只读探索代码库。
5. 如果仍有关键意图不明确，它会向你提问。
6. 它会创建并增量更新 plan 文件。
7. 计划完成后，聊天流中会展示 plan 内容。
8. 你选择 Hand Off、Approve，或直接继续输入反馈让它修改计划。

Plan 产物

Plan Mode 会把计划写到当前工作区的专用目录：

.north-coder/plans/

文件名会带有数字 ID 和短名称，例如：

1-implement-search-feature.md

这个 plan 是一次性的实施文档，不会写入 docs/rfcs/，也不会成为正式 RFC。

只读探索

Plan Mode 没有通用写文件能力。它可以读取文件、搜索代码、查看目录、运行非变更类检查命令，并使用专用工具写入 plan 文件。

它可以做：

• 阅读源码和文档。
• 搜索文件内容。
• 查看 Git 历史或项目结构。
• 运行测试、lint 或 dry-run 类检查来理解现状。
• 使用 write_plan 创建计划。
• 使用 update_plan 增量修改计划。

它不应该做：

• 修改项目源码。
• 运行会写入项目文件的格式化或生成命令。
• 安装依赖。
• 提交、推送或合并代码。

审阅计划

计划完成后，Plan Mode 会调用 propose_plan，界面会渲染计划快照，并在输入框上方展示操作栏。

你可以检查：

• 计划是否准确理解目标。
• 是否列出了关键文件和模块。
• 是否说明了实现步骤。
• 是否包含验证命令或手工检查。
• 是否还有未说明的风险或假设。

如果计划不够好，直接在输入框里反馈。Plan Mode 会更新 plan，然后再次提交给你审阅。

Hand Off 和 Approve

通常推荐中等复杂度任务使用 Hand Off。这样执行会话只需要读取 plan 文件，不需要携带完整探索历史。

和 RFC Mode 的区别

简单判断：需要“设计文档和长期状态”时用 RFC Mode；需要“先看计划再开工”时用 Plan Mode；任务足够小时直接用 General。

写好 Plan Mode 任务

第一条消息建议包含：

• 目标：最终希望完成什么。
• 范围：哪些模块、页面或命令相关。
• 限制：不要改哪些东西，或者必须沿用哪些约定。
• 验证：希望执行阶段跑什么检查。
• 输出偏好：计划需要重点说明哪些风险或决策。

示例：

请用 Plan Mode 调研文档站搜索实现，给出一个修复中文搜索命中率的实现计划。
不要修改代码，计划里要列出涉及文件、验证命令和可能的兼容性风险。

常见问题

Plan Mode 会改我的代码吗？

不会。Plan Mode 没有通用写入工具，只能写入 .north-coder/plans/ 下的计划文件。

计划在哪里？

计划文件位于当前工作区的 .north-coder/plans/ 目录。执行阶段会根据 plan ID 找到并读取对应文件。

可以多轮修改计划吗？

可以。看到计划后直接输入反馈，Plan Mode 会用 update_plan 修改计划，再重新提交给你审阅。

什么时候不该用 Plan Mode？

任务非常明确且很小的时候，不需要 Plan Mode。直接用 General 执行会更快。