Patch Letter Pattern：让你的助手在接触代码前先写一封 Cover Letter
Source: Dev.to
请提供您希望翻译的具体内容（文本、段落等），我将按照要求保留源链接、保持原有的 Markdown 格式并将文本翻译为简体中文。
使用补丁信（Patch Letter）确保 AI 辅助代码更改安全
当你让助手修复一个 bug 时，往往会得到 超出预期的改动——有的很棒，有的……很有创意。
避免意外重构的最快方法不是更大的模型或更长的提示词，而是一个 微小的工作流改动：
在助手编辑代码之前，让它先写一封 补丁信——一封简短的“封面信”，像 pull‑request 描述一样说明拟议的更改。
像审阅规格一样审阅补丁信。只有在你批准后，才让它实现代码。
两步循环
| 步骤 | 发生了什么 |
|---|---|
| 1️⃣ 设计补丁 | 助手编写 补丁信（摘要、动机、实现思路等）。 |
| 2️⃣ 应用补丁 | 获批后，助手编写实际代码。 |
这很无聊，却异常有效。
补丁信迫使助手 在文字上对细节作出承诺：
- 到底会改动哪些内容？
- 会触及哪些文件？
- 哪些内容保持不变？
- 风险点在哪里？
- 我们将如何测试？
大多数 AI 辅助编码失败其实是 规划失败——助手在问题尚未被紧密定义时就开始编写代码。补丁信让计划 可供审阅。
补丁说明模板（10–25 行）
Summary (1–2 lines): 对用户/系统会有什么不同
Motivation: 为何需要此更改
Approach: 实现策略（高层次）
Files/Modules touched: 列出并说明目的
Non‑goals: 此补丁不做的事项
Risk & rollout: 可能出现的问题、如何缓解、回滚说明
Test plan: 你将执行的检查（以及将添加的测试）
Open questions: 在编码前需要决定的任何事项你可以稍后直接将补丁说明粘贴到 PR 描述中。
可直接复制的提示
You are helping me with a code change. **Do NOT write code yet.**
Write a patch letter (like a PR cover letter) for the change below.
Context:
- Repo: [language/framework]
- Constraints: [time budget, style guide, perf, backward compatibility]
- Target behavior: [what should happen]
- Current behavior: [what happens today]
- Evidence: [logs, stack trace, failing test, reproduction steps]
Requirements:
- Keep it under 25 lines.
- Include: Summary, Motivation, Approach, Files touched, Non‑goals, Risks, Test plan, Open questions.
- Be specific: name the likely modules/files and the key functions/areas.
Change request:
[describe the change]
The key line is **“Do NOT write code yet.”**
You’re not banning code forever – you’re sequencing it.示例演练
场景： 一个 API 端点返回分页结果。用户报告在使用特定过滤条件时 page=2 缺少项目。
Context:
- Repo: Node.js + Express + PostgreSQL
- Constraints: no breaking response changes; keep query fast; do not change DB schema
- Target behavior: pagination is stable and deterministic
- Current behavior: items can be skipped or duplicated between pages
- Evidence: QA repro — filter=active, sort=updatedAt desc变更请求：
在按 updatedAt 排序时，即使多行共享相同时间戳，也要使分页保持稳定。
一封完整的补丁说明
Summary: Make /items pagination deterministic by adding a stable tie‑breaker to the sort.
Motivation: When multiple rows share `updatedAt`, offset/limit with a non‑unique ORDER BY can skip/duplicate rows across pages.
Approach: Keep primary sort `updatedAt DESC`, add `id DESC` as a secondary key; ensure cursor/offset logic matches the composite order.
Files touched:
- src/routes/items.ts (handler)
- src/db/itemsQuery.ts (query builder)
- tests/items.pagination.test.ts (new regression tests)
Non‑goals: No schema changes; no new pagination API; no changes to response shape.
Risk & rollout: Existing clients relying on implicit ordering may see a different (but now deterministic) item order for equal `updatedAt`.
Test plan: Add regression test with fixture rows sharing `updatedAt`; verify page 1 + page 2 contain all IDs exactly once; run full test suite.
Open questions: Are we using offset pagination or cursor pagination today? If cursor, what field(s) are encoded?此举的意义
- 解释了 bug 产生的原因。
- 指出了 可能需要编辑的文件。
- 标明 非目标，防止出现隐蔽的重构。
- 突出了 编码前必须明确的关键点：是使用 offset 还是 cursor。
此时，你可以回答开放性问题，调整计划，并 批准 这封补丁说明。随后让助手 实现 该变更。
Assistant 规则（补丁信获批后）
- 保持在非目标范围内。
- 如果发现需要违反非目标或触及其他文件，立即停止并首先提出更新的补丁信。
- 在代码之后，输出与 测试计划 相匹配的简短检查清单。
- (可选) 实现后，在展示完整代码之前提供 10 行差异摘要——这是大型补丁的第二次审查检查点。
何时使用补丁信
- 多个文件 被修改。
- 逻辑或查询被更改。
- 此更改可能导致 范围蔓延。
如果你只做一个很小的局部修改（重命名变量、修正拼写错误），使用补丁信显得大材小用。
TL;DR
- 首先请求补丁信。
- 审核并批准它。
- 然后 请求实现。
这就形成了一个清晰的“合同”：助手可以快速行动，但不能悄悄扩大范围。补丁信往往已经是 80 % 的优秀 Pull Request——包括清晰的摘要、理由、明确的风险以及测试——只剩下实际代码需要添加。
破坏生产环境，
…补丁信只花你 约60 秒，却为你节省 一小时的审查时间。
补丁信模式
- 使计划可审查。
- 批准计划。
- 编写代码。
这是我所知道的保持 AI‑辅助编码 快速 且 理智 的最简单方法。
试试看：
从一个地方——你的下一个 bug‑fix PR。先请求一封补丁信，你会立刻感受到不同。