Claude Code 코드 리뷰 체크리스트: 팀을 위한 PR 리스크 점검

“이 PR 리뷰해줘”만으로는 부족하다

Claude Code에 diff를 주고 “review this PR”이라고만 말하면 대체로 유용하지만 일반적인 피드백이 돌아옵니다.

팀 리뷰에서 필요한 것은 더 구체적입니다. 무엇이 깨질 수 있는지, 어떤 데이터가 닿는지, 테스트 증거가 있는지, merge 전에 반드시 막아야 할 위험이 무엇인지가 먼저입니다.

이 글은 바로 복사해서 쓸 수 있는 코드 리뷰 체크리스트, Claude Code 리뷰 프롬프트, GitHub PR 템플릿, GitHub Actions 기반 CI 가드를 제공합니다.

Claude Code는 인간 reviewer를 대체하지 않습니다. 누락을 줄이고 리뷰 기준을 안정화하는 보조 도구입니다. 공식 자료는 Claude Code의code review setup, Claude Code GitHub Actions docs, GitHub의PR template 문서, protected branches, Actions workflows를 함께 확인하세요. 보안 리뷰 기준은OWASP Secure Code Review Cheat Sheet가 좋습니다.

위험 기반 리뷰란 무엇인가

위험 기반 리뷰는 모든 PR을 같은 무게로 보지 않는 방식입니다. 문구 수정, CSS 여백 조정, 결제 webhook, 파괴적인 database migration은 실패했을 때 영향이 다릅니다. 모두 무겁게 보면 작은 수정이 느려지고, 모두 가볍게 보면 위험한 변경이 통과됩니다.

처음에는 세 단계면 충분합니다.

위험	예시	필수 리뷰
Low	문구, 단순 CSS, 문서, 무해한 로그 문구	1명 리뷰, diff 설명 또는 screenshot
Medium	form, UI state, search, API response shape, 읽기 전용 data access	1명 리뷰, 테스트 증거, Claude Code 리뷰
High	auth, authorization, billing, personal data, migration, delete, webhook	2명 리뷰, rollback plan, 필수 CI, security/privacy 리뷰

Migration은 database structure나 data shape를 바꾸는 작업입니다. 코드는 되돌릴 수 있어도 삭제된 column, 덮어쓴 record, 실패한 backfill은 쉽게 복구되지 않습니다. 그래서 migration 리뷰는 코드가 예쁜지보다 먼저 “실패하면 되돌릴 수 있는가”를 봐야 합니다.

Claude Code에는 이 위험 수준을 명확히 전달하세요. 모호한 리뷰 요청은 naming, formatting, readability 위주로 흐르기 쉽습니다. “High risk: billing webhook and customer email changed”라고 주면 signature validation, idempotency, retry, privacy log, test evidence 쪽으로 더 잘 좁혀집니다.

Masa의 팀 운영 메모에서 반복된 실패는 “quality”, “security”, “maintainability” 같은 추상어만 쓰는 것이었습니다. 제목으로는 괜찮지만 질문으로는 약합니다. 좋은 PR template은 file, data type, risk reason, test evidence, rollback step을 쓰게 만듭니다.

복사해서 쓰는 Review Checklist

아래 내용은 .github/review-checklist.md, 팀 wiki, CLAUDE.md의 review section에 둘 수 있습니다. Claude Code와 사람이 같은 사실을 확인하도록 일부러 구체적으로 적었습니다.

# Code Review Checklist

## 0. PR scope
- [ ] This PR has one clear purpose.
- [ ] Changed files match the stated purpose.
- [ ] Generated or AI-written files are marked in the PR description.
- [ ] No unrelated formatting, dependency, or config changes are mixed in.

## 1. Risk level
- [ ] Risk level is marked as low, medium, or high.
- [ ] High-risk PRs have two human reviewers.
- [ ] High-risk PRs include rollback or recovery steps.

## 2. Security and privacy
- [ ] User input is validated on the server side.
- [ ] Authorization is checked near the data access point.
- [ ] Secrets are not printed, committed, or sent to Claude prompts.
- [ ] Logs do not include email, tokens, addresses, payment IDs, or private content.
- [ ] OWASP-relevant risks such as injection, XSS, broken access control, and SSRF were considered.

