| name | plan |
| description | 用于写作和执行单文件 plan.md。适用于中大型开发、跨模块重构、生产级验收、恢复演练、架构硬化、评测闭环，以及任何不能靠一次小补丁完成的任务；要求把 plan.md 写成需求、事实、失败测试、目标、设计、任务、验证和收口合一的规格驱动执行合同。 |
Plan
plan.md 是单文件规格驱动执行合同。
一个文件管总。
它不是草稿。不是备忘。不是任务碎片。不是写一点算一点。
它同时承担：
- 需求文档
- 当前事实
- 失败测试
- 目标合同
- 设计合同
- 实施任务
- 验证计划
- 收口记录
没有完整 plan.md，不做大改。
执行中发现事实推翻计划，先更新 plan.md，再继续。
核心原则
- 用户输入是线索，不是结论。
- 用户建议的技术方案不能直接变成目标。
- 先把用户话术翻译成可验证问题，再决定方案。
- 计划只写当前要交付的事实主干。
- 不写旧兼容、假过渡、历史残留、临时补丁路线。
- 一个任务只维护一个总计划文件，除非用户明确要求多文档。
- 需求写给用户看，设计写给开发看，任务写给执行者看，验证写给事实看。
- 机器事实和模型判断分开写。
- 每个结论必须能被文件、命令、测试、输出或明确证据支撑。
写作顺序
必须按这个顺序写 plan.md。
1. 需求文档
写用户能理解的非技术说明。
必须回答：
- 用户真正要解决什么实际问题。
- 谁会使用这个能力。
- 用户完成任务时应该看到什么体验。
- 当前范围包含什么。
- 当前范围不包含什么。
- 怎样算业务上完成。
要求：
- 写 WHAT 和 WHY。
- 不写框架、文件、函数、数据库、接口等实现细节。
- 不用用户原话堆砌。
- 不把“用户要求的做法”写成“业务需求”。
2. 当前事实
写已经确认的仓库事实。
必须覆盖：
- 当前代码事实。
- 当前测试事实。
- 当前文档事实。
- 当前配置事实。
- 当前命令输出事实。
- 当前已存在能力。
- 当前缺口。
- 当前未知点。
要求：
- 只写证据支持的事实。
- 旧提交、外部项目、用户偏好只能作为证据来源，不能自动成为当前事实。
- 未确认内容写成线索或未知点。
3. 失败测试
先写什么会失败。
失败测试可以是：
- 自动测试。
- 类型检查。
- 构建命令。
- CLI 输出检查。
- 日志检查。
- 状态文件检查。
- 真实用户路径演练。
要求：
- 每条失败测试必须对应真实产品行为或真实工程风险。
- 不测试口号。
- 不测试纯装饰。
- 不测试没有产品意义的措辞。
- 能自动测就自动测；不能自动测就写清楚手动检查命令和期望输出。
4. 目标
写最终要交付的可验收结果。
目标来自需求、事实和失败测试的收束，不来自用户一句话。
必须回答：
- 用户路径完成到哪里。
- 代码主链路接到哪里。
- 状态和记录落在哪里。
- 输出呈现到哪里。
- 测试和文档同步到哪里。
要求：
5. 不做范围
写清楚本次不做什么。
要求：
- 不做范围必须服务边界清晰，不能成为逃避交付的借口。
- 不写假兼容。
- 不写“以后可能需要”的 speculative 内容。
- 不保留当前产品没有的能力入口。
6. 设计
写技术设计。
必须覆盖：
- 主链路：输入 -> 判断 -> 状态 -> 执行 -> 输出 -> 记录。
- 模块边界。
- 文件职责。
- 状态归属。
- 数据或事件流。
- 错误、恢复、中断、重试边界。
- 与现有架构的关系。
- 影响的测试和文档。
要求：
- 设计必须能指导代码修改。
- 设计必须解释为什么这样改。
- 不写为了显得高级的抽象。
- 不写没有落点的架构词。
- 如果边界一句话说不清，先别写任务。
7. 实施任务
写可执行 checklist。
每项必须是动作。
每项必须能判断完成或未完成。
每项必须尽量包含：
任务顺序按主链路组织，不按想到哪写到哪。
大任务要拆到能独立验证；小任务不要为了拆而拆。
8. 验证计划
写最后怎么证明完成。
必须包含：
- 相关局部测试。
- 完整验证命令。
- 构建或安装检查。
- CLI/UI/远程入口检查。
- 恢复或中断演练。
- 文档同步检查。
- 未验证内容。
- 剩余风险。
9. 收口
任务结束时更新。
必须回答：
- 目标是否完成。
- 失败测试是否变绿。
- 改了哪些文件。
- 跑了哪些验证。
- 哪些内容没有验证。
- 剩余风险是什么。
- 是否需要 commit 或 push；只有用户明确要求时才执行。
执行规则
- 写完计划，再动手。
- checklist 必须随进度更新。
- 新事实推翻计划，先改计划，再继续。
- 不用口头解释替代计划更新。
- 不偷偷偏离计划。
- 不把旧能力、旧状态、旧数据写成当前产品事实。
- 不为了套模板制造多余章节；无关章节写明“不适用”和理由，或删掉。
- 不为了简短牺牲边界、失败测试和验证。
- 提出一个方向后，要把该方向一次性做成完整闭环：research、设计、实现、测试、文档同步、验证和收口都完成。
- 不把方向拆成反复让用户推动的小步。除非遇到客观阻塞，否则同一方向做到可交付、可验证、可长期保留。
- 计划的任务边界必须足够完整，避免今天补一点、明天再补同一主线的尾巴。
标准模板
# [任务名] Plan
## 1. 需求文档
## 2. 当前事实
## 3. 失败测试
## 4. 目标
## 5. 不做范围
## 6. 设计
## 7. 实施任务
## 8. 验证计划
## 9. 收口
完成标准
一个合格的 plan.md 必须满足：
- 用户能读懂需求文档。
- 开发者能按设计改代码。
- 执行者能按任务推进。
- 验证者能按验证计划判断完成。
- 后续接手者能从收口记录知道事实。
说不清，先别改。
