Claude Code로 Pull Request 품질을 높이는 실전 가이드

Pull Request는 팀이 변경을 제안하고, 검토하고, 병합하는 장소입니다. GitHub 공식 문서도 PR을 협업 개발의 중심 기능으로 설명합니다. Claude Code로 구현 속도가 빨라지면 다른 병목이 드러납니다. PR 설명은 짧고, diff는 너무 크고, 테스트 증거는 부족하고, 보안 영향은 흐리고, 리뷰 댓글은 같은 지점을 반복합니다. AI가 코드를 빠르게 만들수록 사람이 검토할 수 있는 형태로 포장하는 일이 더 중요해집니다.

이 글은 Claude Code를 단순한 PR 설명 생성기가 아니라 PR 품질을 지키는 보조 리뷰어로 사용하는 방법을 다룹니다. diff는 변경된 코드 차이, CI는 자동 테스트와 빌드의 관문, diff-size budget은 PR 크기 제한, handoff는 다음 리뷰어에게 넘기는 짧은 인수인계 메모라는 뜻으로 사용합니다. 함께 보면 좋은 글은 Claude Code 코드 리뷰와 Claude Code 테스트 전략입니다.

flowchart LR
  A["Claude Code로 구현"] --> B["PR 템플릿 작성"]
  B --> C["CI에서 diff 크기 제한"]
  C --> D["테스트 증거 추가"]
  D --> E["리뷰 인수인계 준비"]
  E --> F["릴리스 노트 작성"]

이 워크플로에서 참고한 공식 문서는 GitHub Pull Requests, PR 템플릿 만들기, GitHub Actions workflow syntax, protected branches, Actions secrets, Claude Code docs입니다. 커밋 타입을 릴리스에 활용한다면 Conventional Commits도 확인하세요.

좋은 PR의 기준을 템플릿에 고정하기

매번 Claude Code에게 “좋은 PR 설명을 써줘”라고 하면 결과가 흔들립니다. 더 안정적인 방법은 저장소에 .github/pull_request_template.md를 두는 것입니다. GitHub는 PR을 만들 때 템플릿 내용을 본문에 자동으로 보여줄 수 있으므로, 리뷰 기준을 팀원의 기억이 아니라 코드베이스 안에 둘 수 있습니다.

## 변경 내용
<!-- 구현, 설정, 문서, 생성 파일을 나누어 적습니다. -->

## 배경과 판단 이유
<!-- 이슈, 장애, 사용자 요청, 설계 결정을 연결합니다. -->

## 중점 리뷰 영역
- [ ] 비즈니스 로직
- [ ] UI/UX
- [ ] API 또는 데이터베이스 계약
- [ ] 보안과 개인정보

## 테스트 증거
- [ ] 자동 테스트:
- [ ] 수동 확인:
- [ ] 스크린샷 또는 녹화:

## diff 크기
- 변경 파일 수:
- 추가/삭제 줄 수:
- 분리하지 않은 이유:

## 보안과 운영
- [ ] secret, token, 개인정보를 포함하지 않음
- [ ] 로그에 인증 정보나 개인정보를 노출하지 않음
- [ ] 권한, 환경 변수, feature flag 영향 확인
- [ ] 롤백 방법 작성

## 리뷰어 인수인계
<!-- 먼저 읽을 파일, 열린 결정, 위험, 후속 PR을 적습니다. -->

특히 “분리하지 않은 이유”와 “롤백 방법”은 효과가 큽니다. 이 두 칸이 비어 있으면 PR이 너무 크거나 운영 관점이 부족한 경우가 많습니다. Claude Code는 템플릿을 채우는 도구이고, 템플릿은 리뷰 준비 완료의 기준입니다.

사실 기반으로 PR 본문 생성하기

템플릿을 만든 뒤에는 Claude Code가 diff를 읽고 템플릿을 채우게 합니다. 추측을 금지하고, 테스트 증거가 없으면 “미실행”이라고 쓰게 해야 합니다. AI가 만든 PR에서 가장 위험한 것은 그럴듯하지만 검증되지 않은 문장입니다.

