project-plan

name	project-plan
description	只在用户显式调用时触发

Project Plan

核心判断

先判断当前对话模式，再决定计划产物放在哪里：

• 如果最新开发者上下文显示 Collaboration Mode: Plan，可以创建正式实施计划，并使用 update_plan 或当前环境提供的计划工具跟踪步骤。
• 如果当前不是计划模式，不在回复中输出正式实施计划；只做需求深挖、上下文澄清、前置理解草稿和事实取证，并把需要沉淀的阶段性计划材料维护到 PLAN.md。
• PLAN.md 是非计划模式下唯一允许修改的计划材料文件，可记录前置理解、已确认事实、缺口、待确认事项、草案步骤和清理范围；它不属于长期权威文档，也不能替代计划模式中的正式计划。
• 非计划模式下允许读取项目文档、源码、测试、配置和本地工具输出进行计划前取证；取证结果只能用于澄清需求、暴露缺口、维护 PLAN.md 或提示用户切换计划模式。
• 除维护 PLAN.md 外，非计划模式不得修改代码、长期文档或其它任务资产，不得跑验证，不得调用会改变项目状态的执行类工具。
• 不要在默认模式下用普通回复冒充计划，也不要借编辑 PLAN.md 顺手实施方案。

创建流程

在计划模式中，结合用户请求、已有上下文和仓库约束创建计划：

1. 明确最终目标、交付物、边界条件和不能做的事。
2. 先执行上下文回扫，并把「计划前置理解摘要」作为计划开头的第一个组成部分；简单任务可以压缩，复杂任务必须完整展开。
3. 再收集足够事实制定具体实施步骤；上下文不足时，主动到仓库文档、现有代码、测试、配置和本地工具输出中取证。
4. 确认改动涉及的层级、状态拥有者、唯一写入口、跨层载荷和验证入口。
5. 若仍存在会影响计划方向、且无法从上下文或项目现状推断的信息，先向用户提问，暂停正式计划。
6. 使用 update_plan 工具或当前环境提供的创建计划工具生成计划；计划第一项必须承载前置理解，并保持后续状态可跟踪。
7. 把清理施工现场列为独立步骤，并明确列出需要清理的目标、范围、处理方式和保留理由。

计划前置理解摘要

正式计划必须以「计划前置理解摘要」开头，把隐式理解变成可检查的事实；它是计划的一部分，不是计划外的说明块。按任务复杂度调整长度：

任务复杂度	摘要要求
简单任务	用 3 到 5 行确认目标、边界和验证入口。
中等任务	输出完整摘要，每项保持简短。
复杂任务	输出完整摘要，并列出需求来源、已确认路径和未决问题。
信息不足任务	先输出摘要和缺口，再提问；不得直接生成正式计划。

摘要至少覆盖：

• 最终目标：用户真正要达成什么，不只复述原话。
• 已确认需求点：对话中用户明确提出、确认或修正过的需求。
• 已确认实现路径：已经讨论并确认过的做法、技术路线、范围边界和不采用的路径。
• 禁止事项 / 不做范围：用户明确排除的内容，以及仓库规则禁止的行为。
• 涉及项目现实：会影响实现的架构层级、权威文档、文件候选、状态归属、验证入口。
• 仍缺信息：无法从上下文和项目现状推断，且会影响计划的问题。
• 提问清单：只问真正阻塞计划质量的问题；能靠取证解决的不要问用户。

上下文回扫

为避免遗漏前文已经确认的需求，生成摘要前必须执行三遍回扫：

回扫轮次	检查对象	产出
第 1 遍：显性需求	用户明确说“要 / 不要 / 必须 / 禁止 / 确认”的内容	已确认需求点
第 2 遍：路径承诺	对话中已经确认的实现路径、技术选择、范围边界	已确认实现路径
第 3 遍：隐性约束	AGENTS、技能规则、项目文档、已有架构带来的限制	项目约束与不做范围

正式计划中的每个实施步骤都应该能追溯到三遍回扫得到的事实；追溯不了的步骤通常说明它是猜测，应删除、取证或提问。

事实获取

计划中的事实不只来自对话上下文。制定计划前必须按任务风险逐级补齐事实，直到足以写出“基于事实”的步骤：

1. 先使用对话中已经给出的需求、约束、错误信息和用户确认过的事实。
2. 再读取项目内的权威文档、相关源码、测试、配置、脚本和历史约定，确认现状而不是凭目录名推断。
3. 若仍缺少关键事实，运行只读或低风险的本地检查命令获取证据，例如定位引用、查看类型定义、读取测试入口或确认工具脚本。
4. 涉及第三方库、框架、CLI、云服务或普通网络信息时，使用项目规定的文档检索或网络检索工具确认最新事实。
5. 只有当事实无法从本地项目或可靠资料中获得，且不同答案会显著改变计划时，才向用户提问；提问前先说明已经确认了什么、仍缺什么。

凡是会决定计划主路径、文件范围、状态归属、唯一写入口、跨层载荷或验证入口的事实，都必须在正式计划成形前完成取证。不要把这些事前准备包装成实施步骤；已确认事实应汇入计划开头的「计划前置理解摘要」。

只有实施过程中才可能暴露、或需要改动后才能验证的事项，才可以写入计划中的检查、验证或回看步骤。

缺口门禁

