Claude Code 코드 리뷰 프롬프트: 버그 근거와 재현 조건 요청하기

핵심 요약: 코드 리뷰를 맡길 때는 “문제를 많이 찾아 줘”보다 어떤 변경을 어떤 동작 기준으로 검토할지 알려 주세요. 결과에는 파일 위치, 발생 조건, 사용자 영향, 확인 근거가 필요합니다. 아래 프롬프트와 계산 함수 예시는 작성자가 구성한 검토 연습용이며 실제 저장소의 리뷰 결과가 아닙니다.

1. 검토 범위와 정상 동작부터 정하기

검토 대상이 현재 수정 사항인지, 특정 파일인지, 한 기능의 전체 흐름인지 먼저 적으세요. Git을 쓰는 경우 비교할 기준도 실제 저장소에서 정해야 합니다. 막연히 “전체 코드 리뷰”라고 요청하면 오래된 문제와 이번 변경의 문제, 스타일 취향이 섞일 수 있습니다.

정상 동작은 짧은 입력·출력 예로 설명할 수 있습니다. 검색 기능이라면 “검색어가 비어 있을 때 전체 목록을 보여 주는가, 안내만 보여 주는가”를 명시하세요. 화면에서 원하는 결과를 정하지 않으면 동일한 구현도 서로 다른 기준으로 평가하게 됩니다. 기존 설계 문서와 테스트가 있다면 해당 위치도 제공합니다.

2. 기본 코드 리뷰 프롬프트 예시

이번 변경을 코드 리뷰해 줘. 파일은 아직 수정하지 마.
검토 범위: [실제 변경 파일 또는 비교 기준]
요구 동작: [입력과 기대 결과]
우선 확인: 잘못된 결과, 예외 처리, 기존 기능의 회귀.
스타일 선호만으로 문제를 만들지 마.
각 지적은 아래 형식으로 적어 줘.
- 파일과 위치
- 어떤 입력 또는 상태에서 발생하는지
- 사용자에게 어떤 영향이 있는지
- 코드·테스트·실행 결과 중 확인 근거
- 실제로 확인한 문제인지, 아직 확인할 가설인지
실행하지 않은 테스트는 실행했다고 쓰지 마.

리뷰와 수정은 다른 작업이므로, 먼저 지적을 읽고 타당한 문제를 선택한 다음 수정을 요청할 수 있습니다. 코드의 모양만으로 판단하기 어려운 문제는 호출 경로와 실제 데이터 조건을 확인해야 합니다. 이 양식은 지적을 늘리는 목적보다 판단에 필요한 정보를 모으는 목적입니다.

3. 가상 예시: 할인 금액 함수 검토하기

상품 금액과 할인 비율을 받아 최종 금액을 계산하는 함수를 생각해 보겠습니다. 검토 기준은 “금액은 0 이상, 할인 비율은 0부터 100, 잘못된 입력은 명시적으로 처리한다”로 정합니다. 10,000원에 20% 할인이라면 기대하는 금액은 8,000원입니다. 이는 설명을 위해 직접 계산한 값이며 어떤 코드의 실행 결과가 아닙니다.

• 정상 범위: 10,000원·20%에서 정한 기대값과 일치하는지.
• 경계값: 할인 0%와 100%를 어떻게 처리하는지.
• 잘못된 값: 음수, 비어 있는 값, 숫자가 아닌 값의 처리 방식.
• 연결 흐름: 화면에서 받은 문자열이 숫자로 변환되는 위치.
• 표시 규칙: 소수점과 반올림을 어디에서 처리하는지.

함수만 보면 문제가 없어도 입력 변환이나 화면 표시에서 오류가 생길 수 있습니다. 반대로 외부 단계에서 이미 검증된 입력만 받는 함수라면 모든 방어 로직을 중복으로 넣을 필요가 없는 경우도 있습니다. 리뷰에는 “이 입력이 실제로 들어올 수 있는가”라는 조건 확인을 포함하세요.

4. 지적을 사실·가설·개선 제안으로 구분하기

“빈 배열에서 예외가 발생했다”는 실제 재현 결과와 “빈 배열이면 예외가 생길 가능성이 있다”는 코드 해석을 구별해야 합니다. 실행 로그가 없는데 전자로 적혀 있다면 어떤 명령과 입력으로 확인했는지 요청하세요. 실행하지 못한 환경이라면 확인할 방법을 제안으로 남길 수 있습니다.