git diff origin/main...HEAD | claude -p "
이 diff를 읽고 .github/pull_request_template.md 형식으로 Pull Request 본문을 한국어로 작성하세요.

규칙:
- diff에서 확인할 수 없는 사실을 만들지 말 것
- 테스트 증거가 없으면 '미실행'이라고 쓸 것
- 전문 용어는 처음 등장할 때 짧게 설명할 것
- 리뷰 초점은 가장 중요한 파일 또는 영역 3개 이내로 제한할 것
- secret, token, 개인정보, 위험한 로그를 확인할 것
- 마지막에 사람이 확인해야 할 미정 사항을 목록으로 쓸 것
"

이렇게 하면 PR 본문이 단순 요약이 아니라 리뷰 지도처럼 작동합니다. 리뷰어는 전체 브랜치를 훑는 대신 인증 함수, 변경 화면, 마이그레이션 파일부터 볼 수 있습니다. Claude Code는 빠르게 diff를 읽지만, 최종 주장은 사람이 책임져야 합니다.

CI에서 PR 크기 예산을 강제하기

큰 PR은 리뷰 품질을 떨어뜨립니다. Claude Code는 이름 변경, 리팩터링, 포맷팅, 테스트 추가, 문서 수정을 한 번에 할 수 있기 때문에 여러 목적이 한 PR에 섞이기 쉽습니다. diff-size budget은 “이 PR은 몇 파일, 몇 줄까지”라는 공유 규칙입니다.

Node 프로젝트라면 scripts/check-pr-size.mjs를 추가합니다. lockfile과 생성물을 제외하고 실제 리뷰해야 할 변경만 셉니다.

#!/usr/bin/env node
import { execFileSync } from "node:child_process";

const [range = "origin/main...HEAD", maxLinesRaw = "700", maxFilesRaw = "35"] =
  process.argv.slice(2);
const maxLines = Number(maxLinesRaw);
const maxFiles = Number(maxFilesRaw);

const ignored = [
  /^package-lock\.json$/,
  /^pnpm-lock\.yaml$/,
  /^yarn\.lock$/,
  /^dist\//,
  /^coverage\//,
];

function numeric(value) {
  const parsed = Number(value);
  return Number.isFinite(parsed) ? parsed : 0;
}

const output = execFileSync("git", ["diff", "--numstat", range], {
  encoding: "utf8",
}).trim();

let files = 0;
let lines = 0;

for (const row of output.split(/\r?\n/).filter(Boolean)) {
  const [added, deleted, file] = row.split("\t");
  if (ignored.some((pattern) => pattern.test(file))) continue;
  files += 1;
  lines += numeric(added) + numeric(deleted);
}

if (files > maxFiles || lines > maxLines) {
  console.error(
    `PR is too large: ${files} files / ${lines} changed lines. ` +
      `Budget is ${maxFiles} files / ${maxLines} lines.`,
  );
  console.error("Split formatting, generated files, and behavior changes into separate PRs.");
  process.exit(1);
}

console.log(`PR size OK: ${files} files / ${lines} changed lines.`);

다음으로 GitHub Actions에 연결합니다. workflow 파일은 .github/workflows 아래에 둡니다. 이후 protected branch에서 이 job을 required status check로 지정하면 기준을 넘는 PR을 병합 전에 막을 수 있습니다.

name: PR quality

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

permissions:
  contents: read
  pull-requests: read

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

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install dependencies
        run: npm ci

      - name: Run project checks
        run: |
          npm run lint --if-present
          npm test --if-present

      - name: Enforce PR size budget
        run: node scripts/check-pr-size.mjs "origin/${{ github.base_ref }}...HEAD" 700 35

처음에는 700줄, 35파일 정도로 시작하고, 마이그레이션이나 기계적 변경은 예외 이유를 요구하는 방식이 현실적입니다. 핵심은 큰 PR을 금지하는 것이 아니라, 큰 이유를 설명하게 만드는 것입니다.

