dbvc/commit-pr-contract

Commit/PR Contract

目标

• 生成中文的 commit title/body 与 PR 描述
• 强调 commit 是长期证据，PR 是 reviewer 视角的说明
• 只以最终变更集为事实边界，来源限于用户提供的 diff、指定 commit、staged changes 或 working tree changes
• 聊天内容只用于输出范围、ticket/type、AI 是否参与、以及用户明确给出的最终事实；不要写入讨论过程、失败尝试、被否决方案、review 往返、临时调试
• 尽量从最终变更集自行推断风险与 review focus
• 动机、风险、验证如果不在最终变更或用户明确给出的最终事实里，不补叙、不脑补，必要时少写
• 保持简洁、可复用、可追溯

工作流

1. 判断输出范围：只 commit、只 PR、或两者都要
2. 先确定最终变更集：优先使用用户提供的 diff、指定 commit、staged changes 或 working tree changes
3. 从最终变更集提取事实；只在需要补足命名、行为或影响面时查看相关文件
4. 优先根据最终变更集推断动机、风险、验证方式、review focus；推断不了就少写或明确写出缺口
5. 识别是否为多主题改动；如是，提示建议拆分 commit（不强制）
6. 仅补齐最少的必要信息：ticket 编号、commit type、AI 是否参与，以及任何会影响关键结论的缺失事实
7. 生成 commit message（按规则与模板）
8. 生成 PR 描述（按合同式四块结构）

输入最小清单（优先从最终变更获取，缺失时再询问）

• 最终变更集：用户提供的 diff、指定 commit、staged changes 或 working tree changes
• AI 是否参与
• ticket 编号（M-xxx）与 commit type
• 业务动机/影响范围/用户体验变化（仅在最终变更无法支撑结论时询问）
• 验证证据（测试/命令/日志/指标/截图；仅在需要写明 Proof 且现有事实不足时询问）
• 风险与缓解/回滚方式（仅在最终变更无法推断时询问）
• Reviewer 重点关注点（1-2 个，仅在最终变更无法推断时询问）

推断优先级

1. 最终变更集中的事实（用户提供的 diff、指定 commit、staged changes、working tree changes）
2. 用户明确提供且属于最终事实的信息（如 ticket/type、AI 是否参与、已执行的验证）
3. 明确标注的推断（不要伪造证据，不要把聊天过程当成事实）

聊天中的讨论过程、失败尝试、被否决方案、review 往返、临时调试默认不进入输出，除非用户明确要求写入且它们仍然属于最终事实的一部分。

风险与 Review focus 推断提示

• 影响面：是否改动接口/数据结构/配置/权限/支付/计费/安全
• 兼容性：向后兼容、迁移、版本依赖、灰度策略
• 可靠性：异常处理、边界条件、超时/重试、并发/竞态
• 性能：热点路径、N+1、缓存失效、批量规模
• 可观测性：日志/指标/告警是否覆盖关键路径
• 回滚：是否可回退、是否需要数据修复
• 如果能判断风险等级，写出高/中/低并说明原因
• Review focus 只挑 1-2 个最重要的可验证点

Commit message 规则（长期证据）

• 使用格式：M-xxx(type): {title}
• 不臆造 ticket 编号；未知时保留 M-xxx
• 从 feat|fix|inf|chore|test|docs 选 type；不确定时请求澄清或基于改动推断
• Title 说明"做了什么 + 影响对象"，避免复述 PR 关注点
• Body 仅保留长期有价值的信息，避免评审指令/临时协作细节，也不要写聊天里的讨论过程、失败尝试、被否决方案、review 往返、临时调试
• Body 小节按需选用，不强行全写：
  • Why/Context: 仅写最终变更或用户明确最终事实能支撑的动机、业务影响
  • What: 关键实现或行为变化
  • Proof: 只写具体证据，优先使用 自动：<命令或测试名>、手动：<操作与观察结果>、未验证：<明确缺口>
  • Risk: 潜在风险与缓解（仅长期有效信息）
  • Notes: 兼容性/数据迁移/行为差异等
• 没有证据时可以省略 Proof；如果写 Proof，内容必须具体；需要表达未验证时，明确写 未验证：...
• 不要写空泛表述，如 Proof: 已测试、Proof: 测试通过、Proof: 本地测过
• 多主题改动时，提示"建议拆分 commit"，简述原因

PR 描述规则（Reviewer 视角）

• 使用四块结构（中文标题）：
  1. 做了什么/为什么（What/Why）
  2. 证明它可行（Proof it works）
  3. 风险与 AI 参与（Risk + AI role）
  4. 评审关注点（Review focus）
• 默认认为 AI 参与；如用户明确未使用 AI，则写"AI 参与：无"
• 第二块固定写成 1-3 行具体证据：自动验证：...、手动验证：...、未验证：...
• 有验证就写执行项与观察结果；完全没有验证时只写 未验证：...，不要虚构 proof
• 不要写空泛表述，如 证明它可行：验证通过、证明它可行：本地测试通过
• 风险描述面向评审：影响范围、失败方式、缓解/回滚
• Review focus 要具体、可行动（如"关注 X 边界条件""确认 Y 配置覆盖面"）
• 避免复制 commit body；强调评审理解与验证
• 不要把聊天里提到但最终没落地的方案写进 PR 描述

输出格式

• 先输出 commit title + body（纯文本，无额外标签）
• 空一行
• 再输出 PR 描述四块（用清晰标题/小节）

正反例

• 反例：Proof: 已测试
• 反例：证明它可行：验证通过
• 反例：写入"先试了 A 方案，后来改成 B 方案"；如果最终变更只落地 B，就不要记录 A 的讨论过程
• 正例：自动验证：pnpm lint && pnpm test
• 正例：手动验证：创建订单并确认状态流转为 paid