Codex 코드 리뷰 요청법: 버그를 찾는 프롬프트와 검증 체크

요약: 좋은 코드 리뷰 요청은 어느 변경을 비교하고 어떤 문제를 찾을지 알려 줍니다. 지적이 나왔다는 사실만으로 버그가 확정되는 것은 아니므로 근거와 재현 조건을 함께 확인하세요.

1. “리뷰해 줘”에 비교 대상을 추가하기

리뷰를 시작할 때는 파일 하나를 읽는 것인지, 아직 커밋하지 않은 변경을 보는 것인지, 기준 브랜치와 현재 변경을 비교하는 것인지 지정하세요. 범위가 다르면 포함되는 코드와 판단 기준도 달라집니다. 검토가 끝난 뒤에는 어떤 비교 범위를 사용했는지 결과에서 확인하는 것이 좋습니다.

OpenAI 공식 코드 리뷰 문서는 Git 체크아웃의 변경을 검토하는 /review와 pull request를 다루는 Code Review 흐름을 구분합니다. 공식 안내에서 로컬 /review는 우선순위가 있는 지적을 보고하고 작업 파일을 바꾸지 않는 검토 흐름으로 설명됩니다. 구체적인 선택 항목은 자신이 사용하는 앱, CLI, IDE에서 확인하세요.

2. 스타일보다 실제 동작을 먼저 묻기

들여쓰기와 변수 이름까지 모두 평가하면 중요한 결함이 가벼운 취향 문제 사이에 섞일 수 있습니다. 가상의 장바구니 수정이라면 “수량이 0일 때 삭제되는지”, “오래된 가격으로 결제가 진행될 수 있는지”처럼 동작을 기준으로 검토 범위를 정해 보세요.

이때 이미 존재하던 문제와 이번 변경이 새로 만든 문제도 구분해야 합니다. 변경된 줄 근처에서 발견한 문제라고 해서 그 수정 때문에 생겼다고 단정할 수는 없습니다. 리뷰 결과에 문제 발생 조건, 해당 코드의 근거, 사용자가 받는 영향, 이번 변경과의 관계를 요청하면 판단하기 쉬워집니다.

3. 바로 응용할 수 있는 리뷰 프롬프트

현재 브랜치의 장바구니 변경을 지정한 기준 브랜치와 비교해 주세요.
이번 변경으로 생길 수 있는 동작 오류와 회귀를 우선 검토해 주세요.
특히 수량 0, 중복 클릭, 응답 실패 상황을 살펴봐 주세요.
이 요청에서는 코드를 수정하거나 PR 댓글을 게시하지 마세요.
각 지적에 파일 위치, 발생 조건, 근거, 예상 영향을 포함해 주세요.
확인된 사실과 추가 검증이 필요한 가능성을 구분해 주세요.
검토 범위와 직접 확인하지 못한 부분도 알려 주세요.

기준 브랜치는 실제 저장소의 이름으로 지정해야 합니다. main이라는 이름을 사용하는지 모르면서 예시를 그대로 넣지 마세요. 아직 저장소를 이해하지 못했다면 먼저 사용 가능한 브랜치와 현재 변경을 설명받고 범위를 정할 수 있습니다. 이 예시는 특정 프로젝트에서 수행한 리뷰 결과가 아닌 요청 템플릿입니다.

4. 지적 하나를 검증 가능한 작업으로 바꾸기

예를 들어 “중복 클릭으로 상품이 두 번 추가될 수 있다”는 지적이 나왔다면 어떤 상태에서 가능한지 먼저 질문합니다. 버튼이 이미 비활성화되는지, 서버가 중복 요청을 처리하는지, 재현에 필요한 타이밍은 무엇인지 살펴볼 수 있습니다. 주변 코드를 읽지 않은 추측인지 구체적인 경로가 있는지 구분하세요.

중복 추가 지적의 재현 조건을 확인해 주세요.
관련 호출부와 중복 방지 처리가 있는지 살펴보고
현재 코드에서 가능한 경로와 아직 확인하지 못한 조건을 설명해 주세요.
결함이 확인되면 최소 수정안과 필요한 검증을 제안해 주세요.

리뷰와 수정은 목표가 다릅니다. 문제를 확인한 뒤 수정을 맡기면 불필요한 변경을 줄일 수 있습니다. 여러 지적 중 일부가 잘못된 가정으로 밝혀졌다면 그 사실을 후속 요청에 넣어 같은 추측이 반복되지 않도록 하세요.

5. 리뷰가 끝난 뒤의 체크리스트

• 비교 범위: 원했던 브랜치나 변경 집합이 맞는지 확인합니다.
• 코드 근거: 현재 파일의 해당 위치가 지적과 일치하는지 봅니다.
• 재현 조건: 정상 입력과 오류 입력을 구분해 실제로 가능한지 확인합니다.
• 검증 결과: 실행한 테스트와 아직 미확인인 동작을 나눕니다.
• 최신 상태: 리뷰 후 코드가 바뀌었다면 이전 지적이 여전히 적용되는지 확인합니다.

