dev-plan

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

路径约定：references/ 与 scripts/ 均相对于本 SKILL.md 所在目录。运行脚本前，在目标仓根目录按实际加载位置设置 SKILL_DIR="<本 SKILL.md 所在目录>"；计划文件与仓库根参数仍按目标仓路径填写。

适用边界：只管写与评审，不管实施

按既有计划实施、goal 执行或续做不用本 skill：「实施者定位」与「实施进度」已带齐实施需要的全部约定（进度回写、独立记录格式、subagent 并行、回写后自查），实施者直接读计划。同一对话里写完计划接着实施，也按计划顶部两节执行，不再读本 skill 的参考。由此推出一条写作约束：实施期需要的任何规则都必须写进骨架的这两节，不能只留在本 skill 里。

生成计划不出现本 skill 名称、目录或脚本路径，包括“不要加载”的否定提醒；实施入口用正向指令说明先读哪些内容、如何推进与回写。计划提到规划、里程碑或就地修订实施偏差，不等于用户要求重新撰写或评审计划。若误在实施期加载本 skill，直接返回计划继续实施，不读取骨架或参考、不重走规划流程。

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

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

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

目标与质量门

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

一份计划同时过四道门：

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

交付约定

• 模板：除非用户显式指定另一份模板，否则必须通读并使用本 skill 自带的 references/plan-skeleton.md。不要探测或依赖仓库内的 PLAN-TEMPLATE；出仓后的目标仓通常没有它。计划全文不提用了哪份 skill、骨架或参考——读者是实现者，写作用了什么工具与他无关。
• 落盘：用户指定路径优先；否则仓库根存在 goal/ 时写 goal/<代号>.md，不存在时写 docs/plan/<代号>.md（按需创建目录）。目标文件已存在时先确认再覆盖。
• 范例：输出目录里若有同类型旧计划，可选读 1–2 份校准项目惯例；旧计划只是样例，不是事实源，路径、行为和数字仍须核实。
• 代码基线：Git 仓库中记录调查日期、commit SHA 和工作区是否 dirty；非 Git 仓库记录调查日期与可用版本标识。dirty 时说明相关事实来自当前工作树，不能只写 HEAD。只保留最近一次核对的一条基线，改稿时就地更新，不追加复核经过。
• 计划状态：使用 Ready、Blocked 或 Proposed。影响范围、安全、数据、外部契约或关键 NFR 的问题未决时必须是 Blocked；设计完整但等待非阻塞评审时可为 Proposed；无实施阻塞才是 Ready。顶部状态行只写状态，定级理由写 §11，实施进展只写「实施进度」。
• 实施进度：计划顶部是本计划实施进度的唯一汇总入口，初稿初始化恢复快照和空的完成记录。实现与验收详情按里程碑保存在计划旁的 <计划文件名去扩展名>.records/M<n>.md，只留结果、验证证据与续做所需缺口；子任务不默认另建过程文档，不预建空记录。

控制计划与执行成本

• 信息只展开一次：已有 PRD 就沿用需求 ID，以来源、差异和设计/验收链接建账本，不复制验收原文。账本已覆盖需求 → 设计 → 验证时，省略末尾重复映射表；接口、NFR、风险在所属章节定义，其余位置引用。保留影响实现的精确信息，删去重复解释。
• 里程碑围绕可验证成果：不要把每个模块或工种都升成独立里程碑。同一能力、同一环境且无独立发布/回滚或风险门的工作，可合成一个里程碑，内部保留任务依赖和局部检查。独立安全、数据迁移、不可逆操作、发布及用户约定的分期门仍单列。
• 开发前置不等于终验前置：依赖写到实际需要的契约/子任务与验证，不默认等待上游整个里程碑；前置检查必须证明该成果可用。端到端走查、全量回归、故障演练和评测可集中到阶段收口，各里程碑保留自身新增行为与风险的检查；阶段收口通过前不得宣称整期或整条跨期需求已验收。
• 验证与证据复用：§9 定义检查 ID/测试组、覆盖的需求或验收行、环境与执行时点，里程碑引用检查 ID，不重抄断言。执行时点须晚于所需能力/环境就绪，不让骨架里程碑验收尚未实现的端到端路径。同一部署可合并 API/UI 主路径走查；相关代码、配置、依赖、输入与环境未变时复用已通过证据，变更后重跑受影响检查，阶段收口跑必要集成回归。重构仍先建立行为基线。

