Plan First Zh

---
name: plan-first-zh
description: 让 agent 在改代码、配置、构建脚本、依赖、对外接口或设计文档之前，先写计划并等用户批准。每个任务写两份文件：给 agent 的详细计划（docs/plan/）和给人读的短计划（docs/human/），短计划借鉴 ASD-STE100 的写法。用于新功能、重构、迁移、依赖或接口改动、多文件修改的开始，以及用户要求先出计划、计划模式或批准后再写代码时。不用于提问、读代码、运行现有测试、改错别字或注释，以及恢复设计行为的小 bug 修复。用户用中文交流时使用本 skill。
license: MIT
metadata:
  author: "Asher"
  homepage: "https://github.com/AsherHou/asd-ste100-for-coding"
---
# 规则：开发前先出计划，批准后再动手

> 本 skill 包含 plan-first 的完整规则。人读版模板是本文件的最后一节；规则里提到 `human-template.md` 时，就用那一节。用户用英文交流时，改用 `plan-first` skill。项目已经通过 `CLAUDE.md` 或 `AGENTS.md` 加载了 plan-first 时，按那一份执行，忽略本 skill。

## 1. 什么时候要先出计划

改动下面这些内容的开发任务，都要先写计划，等用户批准后再执行：代码、配置、构建脚本、依赖、对外接口、设计文档、补丁。

以下情况例外。可以直接做，但要在回复里说清楚改了什么、为什么改：

- **修 bug**：让现有功能恢复到设计预期的行为，而且不改设计、对外接口、配置项、数据格式和依赖。设计预期以现有测试、文档或用户的描述为准。三者都没有或互相矛盾时，按"拿不准"处理。测试以外的改动超过 3 个文件或约 50 行，就按开发任务处理。这两个数字是上限，不是判据，可以按项目调整，但要写成数字。
- **不改东西的工作**：查资料、调研、回答问题、读代码、运行现有的构建和测试命令。
- **不影响行为的小改动**：只改注释或文档里的错别字，或者只改空白和格式，而且不超过 3 个文件。程序输出、界面文字、配置项和标识符里的错别字，按修 bug 处理。全仓库格式化按开发任务处理。
- **用户已说清楚的小改动**：用户的要求已经给出具体改法或具体值。改动还要满足四条：最多改 3 个文件；不新增依赖；不改对外接口、数据和权限；撤销提交能完全回退。另外，执行时不需要 AI 自己做任何用户能看到的取舍。满足时可以直接做，回复里还要写出影响面四行，并按第 4 节提交。只要有一条不满足，或者执行中发现要做用户能看到的取舍，就停下来，按开发任务出计划。
- **用户明确说了"直接做""不用出计划"**。

拿不准属于哪一类时，就当作需要计划，或者先问用户。

## 2. 写两份文档

同一个任务写两份文档，文件名相同，放在不同目录：

| 文档 | 位置 | 读者 |
|---|---|---|
| plan | `docs/plan/YYYY-MM-DD-<任务短名>.md` | 执行任务的 agent |
| human | `docs/human/YYYY-MM-DD-<任务短名>.md` | 用户本人 |

- 项目的 CLAUDE.md 或 AGENTS.md 指定了别的计划目录时，用指定的目录。
- 任务短名用小写英文加连字符，例如 `2026-10-04-contract-freeze.md`。
- 目录不存在就先创建。
- 两份文档开头互相给出链接。

### plan：写给 agent

**目标**：换一个没看过这段对话的 agent，只读这一份文档，也能把任务正确做完。

按顺序包含：

1. **状态行**：草稿 / 待批准 / 已批准 / 执行中 / 已完成，加上版本号和日期。
2. **目标和完成标准**：标准要能检查，比如"某命令输出某结果""某文件存在且通过某测试"。做多个功能时，按功能编号分组，编号和人读版一致。人读版各功能的"做完后"由这些标准改写。
3. **背景与约束**：相关的设计章节、已确认的事实、不能做的事。
4. **方案与关键决策**：选了什么、为什么选；被否掉的方案各用一句话说明原因。AI 自己能定、而且能回退的小选择，也记在这里。
5. **改动清单与影响面**：具体到文件或目录，标明新建、修改还是删除。另外按人读版的四行写影响面：会改、新增、删除、对外行为。对外行为包括安全和权限的变化，没有的项写"无"。人读版的"影响面"由这四行改写，内容一致。
6. **步骤**：编号。每步写清做什么、产出什么、怎么验证（给出命令或检查方法）。
7. **风险处理与停下条件**：每个风险写明放进了哪一处：改方案消除了 / 写成了用户决定 / 写成停下条件。停下条件是执行时一旦遇到就必须停下来问用户的情况。撤销提交也退不回去的改动，写明怎么补救。
8. **不做的事**：明确列出范围外的内容，防止越做越多。
9. **待用户决定的问题**：只限第 2 节 human 部分规定的三类。每个问题注明能否回退，难回退的写代价，并给出推荐选项和理由。
10. **需要用户做的事**：用户必须亲手做的事；没有就写"无"。
11. **变更记录**：每修订一次加一行。
12. **执行记录**：执行时追加，记下偏差和验证结果；完成后写完整结果。

