Claude Code 팀처럼 코드 검토하기

최근 Anthropic이 Claude Code 팀의 코드 검토 방식을 공개했습니다: How the Claude Code team does code review. 이 글의 목표는 한 문장으로 요약됩니다. 되돌리기나 장애를 늘리지 않으면서, 사람이 검토에 쓰는 시간을 최대한 줄이는 것. 이제 검토는 병합 직전에 한 번 거치는 관문이 아닙니다. 자동화된 검사가 전 과정에 걸쳐 돌아가고, 사람의 주의는 위험한 부분에만 쓰입니다.

저희도 크게 공감했습니다. 저희는 열 명 남짓한 엔지니어링 팀으로, 1년 넘게 같은 목표를 향해 왔습니다. 사람의 노력은 정말 필요한 곳에 쓰고, 나머지는 AI에게 맡기는 것. 이를 위해 쓰는 도구가 바로 저희가 직접 만든 AI 코드 검토 서비스 HeyDeer입니다. 아래에서 Anthropic의 글과 나란히 저희의 방식을 소개하고, HeyDeer가 왜 이렇게 설계되었는지 설명하겠습니다.

1. 왜 이제 사람이 모든 줄을 검토할 수 없을까

Anthropic에 따르면 Claude Code 코드의 약 90%를 Claude가 작성하며, 병합된 PR 수는 몇 달 만에 두 배 이상 늘었습니다. 저희가 걸어온 길도 비슷합니다.

예전에는 코드 검토 기준이 엄격했습니다. 누군가가 모든 줄을 꼼꼼히 읽고 더 나은 작성 방법은 없는지 고민했습니다. 나쁜 코드가 한번 코드베이스에 들어가면 걷어내기 어렵기 때문입니다.

Opus 4.1 무렵에는 이미 AI가 코드의 70~80%를 작성하고 있었고, GitHub에서 검토를 기다리는 PR이 계속 쌓여 갔습니다. 점점 따라가기 버거워졌습니다. 지금은 Opus 5.5 덕분에 모델이 충분히 똑똑해져서, 엔지니어는 주로 목표를 정하고 구현은 코딩 에이전트에게 맡깁니다. 이제 코드의 거의 100%를 AI가 작성합니다. 여전히 사람이 모든 줄을 검토한다면, 사람이 전체 과정에서 가장 느린 단계가 될 것입니다.

한편 한 줄 한 줄 검토하는 일의 가치도 예전만 못합니다. 저희가 가장 신경 쓰던 코드 스멜은 AI가 쉽게 정리할 수 있어서, 이제 사람이 일일이 찾아낼 필요가 없습니다. 이 방법은 다른 글에서 따로 소개하겠습니다.

그래서 이제 질문은 “사람이 어떻게 더 빨리 검토할까?”가 아니라 다음과 같습니다.

1. 어떤 변경이 정말로 사람의 확인을 필요로 할까?
2. 사람이 보지 않는 변경은 어떻게 높은 품질을 유지할까?

하나씩 살펴보겠습니다.

2. 어떤 변경에 사람이 필요할까: 위험 수준에 따른 구분

Anthropic의 답은 위험 수준에 따른 사람의 승인입니다. 분류기가 작성자가 누구인지가 아니라 변경 자체를 보고 위험 수준을 정합니다. 낮은 위험의 변경은 자동화된 검사를 통과하면 사람의 승인이 필요 없고, 중간 위험은 한 명, 높은 위험은 두 명의 승인이 필요합니다.

HeyDeer도 같은 방식으로 동작합니다. 모든 검토에서 PR의 위험 수준(낮음, 중간, 높음)을 평가하고 그 이유를 설명합니다. HeyDeer가 승인할 수 있는 PR 설정에서 HeyDeer가 승인할 수 있는 위험 수준을 선택할 수 있습니다.

낮은 위험과 중간 위험: HeyDeer가 승인

저희 팀은 위험이 낮거나 중간인 PR을 선택했습니다. PR이 높은 위험이 아니고 HeyDeer의 전체 검토에서 문제가 발견되지 않으면, HeyDeer가 승인하고 PR은 main에 자동으로 병합됩니다.

이렇게 일한 지 8개월이 되었지만, 버그가 있는 코드를 병합해서 프로덕션 서비스가 중단된 적은 한 번도 없습니다.

높은 위험: 방향은 사람이 판단하고, 세부 사항은 HeyDeer가 처리

