Codex review --base와 --commit 비교: 코드 리뷰 범위는 어떻게 고를까

TL;DR

현재 브랜치가 기준 브랜치에서 갈라진 뒤 쌓은 전체 diff를 검토하려면 codex review --base <BRANCH> 를 고릅니다. 이미 만들어진 커밋 하나의 정확한 change set만 다시 보려면 codex review --commit <SHA> 를 고릅니다.

둘은 우열 관계가 아닙니다. OpenAI 공식 문서는 --base , --commit , --uncommitted , custom prompt를 서로 충돌하는 review target으로 설명합니다. 한 실행에는 하나만 선택하세요. Codex finding을 실제 diff와 테스트에 대조한 뒤 사람이 다음 행동을 승인합니다.

핵심 3줄 요약

핵심 1

기능 브랜치의 누적 변경을 기준 브랜치와 비교하면 --base 가 맞습니다.

핵심 2

핫픽스나 후속 수정처럼 커밋 하나가 도입한 변경만 보면 --commit 이 맞습니다.

핵심 3

finding은 검토 입력입니다. 수정·커밋·푸시·병합은 코드와 테스트를 확인한 사람이 결정합니다.

이 글에서 다룰 내용

--base 와 --commit 이 읽는 review scope의 차이
같은 병합 전 검토에서 target 하나를 고르는 기준
실행 전에 Git 명령으로 실제 범위를 확인하는 순서
finding을 근거·검증 상태·승인자로 나누는 방법
그대로 복사해 쓰는 범위 제한 프롬프트와 FAQ

먼저 고를 것은 브랜치 누적인지 한 커밋인지입니다

코드 리뷰 범위는 Codex에 얼마나 많이 읽힐지 정하는 입력 경계입니다. 공식 Code review 문서에 따르면 Review against a base branch는 merge base를 찾아 현재 브랜치 diff를 검토합니다. Review a commit은 선택한 커밋의 정확한 change set을 검토합니다.

한 문장 정의는 이렇습니다. --base 는 기준 브랜치 이후 누적된 현재 브랜치의 차이를 보는 target입니다. --commit 은 지정한 SHA가 도입한 한 묶음의 차이를 보는 target입니다.

Codex는 선택한 diff를 읽고 우선순위가 있는 실행 가능한 finding을 보고합니다. 공식 문서상 review는 working tree를 바꾸지 않습니다. 이 경계는 출력 형식을 설명할 뿐 finding의 정확성, 테스트 통과, 병합 가능성을 보증하지 않습니다.

선택 기준: --base인가 --commit인가

기준 브랜치 이후 전체 변경을 보면 --base

풀 리퀘스트를 열기 전 기능 브랜치 전체가 main 또는 조직이 정한 기준 브랜치와 어떻게 다른지 확인하려면 --base 를 선택합니다. 첫 행동은 기준 브랜치 이름과 merge base가 이번 검토 의도에 맞는지 확인하는 일입니다.

예를 들어 현재 브랜치가 여러 커밋으로 기능 하나를 완성했다고 합시다. 최종적으로 남은 누적 diff가 검토 대상이라면 다음 형태를 사용합니다.

codex review --base main

이때 완료물은 “브랜치가 안전하다”는 선언이 아닙니다. 기준 브랜치, merge base, 변경 파일 목록, finding, 실제 코드 위치, 검증 명령과 상태가 연결된 내부 리뷰표입니다.

커밋 하나의 정확한 change set을 보면 --commit

핫픽스, 되돌림 후속 수정, 리뷰 지적을 반영한 한 커밋처럼 특정 SHA가 만든 변화만 확인하려면 --commit 을 선택합니다. 첫 행동은 검토할 SHA와 그 커밋의 파일 목록이 요청한 작업과 같은지 확인하는 일입니다.

codex review --commit <SHA>

--commit 에는 --title 을 함께 사용할 수 있습니다. 다만 제목은 표시용 문맥입니다. 검토 범위를 바꾸는 근거는 SHA와 실제 change set입니다. 커밋 메시지만 보고 올바른 target이라고 판단하지 않습니다.

시작 전 review target과 설치 표면을 확인하세요

현재 작업 환경의 codex review --help 에서 --base <BRANCH> 와 --commit <SHA> 가 보이는지 먼저 확인합니다. 이 글을 검증한 로컬 환경은 codex-cli 0.144.6 이었고 두 옵션을 모두 노출했습니다. 문서와 설치된 CLI가 다르면 현재 바이너리의 인식 결과를 우선 기록하세요. 확인되지 않은 업데이트·재시작 해결책은 만들지 않습니다.

공식 명령 레퍼런스는 --uncommitted , --base , --commit , custom prompt가 서로 충돌한다고 명시합니다. 여러 범위를 한 명령에 붙이지 않습니다. 이번 검토가 답할 질문을 먼저 적고 target 하나를 고릅니다.

