Claude Code에 코드 리뷰 시키기: 머지 전에 버그·중복·과설계 잡아내는 셀프 리뷰 루틴

기능을 만들었다고 바로 머지하면, 나중에 고치기 더 비싼 문제가 섞여 들어가기 쉽습니다. 특히 혼자 개발할 때는 “내가 방금 짠 코드가 이상할 리 없다”는 익숙함이 가장 큰 사각지대가 됩니다. Claude Code를 구현자가 아닌 적대적 리뷰어로 한 번 더 투입하면 이 간극을 줄일 수 있습니다.

조코헌트에 출시된 프로덕트는 377개지만, 출시 첫 24시간 안에 업보트나 댓글 같은 반응을 하나라도 받은 프로덕트는 45%였습니다. 모든 버그를 없애야 한다는 뜻은 아니지만, 초기 사용자가 적은 시점일수록 리뷰와 테스트로 먼저 발견할 수 있는 문제를 놓치지 않는 편이 좋습니다.

1. 리뷰 전에 범위를 고정하기

변경 의도와 검증 기준 정리

Claude Code에게 저장소 전체를 무작정 보라고 하면 중요하지 않은 파일까지 훑느라 핵심을 놓칠 수 있습니다. 먼저 이번 작업의 범위를 짧게 고정하세요.

무엇을 바꿨는가
왜 바꿨는가
어떤 사용자 흐름이 달라지는가
깨지면 안 되는 기존 동작은 무엇인가
테스트나 수동 확인을 어디까지 했는가

예를 들어 “결제 성공 후 주문 상태를 갱신하는 API를 추가했다. 중복 요청에도 주문이 두 번 처리되지 않아야 한다”처럼 작성합니다. 구현 전에 계획을 정리하는 방법은 Claude Code에 ‘계획 먼저’ 시키는 plan-first 워크플로우와도 이어집니다.

리뷰 대상 diff 만들기

리뷰 요청에는 전체 코드보다 변경 diff와 관련 파일을 우선 제공하는 편이 효율적입니다. 기준 브랜치와 현재 브랜치를 명확히 하고, 생성된 파일·설정 변경·데이터베이스 변경도 빠뜨리지 마세요. 리뷰 전에는 포맷터와 테스트를 먼저 실행해 단순한 문법 오류와 설계 문제를 분리합니다.

2. 적대적 리뷰 프롬프트 설계

역할과 우선순위 지정

다음처럼 리뷰어의 역할과 출력 형식을 함께 지정하면 답변이 훨씬 실용적입니다.

현재 변경사항을 시니어 리뷰어처럼 검토해줘. 정상 동작을 칭찬하기보다 실패 가능성을 먼저 찾아줘. 버그, 보안·권한 문제, 경쟁 조건, 중복 로직, 과한 추상화를 우선순위 순으로 정리해줘. 각 항목에는 파일과 위치, 재현 조건, 영향, 수정 방향을 포함해줘. 근거가 부족하면 추측이라고 표시하고, 문제 없음과 확인하지 못한 항목도 구분해줘.

“문제 찾아줘”보다 “어떤 관점으로, 어떤 형식으로, 어디까지 판단할지”를 적는 것이 핵심입니다. 프롬프트의 명세·제약·예시 구조는 AI에게 코드를 잘 시키는 프롬프트 작성법에서 더 자세히 다뤄볼 수 있습니다.

관점을 나눠 여러 번 묻기

한 번에 모든 것을 검사하게 하기보다 리뷰를 나누세요.

동작 리뷰: 정상·실패·경계 입력에서 기대와 다르게 움직이는가
데이터 리뷰: null, 중복, 오래된 데이터, 재시도에 안전한가
권한 리뷰: 다른 사용자의 데이터나 관리자 기능에 접근할 수 있는가
유지보수 리뷰: 중복 분기, 불필요한 추상화, 기존 규칙 위반이 있는가

이렇게 나누면 각 답변을 실제 체크리스트처럼 검증하기 쉽습니다.

3. 지적을 검증 가능한 작업으로 바꾸기

재현 절차부터 요구하기

AI의 지적을 곧바로 사실로 받아들이지 마세요. “이 문제가 실제로 발생하는 최소 입력과 실행 흐름을 제시해줘. 관련 코드를 근거로 설명하고, 재현할 수 없다면 확신도를 낮춰 표시해줘”라고 다시 물어보세요.

그다음 직접 테스트를 추가하거나 로그를 확인합니다. 디버깅도 증상·가설·검증 순서로 진행하면 추측성 수정이 줄어듭니다. 이 흐름은 Claude Code 디버깅 잘 시키는 법의 방식과 잘 맞습니다.

수정은 한 묶음씩 적용하기

발견된 문제를 모두 한 번에 고치게 하면 원래 변경과 수정 변경이 섞입니다. 우선순위가 높은 한 항목만 수정하고, 테스트를 실행한 뒤 다음 항목으로 넘어가세요. 수정 후에는 “방금 변경으로 새로 깨질 수 있는 경로를 다시 리뷰해줘”라고 회귀 리뷰를 요청합니다.

4. 사람이 최종 판단해야 하는 지점

AI는 코드에 드러난 패턴을 빠르게 찾지만, 제품의 우선순위와 운영 맥락까지 자동으로 알지는 못합니다. 다음은 사람이 결정해야 합니다.

이 복잡성이 실제 사용자 가치에 필요한가
드문 실패를 막기 위해 구현 비용을 더 쓸 것인가
호환성을 깨도 단순한 구조로 바꿀 것인가
개인정보·결제·권한처럼 배포 전 별도 확인이 필요한가
리뷰 지적이 실제 요구사항과 충돌하지 않는가

조코헌트에서 댓글을 받은 프로덕트가 29%라는 점을 보면, 출시 후 모든 문제가 충분한 피드백으로 발견된다고 기대하기는 어렵습니다. 그래서 AI 리뷰는 사용자 피드백을 대체하는 장치가 아니라, 피드백이 오기 전 잡을 수 있는 결함을 줄이는 사전 필터로 사용하는 편이 현실적입니다.

5. 머지 직전 5분 체크리스트

변경 목적과 영향 범위를 한 문장으로 설명할 수 있는가
정상·실패·경계 입력을 확인했는가
권한과 사용자 데이터 경계를 점검했는가
AI 지적마다 근거와 재현 가능성을 확인했는가
테스트·타입체크·린트를 실행했는가
사람이 보류한 판단과 남은 위험을 기록했는가

좋은 셀프 리뷰는 AI에게 “괜찮아?”라고 묻는 과정이 아닙니다. 변경 범위를 고정하고, 실패 관점을 나누고, 지적을 재현한 뒤, 사람이 출시 위험을 판단하는 짧은 검증 루틴입니다. 이 루틴을 머지 전 습관으로 만들면 혼자 개발해도 리뷰 없는 코드가 그대로 쌓이는 속도를 늦출 수 있습니다.