If you use an assistant to help you code, you’ve probably seen this movie:
- You ask for a small fix.
- You get a lot of changes.
- Some of them are great.
- Some of them are… creative.
- And now you’re reviewing a surprise refactor you didn’t budget for.
The fastest way I’ve found to prevent that isn’t a better model or a longer prompt.
It’s a tiny workflow change:
The Patch Letter Pattern
Before the assistant edits code, make it write a patch letter — a short “cover letter” describing the proposed change as if it were a pull request description.
You review the patch letter like a spec. Only after you approve it do you ask for implementation.
This turns “please fix this” into a controlled two-step loop:
- Design the patch (patch letter).
- Apply the patch (code).
It’s boring. It’s also ridiculously effective.
Why it works
A patch letter forces the assistant to commit to specifics in text:
- What exactly will change?
- Which files will be touched?
- What won’t change?
- What’s the risk surface?
- How will we test it?
Most AI-assisted coding failures are really planning failures. The assistant starts writing before the problem is framed tightly enough.
A patch letter makes the plan reviewable.
What a good patch letter contains
Keep it short (10–25 lines). I like this structure:
- Summary (1–2 lines): what will be different for users/systems
- Motivation: why this change is needed
- Approach: the implementation strategy (high level)
- Files/Modules touched: list, with purpose
- Non-goals: what we will not do in this patch
- Risk & rollout: what could break, how to mitigate, rollback notes
- Test plan: the checks you will run (and which tests you’ll add)
- Open questions: anything that needs a decision before coding
You can paste the patch letter directly into a PR description later.
Prompt template: “Write the patch letter”
Copy/paste this prompt and fill in the bracketed parts:
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.
Example: Fix a subtle pagination bug
Let’s say you have an API endpoint that returns paginated results. Users report missing items when they request page=2 with certain filters.
You send:
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
Change request:
Make pagination stable when sorting by updatedAt, even when multiple rows share the same timestamp.
A solid patch letter would look like:
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.
Risks: 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 page1+page2 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?
Notice what this accomplishes:
- It explains why the bug happens.
- It names the likely files.
- It calls out non-goals so you don’t get a stealth refactor.
- It surfaces the one thing that matters before coding: offset vs cursor.
At this point you can answer the open question and adjust the plan.
Prompt template: “Implement exactly this patch letter”
Once you approve the patch letter, send it back and ask for implementation.
Implement the change described in this patch letter.
Rules:
- Stay within the Non-goals.
- If you discover you need to violate a Non-goal or touch additional files, STOP and propose an updated patch letter first.
- After the code, output a short checklist matching the Test plan.
Patch letter:
[paste the patch letter here]
This creates a clean “contract”: the assistant can move fast, but it can’t silently expand scope.
Practical tips (this is where it gets good)
1) Use the patch letter as your PR description
You’ll often find that the patch letter is already 80% of a great pull request:
- clear summary
- rationale
- explicit risks
- explicit tests
You can later edit it for tone, but the structure stays.
2) Turn “Open questions” into decisions
If the patch letter includes open questions, you have options:
- Answer them.
- Provide constraints (“we can’t change that API”).
- Or explicitly defer them (“out of scope for this patch”).
The point is that you make decisions before code is written.
3) Ask for a "diff summary" before the diff
If you want even tighter control, add one more line:
After implementing, provide a 10-line diff summary (what changed where) before showing code.
It sounds redundant, but it’s a second review checkpoint — especially useful when the assistant outputs a large patch.
4) Works for refactors too
For refactors, patch letters are even more valuable because refactors are where scope creep hides.
Add a non-goal like:
- “No behavior changes; only restructure.”
And force a test plan like:
- “Run golden tests / snapshot tests / integration tests.”
When not to use it
If you’re doing a tiny, local change (rename a variable, fix a typo), a patch letter is overkill.
But for anything that:
- touches multiple files,
- changes logic,
- changes queries,
- or could break production,
…the patch letter costs you ~60 seconds and saves you an hour of review.
Takeaway
The Patch Letter Pattern is just this:
- Make the plan reviewable.
- Approve the plan.
- Then write code.
It’s the easiest way I know to keep AI-assisted coding fast and sane.
If you try it, start with one place: your next bug fix PR. Ask for a patch letter first, and you’ll feel the difference immediately.
Top comments (0)