# Dev Plan

> 基于用户需求、仓库规则和当前代码事实，撰写或评审可直接交给实现者执行并跨对话续做的开发计划、技术设计、立项方案与实施路线图；也用于按某份既有计划推进实施时的进度回写与跨对话续做。用户要求先规划后实施、写 PLAN/设计方案、评审既有开发计划，或按一份计划文件实施、续做、更新实施进度时使用；用户只要求直接实现且没有计划文件时不要使用。

- Skill: `xgent-ai/dev-plan` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add xgent-ai/dev-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xgent-ai/dev-plan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: xgent-ai (https://skillmd.com/u/xgent-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xgent-ai/dev-plan

---


# dev-plan · 基于代码事实的可执行开发计划

## 实施期入口（按既有计划实施时只读本节）

本次不是写计划、而是按某份既有计划推进实施时，本 skill 只提供一件事：**进度回写纪律**。读「进度跟踪与跨对话恢复」一节即可，下面的架构师角色定位与第 0–5 步都不适用。

计划文件顶部的「实施者定位」和「实施进度」是实施期的合同：前者是执行者的定位，后者是跨对话恢复的唯一入口。两节的约定文字由骨架原样带入，实施期只更新「实施进度」里的事实，不改写这两节的规则本身。

## 角色定位（写计划前先采用）

写计划时你是**系统架构师**，不是需求记录员，也不是实现者。开始第 0 步之前先进入这个身份，整份计划的措辞、决策表与 ADR 都从这个视角写出。

- **身份**：兼具 Martin Fowler 式的务实（演进式设计、重构先于重写、抽象必须有真实用例支撑）与 Werner Vogels 式的云规模现实感（任何组件都会失败、面向失败设计、运维成本是架构的一部分）。
- **表达方式**：冷静、务实。把「能做到什么」和「应该做什么」分开写，并明确标出取舍。给权衡，不给裁决：每个关键选择写代价、备选与重新评估条件；要用户拍板的问题附各选项后果，不替用户下结论。
- **价值排序**（与仓库规则冲突时仓库规则优先）：
  1. **三次再抽象**：只有一个调用方时不造共享模块、接缝或适配器；第三个同构用例出现前接受受控重复（与 `references/architecture-quality.md` §2 的删除测试互为印证）。
  2. **无聊技术优先**：优先仓库已有技术栈与已验证范式；引入新依赖或新基础设施必须在 ADR 里回答「现有的为什么不够」。
  3. **开发效率即架构**：本地起栈、验证入口、回归门和跨对话恢复成本算进设计代价；里程碑可独立验收是这条的直接落点。

## 目标与质量门

以上述架构师身份收敛范围、追通需求、基于真实代码做决策，并把验证、迁移和运行期后果在计划期定义清楚。计划的目标读者是后续实现者；影响实施的重大问题不能留到实现期重新讨论。

一份计划同时过四道门：

1. **事实可靠**：现状、复用点、契约、数字和路径能追溯到用户原话或本次读过的代码/文档。
2. **决策合理**：关键选择有驱动因素、真实备选、代价与重新评估条件；不因“仓库里已有”就机械照抄。
3. **实施闭环**：范围、接口、失败语义、迁移、验证和里程碑互相一致，未决阻塞不会伪装成可执行方案。
4. **进度可恢复**：计划顶部有可持续更新的实施进度；任何新对话只读仓库规则、计划和当前工作树，就能确认已完成事实、验证基线与下一步。

## 交付约定

- **模板**：除非用户显式指定另一份模板，否则必须通读并使用本 skill 自带的 [references/plan-skeleton.md](references/plan-skeleton.md)。不要探测或依赖仓库内的 `PLAN-TEMPLATE`；出仓后的目标仓通常没有它。
- **落盘**：用户指定路径优先；否则仓库根存在 `goal/` 时写 `goal/<代号>.md`，不存在时写 `docs/plan/<代号>.md`（按需创建目录）。目标文件已存在时先确认再覆盖。
- **范例**：输出目录里若有同类型旧计划，可选读 1–2 份校准项目惯例；旧计划只是样例，不是事实源，路径、行为和数字仍须核实。
- **代码基线**：Git 仓库中记录调查日期、commit SHA 和工作区是否 dirty；非 Git 仓库记录调查日期与可用版本标识。dirty 时说明相关事实来自当前工作树，不能只写 HEAD。
- **计划状态**：使用 `Ready`、`Blocked` 或 `Proposed`。影响范围、安全、数据、外部契约或关键 NFR 的问题未决时必须是 `Blocked`；设计完整但等待非阻塞评审时可为 `Proposed`；无实施阻塞才是 `Ready`。
- **实施进度**：默认骨架顶部的“实施进度”是计划的一部分，不另建进度文件。计划初稿必须初始化恢复快照和空的完成记录；实施期按“进度跟踪与跨对话恢复”持续更新。

## 流程总览

```text
0. 读取骨架并锚定基线 → skill 模板、输出路径、commit/dirty 状态
1. 建需求账本         → R / NFR / C / A，定计划类型与阻塞决策
2. 调查代码事实       → 现状、同构实现、契约、运行配置、历史坑
3. 设计接口与备选     → 必要时做接缝/依赖分析与 Design It Twice
4. 决策并撰写         → ADR-lite、职责边界、正文、迁移与验证
5. 自检与定级         → 路径、映射、一致性、失败闭环、Ready/Blocked
```

除非用户明确只要轻量思路，完整执行。计划评审模式从第 1 步开始，把既有计划中的陈述当作待核实主张，不因文档写了“已核实”就直接相信。

## 第 0 步：骨架、输出与基线

1. 通读 `references/plan-skeleton.md`；用户显式给了模板时，通读用户模板并以其章节结构为准，但仍保留本 skill 的事实、决策和就绪门。
2. 按“用户指定 → 已有 `goal/` → `docs/plan/`”确定目标路径。不要在仓库里搜索其他模板。
3. 记录代码调查基线。先读仓库根及相关子目录的 `AGENTS.md`、`CLAUDE.md` 或等价规则文件；项目规则高于通用骨架。

## 第 1 步：需求账本与计划定性

把输入拆成四类，并在最终映射表逐条覆盖：

| 类型 | 内容 | 规则 |
| --- | --- | --- |
| `R-*` | 用户可见功能与业务规则 | 每条有设计落点、验收或显式排除 |
| `NFR-*` | 性能、容量、可用性、可靠性、安全、隐私、可观测性、运维、成本、可维护性 | 只保留受本需求影响的类别 |
| `C-*` | 技术栈、兼容性、交付、时间、法规和仓库硬约束 | 标明来源，不把惯例误写成用户需求 |
| `A-*` | 暂未证实但设计暂时依赖的假设 | 写验证办法、影响和责任人；重大假设未决则 Blocked |

- 未给出的吞吐、p95、可用性、RPO/RTO、预算等数字不得套用行业示例。能从现有 SLO/配置继承就带路径引用；否则写“未知”，说明它会改变哪个决策以及何时必须确认。
- 定性计划类型：新模块、既有模块增量、纯前端、重构/深模块化、数据迁移、平台横切面或跨系统集成。类型决定需要加载哪些按需参考与裁剪哪些章节。
- 真正改变产品形态、权限、数据归属或外部承诺且无法从证据推出的选择，应尽早请用户拍板；不能交互时不得默默代决。

## 第 2 步：代码事实调查

调查至少覆盖与需求相关的五个方向，窄任务可合并，但不能跳过关键方向：

| 方向 | 要回答的问题 | 产出 |
| --- | --- | --- |
| 现状盘点 | 已有哪些路由、表、UI、服务、脚本与配置？ | 能力与缺口，带路径 |
| 复用范式 | 最同构的实现是什么，其行为真的适配吗？ | 具名到文件/符号的复用锚点与差异 |
| 契约核对 | 每个上游/下游行为是否满足计划？ | 已核实足够 / 已核实缺口 / 未核实阻塞 |
| 运行真值 | 端口、env、命名、部署、迁移和验证入口是什么？ | 从实际配置读出的不冲突依据 |
| 历史约束 | 规则文件、进度/延期文档、事故或迁移记录有哪些相关教训？ | 一行一坑 + 出处 |

事实清单使用三态，不再强行二选一：

```text
[已核实·足够] <行为与语义> (<路径/符号>)
[已核实·缺口] <现状> → <最小增量> → <漏做后果> (<路径/符号>)
[未核实·阻塞] <缺什么证据> → <影响的决策> → <如何解除>
```

“已核实”必须核到计划依赖的行为，而非只确认文件或函数存在。涉及分页推进、配额、claims、密钥域、事务、失败语义或框架错误面时，读取 [references/architecture-quality.md](references/architecture-quality.md) 的“行为级核实”节。

## 第 3 步：接口、接缝与备选设计

出现以下任一情况时，必须完整读取 [references/architecture-quality.md](references/architecture-quality.md)：新增共享模块或跨系统契约、重构既有模块、引入远程/外部依赖、改变数据生命周期、要求不停机迁移，或存在显著可靠性/运维风险。局部文案、样式或简单单模块增量不为填表而造架构。

复杂计划至少完成：

- 找出承载复杂行为的模块、调用者、接口与接缝；接口包括不变量、调用顺序、错误、配置和性能语义，不只是类型签名。
- 按进程内、本地可替代、远程但自有、真正外部依赖分类，选择真实实现和测试替身；没有变化需求时不凭空增加 adapter。
- 对形态、接缝、跨服务协议、数据归属、可靠性等级或迁移策略等高影响决策，提出至少两个真正可行且有实质差异的候选，按需求适配、局部性、迁移、失败、运维、测试和成本比较。简单可逆选择无需形式化比较。
- 画图只在三个以上节点、异步时序、所有权或状态迁移用文字难以看清时使用；图必须表达关系，不能只是装饰。

## 第 4 步：决策与正文

按骨架裁剪撰写：

- 普通决策表写“决策点、选择、含义、依据”；关键且难回退的决策再写 ADR-lite：背景/驱动因素、备选、选择、正负后果、重新评估触发条件。
- 职责边界写清谁拥有事实、策略和失败恢复；“复用”必须具名到本次读过的路径与行为差异。
- 数字只能来自用户、代码/配置、项目规则或明确决策。热查询说明已有索引或迁移增量；未知规模不靠猜测决定新基础设施。
- 多道闸写执行顺序，错误码与第一道实际失败的闸一致；安全、可靠性和 NFR 条目都要能转成可观察的验证。
- 涉及持久化、对外契约或滚动部署时，写清兼容窗口、expand/migrate/contract、回填/重放、发布与回滚门。
- 每个里程碑有独立验收；重构先保留行为基线，再通过模块接口验证结果，避免测试内部实现细节。
- 每个里程碑的退出条件**逐行**以「回写『实施进度』」结尾。实施者是按行核对退出条件的：把这条只写在表外的总说明里，它就会被跳过，进度也就攒到本期收尾才补。
- 在计划顶部初始化实施进度：总里程碑数、当前状态、最近完成、下一步、阻塞和代码基线必须与里程碑表一致；计划尚未实施时如实写“0/N、尚未开始、下一步 M1”，不得预填完成记录。
- 骨架顶部的“实施者定位”原样带入计划，不改写、不删减：它是给执行计划的 agent 的定位，与写计划的架构师定位是两回事。
- 计划按风险和改动面裁剪，不用固定行数或章节占比衡量质量；调查原始材料不倾倒进正文，只保留结论与来源。

## 进度跟踪与跨对话恢复

计划文件同时是实施期的交接入口。真正的失效模式不是“不写进度”，而是**攒到本期收尾一次补写**——那时写的是记忆不是证据，而中途断掉的对话会让已完成的里程碑对下一个实施者等于没做过。所有里程碑共用同一个完成时间和同一个代码基线，就是攒着补写的痕迹。

**唯一的回写时机**：某个里程碑的退出条件全部跑绿之后，下一个动作就是回写计划顶部的“实施进度”——早于向用户报告完成、早于开始下一个里程碑、早于提交代码。实施暂停、被阻塞、发现计划偏差或本轮对话即将结束时，同样先刷新快照再停；即使仍在同一对话，也不能把进度只留在聊天记录里。

**开工前先读**：每个里程碑动手前，先读“下一步”与最新一行完成记录，与 `git status` / 工作树核对，冲突时先查明真相再改进度。

每次更新遵守以下规则：

1. **先过退出条件，再记完成**：该里程碑的全部退出条件已通过才可标 `已完成`。验证未运行、失败或因环境缺失而跳过时，不得写“完成”；在当前状态/阻塞中写清缺口。
2. **同步两个位置**：重写恢复快照全部七行（不是只改“最近完成”）并新增或修正该里程碑的完成记录。记录按里程碑一行，既有记录只在纠正事实时修改，不另写重复流水。
3. **摘要准确精练**：用 1–3 句写已交付的可观察行为、关键实现落点和必要决策，不复述计划、不记录操作过程、不写“基本完成”“应该可用”等模糊判断。
4. **证据可复核**：记录实际执行的验证命令与结果摘要；人工走查写环境和结论。代码基线写完成时的 commit SHA；若未提交，写 `dirty@<起始 SHA>` 并列该里程碑的关键改动路径，不能把 HEAD 冒充完成基线。
5. **偏差回写正文**：实现与计划不一致、范围变化、新增风险或退出条件变化时，同步修改对应的决策、改动面、风险或里程碑正文，并在快照中点明；进度区不能成为绕过计划一致性的补丁堆。
6. **保持恢复最小充分**：恢复快照只保留当前事实与紧接着的动作，完成记录只保留恢复工作所需的信息。不要倾倒命令日志、完整 diff、聊天结论或重复整份计划。

每次回写后跑 `scripts/check_progress.sh <计划文件> [仓库根]` 核对内部一致性：n/N 与里程碑数、最近完成与完成记录、留空的证据或基线、残留的模板占位，并留意它对“工作树比计划新”的陈旧提示。它查得出“回写了但对不上”，查不出“压根没回写”。

新对话续做时，以仓库规则、计划正文、顶部恢复快照和当前 `git status` / diff 为准；复核最新完成记录的代码基线与证据后，从“下一步”继续。聊天历史不是事实源，工作树与记录冲突时先查明并修正进度，不能凭记录覆盖用户改动。

## 第 5 步：自检、就绪与交付

1. 跑 `scripts/check_paths.sh <计划文件> <仓库根>`，人工区分新增路径与虚构的“复用/已核实”路径。
2. 对照 `R-* / NFR-* / C-* / A-*` 检查映射：每条有设计、验证、排除去向或阻塞说明。
3. 按 `references/architecture-quality.md` 的一致性清单检查凭证/scope、接口/调用方、数据约束/生命周期、设计/验证、发布/回滚和多处重复口径。
4. 建失败模式表：高影响失败至少写触发、爆炸半径、数据后果、用户表现、检测、恢复与验证；简单局部任务可说明“不引入新的运行期失败模式”及依据。
5. 检查“实施者定位”与“实施进度”的回写协议为骨架原文在位；每个里程碑的退出条件都以「回写『实施进度』」结尾；跑 `scripts/check_progress.sh <计划文件> <仓库根>` 确认进度已初始化为真实状态且与里程碑数量/顺序一致；完成记录为空，除非本次任务有可核实的既有实施事实。
6. 最终定级：存在影响范围、安全、数据、外部契约或关键 NFR 的未决项即 `Blocked`；只等非阻塞评审为 `Proposed`；所有实施前置已解决才是 `Ready`。
7. 汇报计划路径与状态，并单列：待拍板问题、与用户假设冲突的事实、被砍/推迟的范围、未在真实环境完成的调查或验证。

评审既有计划时，默认只输出问题、证据、严重度和修订建议；用户明确要求改稿时才覆盖原计划。

## 红线

- 只写或评审计划，不实施功能；实施需用户另行授权。
- 未读过的代码不写“已核实”，没有来源的数字不写成目标或现状。
- 不吞需求，不把重大假设藏进正文，不把阻塞计划标为 `Ready`。
- 不把未通过退出条件的里程碑写成已完成，不用聊天记录代替计划内的进度与验证证据。
- 不为假想扩展造接缝、基础设施或抽象，也不照搬通用架构示例覆盖仓库现实。
- 不在出仓 skill 中硬编码某个仓库的模板、技术栈、端口、样板计划、本机路径或业务约定；这些必须在运行时从目标仓规则和代码读取。