Anthropic의 Claude Code 권장 작업 방식도 검증 기준을 제공하고 결과를 독립적으로 검토하는 방향을 설명합니다. 리뷰 답변은 정답 목록으로 받아들이기보다 각 지적의 코드 경로와 영향을 대조하세요. 설명이 구체적이어도 잘못된 가정이 있을 수 있습니다.

검토 후에는 지적마다 “재현됨”, “추가 확인 필요”, “현재 요구 범위 밖”처럼 상태를 기록하면 좋습니다. 근거가 없는 지적을 수정하기 위해 코드를 복잡하게 만들기보다, 발생 조건을 먼저 확인해 필요한 변경을 선택하세요.

5. 수정 후에는 같은 조건으로 다시 확인하기

문제를 수정했다면 원래 재현 조건과 정상 조건을 모두 확인하세요. 할인 비율이 잘못된 경우만 막고 정상 20% 입력까지 실패하게 만들면 다른 회귀가 생긴 것입니다. 관련 테스트와 명령은 실제 프로젝트의 방식을 따라야 합니다. 테스트 이름만 생성한 상태와 실행해 통과한 상태도 구분합니다.

완료 보고는 “수정 파일, 문제 원인, 실행한 검증, 남은 확인 사항”으로 정리할 수 있습니다. 공식 작업 예시에서도 테스트와 변경 검토를 단계별로 다룹니다. 보고에 없는 검증을 독자가 수행한 것으로 추정하지 않도록, 미실행 항목도 분명히 적어 달라고 요청하세요.

6. 변경 리뷰와 요구 사항 리뷰를 구분하기

현재 변경에서 생긴 버그를 찾는 작업과 계획의 모든 요구 사항이 구현됐는지 확인하는 작업은 질문이 다릅니다. 전자는 변경 전후 코드 경로와 회귀를 중심으로 읽고, 후자는 계획의 항목을 구현·검증 근거와 짝짓습니다. 어느 쪽인지 적어야 “기능은 있지만 요구 조건 하나가 빠진 경우”도 의미 있는 지적으로 분류할 수 있습니다.

확인일 기준 공식 권장 문서에는 현재 diff를 별도 서브에이전트가 검토하는 기본 제공 /code-review 기능도 소개돼 있습니다. 처음부터 모든 검토 방식이 동일하다고 생각하기보다, 자신의 목적이 변경 오류 확인인지 계획 대조인지 먼저 정하세요. 기능을 호출했다는 사실 자체가 문제 재현이나 모든 요구의 충족을 증명하지는 않습니다.

7. 가상 코드에서 지적의 근거를 끝까지 추적하기

앞의 할인 예시를 조금 더 구체화하겠습니다. 다음 JavaScript 코드는 연습을 위해 만든 가상 코드이며 실제 프로젝트에서 실행한 결과는 없습니다. 화면에서 “20%”를 숫자 20으로 변환해 전달한다는 조건을 가정합니다. 할인 비율을 0.2로 전달하는 다른 설계라면 판단이 달라지므로, 입력 계약을 먼저 정해야 합니다.

function finalPrice(price, discountPercent) {
  return price * (1 - discountPercent);
}

정한 계약대로라면 10,000과 20을 대입했을 때 식은 10,000 × (1 − 20)이 되어 −190,000입니다. 요구한 8,000과 다릅니다. 이 값은 코드를 실행한 로그가 아니라 식을 직접 대입한 계산입니다. 지적은 “할인 함수가 이상함”보다 “퍼센트 단위 20을 받는 계약에서 비율 변환이 없어 정상 입력도 음수가 됨”으로 쓰면 원인과 조건이 드러납니다.

고친 식이 퍼센트 값을 100으로 나누더라도 입력 거부, 소수점, 통화 표시까지 저절로 정해지는 것은 아닙니다. 예를 들어 999원에 15% 할인은 산술적으로 849.15원입니다. 실제 판매 금액을 반올림할지 버릴지는 프로젝트 요구에 맞춰 정해야 합니다. 리뷰어가 자기 취향으로 금액 정책을 바꾸지 않도록 기준을 제공합니다.

이 함수의 입력 계약은 할인 비율을 0~100 숫자로 받는 것입니다.
호출부에서 실제로 이 계약을 지키는지 먼저 추적해 줘.
10,000 / 20% 사례의 식과 기대값 차이를 설명해 줘.
실행 로그가 없으면 '정적 검토와 계산으로 판단'이라고 표시해 줘.
입력 검증·반올림 정책은 기존 문서에서 확인하고,
근거가 없으면 별도 결정 사항으로 남겨 줘.