리뷰에는 비밀값, 고객 데이터, 운영 환경 덤프를 넣지 않습니다. 저장소에 이미 민감 정보가 들어갔다면 Codex review보다 노출 범위 확인과 조직의 사고 대응 절차가 먼저입니다.

실행 순서: 한 target만 골라 코드 리뷰 범위를 검증하세요

1단계. 검토 질문과 완료물을 한 문장으로 적습니다

2단계. Git에서 실제 입력 범위를 먼저 봅니다

--base 를 고르면 현재 브랜치와 기준 브랜치를 확인하고 merge-base 기반 diff의 파일 목록을 봅니다. --commit 을 고르면 SHA, 부모 대비 diff와 파일 목록을 확인합니다. 저장소의 실제 상태가 요청과 다르면 여기서 멈춥니다.

git branch --show-current
git merge-base HEAD <BRANCH>
git diff --stat <BRANCH>...HEAD
git show --stat --oneline <SHA>

3단계. 한 target으로 Codex review를 실행합니다

브랜치 누적 diff를 골랐다면 codex review --base <BRANCH> , 단일 change set을 골랐다면 codex review --commit <SHA> 를 실행합니다. 두 명령을 같은 검토의 필수 연속 단계로 만들지 않습니다. 첫 파일럿에서는 선택한 질문 하나에 target 하나만 사용합니다.

4단계. finding을 실제 코드와 대조합니다

각 finding에서 파일·위치·실패 조건·영향을 찾습니다. 선택한 diff 밖의 오래된 문제인지, 이번 change set이 만든 문제인지 구분합니다. 코드 근거를 찾지 못하면 확인 필요 , 실제 동작과 충돌하면 상충 , 근거와 재현이 맞으면 확인 완료 로 남깁니다.

5단계. 저장소가 정한 검증 명령을 실행합니다

README, 패키지 스크립트, CI 설정에 기록된 테스트·lint·type check·build만 사용합니다. 존재하지 않는 명령을 추정하지 않습니다. 리뷰 전에 이미 실패하던 검사와 이번 diff로 생긴 실패를 나눠 기록합니다.

6단계. 사람이 target과 다음 행동을 승인합니다

검토자는 기준 브랜치 또는 SHA, 실제 파일 목록, 수용·기각·보류 finding, 검증 결과를 확인합니다. 수정이 필요해도 review 결과에서 바로 commit·push·merge하지 않습니다. 코드 소유자가 최소 수정, 재검증과 다음 Git 동작을 각각 승인합니다.

그대로 복사해 쓰는 선택형 프롬프트

이 프롬프트는 review target을 고르고 결과를 검증하기 위한 내부 체크리스트입니다. --base 나 --commit 과 custom prompt를 같은 명령에 붙이지 마세요. target 선택 전 또는 review 결과 검증 단계에서 별도로 사용합니다.

목표: 현재 코드 검토 질문에 맞는 Codex review target 하나를 고르고 finding 검증표를 완성한다.

선택 조건: 기준 브랜치 이후 현재 브랜치의 누적 diff가 질문이면 --base를, 지정한 커밋 하나의 정확한 change set이 질문이면 --commit을 선택한다.

허용 입력: 현재 Git 저장소의 브랜치명, merge base, 사용자가 지정한 SHA, 실제 diff와 파일 목록, Codex finding, 저장소에 정의된 검증 명령 결과만 사용한다.

제외 입력·행동: 저장소 밖 자료, 비밀값, 개인정보, 운영 데이터, 승인되지 않은 네트워크 접근, 자동 수정, stage, commit, push, merge를 제외한다.

완료 기준: 선택한 target과 실제 diff 범위가 일치하고 모든 finding에 코드 근거와 검증 상태가 있거나 확인 필요가 표시돼야 한다.

무창작 원칙: 존재하지 않는 파일·SHA·브랜치·테스트·실행 결과·결함을 만들지 않는다. 근거가 없으면 확인 필요로 남긴다.

승인 지점: 코드 소유자가 target, diff, finding과 검증 결과를 확인한 뒤에만 수정·stage·commit·push·merge를 별도로 승인한다.

검증 체크리스트

이번 질문은 브랜치 누적 diff와 단일 커밋 change set 중 어느 쪽입니까?
codex review --help 에서 선택한 옵션을 현재 설치본이 인식합니까?
--base 라면 기준 브랜치와 merge base, --commit 이라면 SHA와 부모 대비 diff를 확인했습니까?
한 실행에 review target 하나만 사용했습니까?
각 finding을 실제 파일과 선택한 diff 안에서 대조했습니까?
기존 실패와 이번 변경으로 생긴 실패를 나눴습니까?
수정·commit·push·merge가 사람 승인 뒤로 분리됐습니까?

실무 인사이트: finding 수보다 범위 증거가 중요합니다

리뷰 결과가 길다고 검토가 잘된 것은 아닙니다. --base 에서 잘못된 기준 브랜치를 고르면 관련 없는 누적 변경이 섞일 수 있습니다. --commit 에서 잘못된 SHA를 고르면 필요한 변경을 놓칩니다.