높은 위험의 PR은 여전히 다른 엔지니어의 승인이 필요합니다. 하지만 그 사람의 역할이 달라졌습니다. 한 줄씩 실수를 찾는 대신, 더 높은 관점에서 PR의 접근 방식과 방향이 옳은지 판단합니다. 이는 Anthropic의 글에서 사람이 계속 관여하는 지점과 일치합니다. 무엇을 만들지 결정하고, 아키텍처를 검토하고, 변경을 뒷받침하는 근거를 읽는 일입니다. 세부 사항은 HeyDeer에 맡기면 됩니다.

사람이 중요한 부분을 더 빨리 찾을 수 있도록 HeyDeer는 워크스루를 제공합니다.

• 관련된 변경을 묶어 각 그룹에 필독, 읽기 권장, 훑어보기를 표시하고, 주요 흐름에서 벗어난 변경은 각각의 이유와 함께 기타에 나열합니다. 무엇을 건너뛰어도 되는지 한눈에 보이므로 가장 중요한 부분에 주의를 집중할 수 있습니다.
• PR의 위험 수준과 그 판단 근거를 알려 주므로, 무엇을 신중하게 확인해야 하는지 알 수 있습니다.

검토자는 더 이상 첫 파일부터 마지막 파일까지 차례로 읽지 않습니다. 사람의 판단이 가장 필요한 몇 곳으로 바로 갑니다.

3. 사람이 보지 않는 곳에서도 높은 품질 유지하기

AI가 대부분의 PR을 승인하려면 그 검토를 믿을 수 있어야 합니다. 있는 문제는 찾아내되, 사람을 노이즈에 파묻히게 해서는 안 됩니다. HeyDeer는 두 가지를 모두 목표로 설계되었고, 각 팀이 자신의 검토 방식에 맞게 조정할 수 있습니다.

정확성: 여러 모델이 검토하고 서로 교차 검증

Anthropic의 AI 검토는 여러 에이전트가 병렬로 버그를 찾은 다음, 다른 에이전트들이 각 발견 사항에 투표하게 하고, 통과한 것만 게시합니다.

HeyDeer는 한 걸음 더 나아갑니다. 서로 다른 회사의 모델이 각 변경을 검토하고 서로 교차 검증합니다. 단일 모델은 문제를 놓치기도 쉽고 없는 문제를 보고하기도 쉬우며, 같은 모델을 여러 개 돌려도 같은 실수를 반복하기 쉽습니다. 모델마다 사각지대가 다르기 때문에 교차 검토는 눈에 띄게 더 많은 문제를 찾아내고, 교차 검증은 노이즈와 오탐을 상당 부분 걸러 냅니다.

노이즈를 줄이는 일은 사람의 주의를 지키는 일이기도 합니다. 오탐이 너무 많으면 사람은 따라가지 못하고 결국 읽지 않게 됩니다. 그렇다고 모든 것을 코딩 에이전트에게 넘기면, 에이전트가 오탐을 그대로 따라 고치면서 코드베이스가 불필요하게 비대해질 수 있습니다. 검토를 AI에게 맡기는 방식은 그 결과가 정확할 때만 통합니다.

철저함: 저장소 검사로 팀의 컨벤션 적용

Anthropic의 방식은 같은 검토 의견이 계속 나오면 그 근원에서 해결하는 것입니다. 스킬, 린트 규칙, CLAUDE.md, REVIEW.md에 반영하는 식입니다.

저희 경험상 범용 검토 도구는 특정 코드베이스의 요구 사항을 잘 다루지 못합니다. 버튼 레이블의 대소문자 규칙, 인터페이스 문구의 어조, React 사용에 관한 팀의 컨벤션 같은 것들입니다. 이런 컨벤션을 AGENTS.md나 스킬에 적어 두면 코딩 에이전트가 코드를 작성할 때 참고하지만, 전체 코드 검토에서는 방대한 컨텍스트 속에 묻혀 놓치기 쉽습니다.

HeyDeer의 저장소 검사는 바로 이런 경우를 위해 만들어졌습니다. 확인하고 싶은 요구 사항을 .agents/checks에 평범한 문장으로 적어 두면, HeyDeer가 검사마다 전담 검토자를 배정합니다. 이 검토자는 해당 파일을 변경하는 모든 PR을 그 요구 사항 하나에 비추어 검토하므로 빠뜨리는 것이 없습니다.

조정 가능성: 팀의 검토 방식에 맞는 피드백 범위

