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. 进度可恢复：计划顶部用简要状态和记录索引支持续做；新对话先读仓库规则、计划和当前工作树，只在核验证据、排错或接续未完工作时读取相关记录。

开发范围与 non-scope

业务链路涉及的系统，不自动成为本计划的开发对象。 写需求账本前，依据用户任务、已确认需求与项目职责，明确本期交付对象、允许修改的仓库/包/模块及行为，并标明范围依据；顶部概括开发范围，§0.4/§0.5 写清职责与排除，§1.2 落到改动路径。

• 依赖与开发归属分开：同仓、同团队、自有服务、源码可读或账号可操作都不等于纳入本期。对范围外系统只核实本方接入所需的契约、能力和就绪证据，不替它设计内部实现。用户已明确纳入的多系统任务可分别规划；不因“外部”一概排除，也不重复索取已有授权。
• 外部缺口留作依赖：需要外部新增接口、权限、数据、配置或部署时，在 §4/§11 写提供方（未知则待确认）、所需行为、就绪证据、解除条件及阻塞开发/集成/终验的哪一段，不放入本方交付物和开发里程碑。关键契约或范围未决仍为 Blocked，仅有外部依赖不构成阻塞；独立已确定部分可另立明确范围的计划，不宣称全链路已交付。
• 排除写到动作：区分明确不做、外部提供与已确认延期；范围外职责不默认变成本项目下一期任务。接入登录不自动包含建设身份平台，消费支付结果不自动包含实现支付服务。测试替身只模拟已约定契约所需行为，不为开发或终验造一套替代外部系统。
• 按交付物反查范围：代码、共享契约、迁移、配置、种子、脚本、部署、故障恢复和验收准备均须在已确认范围内；端到端验收可以检查外部行为，但不授权改造外部系统。需要扩范围时列明增量、责任与影响，只询问尚未确定的部分；不得借“闭环”“解除阻塞”或就地修订偏差自行扩张，也不得删掉用户要求的真实集成验收。

开发验收的可执行性

• 默认由 AI Agent 验证：开发退出条件要能用本阶段可获得的工具、账号、数据与环境执行。没有用户或已确认约束的依据，不增设招募真人、真人样本人数、满意度调查等前置。
• 用户角色由 Agent 按约束模拟：明确角色已知什么、可读什么资料、有什么权限，以及任务与成功判据。验证时不能靠角色未掌握的专业知识、内部源码或实现者口头补步骤。结果标为角色模拟，记录实际产物与卡点；不能推导真人成功率或满意度。
• 真人验证按阶段单列：确需真人的可用性/效果指标通常放在公测或上线后验证，不默认阻塞开发退出。上游已有真人指标时核对来源与阶段；用户明确要求的开发真人验收门不得默默删去或改成模拟，须列出资源、责任方、执行节点及受影响范围。
• 真实环境可以由 Agent 操作：有权限和工具时，Agent 直接验证真实页面、接口、账号及设备；模拟用户知识不等于模拟系统，mock 仍不能替代要求的真实集成。

例如，「找若干不熟悉 Rust 的人测试」若只是验证上手路径，应改为「Agent 模拟不掌握 Rust 的首次使用者，仅凭公开快速入门与示例，在干净环境完成指定任务，记录结果与缺失步骤」。真人群体的学习成本与满意度另留真实用户验证。

交付约定

