---
date: 2026-05-11
tags: [pr-workflow, dogfooding, body-sync]
severity: medium
---

# PR push 新 commit 后必须按最终状态视角 PATCH body，不要堆 addendum

## 现象

PR #301（落地 PR 模板 v2）已 push 第一个 commit + 创建 PR + body 写好。随后用户要求把 AI Review 评论模板合到本 PR 一起推。第二个 commit push 后，我用 Gitea API PATCH 在 PR body 末尾追加一段：

```markdown
---

## 追加 commit：AI Review 评论结构化（commit d3275d22）

**第二个 commit 主题**：把 ai-review-runner ...
```

**用户当场指出问题**："PR 已提交后再 commit，应该更新 PR，把最新的情况反映上去"——意思是要按"合并后是什么"重写整个 body，不是堆"原来 + 后来又加了"的演进史。

## 根因

两个本能错误叠加：

1. **"补丁式" PATCH 心态**：API PATCH 允许传完整新 body，但我下意识只想"加一段"——把新 commit 当作 PR 描述的增量。
2. **忘了自己刚定的规则**：13-pr-description-spec.md 元规则 #1 写着"写最终状态，不写演进过程"——而"## 追加 commit"段就是演进史。**本 PR 自身就是 dogfooding 规范的 PR，却第一时间违反了自己写的规则**。

讽刺点：这个错误恰恰证明了为什么规范本身需要写入 13-——人/AI 的本能就是堆增量，不重写最终状态。

## 解法

**规则 #6 加入 13-pr-description-spec.md 六条元规则**（含本 PR 第 6 commit 的 title 扩展）：

> PR push 新 commit 后必须 PATCH **title + body** 反映最终状态。重写整个 body 按"合并后是什么"视角；改 `## 主要组成` / `## 后续跟进` / `## 权衡与备选方案` 等已有段补充新增内容，不新增 "## 追加 ..." 段。**如果 PR 内容已超出原 title 涵盖范围，同步 PATCH title**。

### title 扩展的二次 dogfood

第 5 commit push + body 5 次 PATCH 后，用户指出"PR 标题没改"——title 还是第 1 commit 的"模板 v2 — 两层设计 + 全中文段标题 + 未来回顾段"，已不能涵盖 5 commit 的真实内容（含 AI Review 结构化 / 规则 #6 / 本地前置自检）。

把规则 #6 从"PATCH body"扩展为"PATCH title + body"——title 也是 PR 最终状态的一部分，跟 body 同源。Gitea API `PATCH /pulls/<num>` 接受 `title` + `body` 字段，一次调用同时改。

落地点：
- `docs/standards/13-pr-description-spec.md`：元规则表 5 条 → 6 条；评审检查清单加一项
- `.agents/skills/git-main/SKILL.md` 第 5 段：列具体做法（重写整个 body / 改已有段 / 用 PATCH API）
- `.agents/skills/code-review/references/review-checklist.md` 关注级问题：加 "PR push 新 commit 后 body 没 PATCH 跟上最终状态" 作为高频违规

## 给未来 AI 的判断口诀

每次 push 新 commit 到已存在 PR 之后**必须**：

1. 当作"PR 现在做了什么"重新写一遍 body，不是当作"原 body + 补丁"
2. 把新 commit 的内容融进现有段（`## 主要组成` 表格新加一行 / `## 权衡与备选方案` 新加一个 bullet / `## 后续跟进` 划掉解决的、加新发现的）
3. **不要**新增 `## 追加 commit X / ## 补丁 / ## Update N` 这类演进史段
4. Gitea API：`PATCH /repos/<owner>/<repo>/pulls/<num>` body 字段传新 body，单次完整替换

判定线：合并后 reviewer 看 squash 后的 commit 是看不到"演进"的——squash 把多个 commit 合成一个，只有 PR body 是 reviewer 看到的 PR 完整描述。body 写演进 = reviewer 看不到，未来 archaeologist 看到的是"PR 干了 X，然后又加了 Y"——和"PR 最终干了 X + Y"传递的信息完全不同。

## 关联

- PR #301（本次犯错 + 修复 + 规则沉淀的同一个 PR）
- 元规则 #1（"写最终状态，不写演进过程"）——本规则 #6 是 #1 的应用扩展，针对"PR 已存在 + 后续 commit"这个特定场景