팀마다 검토 피드백에서 필요로 하는 것이 다르기 때문에, HeyDeer는 피드백 범위 설정을 제공합니다.

• 간결: 금융처럼 여전히 사람의 검토에 주로 의존하는 팀에 적합합니다. 중요한 문제만 남기므로 사람이 가장 중요한 곳에 시간을 쓸 수 있습니다.
• 균형(기본값) 또는 상세: 검토와 수정 대부분을 코딩 에이전트나 HeyDeer에게 맡기는 팀에 적합합니다. 작은 문제를 고치는 데 AI는 비용이 거의 들지 않으므로, 사소한 문제까지 해결됩니다.

4. 검토 이후: PR이 수렴할 때까지 Autopilot이 수정

검토에서 문제가 발견되면 누군가는 그것을 고쳐야 합니다. 엔지니어가 매 회차마다 돌아와 의견을 읽고, 에이전트에게 수정을 요청하고, 다음 검토를 기다려야 한다면 그 사람의 주의는 여전히 묶여 있는 셈입니다.

Anthropic의 글은 아주 현실적인 문제를 솔직하게 다룹니다. AI 검토가 수렴하지 못할 수 있다는 것입니다. 그들의 PR 하나는 하룻밤 사이에 50회차가 넘는 검토와 수정을 거쳤습니다. 검토자가 계속 지적한 내용의 약 59%는 첫 검토 때부터 있던 코드였습니다. 회차마다 새로운 버그가 아니라 오래된 버그를 몇 개씩 더 찾아낸 것입니다. 이후 그들은 회차 수 제한, 처음 몇 번 이후에는 새 변경만 재검토하기, 이미 게시한 발견 사항을 반복하지 않기 등 여러 개선을 거쳤습니다.

HeyDeer는 처음부터 수렴을 검토의 설계 목표로 삼았습니다. HeyDeer가 작은 문제를 여러 개 찾으면 Autopilot에 맡길 수 있습니다. Autopilot은 남은 항목을 고치고 PR 브랜치에 push한 뒤 자신의 변경을 검토하며, PR을 병합할 준비가 되거나 사람이 답해야 할 질문이 생길 때까지 이를 반복합니다. 저희가 써 보니 대부분의 PR은 2회차, 더 복잡한 PR은 3회차면 끝납니다. Autopilot은 최대 5회차까지 실행되며, 멈출 때는 그 이유와 아직 사용자가 처리해야 할 부분을 설명합니다.

저희에게 이 점은 아주 중요합니다. 사람에게 컨텍스트 전환은 비용이 매우 큽니다. 새 기능을 작성하면서 지난 PR의 의견이 처리되었는지 신경 쓰는 것처럼, 엔지니어가 두 가지를 동시에 머릿속에 담아 두길 원하지 않습니다. Autopilot을 시작하고 나면 엔지니어는 안심하고 다음 작업으로 넘어갈 수 있습니다.

이를 모두 합치면 저희 팀의 일상은 이렇습니다. 엔지니어는 PR을 열고 나면 다른 일로 넘어갈 수 있습니다. HeyDeer가 PR을 검토하고, 발견한 문제는 Autopilot이 고칩니다. 위험이 낮거나 중간인 PR은 HeyDeer가 승인해 main에 바로 병합되고, 높은 위험의 PR은 다른 엔지니어가 워크스루를 보며 방향을 확인합니다.

5. 어떤 팀이 이렇게 일할 수 있을까

“높은 위험의 변경만 사람이 검토한다”는 방식은 누구에게 맞을까요? 지금의 AI 역량이라면, 특별히 민감한 정보를 다루는 사업이 아닌 한 대부분의 스타트업과 중소기업이 이렇게 일할 수 있다고 생각합니다. 처음에는 HeyDeer가 낮은 위험의 PR만 승인하게 하고, 팀에 신뢰가 쌓이면 중간 위험까지 넓혀 가면 됩니다.

맺으며

Anthropic의 실천 방식과 저희가 HeyDeer를 쓰는 방식을 대략 대응해 보면 다음과 같습니다.

도구와 모델은 바뀌겠지만 목표는 바뀌지 않습니다. 사람의 주의는 팀에서 가장 희소한 자원이므로, 가장 중요한 곳에 써야 합니다. 여러분의 팀도 AI가 코드를 작성하는 속도를 사람의 검토가 따라가지 못하고 있다면, HeyDeer를 사용해 보세요.