Claude Code Small PR Proof Pack: 작은 PR을 리뷰 가능한 상태로 만드는 증거 세트

Claude Code가 만든 변경은 diff가 작다고 해서 자동으로 리뷰하기 쉬워지지 않습니다. 리뷰어는 여전히 왜 바꿨는지, 어떤 파일을 건드렸는지, 어떤 명령을 실행했는지, 공개 URL을 열어 보았는지, CTA가 올바른 다음 행동으로 이어지는지, 문제가 생기면 어떻게 되돌릴 수 있는지를 알아야 합니다.

이 글에서는 그 정보를 Small PR Proof Pack이라고 부릅니다. 작은 PR에 붙이는 증거 세트입니다. 목적은 절차를 늘리는 것이 아니라, AI가 만든 변경을 사람이 믿고 합칠 수 있도록 판단 자료를 미리 제공하는 것입니다.

관련해서는 review gate before commit, team handoff rules, build error triage loop도 함께 보면 좋습니다. 공식 자료는 Claude Code documentation, GitHub pull request docs, GitHub Actions docs를 참고하세요.

Small PR Proof Pack이란

Proof Pack은 PR 본문이나 작업 메모에 붙이는 리뷰용 영수증입니다. 여기서 영수증이란 작성자만 이해하는 기록이 아니라, 다음 날 다른 사람이 봐도 같은 판단을 할 수 있는 기록입니다.

Claude Code는 기사, 컴포넌트, 스크립트, 설정 파일을 빠르게 수정할 수 있습니다. 하지만 빠른 수정일수록 경계가 중요합니다. 두 줄짜리 변경도 CTA를 잘못된 상품으로 보낼 수 있고, CSS 한 파일 수정도 모바일 코드 블록을 깨뜨릴 수 있습니다. 다국어 글을 추가했는데 zh나 ko가 너무 얇거나 영어 CTA가 그대로 남는 일도 흔합니다.

최소한의 Proof Pack은 다음과 같습니다.

small_pr_proof_pack:
  owner: "Masa"
  goal: "기사 하단 CTA를 더 명확하게 만든다"
  changed_files:
    - "site/src/content/blog/example.mdx"
  verification:
    - command: "npm run build"
      result: "passed"
    - command: "node scripts/check-code-fences.mjs"
      result: "passed"
  public_checks:
    - url: "https://claudecode-lab.com/ko/blog/example/"
      checked:
        - "h1 is correct"
        - "hero image loads"
        - "mobile layout has no horizontal scroll"
        - "CTA opens the expected product"
  rollback:
    command: "revert this PR"
    risk: "content-only change"

핵심은 goal, changed files, verification, public checks, revenue path, rollback입니다. 이 항목들이 없으면 리뷰어는 diff, 터미널 출력, 브라우저, 대화 기록을 다시 찾아야 합니다.

복사해서 쓰는 PR 템플릿

## Goal
-

## Scope
- Changed:
- Not changed:

## Proof
- Command:
- Result:

## Public URL Check
- URL:
- H1:
- Canonical:
- Hero image:
- Mobile layout:
- Code block:

## Revenue Path Check
- Free PDF:
- Gumroad:
- Training/contact:

## Rollback
-

Not changed 항목이 특히 중요합니다. Claude Code로 작업한 PR에서 리뷰어가 가장 불안해하는 부분은 작업 범위가 조용히 넓어진 경우입니다. 목표가 기사 CTA 하나라면, 관련 없는 스크립트나 상품 설명, 환경 설정이 같이 바뀌면 안 됩니다. 바꾸지 않은 범위를 적어 두면 이상한 변경을 빠르게 찾을 수 있습니다.

리뷰 가능성을 간단한 함수로 표현하기

const proof = {
  filesChanged: 2,
  commands: ["npm run build", "node scripts/check-code-fences.mjs"],
  publicUrlChecked: true,
  mobileChecked: true,
  revenuePathChecked: true,
  rollbackWritten: true,
};

export function isReadyToCommit(receipt) {
  return receipt.filesChanged <= 5 &&
    receipt.commands.length > 0 &&
    receipt.publicUrlChecked &&
    receipt.mobileChecked &&
    receipt.revenuePathChecked &&
    receipt.rollbackWritten;
}

console.log(isReadyToCommit(proof));

이 코드는 리뷰를 대체하려는 것이 아닙니다. 최소 기준을 눈에 보이게 만드는 장치입니다. Claude Code에게 “괜찮아 보이면 commit”이라고 맡기기보다, “이 증거가 있으면 commit 후보”라고 알려 주는 편이 안전합니다.

사용 사례1: 기사 CTA 수정

첫 번째 사례는 기사 하단 CTA를 고치는 PR입니다. ClaudeCodeLab의 글은 단순한 읽을거리가 아니라 무료 PDF, Gumroad 상품, Prompt Templates, Setup Guide, 교육 상담으로 이어지는 유입 경로입니다. CTA 문구와 링크가 어긋나면 PV가 늘어도 가입, 구매, 문의로 이어지지 않습니다.

이 PR의 Proof Pack에는 대상 기사, 기사 하단 CTA, Products 페이지, Gumroad 링크, 상담 페이지를 넣습니다. npm run build 같은 명령도 필요하지만, 공개 URL을 실제로 열어 보는 것이 더 중요합니다. 모바일에서 버튼을 누르기 쉬운지, 광고와 CTA가 너무 가깝지 않은지도 확인합니다.

흔한 실패는 본문 중간 링크만 고치고 글 하단 공통 CTA를 잊는 것입니다. 독자는 글을 읽은 뒤 다음 행동을 고르는 경우가 많기 때문에, 하단 CTA는 수익 전환에 직접 연결됩니다.