• 模板：除非用户显式指定另一份模板，否则必须通读并使用本 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，实施进展只写「实施进度」。
• 需求来源与期次：从 PRD 派生的计划在顶部「需求来源」行链接 PRD 并写期次：P1、P2…（P = Phase，P1 即第 1 期）；合并多份来源时逐份列出。来自 CR（CRD）的计划记录 CR 标识、路径/链接、版本及对应 R/Q/RESP（缺失版本如实注明，无编号用稳定章节定位，不补造），区分原来源与实际回写文件，在既有账本/验证映射中标明本计划承接的请求或子范围及收口检查；有 PRD/期次时一并保留，不能把 CR 简化为「用户需求，无 PRD」。仅无文档来源的直接需求写「用户需求，无 PRD」。下游据此追溯需求与完成范围。
• 来源 CR 完成回写：来自 CR 的计划在顶部实施协议保留来源请求回写规则，明确实际回写文件；对应请求实现且约定检查通过后，按请求范围追加实现结果及计划/验证证据，保留原答复历史并查重。仅部分完成时写明余项，不把本方实现冒充发布或对方验收；无法回写时在记录和下一步留下缺口与恢复动作。用户指定其他模板时仍须把这些实施约定写进计划顶部，不依赖实施者另读技能。
• 实施进度：计划顶部是本计划实施进度的唯一汇总入口，初稿初始化恢复快照和空的完成记录。实现与验收详情按里程碑保存在计划旁的 <计划文件名去扩展名>.records/M<n>.md，只留结果、验证证据与续做所需缺口；子任务不默认另建过程文档，不预建空记录。
• 提交：§10 里程碑表后写「提交点」：全部里程碑完成后的最终提交必有；里程碑超过 5 个或含多个阶段收口时，在阶段收口里程碑后另设阶段提交点。提交、回填 SHA 到完成记录「提交」列、全部完成后提示代码评审的规则已写在骨架「实施进度」协议中，随协议原样带入。

控制计划与执行成本

• 信息只展开一次：已有 PRD 就沿用需求 ID，以来源、差异和设计/验收链接建账本，不复制验收原文。账本已覆盖需求 → 设计 → 验证时，省略末尾重复映射表；接口、NFR、风险在所属章节定义，其余位置引用。保留影响实现的精确信息，删去重复解释。
• ID 单处定义、多处引用：需求/约束/假设 ID 在 §0.1 账本唯一登记，已有 PRD 沿用上游 ID 并标来源；检查 V-*、里程碑 M<n>、按需任务 T-* 分别在 §9、§10、内部任务表定义。§7 的 NFR 展开、§13 映射、正文和进度记录都是引用，不算重复定义。引用须能找到本计划定义或账本登记的上游来源；修订时保留已有 ID，删除/拆分后同步引用，不为排序重编号。
• 里程碑围绕可验证成果：不要把每个模块或工种都升成独立里程碑。同一能力、同一环境且无独立发布/回滚或风险门的工作，可合成一个里程碑，内部保留任务依赖和局部检查。独立安全、数据迁移、不可逆操作、发布及用户约定的分期门仍单列。
• 内部任务按需结构化：一个里程碑含多个需独立调度或解除下游前置的任务时，使用骨架的内部任务表，写任务 ID、所属里程碑、交付物/影响路径、前置成果和检查 ID。路径、契约、断言引用正文，不复制全部上下文、不预定无依据的函数细节；简单里程碑省略任务表，任务不另设完成状态或日期，进展与证据仍归入对应里程碑记录。
• 连续实施批次：默认一个实现里程碑就是一批，在 §10 写明整批交付物及完成后运行的检查；确需先解除下游前置、跨风险门或工作过大时，按可验证成果拆批并引用已有任务，不新增批次台账。批次不是单文件、单函数、一次编辑或一轮 goal 对话。批内连续完成相关实现和测试代码，只为当前失败、具体技术疑问或必要前置运行最小反馈；整组局部回归等本批交付齐备再跑，通过后继续下一批，不为汇报或切换任务再验一轮。
• 技术路线写到可直接编码：实施阶段应只剩写代码和跑检查。每个里程碑写明改动落点（路径/符号，新增标 ★）和照着改的同构实现；新增或改变的签名、数据结构、错误语义与页面结构在正文定义，里程碑引用；性能、容量等目标写明达成机制和几分钟内能复测的测量办法。实现者仍需比较做法、查库或框架行为、自行设计接口时，计划没写完。读代码、读依赖源码或做小实验就能回答的技术未知，在第 2–3 步解决并写入结论，不写成「实施时确定」或「到某里程碑再冻结」；只有依赖尚不存在的环境、产物或外部动作的未知才留给实施，排为最早的 spike，写明要回答的问题、判据和每种结果对应的路线。
• 开发前置不等于终验前置：依赖写到实际需要的契约/子任务与验证，不默认等待上游整个里程碑；前置检查必须证明该成果可用。阶段收口通过前不得宣称整期或整条跨期需求已验收。
• 验证分层与执行时点：§9 区分批内最小反馈、批次退出的局部检查和阶段收口。局部检查覆盖本批新增或改动行为、直接受影响模块的已有测试和静态检查，时点写到“哪些交付物齐备后”，不能只写里程碑名或“开发中”。全量测试、端到端、真实环境与界面走查、故障注入、评测和干净构建是收口检查，每阶段只安排一次，不在中间里程碑复跑。阶段按完整、用户可验证的功能组合划分，通常含多个里程碑；计划至少有一个收口。数据、安全、不可逆操作、发布及用户明确要求的风险门仍在实际需要处执行，不因合批延后，也不升级成全量回归。
• 验证与证据复用：§9 定义检查 ID/测试组、覆盖的需求或验收行、可直接运行的命令、环境与执行时点，里程碑引用检查 ID，不重抄断言。局部退出命令限定到包、文件或测试过滤器，不写整仓入口；批内另给能回答具体问题的最小命令，包级测试或静态检查不因叫“局部/快速”就可逐次编辑运行。已知昂贵命令标明成本依据，耗时未知如实写未知；无窄入口时保留在批次退出或收口，不为凑快速反馈另造测试框架。设备、账号、权限、外部审批及观察窗口要有实际获取或执行方式；Agent 能操作的真实检查仍由 Agent 执行，确需人工配合时写清责任方、动作与时点。执行时点晚于所需能力/环境就绪，同一部署可合并 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 步：需求账本与计划定性