## 3. Tests
- [ ] Unit or integration tests cover the changed behavior.
- [ ] Regression tests cover the bug that motivated the PR.
- [ ] Manual verification steps are written with actual result, not "works locally".
- [ ] Snapshot changes are explained.

## 4. Performance
- [ ] New loops, queries, and network calls are bounded.
- [ ] N+1 queries were checked.
- [ ] Large lists, images, and bundles have a budget.
- [ ] Metrics or before/after evidence are attached for performance-sensitive changes.

## 5. Accessibility
- [ ] Keyboard operation works for interactive UI.
- [ ] Focus order and visible focus state are preserved.
- [ ] Form fields have labels and errors that screen readers can understand.
- [ ] Color contrast and reduced-motion behavior are checked where relevant.

## 6. Migration and data risk
- [ ] Migration is backward compatible during rollout.
- [ ] Destructive changes have backup or recovery steps.
- [ ] Old and new app versions can run during deployment.
- [ ] Data cleanup jobs are idempotent.

## 7. AI-generated diff hygiene
- [ ] AI-generated code was read by a human before approval.
- [ ] The diff does not remove tests, monitoring, analytics, or CTA links by accident.
- [ ] New dependencies are justified.
- [ ] Comments do not claim verification that was not actually done.

핵심은 각 항목이 검증 가능해야 한다는 점입니다. “security considered”는 약합니다. “log에 email, token, address, payment ID, private content가 없다”는 확인할 수 있습니다. “accessibility is fine”도 약합니다. “keyboard operation, visible focus, label, readable error message”처럼 증거가 남는 항목이 좋습니다.

Claude Code Review Prompt

Claude Code 프롬프트에는 역할, 위험 수준, context, 금지 사항을 넣습니다. 특히 “수정하지 말고 findings 먼저”가 중요합니다. 리뷰 중 바로 고치기 시작하면 diff가 커지고, 어떤 문제를 팀이 승인했는지 흐려집니다.

You are reviewing a pull request for a production team.

Goal:
- Find concrete risks before merge.
- Prioritize correctness, security/privacy, tests, performance, accessibility, migration/data risk, and AI-generated diff hygiene.
- Do not rewrite code yet. Produce review findings first.

Context:
- Risk level: <low | medium | high>
- Business area: <auth | billing | content | search | admin | analytics | other>
- Sensitive data touched: <none | email | payment | address | health | private content | other>
- Rollout plan: <flag | migration | immediate deploy | other>

Review method:
1. Read the PR summary and changed files.
2. List the top risks by severity.
3. For each finding, include file, line or function, why it matters, and a minimal fix.
4. Separate "must fix before merge" from "follow-up".
5. Check whether tests prove the changed behavior.
6. Check whether any AI-generated code, dependency, config, or formatting change is unrelated to the PR goal.

Output format:
- Findings first, ordered by severity.
- Then missing evidence.
- Then questions for the author.
- Then a short merge recommendation: block, approve with fixes, or approve.

이 프롬프트는codebase navigation과testing strategy와 잘 맞습니다. 리뷰 전에 Claude Code에게 “이 PR이 건드리는 도메인을 짧게 설명해줘”라고 하면 naming이나 formatting 지적만 반복되는 상황을 줄일 수 있습니다.

GitHub PR Template

.github/pull_request_template.md를 두면 GitHub가 PR 작성 화면에 템플릿을 채웁니다. 목적은 문서 작업이 아니라 리뷰 증거를 한곳에 모으는 것입니다. 사람 reviewer, Claude Code, branch protection이 같은 정보를 봐야 합니다.

## Summary
- TODO

## Risk
Risk level: low | medium | high

Risk reasons:
- Data touched:
- Users affected:
- Rollout:

## Review focus
- [ ] Correctness
- [ ] Security/privacy
- [ ] Tests
- [ ] Performance
- [ ] Accessibility
- [ ] Migration/data risk
- [ ] AI-generated diff hygiene

## Test evidence
- Automated:
- Manual:
- Not tested because:

## Security and privacy notes
- Secrets changed: no | yes
- Personal data in logs: no | yes
- Authorization boundary changed: no | yes

