패치 레터 패턴: 어시스턴트가 코드를 건드리기 전에 커버 레터를 작성하게 하세요

발행: 13시간 전 (2026년 3월 5일 오전 12:23 GMT+9)

8 분 소요

I’m ready to translate the article for you, but I need the full text you’d like translated. Could you please paste the content (or the portion you want translated) here? I’ll keep the source link exactly as you provided and preserve all formatting, code blocks, URLs, and technical terms. Thank you!

Source:

패치 레터를 사용하여 AI‑지원 코드 변경을 안전하게 유지하기

어시스턴트에게 버그 수정을 요청하면 예상보다 더 많은 변경이 발생하곤 합니다 – 좋은 것도 있고, … 창의적인 것도 있습니다.
놀라운 리팩터링을 피하는 가장 빠른 방법은 더 큰 모델이나 더 긴 프롬프트가 아니라 작은 워크플로우 변화입니다:

어시스턴트가 코드를 편집하기 전에 패치 레터를 작성하도록 하세요 – 풀‑리퀘스트 설명처럼 제안된 변경을 요약한 짧은 “커버 레터”입니다.
패치 레터를 사양서처럼 검토하세요. 승인한 뒤에야 구현을 요청합니다.

두 단계 루프

단계	내용
1️⃣ 패치 설계	어시스턴트가 패치 레터를 작성합니다 (요약, 동기, 접근 방식 등).
2️⃣ 패치 적용	승인을 받은 후 어시스턴트가 실제 코드를 작성합니다.

지루하지만, 놀라울 정도로 효과적입니다.

패치 레터는 어시스턴트가 텍스트로 구체적인 내용에 커밋하도록 강제합니다:

정확히 무엇이 바뀔까요?
어떤 파일이 수정될까요?
무엇은 바뀌지 않을까요?
위험 영역은 어디인가요?
어떻게 테스트할까요?

대부분의 AI‑지원 코딩 실패는 실제로 계획 실패입니다 – 어시스턴트가 문제를 충분히 명확히 정의하기 전에 코딩을 시작하거든요. 패치 레터는 계획을 검토 가능하게 만들어 줍니다.

Patch Letter Template (10–25 lines)

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

나중에 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?

이것이 달성하는 바

버그가 발생하는 이유를 설명합니다.
수정할 가능성이 높은 파일을 명시합니다.
비목표를 명시해 은밀한 리팩터링을 방지합니다.
코딩에 앞서 가장 중요한 한 가지인 offset vs. cursor 여부를 강조합니다.

이 시점에서 열린 질문에 답하고 계획을 조정한 뒤 패치 레터를 승인할 수 있습니다. 그런 다음 어시스턴트에게 구현을 요청하면 됩니다.

Understood. I will follow these rules for any future patch‑letter requests.

패치 레터를 사용해야 할 때

여러 파일이 수정됩니다.
로직이나 쿼리가 변경됩니다.
변경으로 인해 스코프 크리프가 발생할 수 있습니다.

변수 이름을 바꾸거나 오타를 수정하는 등 아주 작은 로컬 변경이라면, 패치 레터는 과도합니다.

TL;DR

먼저 패치 레터를 요청하세요.
검토하고 승인하세요.
그 다음 구현을 요청하세요.

이렇게 하면 깔끔한 “계약”이 만들어집니다: 어시스턴트는 빠르게 움직일 수 있지만 범위를 조용히 확장할 수 없습니다. 패치 레터는 종종 **훌륭한 풀 리퀘스트의 80 %**에 해당합니다—명확한 요약, 근거, 명시적인 위험 및 테스트—실제 코드를 추가하는 부분만 남게 됩니다.

프로덕션 중단,
…패치 레터는 ~60초 정도 걸리며 1시간의 리뷰 시간을 절약해 줍니다.