先按「开发范围与 non-scope」界定本方改动与外部前置；PRD 的期次决定本期需求集合，不把该期涉及的所有系统一并纳入开发范围。每条需求区分本方承担的行为与依赖方提供的行为，不能因排除外部实现而漏记集成目标或验收前置。

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

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

• 未给出的吞吐、p95、可用性、RPO/RTO、预算等数字不得套用行业示例。能从现有 SLO/配置继承就带路径引用；否则写“未知”，说明它会改变哪个决策以及何时必须确认。
• 定性计划类型：新模块、既有模块增量、纯前端、重构/深模块化、数据迁移、平台横切面或跨系统集成。类型决定需要加载哪些按需参考与裁剪哪些章节。
• 按 PRD 期次出计划：输入为 PRD 加期次（如 P2）时，范围是 PRD 分期矩阵（其默认骨架 §7.2）中落在该期的需求 key 与 AC ID，该期的出口判据、前置与计划规模建议（§7.1）作为约束。账本来源定位到 需求 key/AC ID 与期次；跨期需求写明本期完成哪些 AC、终验在哪一期，非终验期的计划不写成整条需求完成。前置期未交付时按实际影响记 C-*/A-* 并定级。期次不存在、PRD 未分期或分期与条目矛盾时先问，不自行重切；PRD 未分期且未给期次时按整份范围处理。未指定代号时用 PRD 代号加期次，如 LOGIN-P2。
• 真正改变产品形态、权限、数据归属或外部承诺且无法从证据推出的选择，应尽早请用户拍板；不能交互时不得默默代决。

第 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”，不得预填完成记录。顶部「需求来源」按实际来源填写，§10 写与里程碑表一致的提交点。
• 骨架开头的“实施须知”及“实施者定位”“实施进度”协议原样带入计划，不改写、不删减：它们是给执行计划的 agent 的完整合同，与写计划的架构师定位是两回事。回写后自查按计划内条目直接核对，不引入本 skill 的脚本依赖；check_paths.sh、check_progress.sh 与 check_plan.py 留在撰写/评审期使用，不列入计划的实施或终验命令。
• 计划按风险和改动面裁剪，不用固定行数或章节占比衡量质量；调查原始材料不倾倒进正文，只保留结论与来源。

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