## Migration / rollback
- Migration included: no | yes
- Backward compatible: no | yes | not applicable
- Rollback plan:

## Claude Code review prompt
Paste this into Claude Code after the PR is ready:

Review this PR as risk level "<low|medium|high>".
Focus on correctness, security/privacy, tests, performance, accessibility, migration/data risk, and AI-generated diff hygiene.
Return findings first with file/function references and minimal fixes.

체크박스만 많은 템플릿은 피하세요. 사람들은 금방 기계적으로 체크합니다. Risk reasons, Test evidence, Rollback plan처럼 증거를 요구하는 칸이 있어야 리뷰 품질이 올라갑니다.

GitHub Actions CI Guard

다음 workflow와 Node script는 PR body와 변경 파일을 확인합니다. 코드가 맞다는 것을 증명하지는 못하지만, reviewer가 읽기 전에 risk level, test evidence, rollback plan 누락을 막아줍니다.

name: PR review guard

on:
  pull_request:
    types: [opened, edited, synchronize, reopened, ready_for_review]

permissions:
  contents: read
  pull-requests: read

jobs:
  review-guard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Check PR review evidence
        run: node scripts/pr-review-guard.mjs
        env:
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}

import { execSync } from "node:child_process";
import { readFileSync } from "node:fs";

const eventPath = process.env.GITHUB_EVENT_PATH;
if (!eventPath) throw new Error("GITHUB_EVENT_PATH is missing.");

const event = JSON.parse(readFileSync(eventPath, "utf8"));
const pr = event.pull_request;
const body = pr?.body ?? "";
const base = process.env.BASE_SHA ?? pr?.base?.sha;
const head = process.env.HEAD_SHA ?? pr?.head?.sha;

function safeRef(value, name) {
  if (!value || !/^[a-f0-9]{40}$/i.test(value)) throw new Error(`${name} must be a full git SHA.`);
  return value;
}

const changedFiles = execSync(`git diff --name-only ${safeRef(base, "BASE_SHA")} ${safeRef(head, "HEAD_SHA")}`, {
  encoding: "utf8",
}).split(/\r?\n/).filter(Boolean);

const hasRisk = /Risk level:\s*(low|medium|high)/i.test(body);
const hasTests = /## Test evidence[\s\S]*(Automated|Manual):\s*\S/i.test(body);
const hasRollback = /Rollback plan:\s*\S/i.test(body);
const highRisk = /Risk level:\s*high/i.test(body);
const migrationChanged = changedFiles.some((file) => /migrations?|schema|prisma|drizzle/i.test(file));
const sensitiveChanged = changedFiles.some((file) => /auth|session|permission|billing|payment|webhook/i.test(file));
const failures = [];

if (!hasRisk) failures.push("Add Risk level.");
if (!hasTests) failures.push("Add automated or manual test evidence.");
if ((highRisk || migrationChanged) && !hasRollback) failures.push("Add rollback plan.");
if (sensitiveChanged && !/Security and privacy notes/i.test(body)) failures.push("Add security/privacy notes.");

if (failures.length) {
  console.error("PR review guard failed:");
  for (const failure of failures) console.error(`- ${failure}`);
  process.exit(1);
}

console.log("PR review guard passed.");

처음부터 protected branch의 required check로 강제하지 말고 며칠은 advisory로 돌려보세요. High risk와 migration에는 엄격하게, low risk에는 가볍게 적용해야 팀이 계속 사용합니다.

보안, 개인정보, 테스트, 성능, 접근성

보안 리뷰는 input, authorization, output, logging, external call로 나누면 안정적입니다. server-side validation이 있는지, authorization이 UI가 아니라 data access 근처에서 되는지, output이 XSS를 만들 수 있는지, log에 private data가 있는지, 외부 URL이나 webhook이 SSRF 또는 signature bypass로 이어지는지 확인합니다.

개인정보는 secret보다 넓습니다. email, payment ID, address, inquiry text, analytics identifier, private content 모두 주의가 필요합니다. 실제 API key, 고객 email, 계약 내용, 결제 ID를 prompt에 붙여넣지 마세요. 값은 masking하고 구조만 전달합니다.