좋은 리뷰 기록은 finding 수보다 입력 범위를 재현할 수 있습니다. 기준 브랜치와 merge base 또는 SHA, 파일 목록, 검증 명령, 사람의 판단을 함께 남기면 다음 검토자도 같은 target을 다시 확인할 수 있습니다.

한 파일럿에서 두 target을 자동으로 연결하지 않는 이유도 같습니다. 먼저 필요한 증거 질문 하나를 고르세요. 그 범위에서 finding 품질과 검증 비용을 확인해야 선택 근거가 남습니다.

주의할 점

--base 는 merge base를 찾아 현재 브랜치 diff를 검토합니다. 단순히 두 브랜치 이름의 모든 이력을 비교한다고 확대 해석하지 않습니다.
--commit 은 선택한 커밋의 정확한 change set을 검토합니다. 커밋 메시지나 --title 이 범위를 증명하지 않습니다.
--base , --commit , --uncommitted , custom prompt는 한 실행에서 함께 쓰지 않습니다.
Codex가 working tree를 바꾸지 않는 review를 수행해도 finding의 정확성이나 완전성이 보장되지는 않습니다.
수정 요청을 별도로 실행하면 현재 sandbox와 approval 설정이 적용됩니다. review와 수정 승인을 분리합니다.
플랜·지역·언어 제공 조건은 인용한 문서에서 별도로 확인되지 않았습니다. 현재 계정 UI와 조직 정책을 확인합니다.
결제·인증·권한·데이터 삭제처럼 영향이 큰 코드는 코드 소유자와 보안 담당자의 추가 검토를 거칩니다.

자주 묻는 질문

풀 리퀘스트 전체를 검토하려면 어떤 target이 맞나요?

현재 브랜치가 기준 브랜치에서 갈라진 뒤 누적한 전체 diff가 질문이면 --base 를 고릅니다. 실제 기준 브랜치와 merge base, 파일 목록을 먼저 확인하세요.

핫픽스 커밋 하나만 다시 보려면 무엇을 쓰나요?

지정한 SHA가 도입한 정확한 change set만 질문이면 --commit 을 고릅니다. git show 로 SHA와 파일 목록을 확인한 뒤 실행합니다.

--base와 --commit을 같은 명령에 넣어도 되나요?

안 됩니다. 공식 명령 레퍼런스는 두 옵션을 포함한 review target들이 서로 충돌한다고 설명합니다. 한 실행에는 하나만 선택하세요.

finding이 없으면 바로 병합해도 되나요?

아닙니다. finding 부재는 버그 부재의 증명이 아닙니다. 실제 diff, 저장소의 테스트·정적 검사·빌드와 코드 소유자 승인을 확인한 뒤 병합 여부를 결정합니다.

출처

마무리

Codex review target은 모델 순위가 아니라 검토 질문으로 고릅니다. 기준 브랜치 이후 쌓인 현재 브랜치의 누적 diff가 궁금하면 --base , 커밋 하나가 만든 정확한 change set이 궁금하면 --commit 을 선택합니다.

한 실행에 하나의 target만 사용하세요. 실제 diff와 검증 명령으로 finding을 대조하세요. 코드 소유자가 수정·commit·push·merge를 별도로 승인해야 코드 리뷰 범위 선택이 업무 기록으로 남습니다.

Codex review --base와 --commit 비교: 코드 리뷰 범위는 어떻게 고를까

Codex review --base와 --commit 비교: 코드 리뷰 범위는 어떻게 고를까

TL;DR

핵심 3줄 요약

이 글에서 다룰 내용

먼저 고를 것은 브랜치 누적인지 한 커밋인지입니다

선택 기준: --base인가 --commit인가

기준 브랜치 이후 전체 변경을 보면 --base

커밋 하나의 정확한 change set을 보면 --commit

시작 전 review target과 설치 표면을 확인하세요

실행 순서: 한 target만 골라 코드 리뷰 범위를 검증하세요

1단계. 검토 질문과 완료물을 한 문장으로 적습니다

2단계. Git에서 실제 입력 범위를 먼저 봅니다

3단계. 한 target으로 Codex review를 실행합니다

4단계. finding을 실제 코드와 대조합니다

5단계. 저장소가 정한 검증 명령을 실행합니다

6단계. 사람이 target과 다음 행동을 승인합니다

그대로 복사해 쓰는 선택형 프롬프트

검증 체크리스트

실무 인사이트: finding 수보다 범위 증거가 중요합니다

주의할 점

자주 묻는 질문

풀 리퀘스트 전체를 검토하려면 어떤 target이 맞나요?

핫픽스 커밋 하나만 다시 보려면 무엇을 쓰나요?

--base와 --commit을 같은 명령에 넣어도 되나요?

finding이 없으면 바로 병합해도 되나요?

출처

마무리

Related Posts