流程总览

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 或等价规则文件；项目规则高于通用骨架。读规则是为了约束设计，规则清单本身不进计划：有约束的条目落成 C-* 或第 12 节的一行一坑（带规则路径与被约束的具体行为），读过但无约束的文件一个字都不写。

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

把输入拆成四类，并在需求账本或映射表逐条覆盖（保留一份完整映射即可）：

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

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

第 2 步：代码事实调查

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

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

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

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

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

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

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

复杂计划至少完成：

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

第 4 步：决策与正文

按骨架裁剪撰写：

• 普通决策表写“决策点、选择、含义、依据”；关键且难回退的决策再写 ADR-lite：背景/驱动因素、备选、选择、正负后果、重新评估触发条件。
• 职责边界写清谁拥有事实、策略和失败恢复；“复用”必须具名到本次读过的路径与行为差异。
• 数字只能来自用户、代码/配置、项目规则或明确决策。热查询说明已有索引或迁移增量；未知规模不靠猜测决定新基础设施。
• 多道闸写执行顺序，错误码与第一道实际失败的闸一致；安全、可靠性和 NFR 条目都要能转成可观察的验证。
• 涉及持久化、对外契约或滚动部署时，写清兼容窗口、expand/migrate/contract、回填/重放、发布与回滚门。
• 每个里程碑有明确退出条件，局部检查与阶段终验按上文分工；验收合并须说明共同环境、覆盖范围和保留的风险门，不能只删检查或延后风险发现。
• 写清实际前置成果及验证、可并行范围与共享文件/资源的单一负责人。前置已满足、契约稳定且互不干扰才可并行；按任务规模与集成成本决定是否委派，不为并行硬拆。复杂调度按需读 references/execution-workflow.md。
• 每个里程碑的退出条件逐行以「回写『实施进度』」结尾，防止完成后漏记。
• 在计划顶部初始化实施进度：总里程碑数、当前状态、最近完成、下一步、阻塞和代码基线必须与里程碑表一致；计划尚未实施时如实写“0/N、尚未开始、下一步 M1”，不得预填完成记录。
• 骨架开头的“实施须知”及“实施者定位”“实施进度”协议原样带入计划，不改写、不删减：它们是给执行计划的 agent 的完整合同，与写计划的架构师定位是两回事。回写后自查按计划内条目直接核对，不引入本 skill 的脚本依赖；check_paths.sh 与 check_progress.sh 留在撰写/评审期使用，不列入计划的实施或终验命令。
• 计划按风险和改动面裁剪，不用固定行数或章节占比衡量质量；调查原始材料不倾倒进正文，只保留结论与来源。

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

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

评审既有计划时，默认只输出问题、证据、严重度和修订建议；用户明确要求改稿时才覆盖原计划。改稿把结论直接改进正文与对应决策、刷新调查基线；评审出处、采纳/拒绝理由和修订经过留在评审报告与提交说明，不写进计划。

红线

• 写作/评审模式不实施功能；用户已要求按计划实施时，按计划顶部两节直接实施，无需重复请求授权。
• 未读过的代码不写“已核实”，没有来源的数字不写成目标或现状。
• 不吞需求，不把重大假设藏进正文，不把阻塞计划标为 Ready。
• 不把未通过退出条件的里程碑写成已完成，不用聊天记录代替计划内的简要进度与独立的实现/验收记录；不在续做时批量加载历史记录。
• 不为假想扩展造接缝、基础设施或抽象，也不照搬通用架构示例覆盖仓库现实。
• 计划里不写写作过程：用了哪份 skill / 模板 / 参考资料、读过哪些规则文件的清单、调查或复核做了几轮、评审意见的采纳与改稿经过、“本次只写/修订计划、未实施”这类写作当时的状态、“本轮/刚才”这类只在写作对话里成立的指代（来源写“用户 YYYY-MM-DD 确认”）。它们既不是实施事实也不是里程碑进展，会随实施过期、误导实施者、白占上下文；提到 skill 还会诱导实施者去加载只有写计划才需要的内容。
• 不在出仓 skill 中硬编码某个仓库的模板、技术栈、端口、样板计划、本机路径或业务约定；这些必须在运行时从目标仓规则和代码读取。

项目状态回写

若仓库已登记状态台账，或存在仓根 .xgent-ai/sdlc/protocol.md（兼容已有 docs/project-status/protocol.md；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按其格式新增本次事实记录并刷新受影响的状态页与必要索引；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。

登记计划的实际路径、版本、就绪状态与需求关联；实施状态只取顶部真实进度。评审模式登记独立评审事实，不替原计划改状态；本次仅聊天时不登记。