테스트는 주장보다 증거가 중요합니다. “works locally”는 증거가 아닙니다. 어떤 automated test를 실행했는지, 어떤 manual flow를 확인했는지, 결과가 무엇이었는지 적어야 합니다.

성능 리뷰에서는 unbounded loop, N+1 query, repeated network call, bundle growth, image weight, expensive client rendering을 봅니다. 성능 민감 변경은 간단한 before/after 숫자라도 붙이면 리뷰가 훨씬 정확해집니다.

접근성은 screenshot만으로 판단하지 않습니다. keyboard operation, focus order, visible focus, label, error message, dialog focus trap, reduced motion을 확인합니다. Claude Code가 만든 UI는 겉보기에는 깔끔해도 이런 부분이 빠질 수 있습니다.

실무 유스케이스

첫 번째는 인증과 관리자 화면입니다. 사용자 목록, role 변경, audit log는 API나 data access layer에서 보호되어야 합니다. authorization, audit record, personal data logging, unauthorized access test를 봅니다.

두 번째는 billing과 webhook입니다. 결제 webhook은 signature validation, idempotency, retry, duplicate event, cancellation handling, privacy-aware log가 중요합니다. “같은 event가 두 번 와도 상태가 깨지지 않는가”를 Claude Code에 직접 묻습니다.

세 번째는 database migration입니다. column 추가도 배포 중 old app과 new app이 동시에 돌면 실패할 수 있습니다. default, not null, index, backfill, rollback, expand-contract 순서를 확인합니다.

네 번째는 AI가 생성한 큰 UI diff입니다. page, form, modal, table을 한 번에 만들면 CTA 삭제, analytics event 변경, accessibility 누락, snapshot 의미 불명, dependency 추가가 숨어 있을 수 있습니다.

다섯 번째는 매출 경로가 있는 content site입니다. article, product page, lead form의 review는 conversion path도 지켜야 합니다. 제품 페이지 링크, free PDF form, consultation tracking이 깨지면 UI가 보여도 business-critical bug입니다.

흔한 함정과 마무리

첫 번째 함정은 Claude Code의 findings를 검증 없이 믿는 것입니다. AI는 그럴듯한 설명을 만들 수 있습니다. diff, test, official docs, reproduction과 대조해야 합니다.

두 번째 함정은 review와 implementation을 섞는 것입니다. 먼저 findings를 받고, 팀이 승인한 must-fix만 수정하세요. 그래야 PR 책임 범위가 유지됩니다.

세 번째 함정은 AI-generated cleanup입니다. formatting, dependency, config, deleted tests가 유용해 보이는 diff 안에 섞입니다. prompt에 unrelated changes를 따로 나열하라고 명시하세요.

네 번째 함정은 database rollback을 code revert처럼 생각하는 것입니다. commit revert는 삭제된 data를 복원하지 않습니다. High-risk migration에는 backup, recovery SQL, feature flag, staged plan이 필요합니다.

코드 리뷰는 매출도 보호합니다. billing flow, product page, free PDF signup, Gumroad link, analytics event, consultation CTA가 모두 시스템 일부입니다. 개인 연습은무료 체크리스트에서 시작하고, 팀용 prompt, PR template, CLAUDE.md, CI guard는제품과 템플릿에서 정리할 수 있습니다. 실제 repo 적용은교육 및 상담이 맞습니다.

이 형식을 작은 Next.js UI 변경, database migration, Claude Code-generated UI diff 시나리오에 적용해 보니 가장 효과가 큰 것은 Risk level과 Rollback plan을 PR body에 강제하는 것이었습니다. 위험과 data type을 prompt에 넣을수록 Claude Code의 리뷰도 더 구체적이었습니다.

요약

Claude Code 코드 리뷰 체크리스트는 단순한 prompt가 아니라 risk classification, PR evidence, human review, CI, protected branch를 연결하는 팀 workflow입니다.

작게 시작하세요. PR template을 추가하고 CI guard를 advisory로 돌린 뒤, high-risk 변경에 required check로 적용합니다. 이후AI pair programming과CLAUDE.md best practices를 함께 사용해 review standard를 repository 안에 고정하세요.