1. 跑 "$SKILL_DIR/scripts/check_paths.sh" <计划文件> <仓库根>，人工区分新增路径与虚构的“复用/已核实”路径。
2. 跑 python3 "$SKILL_DIR/scripts/check_plan.py" <计划文件>（Python 3 标准库），检查默认骨架的核心表字段、ID 重复定义/悬空引用与模板残留，逐项处置错误和人工复核告警。再核对账本或映射表中每条需求、约束、假设都有设计、验证、排除去向或阻塞说明；脚本不证明上游内容、设计正确性或真实验收。自定义编号或用户指定模板按同等规则人工核对，不为通过脚本改换模板。可裁剪章节，显式未知/Blocked 与初稿空完成记录合法，未填字段和写作指引须清理。
3. 按「开发范围与 non-scope」反查每项交付、里程碑和验收准备，确认外部缺口未转为本方任务，顶部范围、§0.4/§0.5、§1.2 与 §4/§11 一致；再按 references/architecture-quality.md 的一致性清单检查凭证/scope、接口/调用方、数据约束/生命周期、设计/验证、发布/回滚和多处重复口径。
4. 建失败模式表：高影响失败至少写触发、爆炸半径、数据后果、用户表现、检测、恢复与验证；简单局部任务可说明“不引入新的运行期失败模式”及依据。
5. 检查顶部实施协议为骨架原文在位，计划全文没有本 skill 名称、目录或脚本依赖；「需求来源」与 §10「提交点」已填写；来自 CR 的计划还须核对来源/回写文件、请求范围映射和顶部完成回写规则，不能只在正文提示或要求实施者重新加载技能。每个里程碑退出条件以「回写『实施进度』」结尾，依赖与并行边界明确，阶段收口覆盖被集中的验收且保留必要风险门，中间里程碑的退出条件不含收口检查。沿“同批连续改动 → 局部验收 → 续做 → 收口失败修复”走查：批次有完整交付物，批内不会反复跑整组局部检查，证据失效合并到下一适用验证点，续做不额外触发回归，失败复验不无故扩围。每个里程碑有改动落点与同构实现，没有留给实现者的开放设计；跑 "$SKILL_DIR/scripts/check_progress.sh" <计划文件> <仓库根> 确认进度与里程碑一致、记录链接有效；初稿不预填完成事实，详情不写回计划。
6. 最终定级：存在影响范围、安全、数据、外部契约或关键 NFR 的未决项即 Blocked；只等用户指定的非阻塞评审为 Proposed；所有实施前置已解决才是 Ready。
7. 汇报计划路径与状态，并单列：待拍板问题、与用户假设冲突的事实、被砍/推迟的范围、未在真实环境完成的调查或验证。最后提示下一步用 review-dev-plan <计划路径> 评审本计划，按当前客户端的技能调用写法给出可直接复制的命令（如 Codex $review-dev-plan、Claude Code /review-dev-plan），路径填实际文件。

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

红线

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

项目状态回写

若仓库已登记状态台账，或存在仓根 .xgent-ai/sdlc/protocol.md（兼容已有 docs/project-status/protocol.md；两套并存且未登记切换时先核对，不能双写），交付原产物后读取台账的回写规则（默认目录读上述协议），按仓内协议更新受影响对象的当前状态与来源链接，必要时维护索引；v4 日常直接更新当前页，事件留存条件或旧版事件要求以仓内协议为准；未启用时不自动建表，不依赖另装技能。只读/仅聊天/不保存要求优先，登记失败须说明，不影响如实交付已完成的原产物。

登记计划的实际路径、版本、就绪状态与需求关联；实施状态只取顶部真实进度。台账的依据直接链接原计划的恢复快照/完成记录、相关 <计划名>.records/M<n>.md 的验收或未完项章节、已有评审/处置记录及其版本，不把这些内容重写成 SDLC event、过程总结或证据副本，也不先造 event 再用它替代原记录作为来源。里程碑推进、验证结果更新、最终提交和整份计划完成都只更新当前状态与来源，不因这些动作另建事件。

新建事件前先核对原记录及其可取回版本；仅仓内明确要求不可变审计，或仍有无法由原记录与当前页保留的并发/纠错事实时才独立留存，写明依据与必须保留的差异，其余直接引用。旧协议强制事件时按其要求保留最小必要内容与原记录链接，不再复述实施和验收过程；协议升级须有用户授权。评审模式登记独立评审事实，不替原计划改状态；本次仅聊天时不登记。