PR 댓글로 공유할 때도 코드 위치와 근거를 다시 점검하세요. 공식 문서는 대화에서 검토하는 것과 실제 댓글 게시 또는 승인·병합이 별개임을 안내합니다. 공유할 지적을 먼저 초안으로 정리하면 확인되지 않은 가능성이 확정된 결함처럼 전달되는 일을 줄일 수 있습니다.

6. /review를 쓰기 전에 변경 범위 읽기

로컬 리뷰에서는 먼저 저장소 상태를 읽으면 잘못된 대상을 검토하는 일을 줄일 수 있습니다. 다음은 Git 저장소에서 현재 변경과 브랜치를 살펴보는 명령입니다. 출력된 파일 중 다른 사람의 진행 중인 변경이 있다면 리뷰 범위에 포함할지 구분하세요. 지금 눈에 보이는 모든 변경이 Codex가 만든 변경인 것은 아닙니다.

git status --short
git diff --stat
git diff --cached --stat
git branch --list

공식 CLI 문서의 /review는 기준 브랜치, 커밋하지 않은 변경, 특정 커밋, 직접 지정한 리뷰 기준을 선택하는 흐름을 안내합니다. CLI의 커밋하지 않은 변경 리뷰에는 staged·unstaged·untracked 파일이 포함됩니다. 따라서 이미 staging한 파일이 빠질 것이라고 생각하거나, 새 파일이 검토되지 않을 것이라고 단정하면 안 됩니다. 사용하는 화면의 범위를 읽고 결과에도 선택한 범위를 남기세요.

보고 싶은 대상	선택 기준	특히 주의할 점
지금 수정 중인 작업	커밋하지 않은 변경	다른 작업자의 변경 포함 여부
기능 브랜치 전체	실제 기준 브랜치와 비교	기준이 최신이며 의도한 대상인가
하나의 수정 묶음	특정 커밋	앞뒤 커밋의 맥락도 필요한가
특정 위험 조사	관련 경로와 리뷰 기준 명시	호출부를 빼고 결론 내리지 않는가

기준 브랜치를 모르면 이름을 추측하지 말고 저장소의 브랜치 목록과 팀 작업 방식을 먼저 읽으세요. 리뷰 대상이 무엇인지 결정한 다음 /review를 실행하면 됩니다. 리뷰 결과를 읽기 전에 범위부터 확인하면 지적이 예상과 다르게 많거나 적은 이유를 파악하기 쉽습니다.

7. 수량 0 오류를 가상 코드로 검토하기

다음은 리뷰 연습을 위한 가상 코드입니다. 장바구니 정책이 “수량 0이면 항목 삭제”라고 가정합니다. 실제 프로젝트에서 실행한 코드나 발견한 결함이 아닙니다. 제품의 수량 정책이 다르면 결론도 달라지므로 요구사항과 함께 읽어야 합니다.

function normalizeItem(input) {
  return {
    productId: input.productId,
    quantity: input.quantity || 1
  };
}

이 예시에서 ||는 0을 기본값 1로 바꿀 수 있습니다. 코드만 읽으면 그런 값 변환을 설명할 수 있지만, 실제 장바구니가 잘못 저장된다고 결론 내리려면 이 함수가 언제 호출되는지 확인해야 합니다. 수량 0 요청이 삭제 전용 경로로 처리되어 이 함수에 들어오지 않는다면 사용자의 삭제 동작에는 영향을 주지 않을 수 있습니다. 이 구분이 리뷰에서 추측과 결함을 나누는 핵심입니다.

가정한 요구사항: 수량 0 요청은 항목을 삭제합니다.
normalizeItem의 기본값 처리와 실제 호출 경로를 함께 검토하세요.
0이 1로 바뀌는 경로가 삭제 요청에서 도달 가능한지 확인하세요.
다른 계층에서 0을 처리한다면 해당 근거를 제시하세요.
도달 여부를 확인할 수 없다면 결함으로 확정하지 말고 필요한 자료를 적으세요.

예상 지적의 형태도 미리 정할 수 있습니다. “기본값 연산자가 나쁘다”가 아니라 “수량 0의 삭제 요청이 이 함수에 들어오는 경로에서는 1로 정규화되어 항목이 남을 수 있다”처럼 조건을 적는 것입니다. 수정 제안에서는 0, 값 누락, 음수, 정상 양수를 구분할 수 있어야 합니다. ||를 다른 연산자로 바꾸는 것만으로 제품의 수량 정책 전체가 구현되는 것은 아닙니다.

8. 지적을 사실·가정·검증 계획으로 나누기

리뷰 문장은 근거의 수준이 서로 다릅니다. “해당 함수는 0을 1로 바꾼다”는 예시 코드의 동작 해석이고, “삭제 요청이 이 함수에 들어온다”는 호출 경로에 대한 확인입니다. “사용자의 상품이 남는다”는 제품 전체 결과이므로 저장과 응답 경로까지 필요합니다. 근거 수준을 나누어 보면 어느 단계에서 추가 자료가 필요한지 알 수 있습니다.