如果事实不足以决定实现路径，不要把猜测写成执行步骤。按以下门禁处理：

情况	处理方式
缺口可从仓库文档、源码、测试、配置中确认	先自行取证，不问用户。
缺口可从已有对话合理推断，且风险低	写明推断依据，继续计划。
缺口无法从上下文或项目现状推断，且会改变方案	先问用户，暂停正式计划。
缺口不影响当前计划主路径	放入“非阻塞假设 / 后续确认”，继续计划。

提问前先说明已经确认了什么、仍缺什么、为什么这个缺口会改变计划。

取证展示粒度

取证结果要透明但克制：

内容	展示方式
读过哪些权威文档 / 源码 / 测试 / 配置	简短列出。
确认到的关键事实	写入计划开头的「计划前置理解摘要」。
影响路径选择的证据	在复杂任务步骤的 依据 字段中引用。
大段文件内容 / 普通搜索结果	不展示。
与计划无关的旁支发现	不展示；除非构成风险。

计划质量

计划必须立足现实，而不是想象或猜测：

• 每个步骤都应该能被执行者直接落地，避免“完善逻辑”“处理问题”这类空泛表述。
• 每个步骤都必须写出 目的、实施方案 和 阶段成果，不能只用一句标题或简单编号带过。
• 复杂任务的每个步骤必须额外写出 依据，说明它来自哪些已确认需求、实现路径或项目事实。
• 不确定的事实必须先调查，再实现；不要把未经确认的设计、文件位置、状态归属或验证入口当作既定事实。
• 计划中的实现步骤必须能追溯到已确认事实；若只能写出“可能需要”“预计会”，说明事实仍不足，应继续取证。
• 步骤粒度按工作量划分：一个步骤应有清晰产出，但不要细到单个无意义编辑动作。
• 跨层任务要显式列出阅读文档、定位权威来源、实现、验证和文档同步。
• 验证步骤要写出具体命令或检查对象；如果验证条件未知，先列出确认验证入口的步骤。
• 计划应覆盖收尾动作：回看 diff、确认命名与边界、按目标和范围清理废弃资源、说明未执行或失败的验证。

步骤描述格式

计划中的每个步骤都必须使用同一结构，确保执行者无需重新猜测意图：

1. 步骤名称
   - 依据：复杂任务必填，说明来自已确认需求点 A、实现路径 B、项目事实 C。
   - 目的：说明这一步要消除什么不确定性、建立什么前提，或完成什么可交付变化。
   - 实施方案：
     1. 写出第一项可执行动作。
     2. 写出第二项可执行动作。
     3. 必要时继续列出检查对象、文件、命令或决策点。
   - 阶段成果：说明这一步完成后会得到什么事实、代码改动、测试结果、文档更新或决策结论。

规则：

• 实施方案 至少包含 2 个可执行子项；复杂步骤可以扩展到 5 个左右，但不要堆砌无意义动作。
• 简单和中等任务可以省略逐步 依据 字段，但复杂任务、争议路径和多方案取舍必须写出。
• 目的 要解释为什么这一步存在，不要复述步骤标题。
• 阶段成果 必须可检查，例如“确认权威写入口是某文件中的某类”“得到待修改文件清单”“通过某条验证命令”。
• 如果某一步只是等待用户确认，也要写明确认项、确认方式和确认后进入哪个后续步骤。

推荐结构

优先使用 5 到 8 个步骤。简单任务可以更短，跨层任务可以更长；输出时按“步骤描述格式”展开每一步即可，示例只保留骨架：

1. 计划前置理解摘要
2. 梳理目标与约束
3. 收集上下文、文档、代码和工具输出中的事实
4. 补齐仍缺失的关键事实，必要时查官方资料或向用户提问
5. 定位权威状态、唯一写入口和验证入口
6. 实施最小闭环改动
7. 清理施工现场
8. 执行验证
9. 回看 diff 并同步文档

清理施工现场

清理步骤不能省略，也不能只写原则。计划中必须明确列出本次需要清理的目标和范围；没有对应清理项时，也要写明“已检查，无需清理”的依据。

清理计划建议使用以下结构：

- 清理目标：具体到文件、目录、类型、函数、样式类、本地化键、测试资产或文档段落。
- 清理范围：说明只检查或修改哪些模块、页面、测试、配置或文档，不触碰哪些无关区域。
- 处理方式：删除、合并、迁移、重命名、保留兼容层或仅记录。
- 保留理由：若暂不清理，说明仍被谁使用，以及后续移除条件。

根据任务实际影响，至少检查这些目标类型：

• 代码资源：不再使用的代码分支、变量、函数、类、类型、常量、导出和导入。
• 前端资源：不再使用的组件、样式类、设计 token、页面局部状态、路由入口和图标资源。
• 文案资源：废弃文案、本地化键、错误信息、提示语和文档碎片。
• 测试资源：过期测试、夹具、快照、mock、脚本参数和临时测试文件。
• 配置资源：废弃配置项、环境变量、构建脚本、CLI 参数和工具入口。

边界要求：

• 不做与本任务无关的大范围重构；发现无关脏改时只记录，不擅自回滚。
• 保留必要兼容层时，必须说明兼容对象、当前调用方和后续移除条件。
• 清理范围必须和已确认事实一致，不能凭猜测删除看似无用的资源。