테스트 증거를 재현 가능하게 남기기

“테스트 통과”만으로는 부족합니다. 리뷰어가 다시 확인할 수 있도록 명령, 결과, 수동 확인, 스크린샷, 미확인 항목을 분리해야 합니다. Claude Code가 정리할 수 있지만 실행하지 않은 명령을 통과한 것처럼 쓰게 해서는 안 됩니다.

claude -p "
현재 브랜치의 Pull Request에 넣을 테스트 증거를 정리하세요.

형식:
## 자동 테스트
- 명령:
- 결과:
- 실패했다면 원인:

## 수동 확인
- 확인한 화면, API, 작업:
- 입력 데이터:
- 기대 결과:
- 실제 결과:

## 미확인
- 아직 확인하지 않은 항목:
- 병합 전 누가 확인해야 하는지:

사실만 쓰고, 실행하지 않은 명령을 통과로 표시하지 마세요.
"

대표 유스케이스는 세 가지입니다. UI 변경은 스크린샷, 화면 폭, 접근성 확인이 필요합니다. API 변경은 호환성, 실패 응답, 로그 동작을 적어야 합니다. 배치나 마이그레이션은 dry run, 롤백, 예상 실행 시간을 남겨야 합니다. 이 구분만 있어도 리뷰어는 자기 전문 영역부터 볼 수 있습니다.

보안과 개인정보를 PR 단위로 확인하기

AI가 만든 변경은 예상보다 넓게 퍼질 수 있습니다. secret은 예시 코드, 로그, fixture, 스크린샷에 섞일 수 있습니다. GitHub Actions secrets는 워크플로에서 민감한 값을 다루기 위한 기능이지만, 그 값을 로그나 PR 본문에 출력해도 된다는 뜻은 아닙니다.

이 diff를 보안과 개인정보 관점에서 리뷰하세요.

확인 항목:
1. secret, token, API key, cookie, session id
2. 로그, fixture, 스크린샷, 오류 메시지의 개인정보
3. 권한 검사가 UI가 아니라 서버에서도 강제되는지
4. GitHub Actions permissions가 과도하게 넓지 않은지
5. 실패 응답이 내부 경로나 인증 정보를 노출하지 않는지
6. feature flag 또는 환경 변수가 배포 범위를 바꾸는지

각 항목에 High/Medium/Low 심각도를 붙이고 구체적인 파일명을 포함하세요.
확정할 수 없지만 의심되는 영역도 따로 적으세요.

마지막 문장이 중요합니다. 보안 리뷰에서는 “문제 없음”보다 “확인하지 못한 위험”이 더 유용할 때가 많습니다.

리뷰 인수인계와 댓글 답변 정리하기

handoff가 약하면 다음 리뷰어가 모든 대화를 다시 읽어야 합니다. 시간대가 다른 팀, 오래 열린 PR, 교대 리뷰에서 특히 손해가 큽니다. PR 댓글과 diff 통계를 Claude Code에 넘기고 짧은 상태 메모를 만들게 합니다.

PR_NUMBER=123
{
  gh pr view "$PR_NUMBER" --comments
  gh pr diff "$PR_NUMBER" --stat
} | claude -p "
이 Pull Request의 리뷰 인수인계 메모를 작성하세요.

포함할 내용:
- 목적을 두 문장 이내로 설명
- 먼저 읽을 파일 최대 3개
- 이미 처리한 리뷰 댓글
- 아직 결정이 필요한 댓글
- CI, 수동 테스트, 릴리스 위험

리뷰어가 5분 안에 상태를 파악할 수 있는 길이로 작성하세요.
"

댓글 답변도 마찬가지입니다. “수정했습니다”만 쓰면 부족합니다. 어느 파일을 어떻게 바꿨는지, 어떤 테스트가 덮는지, 제안을 반영하지 않았다면 이유가 무엇인지 적어야 합니다. Claude Code 초안을 쓰되 방어적이거나 추측이 섞인 문장은 제거합니다.

PR에서 릴리스 노트까지 연결하기

