code-delivery-gate

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. §1 计划更新：目标、改动范围表、明确不做、依赖前置。
2. §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

1. 阅读 RUNBOOK，执行「交付前自检」清单。
2. 自行完成所有 Agent 项。
3. 结果写入交付摘要「自主验证」一节。

---

阶段四：工程完成后 — 项目文档

全部工程工作（含阶段一～三）完成后，在交付摘要之前，编写或更新项目级文档。

文件路径

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 可做的安装/测试/看日志甩给用户。