plan

计划

制定以项目原则为依据的实施计划。将计划写入 brain/plans/。不要实施任何内容——计划就是交付物。

自主会话模式

当此技能在非交互式 Noodle 执行会话中运行时（例如 Cook、Oops 或 Repair）：

• 跳过步骤 2（AskUserQuestion）——初始提示已完整定义范围。
• 跳过步骤 6 的暂停——写好计划并提交，发出 stage_yield（见步骤 6），然后结束会话。不要等待人工审核。
• 步骤 4（find-skills）——无需确认即可自主安装技能。

其他步骤照常执行。

使用 Tasks 跟踪进度。 为每个步骤创建一个任务（TaskCreate），开始时将其标记为 in_progress，完成后标记为 completed。每完成一个步骤后检查 TaskList。

步骤 0 — 评估复杂度

在运行完整规划工作流之前，先评估此任务是否确实需要计划：

极小型任务（1–2 个文件，方案显而易见）： 告知用户此任务不需要计划，并建议直接实施，不必使用计划技能。到此停止——不要实施。

需要规划（继续执行步骤 1）：

• 更改涉及 3 个或更多文件，或引入新架构
• 存在多种可行方案，需要用户权衡
• 任务范围不明确，或涉及跨领域问题
• 用户明确要求制定计划

步骤 1 — 加载原则

阅读 brain/principles.md。遵循所有 [[wikilink]]，并阅读每个链接指向的原则文件。这些原则将指导计划中的所有决策——在计划概述和阶段文件中按名称引用它们。

不要跳过此步骤。不要依赖记忆中的原则内容——每次都要重新阅读。 步骤 5b 的自检会确认引用存在。

步骤 2 — 明确范围和约束

使用 AskUserQuestion 在探索代码库之前消除歧义：

• 哪些内容属于范围，哪些明确不在范围内？
• 是否存在约束（依赖项、平台要求、需要保留的现有模式）？
• 怎样才算“完成”？

提出带有具体选项的问题。如果请求已经明确，简要确认范围边界后继续。

步骤 3 — 使用子 Agent 探索上下文

始终通过 Task 工具将探索工作委派给子 Agent。不要在主上下文中大规模探索代码库。

启动探索 Agent（subagent_type: Explore）来：

• 阅读受影响区域的现有代码
• 识别模式、惯例和依赖项
• 梳理与更改相关的架构
• 查找测试、类型和相关基础设施

调查相互独立的领域时，并行运行多个 Agent。对于大规模探索，使用团队。

步骤 4 — 收集领域技能

匹配已安装的技能并发现缺失的技能。请参阅 references/domain-skills.md 中的路由表和发现工作流。

步骤 5 — 编写计划

使用文件工具创建计划。完整目录结构、概述/阶段文件格式、验证策略和 CLI 脚手架步骤，请参阅 references/templates.md。

阶段规模

• 每个阶段处理 1 个函数/类型及其测试，或 1 个 Bug 修复——不要按“一个文件”或“一个组件”划分（范围太易变）
• 尽可能将每个阶段涉及的文件控制在 2–3 个以内
• 优先采用 8–10 个较小阶段，而不是 3–4 个大型阶段——小阶段能保留未来的选择空间
• 如果某个阶段列出超过 5 个测试用例或超过 3 个函数，应将其拆分

重新设计检查

对于涉及现有代码的更改，应从第一性原理出发进行重新设计：

“如果从零开始构建，并满足此需求，我们会构建什么？”

不要将更改生硬地拼接到现有设计上——应进行整体重新设计。

方案替代项检查

对于架构决策，在概述的“约束”部分简要列出 2–3 种方案。说明选择了哪一种以及原因。这样可以避免过早定案，并记录探索过的设计空间。请参阅 brain/principles/exhaust-the-design-space.md。

更新计划索引和待办事项

写入计划后，确认以下两项均已存在：

• brain/plans/index.md 中有 - [[plans/NN-plan-name/overview]]
• brain/todos.md 的待办事项中有该计划的维基链接

新增待办事项：读取 ``，追加 N. [ ] description [[plans/NN-plan-name/overview]]，递增 next-id。不要编辑 brain/index.md ——自动索引钩子会维护它。

归档已完成的计划

将目录移至 brain/archive/plans/，更新 brain/plans/index.md，并通过 todo 技能将待办事项标记为已完成。

第 5b 步——自检

写完所有计划文件后，继续之前请核实以下三项约束。发现任何违规之处都要先修正。

**引用的原则：**概述必须通过 [[wikilink]] 至少引用 2 条知识库原则。如果没有，请重新阅读 brain/principles.md，并将最相关的原则补充到概述的设计决策中。

**阶段规模：**检查每个阶段。如果某个阶段涉及超过 3 个文件，或列出超过 5 个测试用例，就将其拆分成更小的阶段。统计“变更”下列出的文件数——如果超过 3 个，该阶段就太大了。

**阶段中不得包含代码：**阶段文件不得包含 Go/TS/Python 代码块。可以命名类型和函数，但不要定义它们。阶段内容应像是给资深工程师的简要任务说明，而不是差异或实现规范。如果发现代码块，请用描述预期结构的文字替换。

第 6 步——展示并交还

总结计划：列出各阶段、范围边界、适用技能和验证方法。请用户审阅 brain/plans/ 中的计划文件。

发出 stage_yield，表示交付内容已完成：

noodle event emit --session $NOODLE_SESSION_ID stage_yield --payload '{"message": "Plan written to brain/plans/NN-slug-name/overview.md"}'

这会告知 Noodle 后端当前阶段的工作已完成，即使 Agent 进程尚未退出也是如此。否则，只有在进程正常退出后，阶段才会完成。

**到此为止。**不要开始实施。由用户决定何时以及如何执行该计划。