| name | code-delivery-gate |
| description | 每个 Agent 对话默认遵循的交付质量门：写代码前写更新日志锁定计划与逻辑链；交付前三 阶段（清理、对照日志自查、RUNBOOK 运维）；全部完成后写 docs/PROJECT.md 类项目文 档。适用于一切写代码、改代码、修 bug、重构、交付或声称「已完成」的任务。 |
| disable-model-invocation | false |
代码交付质量门（Code Delivery Gate）
默认启用：已配置为自动套用（disable-model-invocation: false + 建议写入 Cursor User Rules，见 USER-RULE.md）。
硬性规则：涉及写/改代码时，必须按 阶段零 → 实现 → 阶段一 → 阶段二 → 阶段三 → 阶段四 顺序执行。在向用户汇报「已完成」之前，阶段一～三须全部通过；阶段零与阶段四不得跳过。
总流程
阶段零（写代码前）→ 实现代码 → 阶段一（清理）→ 阶段二（对照日志自查）→ 阶段三（运维）→ 阶段四（项目文档）→ 交付摘要
| 阶段 | 时机 | 产出 |
|---|
| 零 | 动任何代码之前 | docs/delivery/logs/YYYY-MM-DD-<任务>.md |
| 一 | 声称完成之前 | 改动区内无多余代码 |
| 二 | 阶段一之后 | 更新日志第 4 节「自查结论」已填写 |
| 三 | 阶段二之后 | RUNBOOK 自检已执行 |
| 四 | 阶段三之后、交付摘要之前 | docs/PROJECT.md（新建或增量更新） |
模板：templates/UPDATE-LOG-TEMPLATE.md · templates/PROJECT-DOC-TEMPLATE.md · 详版样例：example.md
Skill 使用提醒（对用户可见）
让用户知道本 skill 已生效；同一对话内不重复刷屏。
何时提醒
| 时机 | 是否必须 | 说明 |
|---|
| 首次适用本 skill | 必须 | 第一次开始写/改代码或进入交付流程时 |
| 阶段零 / 一 / 二 / 三 / 四 | 可选 | 各最多一行进度提示 |
| 最终交付摘要 | 必须 | 见下方「完成标记」 |
纯问答、只读、未改代码且未声称完成 → 不提醒。
提醒格式
启用（首次，回复最前一行）：
> **[code-delivery-gate] 已启用** — 阶段零（更新日志）→ 实现 → 阶段一（清理）→ 阶段二（对照自查）→ 阶段三（运维）→ 阶段四（项目文档）。
完成标记（交付摘要标题下第一行）：
> **[code-delivery-gate] 已执行** — 阶段零～四已完成（日志 ✓ / 清理 ✓ / 对照自查 ✓ / 运维 ✓ / 项目文档 ✓）。
未全完成时将对应 ✓ 改为 部分 并说明；禁止虚假「已执行」。
阶段零：写代码前 — 更新日志（阶段二对照 SSOT）
在创建或修改任何项目代码之前，必须先写更新日志。未写日志不得开始写代码（紧急 hotfix 可边写边补，但须在阶段二前补全并注明）。
文件路径
docs/delivery/logs/YYYY-MM-DD-<任务简称>.md
- 目录不存在则创建。
<任务简称>：kebab-case，如 add-auth-login、fix-payment-webhook。- 同对话续写同一任务 → 更新同一文件，勿新建重复日志。
必填内容
按 templates/UPDATE-LOG-TEMPLATE.md 填写至少：
- §1 计划更新：目标、改动范围表、明确不做、依赖前置。
- §2 目标逻辑链：六环链路 + 每环预期行为与计划涉及的文件/函数 + 验收标准 + 风险边界。
写代码过程中可在 §3 实施记录 追加实际改动；与计划偏离须在表中说明原因。
与阶段二的关系
阶段二的逻辑链路自查 以本节 §2 为唯一对照标准（SSOT）：
- 代码与 §2 不一致 → 要么改代码，要么先改日志 §3 说明再改代码。
- 阶段二结束时必须填写日志 §4 自查结论（逐环打勾 + 偏差说明）。
阶段一：写完代码后 — 区域内多余代码检查
范围：本次任务新增或修改的文件及其直接依赖。
| 检查项 | 处理 |
|---|
| 未使用的 import / 变量 / 函数 / 组件 / 类型 | 删除 |
| 重复 helper（与项目已有工具重复） | 删除或复用现有 API |
| 注释大段旧代码、调试输出、临时 mock | 删除或正式实现 |
| 复制粘贴残留、死路由、未接线 UI | 合并/删除/完成接线 |
| 过宽 try/catch、空占位 | 实现或 TODO+原因 |
阶段二：写完代码后 — 严肃自查（对照更新日志）
先打开 本次任务的 docs/delivery/logs/….md，再执行下列自查。
2.1 逻辑链路自查（对照 §2）
逐环核对：代码是否真实存在且可到达，并与日志 §2 一致。
触发入口 → 输入校验 → 核心逻辑 → 持久化/副作用 → 返回/展示 → 失败与回滚
必须能回答：入口、数据流、分支、副作用、边界、回归——答案须能指向具体文件/函数，并与日志 §2 表一致。
有测试则跑；有构建则构建；有 linter 则查改动文件。
2.2 用户负担自查
凡 agent 能执行的（安装、迁移、测试、构建、lint、日志、健康检查）必须由 agent 执行；仅密钥/生产授权等才可要求用户。
2.3 回填更新日志 §4
在日志文件中填写「阶段二自查结论」，全部通过后再进入阶段三。
阶段三：自主运营运维
路径：ops/RUNBOOK.md
- 阅读 RUNBOOK，执行「交付前自检」清单。
- 自行完成所有 Agent 项。
- 结果写入交付摘要「自主验证」一节。
阶段四：工程完成后 — 项目文档
全部工程工作（含阶段一～三）完成后，在交付摘要之前，编写或更新项目级文档。
文件路径
docs/PROJECT.md
已存在则 增量更新（改架构/流程/命令/变更索引），勿另起无关文件名。
写法要求
- 结构：以 templates/PROJECT-DOC-TEMPLATE.md 为骨架。
- 深度与可读性：以 example.md 为参考样例——面向「产品、新同学、想理解怎么跑起来的人」；写清模块职责、关键逻辑链、怎么跑怎么查，避免只堆文件列表。
- 必须包含：项目是干什么的、架构/模块、至少一条与本次改动相关的主流程逻辑链、真实可复制的安装/测试/构建命令、链到本次
docs/delivery/logs/….md 的变更索引。
- 禁止：空模板、与代码不符的过时描述、把交付摘要原样粘贴当项目文档。
完成汇报模板
## 交付摘要
> **[code-delivery-gate] 已执行** — 阶段零～四已完成（日志 ✓ / 清理 ✓ / 对照自查 ✓ / 运维 ✓ / 项目文档 ✓）。
### 改动范围
[文件/模块列表]
### 更新日志（阶段零 / 二）
[`docs/delivery/logs/….md`](docs/delivery/logs/….md) — §4 自查结论摘要
### 多余代码清理
[删除了什么 / 为何保留某段]
### 逻辑链路结论
[对照日志 §2：入口→结果，关键分支与失败路径]
### 自主验证（运维）
[命令与结果]
### 项目文档（阶段四）
[`docs/PROJECT.md`](docs/PROJECT.md) — 本次更新章节摘要
### 仍需您配合（仅必要时）
[精确步骤；若无写「无」]
禁止事项
- 禁止未写阶段零更新日志就开始改代码（hotfix 除外且须补录）。
- 禁止阶段二不对照更新日志、不填 §4 自查结论。
- 禁止跳过阶段四或交付时不链出
docs/PROJECT.md。
- 禁止在未完成阶段一～三时使用「应该没问题」「你试一下」。
- 禁止把 agent 可做的安装/测试/看日志甩给用户。
