plan

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 必须满足：

• 用户能读懂需求文档。
• 开发者能按设计改代码。
• 执行者能按任务推进。
• 验证者能按验证计划判断完成。
• 后续接手者能从收口记录知道事实。

说不清，先别改。