写法：可以写得密，多用列表、路径、命令；不写客套话和重复内容。plan 里没有内容的项只写一行"无"。

### human：写给人

**目标**：用户不读代码，也能判断四件事：这次做什么、会动到哪里、要拍板什么、要亲手做什么。人读版只写这四件事。按惯例办的事写进规则（见第 4 节），不在每份计划里重复。

写之前：

- 先读同目录的 `human-template.md`，按模板填写。
- **不设"风险"一节。** 每份计划都列风险，用户就会习惯性地放过它们。每个风险必须放进一处：
  - 改方案能消除的，就改方案。
  - 要用户取舍的，写成"需要你决定的事"。
  - 执行时才知道的，写进 plan 的停下条件。
- 三处都放不下，说明计划还没想清楚，先不要交给用户。

human 开头依次写：一级标题（一句话说清做什么）、状态行（格式同 plan 第 1 项）、指向 plan 的链接。模板和本节不一致时，以本节为准。

固定结构：标题文字和顺序固定，标题里不写答案。

1. **## 这次要做什么**：按功能写。一次只做一个功能时，固定写三行；做多个功能时，每个功能单独编号，各写自己的目的和做完后，最后统一写一行"不做"。
   - 目的：要解决什么问题，不做会怎样。一到两句。
   - 做完后：用户能检查的结果，一般每个功能 1 到 4 条。所有功能的"做完后"合起来，要涵盖 plan 的全部完成标准。用户提过的要求，注明"这是你的要求"。
   - 不做：最容易被误以为会做的 1 到 3 件事。

   多个功能时的写法：

   ```
   1. **<功能名>**
      - 目的：……
      - 做完后：
        - ……
   2. **<功能名>**（依赖功能 1）
      - 目的：……
      - 做完后：
        - ……

   不做：……
   ```

   - 功能名用"动词 + 对象"，例如"支持中文输入""新增登录交接"。
   - 功能之间有先后依赖的，在功能名后注明"（依赖功能 N）"。
   - 后面各节提到某个功能时，用"功能 N"指代，不再重复功能名。
2. **## 需要你决定的事**：始终保留。只放三类事：
   - 产品方向，或用户能看到的行为上的取舍；
   - 难回退的事；
   - 要花钱、花用户时间、动用户账号的事。

   命名、格式、目录、git 这类约定，按规则办或由 AI 定，记进 plan。

   每项的问句加粗，后面注明"（能回退）"或"（难回退）"。做多个功能时，在括号里加上所属功能，例如"（功能 2，难回退）"。在下面用子项写"推荐："和理由，可以加"备选："。难回退的加"代价："。末行写：全部按推荐，回复"批准"即可开始；要改某项，回复如"1 选备选"，其余按推荐，也即可开始。

   没有要决定的事时，这一节只写一行：无需决定，回复"批准"即可开始。
3. **## 需要你做的事**：只在有时出现，没有就整节不写。写用户必须亲手做的事：什么时候做、做什么、为什么。这类事越少越好，AI 能做的不交给用户。
4. **## 影响面**：固定四行，只写确定的事实，3 项以上就分条。做多个功能时，按整轮合并来写；某一条只属于一个功能的，在行末注明"（功能 N）"。
   - 会改：改哪些部分，约几个文件。
   - 新增：新的文件、依赖、概念或做法，各附一句理由。
   - 删除：删掉的文件、功能或数据；没有就写"无"。
   - 对外行为：用户或其他程序能看到的变化，包括安全和权限的变化；没有就写"无"。

   撤销提交也退不回去的改动（例如删除数据、改外部账号、对外发布），还必须写成"需要你决定的事"。
篇幅和格式：