항목	좋은 보고의 내용
발생 조건	수량 0 요청이 정규화 함수를 거치는 경우
코드 근거	해당 파일·함수와 호출 경로
기대 동작	현재 요구사항에서 정한 삭제 처리
확인 방법	0 요청 후 저장 결과 또는 응답 확인
남은 조건	다른 계층의 삭제 처리 여부 등

리뷰 지적을 다음 항목으로 다시 정리해 주세요.
발생 입력, 기대 동작, 코드 근거, 사용자 영향, 이번 변경과의 관계.
직접 실행한 재현이 있으면 명령과 결과를 적으세요.
실행하지 않았다면 코드 해석과 검증 계획으로 표시하세요.
호출부나 요구사항이 부족한 지적은 필요한 자료를 구체적으로 남기세요.

우선순위도 영향에 맞춰 판단합니다. 정상 주문을 막거나 데이터를 잘못 저장하는 문제는 변수 이름 취향보다 먼저 보아야 합니다. 단, 영향이 큰 말로 표현되었다고 심각한 결함이 확정되는 것은 아닙니다. 재현 가능성, 실제 사용 경로, 영향을 받는 입력을 함께 살펴보세요. 작은 리팩터링에 운영 전체 장애를 추측하는 보고가 나오면 연결 근거를 다시 요청하는 것이 좋습니다.

지적이 틀렸다면 “이미 처리하고 있다”에서 끝내지 말고 어떤 경로와 검증이 그 가정을 반박하는지 기록합니다. 예를 들어 삭제 요청이 별도 처리되어 이 함수를 호출하지 않는다면 해당 코드와 테스트를 연결해 주세요. 다음 검토에서 같은 오해를 반복하지 않도록 요구사항이나 호출 구조 설명을 보완할 수도 있습니다.

9. 수정 후 재검토와 PR 공유까지 이어 가기

결함이 확인되었다면 필요한 부분만 수정하고 관련 검증을 실행합니다. 수량 예시에서는 0뿐 아니라 값 누락과 정상 양수 입력도 함께 보아야 기본값 변경의 부작용을 찾을 수 있습니다. 테스트 기대값을 현재 코드에 맞추기 전에 제품 정책을 다시 확인하세요. 코드를 바꾼 뒤에는 이전 리뷰의 위치와 설명이 여전히 최신 파일에 맞는지도 살펴봅니다.

확인된 수량 0 결함을 최소 범위로 수정해 주세요.
값 누락·0·정상 양수 입력의 기존 정책을 구분해 주세요.
관련 테스트를 실행하고 변경된 동작과 보존한 동작을 보고하세요.
수정 후 동일 경로를 다시 검토해 새 문제나 빠진 조건을 찾아 주세요.
아직 확인하지 못한 통합 동작은 별도로 표시하세요.

PR에 공유할 때는 지적을 그대로 붙여 넣기보다 검증한 사실 중심으로 초안을 만드세요. 좋은 댓글은 발생 입력, 기대 결과, 현재 코드에서 다른 결과가 나오는 이유, 확인할 검증을 짧게 연결합니다. 아직 실행하지 않은 재현을 “확인했습니다”라고 쓰면 안 됩니다. 다음 템플릿은 검증 정도에 맞춰 바꿔 사용할 수 있습니다.

수량 0 요청이 이 정규화 경로를 거치면 기본값 1로 바뀔 수 있습니다.
현재 요구사항은 0에서 삭제하는 동작이므로 호출 경로를 확인해 주세요.
[검증한 근거 또는 아직 필요한 검증]을 기준으로
0과 값 누락을 구분하는 처리 및 관련 사례 추가를 제안합니다.

공식 Code Review 안내에서 대화 중 검토와 실제 댓글 게시·리뷰 제출은 구분됩니다. 초안을 읽고 파일 위치와 최신 diff가 맞는지 확인한 뒤 공유하세요. 리뷰가 끝난 후 수정 커밋이 추가됐다면 과거 결과를 그대로 최종 판단으로 사용하지 말고 바뀐 범위를 다시 읽습니다. 중요한 것은 지적의 개수보다 실제 변경을 이해하고 확인 가능한 결함부터 해결하는 것입니다.

10. 자주 묻는 질문

지적이 없으면 안전한 코드인가요? 검토한 범위에서 문제를 찾지 못했다는 뜻입니다. 모든 환경과 입력의 동작을 증명한 결과로 해석하지 마세요.

Codex 리뷰만으로 사람의 검토를 대신할 수 있나요? 변경을 이해하고 놓친 사례를 찾는 데 활용하되, 서비스 요구사항과 운영 맥락을 아는 담당자가 최종 판단할 수 있어야 합니다.

테스트가 통과해도 리뷰가 필요한가요? 테스트는 작성된 사례를 확인합니다. 빠진 사례나 변경 목적과 코드의 불일치를 살펴보는 리뷰는 다른 질문에 답합니다. 중요한 변경이라면 두 결과를 함께 읽는 것이 좋습니다.

공식 출처 및 확인일: OpenAI 공식 문서: Code review. 2026년 10월 3일 확인. 명령과 기능은 현재 환경 및 권한을 확인한 뒤 사용하세요.