PR은 병합으로 끝나지 않습니다. 사용자에게 보이는 변경, 내부 운영 변경, breaking change를 릴리스 노트로 넘겨야 합니다. Conventional Commits는 분류에 도움이 되지만, 최종 문장은 사용자가 이해할 말로 바꿔야 합니다.

gh pr list --state merged --base main --limit 20 \
  --json number,title,body,mergedAt \
  | claude -p "
병합된 Pull Request를 바탕으로 다음 릴리스 노트 초안을 한국어로 작성하세요.

섹션:
## 새 기능
## 수정
## 성능
## 문서
## 개발자 변경

규칙:
- PR 번호를 유지
- 내부 변경은 짧게 작성
- breaking change, 마이그레이션, feature flag를 강조
- PR 본문에 근거가 없는 영향은 만들지 말 것
"

릴리스 노트에 쓸 수 없는 PR 설명은 리뷰에도 대체로 불친절합니다. 나중에 사용자에게 어떻게 설명할지 생각하면 PR 배경도 자연스럽게 명확해집니다.

AI가 만든 시끄러운 PR 피하기

가장 흔한 실패는 노이즈입니다. 관계없는 포맷팅, 광범위한 이름 변경, 요청하지 않은 리팩터링, 중복 주석, 마케팅 문구 같은 설명, 검증하지 않은 테스트 결과는 모두 리뷰 시간을 늘립니다.

규칙은 단순합니다. 포맷팅만 있는 변경은 별도 PR로 분리합니다. 생성 코드는 필요한 최소 diff만 남깁니다. PR 본문에는 사실만 씁니다. Claude Code의 제안을 받아들였다면 이유를 한 문장으로 설명합니다. 기계적 변경, 동작 변경, 테스트 추가는 가능하면 분리합니다.

시끄러운 AI PR	리뷰 가능한 PR
“Claude가 모듈을 개선함”	“server/auth.ts로 권한 검사를 모음”
포맷팅과 동작 변경이 섞임	포맷팅 PR과 기능 PR 분리
증거 없이 “문제 없음”	명령, 결과, 남은 확인 항목 작성
리뷰 초점 없음	파일과 위험을 먼저 지정

ClaudeCodeLab의 수익 동선에 넣기

이 주제는 템플릿, 교육, 구현 상담으로 자연스럽게 이어집니다. 팀에 필요한 것은 하나의 prompt가 아니라 PR 템플릿, CLAUDE.md 규칙, CI 게이트, 리뷰 습관입니다. CLAUDE.md 템플릿, 팀 인수인계 규칙, 교육 및 상담으로 연결하면 독자가 자기 팀에 적용할 다음 단계를 찾기 쉽습니다.

처음부터 전부 자동화하지 마세요. 1주차는 PR 템플릿, 2주차는 diff 크기 게이트, 3주차는 리뷰 인수인계, 4주차는 릴리스 노트 자동 초안 정도가 적당합니다. 규칙을 한꺼번에 넣으면 팀은 품질보다 절차를 먼저 싫어하게 됩니다.

직접 적용해 본 결과

작은 Node 프로젝트에서 이 흐름을 적용해 보니 PR 템플릿과 크기 게이트의 조합이 가장 효과적이었습니다. Claude Code만으로 본문을 쓰면 길지만 불균형했습니다. 템플릿을 두자 미실행 테스트, 보안 확인, 리뷰 파일, 롤백 방법이 드러났습니다. 700줄, 35파일 예산은 포맷팅과 동작 변경을 미리 나누는 기준이 되었습니다.

정리

Claude Code로 Pull Request 품질을 높이는 핵심은 AI에게 더 멋진 문장을 쓰게 하는 것이 아닙니다. 엄격한 템플릿, CI diff 크기 제한, 재현 가능한 테스트 증거, 보안과 개인정보 체크리스트, 리뷰 인수인계, 릴리스 노트까지 이어지는 구조를 만드는 것입니다. 그래야 AI가 빠르게 만든 변경도 사람이 안정적으로 리뷰하고 배포할 수 있습니다.