- **目标是易读，不是压缩。** 一般 300 到 800 字，这不是下限，四件事写完就停。大任务最多 1500 字。内容多就分条写完整，不要压缩句子。超过 1500 字就拆成多个计划。
- 同一件事只写一次。不贴代码，不用表格、HTML 和锚点，尽量不写路径和命令。
- 每个字段单独成一个列表项，或者用空行分开，不要只靠单个换行分行。
- 加粗只用在功能名和决定的问句上。
- 每句都要在 plan 里有依据，不写 plan 里没有的承诺和数字。

写法规则：

参考 ASD-STE100 的思路；英文文档可以直接遵循 STE100 的写作规则，但不要求使用它的词典。中文文档按下面的规则写。英文项目改用英文版 plan-first。

句子

1. 一句只讲一件事，不超过 40 字。计字数时不算标点，一个英文词或一个数字算 1 字。
2. 句子要完整，不靠省略词语来缩短。不写电报体，也不写"A→B，C 待定"这种半句。
3. 写清楚谁做事。用"我会……""你需要……"，不用"将被……""进行了……"。

词语

4. 同一个东西从头到尾用同一个名字，并和 plan 一致。
5. 新术语第一次出现时，用一句话解释。以前的人读版已经解释过的不再解释。能用日常词就不用术语。
6. 不用空泛的词，如"相关""进行""实现""优化""赋能""闭环"，直接说具体做了什么。
7. 用具体数字，不写"很快""较大"。例如写"约 20 分钟""2GB"。

段落

8. 每段不超过 4 句，只讲一个主题。
9. 同一个列表里的各项，句式保持一致。

## 3. 批准、修改和执行

- **请求批准**：两份文档写完后，在回复里给出它们的路径，再用三到五行概括要点和需要决定的事，然后停下，等用户批准。
- **处在计划模式时**：有的工具在计划模式下只允许写它自己的计划文件，例如 Claude Code。这时把人读版全文放在计划文件的前半部分，plan 全文放在后半部分，然后请求批准。用户接受这份计划就算批准，所有决定都按推荐，除非用户写明要改哪项。批准后的第一步，把两部分分别写进 `docs/human/` 和 `docs/plan/`，状态写"已批准"。然后再开始执行。用户在工具的权限弹窗里允许写文件或运行命令，不算批准计划。
- **什么算批准**：只有用户明确表示同意（比如"同意""可以""开始吧""执行"）才算。只在"需要你决定的事"已列的选项里做选择（如"1 选备选""批准，2 选备选"），也算批准。带条件的同意（如"可以，但……"）按修改处理。提问、讨论、没有回复，都不算。用户只批准部分内容时，没批准的部分不做。这也算修改，按"修改要两份一起改"处理。
- **批准要写进文档**：用户批准后，先把两份文档的状态改成"已批准"，写上被批准的版本号。用户在已列选项里做选择时，写进选择后的版本就是被批准的版本。开始执行时改成"执行中"。改了计划要重新请求批准时，先把状态改回"待批准"。换会话或换 agent 后，以文档里的状态和版本号为准。
- **修改要两份一起改**：不管是用户提出的修改，还是你自己发现需要改，都要同时更新两份文档，在 plan 的变更记录里加一行，然后重新请求批准。用户只在已列选项里做选择时例外：把选择写进两份文档，在变更记录里加一行，然后直接执行。修改删掉了某些内容时，把它们移出两份文档的"做完后"、完成标准、改动清单和影响面。这些内容写进 plan 的"不做的事"。
- **执行中偏离计划**：plan 第 5 项的影响面就是边界，它和人读版的影响面一致。
  - 小偏差：不改变任何完成标准，也不超出影响面的四行。可以直接做，记进 plan 的执行记录。
  - 大偏差，或者碰到停下条件：马上停下，告诉用户，改好两份文档后重新请求批准。
- **执行完成**：
  - 两份文档的状态改成"已完成"。完整结果只写进 plan 的执行记录，人读版不加结果。
  - 在回复里给用户一份完成汇报，写法规则同人读版。第一行写"完成："加任务名，下面固定四块，空的不写：
    1. 做完后：逐条写"达成"或"没达成"，附上证据。做了多个功能时，按功能分组。
    2. 和计划不一样的地方：先写超出影响面的。
    3. 你可以这样检查：给 1 个用户自己能做的检查。
    4. 还剩什么：需要另出计划的事，写明。
- **派子 agent 或换会话执行**：任务说明里要写明 plan 路径、步骤号、被批准的版本号和"用户已批准"。接手的 agent 先核对：说明这样写了，而且版本号和状态行一致，就按 plan 做。这时不另写计划，也不向用户请求批准。说明没这样写，或者版本号对不上，就只汇报，不改文件。子 agent 碰到大偏差或停下条件，就把情况交回派它的 agent。其他任务仍按第 1 节判断。

