CLAUDE.md와 REVIEW.md로 Claude Code Review를 풀 리퀘스트 게이트로 쓰기

Anthropic은 2026년 3월 9일 Claude Code용 Code Review를 내놓으면서, 모든 엔지니어링 매니저가 찔끔할 숫자 하나를 공개했다. Anthropic 내부에서 엔지니어 1인당 코드 산출량이 1년 만에 200% 늘었고, 리뷰가 병목이 됐다는 것이다 (Anthropic). 진짜 이야기는 여기 있다. AI 코딩은 리뷰 업무를 없애지 않았다. 압박 지점을 옮겼을 뿐이다.

쓸모 있는 대응은 “Claude가 자기 숙제를 직접 승인하게 하자”가 아니다. 그러면 예의 바른 버그 공장이 생긴다. 쓸모 있는 대응은 Claude Code Review를, 팀이 실제로 믿는 규칙을 가진 반복 가능한 PR 게이트로 만드는 것이다.

Anthropic의 설정 문서는 이제 이걸 현실적으로 가능하게 해준다. 리뷰어는 @claude review라고 댓글을 달아 리뷰를 트리거할 수 있고, Code Review는 저장소의 CLAUDE.md 파일과 루트의 REVIEW.md를 읽는다. CLAUDE.md 위반은 nit 수준의 지적으로 처리되며, Claude는 PR 때문에 CLAUDE.md가 낡아졌다는 점까지 표시할 수 있다 (Claude Help Center). REVIEW.md는 리뷰 전용 규칙을 넣는 곳이다. Anthropic이 든 예시도 여기에 들어간다. “새 API route에는 반드시 통합 테스트가 있어야 한다.”

이 한 문장이 핵심이다. AI 리뷰어에게 “조심해줘”라고 부탁하지 마라. 저장소의 법을 줘라.

풀 리퀘스트 diff가 Claude Code Review로 들어가 병렬 리뷰 에이전트로 나뉘고 C를 확인하는 흐름 스케치

문제: AI가 PR 리뷰를 더 시끄럽게 만들었다

커뮤니티 논쟁이 지저분한 이유는 양쪽이 모두 맞기 때문이다.

Claude Code Review에 대한 Hacker News 스레드에서 개발자들은 가격, 가치, 그리고 AI 생성 코드를 리뷰하는 도구를 AI 벤더가 판다는 불편한 사실을 두고 맞섰다. 한 댓글 작성자는 Anthropic이 공개한 대형 PR 수치를 짚으며 에이전트형 개발 품질에 대한 경고 신호로 읽었고, 다른 이들은 깊이 있는 두 번째 눈이야말로 이 도구가 제값을 하는 지점이라고 주장했다 (Hacker News).

Reddit에는 같은 논쟁의 더 현실적인 버전이 있다. 한 스레드에서 어떤 개발자는 Claude가 가끔 자신도 이해하지 못하는 코드를 쓰는데, 사람들이 Claude 생성 코드를 리뷰 없이 넘길 만큼 정말 신뢰하는지 물었다. 답은 직설적이었다. 리뷰해라, 검증해라, 변경을 작게 유지해라, 그리고 위임했다고 책임이 사라지는 척하지 마라 (Reddit). 다른 스레드에서는 Claude의 산출물을 별도의 AI 에이전트로 리뷰하되, 그 리뷰 자체도 코드베이스와 대조해 확인하는 방식을 논의했다 (Reddit).

내 생각은 이렇다. Claude가 쓴 코드를 Claude로 리뷰하는 건 괜찮다. 단, 그걸 독립적인 판단으로 취급하지 않는다면 말이다. 엄청난 컨텍스트를 가진, 빠르고 문자 그대로 받아들이는 주니어 리뷰어라고 생각하라. 소유권은 없다. 지루한 누락, 파일 간 불일치, 빠진 테스트, 보안 발등찍기, 오래된 문서, 인간 리뷰어가 대충 넘기기 쉬운 지점을 잡아내야 한다.