사용 사례2: 모바일 코드 블록 수정

두 번째 사례는 모바일 코드 블록 표시 문제입니다. 기술 글에는 긴 명령어, URL, JSON, YAML이 자주 들어갑니다. 데스크톱에서는 정상이어도 휴대폰에서는 가로 스크롤, 확대된 듯한 화면, 배경 없는 코드 블록, 깨진 fence가 나타날 수 있습니다.

Proof Pack에는 확인한 viewport를 적습니다. 예를 들어 390px 폭에서 긴 코드 줄, 테이블, CTA 주변을 확인했다고 쓰면 리뷰어가 판단하기 쉽습니다. Playwright 스크린샷을 찍었다면 저장 위치도 남깁니다. build 성공은 문법 확인일 뿐, 독자의 모바일 경험을 보장하지 않습니다.

흔한 실패는 PC 미리보기만 보고 합치는 것입니다. 검색과 소셜 링크로 들어온 독자는 모바일 비중이 높고, 작은 표시 문제도 체류 시간과 전환율에 영향을 줍니다.

사용 사례3: 다국어 기사 추가

세 번째 사례는 10개 언어 기사를 추가하는 PR입니다. 다국어 페이지에서는 slug가 같아도 품질이 같지 않을 수 있습니다. 일본어 canonical은 충분한데 중국어와 한국어가 얇거나, 영어 CTA가 모든 언어에 그대로 남거나, description에 깨진 문자가 들어갈 수 있습니다.

Proof Pack에는 전체 언어 파일 존재 여부, frontmatter, description 길이, 내부 링크, 코드 fence, 대표 언어의 표시 확인을 넣습니다. 매번 10개 언어를 모두 수동으로 읽기 어렵다면 일본어, 영어, 중국어, 한국어를 우선 확인하고 나머지는 구조 검사를 통과시키는 방식이 현실적입니다.

흔한 실패는 번역 파일을 만든 것만으로 게시 완료라고 생각하는 것입니다. 목표는 페이지 수가 아니라 각 언어 독자가 문제를 이해하고, 코드를 복사하고, 올바른 다음 행동으로 이동하는 것입니다.

Claude Code에 맡길 때의 프롬프트

이 PR을 Small PR Proof Pack 형식으로 마무리해 주세요.

필수:
- 목표를 한 문장으로 쓴다
- changed와 not changed를 나눈다
- 실행한 명령과 결과를 쓴다
- 공개 URL, 모바일 표시, CTA 경로를 확인한다
- rollback 방법을 쓴다

금지:
- 확인하지 않았는데 확인했다고 쓰지 않는다
- 관련 없는 리팩터링을 섞지 않는다
- 실패한 검증을 숨기지 않는다

이 프롬프트는 Claude Code를 묶어 두기 위한 것이 아니라, 결과물과 판단 자료를 함께 만들게 하기 위한 것입니다. AI는 수정 자체를 빠르게 만들 수 있지만, 팀이 필요한 것은 안심하고 합칠 수 있는 수정입니다.

실패 사례와 함정

가장 약한 PR 본문은 “Claude Code로 수정했습니다” 한 줄입니다. 이 문장은 리뷰어에게 거의 아무 정보도 주지 않습니다. 리뷰어는 목표를 추측하고, diff를 다시 읽고, 검증 여부를 찾아야 합니다.

두 번째 실패는 build 성공을 전체 증거로 보는 것입니다. build는 H1, canonical, hero image, CTA, Gumroad 링크, 모바일 레이아웃을 보장하지 않습니다. 콘텐츠 사이트에서는 수익 경로가 깨져도 build는 통과합니다.

세 번째 실패는 rollback을 쓰지 않는 것입니다. 콘텐츠만 바뀐 경우에는 PR revert로 충분할 수 있습니다. 하지만 상품 링크, 메일 발송, Cloudflare 환경 변수, 외부 설정이 연결되어 있으면 복구 절차를 따로 적어야 합니다. 짧은 rollback을 쓰기 어렵다면 이미 작은 PR이 아닐 수 있습니다.

네 번째 실패는 증거를 너무 많이 붙이는 것입니다. Proof Pack은 감사 보고서가 아닙니다. 리뷰어가 30초 안에 위험을 판단할 수 있도록 목표, 명령, URL, CTA, 남은 위험만 남기는 편이 좋습니다.

수익 경로까지 확인하기

ClaudeCodeLab의 목표는 글을 많이 쌓는 것이 아니라 검색 유입을 등록, 구매, 상담으로 전환하는 것입니다. 초보자에게는 free cheatsheet, 반복 사용자는 50 Prompt Templates, 팀 도입과 권한 설계 독자는 Setup Guide와 교육 상담이 더 잘 맞습니다.

따라서 기사, CTA, 상품 카드, 내비게이션을 건드리는 PR에는 Revenue Path Check를 넣어야 합니다. 전 사이트를 매번 볼 필요는 없지만, 이번 변경이 영향을 주는 경로는 반드시 확인해야 합니다.

손으로 적용해 본 결론

이 Proof Pack을 기사 CTA, 모바일 코드 블록, 다국어 기사 추가에 적용해 보면 최소 세트가 분명해집니다. 목표, 범위, 검증 명령, 공개 URL, 모바일 확인, 수익 경로, rollback입니다. 이 정도면 일상 운영을 느리게 하지 않으면서도 Claude Code가 만든 PR의 리뷰 품질을 크게 높일 수 있습니다.