Claude Code 리뷰 워크플로 체크리스트: 출시 전 PR 리스크 잡기

첫 세 줄이 리뷰 깊이를 정합니다

Claude Code 리뷰가 얕게 느껴질 때 문제는 보통 모델 자체가 아닙니다. 변경 범위, 깨지면 안 되는 동작, 실행한 검증, 사람이 내려야 할 판단을 주지 않으면 결과는 무난한 요약으로 흐릅니다.

여기서 말하는 리뷰 워크플로는 AI에게 감상을 맡기는 일이 아닙니다. diff를 작게 정의하고, 리스크를 이름 붙이고, 증거를 남긴 뒤, findings 중심의 결과를 받아 사람이 최종 판단하는 절차입니다.

초보자를 위해 풀어 쓰면 diff는 “이번 PR에서 바뀐 부분”, review gate는 “배포 전 반드시 통과하는 관문”, verification receipt는 “무엇을 실행했고 어떤 결과였는지 남기는 증거”입니다. Claude Code 기본은 공식 Claude Code overview와 common workflows를 참고하세요. Pull request 리뷰 상태는 GitHub pull request reviews, Node 명령은 npm scripts 문서가 기준입니다.

이 글은 더 세부적인 Claude Code 코드 리뷰 체크리스트와 verification receipt workflow와 함께 쓰면 좋습니다.

Claude Code에 diff를 주기 전에 정리할 것

좋은 리뷰에는 Scope, Risk, Evidence, Handoff가 필요합니다. 이 네 가지가 없으면 Claude Code는 위험한 결함보다 일반적인 개선 의견을 먼저 말하기 쉽습니다.

입력	목적	약한 작성	강한 작성
Scope	변경 범위 제한	여러 가지 수정	글 하단 CTA 링크, 문구, 모바일 여백만 변경
Risk	영향 명시	문제 없을 듯	제품, 상담, 내부 링크가 매출 경로에 영향
Evidence	검증 증거	로컬에서 봄	npm run build 성공, 360px에서 CTA 클릭 확인
Handoff	출력 정의	봐 주세요	P1/P2/P3 findings, 잔여 리스크, 다음 체크 반환

flowchart LR
  A["Diff"] --> B["Scope and risk"]
  B --> C["Claude Code review"]
  C --> D["Human decision"]
  D --> E["Fix, verify, or ship"]
  E --> F["Review receipt"]

중요한 경계는 분명합니다. Claude Code는 승인자가 아니라 두 번째 검토자입니다. 누락을 줄이고, 테스트를 제안하고, 약한 가정을 지적할 수 있지만 수정, 재검증, 출시 여부는 PR 소유자가 결정합니다.

리뷰 전 체크리스트

먼저 작업 트리 상태와 검증 명령을 모읍니다. 아래 예시는 Node 프로젝트 기준입니다. 다른 스택에서는 go test ./..., pytest, bundle exec rspec 같은 팀 표준 명령으로 바꾸면 됩니다.

git status --short
git diff --stat
git diff --name-only
npm run build
npm run test -- --runInBand

다음 체크리스트를 PR 설명, .github/review-checklist.md, 팀 Wiki에 넣을 수 있습니다.

# Claude Code Review Checklist

## Scope
- [ ] This PR has one clear purpose.
- [ ] Changed files match the stated purpose.
- [ ] No unrelated formatting, dependency, or generated files are mixed in.

## Risk
- [ ] Risk level is marked as low, medium, or high.
- [ ] User-facing routes, forms, auth, billing, analytics, and CTA paths are named.
- [ ] Rollback or recovery steps are written for high-risk changes.

## Evidence
- [ ] Build, test, lint, or typecheck commands are listed with results.
- [ ] Manual checks include browser width, account state, and actual URL when relevant.
- [ ] Screenshots, logs, or console output are attached for UI and integration changes.

## Review output
- [ ] Findings come first, ordered by severity.
- [ ] Each finding has file reference, reproduction condition, and expected fix.
- [ ] Residual risk is written even when no blocker is found.

이 체크리스트의 목적은 “괜찮아 보인다”는 감상이 아니라 출시 전에 막아야 할 위험을 찾는 것입니다.

바로 쓸 수 있는 리뷰 프롬프트

프롬프트는 짧아도 됩니다. 대신 findings first, severity order, do not rewrite code yet를 명확히 넣습니다.

Review this diff with a bug-finding mindset.

Scope:
- Only review the files changed in this PR.
- Do not rewrite code yet.

Prioritize:
1. behavioral regressions
2. security, privacy, or permission mistakes
3. missing tests or weak verification
4. broken mobile layout, internal links, product CTA, or training CTA

Return:
- Findings first, ordered by P1/P2/P3 severity
- File and line references when possible
- Why each issue matters to users or revenue
- Checks I should run next
- Residual risk if no blocker is found

첫 번째 패스는 읽기 전용으로 두는 편이 안전합니다. 리뷰 중에 Claude Code가 바로 수정하면, 어떤 이슈가 왜 중요했는지 팀이 추적하기 어렵습니다. findings에 합의한 뒤 별도 수정 작업으로 넘깁니다.

실무에서 자주 쓰는 네 가지 사례