최종 승인자가 되어서는 안 된다.

Anthropic도 이 점을 직접 말한다. Code Review는 PR을 승인하거나 자체적으로 막지 않는다. 기존 리뷰 워크플로는 그대로 유지된다 (Claude Help Center). 그러니 “게이트”는 팀의 게이트다. Claude가 실행되기 전에는 인간 승인이 없고, Important 지적은 해결되거나 명시적으로 면제되어야 하며, PR 작성자는 저장소별 규칙을 처리해야 한다.

지루하다. 좋다. 지루한 게이트가 사고를 막는다.

설정: Markdown 파일 두 개, 역할 두 개

Claude Code Review에는 중요한 메모리 표면이 두 개 있다.

CLAUDE.md는 공유 프로젝트 컨텍스트다. 리뷰에만 쓰이는 게 아니라 Claude Code 세션 전반에 적용된다. Anthropic은 명령어, 컨벤션, 짧은 아키텍처 메모, 강한 제약, 알려진 함정을 여기에 쓰라고 권한다. 또한 Enterprise 세션에서 프롬프트 캐싱이 반복 토큰 비용을 줄여주긴 하지만, 이 파일은 컨텍스트에 로드되기 때문에 대략 200줄 이하로 신호 밀도를 높게 유지하라고 권한다 (Claude Help Center).

REVIEW.md는 다르다. 저장소 루트에 있고 리뷰 전용이다. Anthropic의 Code Review 문서는 그 내용이 모든 리뷰 에이전트에 높은 우선순위 지시로 주입되며, 심각도, nit 양, 건너뛰기 규칙, 저장소별 체크, 검증 기준, 재리뷰 동작을 제어하는 곳이라고 설명한다 (Claude Code Docs).

내가 쓰는 구분은 이렇다.

File	Purpose	Good rules	Bad rules
`CLAUDE.md`	모든 Claude 작업을 위한 프로젝트 메모리	빌드 명령어, 아키텍처, “요청 검증에는 Zod를 사용”	긴 히스토리, 애매한 취향, 중복 API 문서
`REVIEW.md`	PR 리뷰 정책	“새 API routes에는 통합 테스트 필요”	뻔한 “깨끗한 코드를 작성하라” 조언
CI 설정	결정론적 강제	타입체크, 유닛 테스트, 린트, 마이그레이션 체크	컴파일러가 증명할 수 있는 것에 대한 LLM 전용 체크

안정적인 컨텍스트는 CLAUDE.md에 넣어라. 리뷰 압박은 REVIEW.md에 넣어라. 결정론적인 것은 CI에 넣어라.

CLAUDE.md, REVIEW.md, CI라는 세 열로 컨텍스트 규칙과 리뷰를 보여주는 간결한 비교 테이블 비주얼

API Routes를 위한 진짜 게이트

어떤 백엔드 팀이 해피패스 유닛 테스트는 있지만 통합 커버리지는 없는 routes를 계속 배포한다고 해보자. 인간 리뷰어가 가끔 잡아낸다. Claude 생성 PR은 이 문제를 더 키운다. 에이전트는 그럴듯한 핸들러 코드를 만드는 데 능하지만, 팀 고유의 리뷰 흉터를 기억하는 데는 약하기 때문이다.

먼저 CLAUDE.md부터 시작한다.

# Project conventions

- API routes live in `src/routes`.
- Integration tests live in `tests/integration`.
- Use `requireAuth()` on non-public routes.
- Validate request bodies with Zod schemas from `src/schemas`.
- Run `pnpm test:integration` before marking API work complete.

그다음 루트에 REVIEW.md를 추가한다.

# Code Review Rules

Treat these as Important unless stated otherwise.

## API routes

If a PR adds or changes a file under `src/routes/**`:
- Flag missing integration test coverage in `tests/integration/**`.
- Flag routes without explicit auth, unless the route is listed as public.
- Flag request bodies that are not validated with a Zod schema.