8. 오탐을 줄이는 질문과 지적 분류하기

예를 들어 “문자열 입력이면 실패할 수 있다”는 지적이 나왔지만 호출부에서 숫자로 변환하고 범위를 검사한다면, 그 입력이 함수까지 도달하는지 추가로 봐야 합니다. 확인하지 않은 경로를 근거로 방어 코드를 계속 쌓기보다, 호출 위치와 데이터 변환을 추적해 지적을 채택할지 결정합니다. 이것은 오류를 무시하는 절차가 아니라 발생 조건을 확인하는 절차입니다.

리뷰 지적 2번을 다시 검토해 줘.
주장한 입력이 외부에서 해당 함수까지 오는 호출 경로를 제시해 줘.
중간 검증이 있다면 그 파일과 조건을 확인해 줘.
현재 코드로 발생할 수 없는 가정이면 지적을 철회하고 이유를 적어 줘.
검토 범위에서 호출부를 찾지 못했다면 '추가 확인 필요'로 남겨 줘.
같은 이유를 표현만 바꿔 여러 지적으로 나누지 마.

보고를 읽을 때는 영향의 크기와 근거의 수준도 별도로 봅니다. 결제 결과가 틀리는 오류는 영향이 클 수 있지만, 발생 경로를 아직 확인하지 못했다면 그 상태를 함께 적어야 합니다. “심각함”이라는 라벨만으로 재현된 문제로 바꾸지 않습니다. 반대로 재현이 작고 간단하다는 이유로 사용자 영향까지 작다고 판단하지 않습니다.

9. 선택한 문제만 고치고 결과를 비교하기

타당한 지적을 골랐다면 수정 요청에 유지할 동작을 함께 넣습니다. 할인 함수의 경우 단위 변환을 바로잡는 작업과 화면 전체 개편은 다른 범위입니다. 관련된 테스트가 있다면 기존 실행 절차를 따르고, 없다면 핵심 입력의 기대 결과를 명시해 확인할 방법부터 정할 수 있습니다. 프로젝트에 없는 테스트 명령을 만들어 실행 결과처럼 쓰면 안 됩니다.

채택한 지적: [번호와 원인]
수정 범위: 할인 비율 변환과 직접 관련된 코드.
유지 조건: 기존 화면·공개 함수 입력 형식 유지.
검증 기준: 정상 20%, 경계 0%와 100%, 기존 입력 거부 정책.
실제 프로젝트의 검증 명령을 근거 파일에서 찾아 사용해 줘.
완료 보고에는 변경 파일, 해결한 원인, 실행 명령과 결과,
실행하지 못한 항목·이유를 나눠 적어 줘.
검증 중 다른 문제가 나오면 이번 수정과 관련 여부를 구분해 줘.

마지막으로 diff를 다시 읽어 요청 범위 밖의 변경이 들어왔는지 봅니다. “테스트 통과”가 표시됐다면 어떤 테스트가 어떤 환경에서 실행됐는지 확인하고, 금액 표시처럼 별도로 남은 항목을 삭제하지 않습니다. 한 개 테스트가 통과했다는 관찰은 그 테스트 범위에 대한 근거입니다. 전체 서비스가 모든 입력에서 정상이라는 결론으로 확대하지 않습니다.

테스트가 실행되지 않았는데 리뷰를 받을 수 있나요?

코드의 조건과 호출 경로를 읽는 정적 검토는 할 수 있습니다. 결과에 미실행 상태를 적고, 어떤 입력으로 무엇을 확인해야 하는지 남기세요. 환경 문제로 실행을 못한 경우 “리뷰 실패” 한마디보다 정적으로 확인한 항목과 남은 동작 확인을 분리하면 다음 작업자가 이어받기 쉽습니다.

자주 묻는 질문과 실수 해결

리뷰에서 문제가 없다고 하면 끝인가요? 확인한 범위와 실행 여부를 봐야 합니다. 스타일 지적이 너무 많으면요? 기능 오류와 요구 사항 위반을 우선하라고 기준을 구체화하세요. 자동 수정까지 맡겨도 되나요? 선택한 지적과 수정 범위를 명시하고, 수정 후 같은 조건의 검증 결과를 확인하세요.

공식 출처와 확인일

• Best practices for Claude Code
• Common workflows

공식 문서 확인일: 2026년 10월 3일. 화면과 제공 조건은 이후 바뀔 수 있습니다.