첫 번째는 CTA와 매출 경로 변경입니다. 글 하단, 제품 카드, 가격 문구, 상담 링크를 바꿨다면 대상 URL, 상품 매칭, 버튼 순서, 모바일 레이아웃, analytics 이벤트를 함께 봅니다. “템플릿” 버튼이 예전 Gumroad 상품으로 가는 것은 실제로 흔한 실패입니다. 글 안에서는 /ko/products/와 /ko/training/ 경로를 독자 의도에 맞게 배치해야 합니다.

두 번째는 인증, 권한, 개인정보입니다. UI 버튼을 숨기는 것과 서버에서 권한을 검증하는 것은 다릅니다. Claude Code에는 누가 실행할 수 있는지, 누가 거부되어야 하는지, 로그에 email이나 payment ID가 남는지, 거부 경로 테스트가 있는지 보게 해야 합니다.

세 번째는 다국어 게시입니다. 한 언어는 자연스러워도 다른 언어에는 오래된 updatedDate, 닫히지 않은 code fence, 빠진 제품 링크, mojibake가 있을 수 있습니다. 프롬프트에는 정확히 어떤 locale 파일만 만질 수 있는지, 어떤 metadata를 보존해야 하는지, 어떤 문자열을 반드시 확인해야 하는지 적습니다.

네 번째는 build 또는 test 실패 triage입니다. 긴 로그 전체보다 실패 명령, 마지막 관련 로그, 직전 diff, 이미 시도한 조치를 주는 편이 좋습니다. 작은 build fix가 무관한 의존성 업데이트로 커지는 것이 흔한 함정입니다.

실패 사례와 피하는 법

가장 나쁜 요청은 “전체를 review 해줘”입니다. 범위가 넓으면 Claude Code는 일반론으로 빠집니다. 더 좋은 요청은 파일, 위험, 제외 범위를 먼저 씁니다.

두 번째 실패는 증거가 없는 리뷰입니다. npm run build, typecheck, 브라우저 경로, 모바일 확인 여부가 없으면 리뷰는 추측이 됩니다. 실행하지 못한 명령도 이유와 함께 적어야 합니다.

수익 경로는 데스크톱만 확인하는 실수가 많습니다. CTA 줄바꿈, 가로 스크롤, /products/와 /training/ 순서, 실제 대상 페이지 오류는 코드만 읽으면 놓치기 쉽습니다.

보안에서는 API key, token, 고객 email, 결제 ID, private content를 프롬프트에 넣지 않습니다. 로그는 최소 재현 정보로 줄인 뒤 전달합니다.

verification receipt를 스크립트로 확인하기

아래 Node 스크립트는 review receipt에 필요한 섹션과 하나 이상의 체크된 명령이 있는지 확인합니다. 완전한 품질 보증은 아니지만, 증거 없이 배포하는 실수를 줄입니다.

{
  "requiredSections": ["Scope", "Risk", "Checks run", "Findings", "Residual risk"]
}

#!/usr/bin/env node
const fs = require("node:fs");

const receiptPath = process.argv[2] || "review-receipt.md";
const policyPath = process.argv[3] || "review-policy.json";
const receipt = fs.readFileSync(receiptPath, "utf8");
const policy = fs.existsSync(policyPath)
  ? JSON.parse(fs.readFileSync(policyPath, "utf8"))
  : { requiredSections: ["Scope", "Risk", "Checks run", "Findings", "Residual risk"] };

const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
const missingSections = policy.requiredSections.filter((name) => {
  const heading = new RegExp(`^## ${escapeRegExp(name)}\\b`, "m");
  return !heading.test(receipt);
});

const hasCheckedCommand = /^- \[(x|X)\] `(npm|pnpm|yarn|node|pytest|go test|cargo test)/m.test(receipt);

if (missingSections.length || !hasCheckedCommand) {
  for (const section of missingSections) console.error(`Missing section: ${section}`);
  if (!hasCheckedCommand) console.error("Missing checked command evidence such as - [x] `npm run build`");
  process.exit(1);
}

console.log("Review receipt passed.");

# Review receipt

## Scope
Article CTA links and mobile layout only.

## Risk
Medium: product and training links affect revenue.

## Checks run
- [x] `npm run build` passed
- [x] mobile CTA path checked at 360px

## Findings
- P2: Product CTA text and destination mismatch on one locale.

## Residual risk
Analytics event names were not checked in production.

팀에서는 이 구조를 PR 템플릿, Claude Code 프롬프트, 가벼운 CI 체크로 나누어 사용할 수 있습니다.

다음 단계

개인 개발자는 무료 Claude Code cheatsheet로 일상 명령과 안전한 리뷰 요청을 먼저 고정하세요. 리뷰, 디버깅, triage 프롬프트를 반복해서 다시 쓰고 있다면 Prompt Templates와 /ko/products/의 자료가 도움이 됩니다.

팀에서는 하나의 똑똑한 prompt보다 CLAUDE.md, 권한 경계, review gate, verification receipt, 최종 승인 책임을 정하는 일이 더 어렵습니다. 실제 repository에 맞춘 도입은 /ko/training/에서 설계할 수 있습니다.