Do not accept unit tests as a substitute for route-level integration tests.

## Evidence bar

For every Important finding, cite the changed file and the missing or conflicting evidence.
If the claim depends on a convention, cite this REVIEW.md rule.

마지막 섹션이 중요하다. LLM 리뷰어는 자신감 넘치는 헛소리를 만들어낼 수 있다. 증거를 요구하면 지적을 파일, 줄, 또는 명시적 정책에 묶게 된다. 오탐을 없애주지는 않지만, 리뷰의 모양을 “느낌”에서 “보여줘”로 바꾼다.

이제 어떤 PR이 다음을 추가한다고 하자.

// src/routes/billing.ts
router.post("/billing/plan", async (req, res) => {
  const result = await updatePlan(req.body.planId);
  res.json(result);
});

좋은 Claude Code Review 댓글은 대략 이렇게 말해야 한다.

Important: src/routes/billing.ts가 명시적인 auth 없이 새 POST route를 추가합니다.
Important: 요청 본문이 스키마 검증 없이 req.body.planId를 읽습니다.
Important: tests/integration/** 아래에 대응되는 통합 테스트가 추가되지 않았습니다.

결정은 여전히 인간 리뷰어가 한다. 어쩌면 라우터 상위에 auth 미들웨어가 적용되어 있을 수 있다. 어쩌면 통합 테스트가 생성된 계약 테스트 스위트에 있을 수 있다. 좋다. 병합 전에 그 논의를 강제로 만들었다면 게이트는 제 일을 한 것이다.

돈을 태우지 않고 트리거하기

Anthropic은 저장소 트리거 모드를 세 가지로 제공한다. PR 생성 후 한 번, 매 push마다, 또는 수동. 수동은 누군가 @claude review라고 댓글을 달기 전까지 비용이 들지 않는다는 뜻이다. 그 이후에는 해당 PR에 추가 push가 있으면 자동으로 리뷰가 트리거된다 (Claude Help Center).

대부분의 팀이라면 “매 push마다”로 시작하지 않겠다. Anthropic은 Code Review가 평균 약 20분이 걸리고, PR 크기와 복잡도에 따라 보통 리뷰당 15~25달러가 든다고 말한다 (Anthropic). 프로덕션 사고와 비교하면 싸다. ESLint 실행과 비교하면 비싸다.

계층형 게이트를 써라.

모든 PR은 일반 CI를 실행한다.
위험한 PR은 @claude review를 받는다.
큰 PR, auth 변경, 결제 변경, 마이그레이션, 공개 API 변경은 인간 승인 전에 Claude 리뷰가 필요하다.
모든 오타 수정마다가 아니라, 큰 변경 후에 Claude 리뷰를 반복한다.
최종 승인은 인간이 책임진다.

가벼운 GitHub PR 체크리스트로 게이트를 명시할 수 있다.

## AI Review Gate

- [ ] CI is green.
- [ ] `@claude review` has run, or this PR is exempt.
- [ ] Important findings are fixed or explained.
- [ ] If this PR changes conventions, `CLAUDE.md` is updated.
- [ ] If this PR changes review policy, `REVIEW.md` is updated.

Claude를 자체 워크플로 안에서 실행하고 싶다면, Anthropic의 GitHub Actions 문서에 anthropics/claude-code-action@v1와 code-review 플러그인 설정이 나와 있다. API 키에는 GitHub Secrets를 쓰라는 흔한 경고도 함께 있다 (Claude Code Docs). 이 경로는 CI 제어권을 더 많이 준다. 관리형 Code Review 경로는 Anthropic이 설명하는 더 깊은 멀티 에이전트 리뷰어를 준다.

둘을 헷갈리지 마라. 하나는 프로그래밍 가능한 자동화다. 다른 하나는 유료 depth-first 리뷰어다.

작은 PR, 위험한 PR, 큰 PR, 반복 push로 갈라지는 리뷰 트리거 결정 트리 다이어그램

요령: Claude가 스타일이 아니라 계약을 리뷰하게 하라

나쁜 REVIEW.md 파일은 포춘쿠키처럼 읽힌다.

Please ensure the code is clean, maintainable, secure, and well tested.

이러면 물컹한 결과가 나온다.

좋은 REVIEW.md 파일은 흉터를 인코딩한다.

## Database migrations

Flag as Important if:
- A migration adds a non-null column without a default on an existing table.
- A migration backfills data without batching.
- Application code starts reading a new column before the migration is deployed.

Skip:
- Formatting comments in generated Prisma client files.

AI 리뷰가 유용해지는 지점이 여기다. 시니어 엔지니어의 취향을 대체하는 게 아니다. 팀의 제도적 기억을 모든 PR에서 재생하는 것이다.

잘 작동하는 규칙 몇 가지는 이렇다.

## Re-review behavior

On the first review, report Important and Nit findings.
On later reviews of the same PR, suppress new Nits unless they are directly caused by the latest push.

## Test policy

Flag missing tests only when the changed behavior is observable through a stable public interface.
Do not request snapshot tests for purely visual copy changes.

## Security policy

Flag any new endpoint that:
- Accepts user input without validation.
- Performs authorization by trusting a user-provided account ID.
- Logs tokens, session IDs, API keys, or full request bodies.

없는 것을 보라. “코드를 우아하게 만들어라”가 없다. 우아함은 인간이 리뷰에서 논쟁하면 된다. Claude는 계약을 확인해야 한다.

그 논쟁들이 놓치고 있는 것

HN과 Reddit 논쟁은 계속 한 질문을 맴돈다. AI가 AI 코드를 리뷰해야 하는가?

틀린 질문이다.

맞는 질문은 이거다. 리뷰의 어느 부분을 명시적으로 만들 의향이 있는가?

리뷰 문화가 시니어 엔지니어들의 머릿속에만 있다면 Claude Code Review는 시끄럽고 제멋대로처럼 느껴질 것이다. 리뷰 문화가 저장소 규칙으로 쓰여 있다면 그것은 배율기가 된다. CLAUDE.md는 Claude에게 프로젝트가 어떻게 돌아가는지 알려준다. REVIEW.md는 Claude에게 팀이 무엇을 병합하지 않을지 알려준다.

이것은 “Claude를 위해 문서를 쓰는” 것에 대한 불평에도 답이 된다. 맞다. 개발자들은 이제 에이전트를 위한 문서를 쓰고 있다. 그 문서가 동시에 온보딩 자료, 리뷰 정책, 사고 예방책이라는 걸 깨닫기 전까지는 우스꽝스럽게 들린다. 좋은 CLAUDE.md는 인간에게도 더 나은 “이 저장소는 이렇게 돌아간다” 파일이다.

날카로운 모서리는 책임이다. Claude가 버그를 놓쳐도 병합한 건 당신이다. Claude가 버그를 지어내도 거절해야 하는 건 당신이다. Claude가 자기 산출물을 리뷰하더라도 독립적인 신호는 여전히 필요하다. 테스트, 타입 시스템, 정적 분석, 관측성, 그리고 변경을 이해하는 인간.

Claude Code Review를 판사가 아니라 게이트로 써라. 매번 짜증나는 질문을 하게 만들어라.

통합 테스트는 어디에 있는가?
auth는 어디서 강제되는가?
이 PR이 CLAUDE.md를 거짓으로 만들었는가?
이 생성 파일은 코멘트할 가치가 있는가?
이 지적은 코드에 근거한 것인가, 그냥 감인가?

제대로 된 PR에 쓰면, 이 정도로도 값은 한다.

Claude Fable 5 on OneHop에서도 같은 설정을 시도해보라. drop-in으로 쓸 수 있고, $10 무료 크레딧으로 시작할 수 있다.

더 읽을거리: Claude Fable 5 시작하기.