## 4. Git 惯例

项目或用户另有 git 约定时，以那边为准；以下是没有约定时的默认做法。

所有任务都按下面的惯例办，各条只在适用时生效。计划里不再重复。除第 2、3 条外，不拿来问用户。

1. 项目必须在 git 仓库里。还没有时，在第一份计划里安排初始化 git，并在人读版"影响面"的"新增"里写明。用户批准计划，就是同意这一步。
2. 提交署名用仓库的本地配置，不改全局配置。第一次提交前发现没有可用的署名配置时，在回复里问用户一次名字和邮箱，之后沿用。
3. 开始执行前，工作区要干净。有不是本次任务造成的未提交改动，先停下来问用户。不要自己用 stash、reset、checkout 或 clean 处理这些改动。
4. 每个计划执行完成后提交。先把两份文档改成"已完成"、写完执行记录，再做最后一个提交，这个提交要包含两份文档。只暂存这个计划改动清单里的文件和两份文档，不用 `git add -A`、`git add .` 或 `git commit -a`。不是本次任务造成的改动不暂存，写进完成汇报。提交说明的第一行写结果，正文写计划文件名。一个计划可以按逻辑拆成几个提交。
5. 不提交编译产物、依赖目录、大文件、密钥和个人数据，用 `.gitignore` 排除。
6. 回退的默认办法是撤销这次任务的提交。
7. 不改写已有的提交历史，例如不强制推送、不变基已提交的内容，除非用户要求。
8. 第 1 节的例外任务里，只读的工作不受第 3、4 条约束。改了文件的例外任务，开始前工作区干净的，做完也要提交，只提交自己改过的文件。提交说明第一行写结果，正文写"无计划："加例外类别，例如"无计划：修 bug"。开始前工作区不干净的，不用停下来问，也不提交，在回复里列出改过的文件。

## 人读版模板

````markdown
<!-- 人读版模板。把 <…> 换成内容，写完删掉所有注释。规则见 plan-first.md 第 2 节"human：写给人"。 -->
# <任务名：一句话说清做什么>

> 状态：待批准 · v1 · YYYY-MM-DD
>
> agent 执行版：[../plan/YYYY-MM-DD-<任务短名>.md](../plan/YYYY-MM-DD-<任务短名>.md)

## 这次要做什么

<!-- 写法一：只做一个功能。 -->

目的：<要解决什么问题，不做会怎样。一到两句。>

做完后：

1. <用户能检查的结果。>
2. <用户能检查的结果。用户提过的要求，注明"这是你的要求"。>

不做：<最容易被误以为会做的 1 到 3 件事。>

<!-- 写法二：做多个功能。每个功能单独编号，功能名用"动词 + 对象"。后面各节用"功能 N"指代。 -->

1. **<功能名>**
   - 目的：<一到两句。>
   - 做完后：
     - <用户能检查的结果。>
2. **<功能名>**（依赖功能 1）
   - 目的：<一到两句。>
   - 做完后：
     - <用户能检查的结果。>

不做：<最容易被误以为会做的 1 到 3 件事。>

## 需要你决定的事

<!-- 只放三类：产品方向或用户可见行为的取舍；难回退的事；花钱、花用户时间、动用户账号的事。 -->
<!-- 没有要决定的事时，本节只写一行：无需决定，回复"批准"即可开始。 -->

1. **<问句？>**（能回退）<!-- 多个功能时写成"（功能 N，能回退）"。 -->
   - 推荐：<选项和理由。>
   - 备选：<可选。>
2. **<问句？>**（难回退）
   - 推荐：<选项和理由。>
   - 代价：<选了以后难撤回的是什么。>

全部按推荐，回复"批准"即可开始；要改某项，回复如"1 选备选"，其余按推荐，也即可开始。

## 需要你做的事

<!-- 没有用户必须亲手做的事，就删掉整节。 -->

- <什么时候做、做什么、为什么。>

## 影响面

<!-- 多个功能时按整轮合并写；只属于一个功能的条目，行末注明"（功能 N）"。 -->

- 会改：<改哪些部分，约几个文件。>
- 新增：<新的文件、依赖、概念或做法，各附一句理由；没有就写"无"。>
- 删除：<删掉的文件、功能或数据；没有就写"无"。>
- 对外行为：<用户或其他程序能看到的变化，包括安全和权限的变化；没有就写"无"。>
````