Codex CLI 코드 리뷰 사용법: codex review --uncommitted로 커밋 전 변경을 점검하는 법
TL;DR
codex review --uncommitted
는 Git 저장소의 staged·unstaged·untracked 변경을 전용 reviewer에게 맡기는 비대화형 명령입니다. Codex는 선택한 diff를 읽고 우선순위가 있는 실행 가능한 발견 사항을 보고하지만 working tree는 바꾸지 않습니다.
리뷰 통과가 곧 코드 승인은 아닙니다. 실행 전 변경 범위를 확인합니다. 각 finding을 실제 코드와 대조하고 프로젝트 테스트를 통과한 뒤 사람이 커밋 여부를 정해야 합니다.
핵심 3줄 요약
git status --short
와 diff로 리뷰 대상이 이번 작업만 포함하는지 먼저 확인합니다.codex review --uncommitted
로 staged·unstaged·untracked 변경을 한 번에 검토합니다.발견 사항마다 코드 근거와 재현 조건을 확인하고 테스트를 통과한 변경만 사람이 커밋합니다.
이 글에서 다룰 내용
Codex CLI 코드 리뷰의 한 문장 정의,
--uncommitted
가 읽는 범위, 한 번에 하나만 고르는 review target, 커밋 전 여섯 단계, 결과 검증용 프롬프트, 오탐과 자동 수정 주의점을 다룹니다.
Codex CLI 코드 리뷰는 무엇이고 언제 쓰면 좋은가
Codex CLI 코드 리뷰는 선택한 Git diff를 전용 reviewer가 읽고 우선순위가 있는 실행 가능한 발견 사항을 보고하는 기능입니다.
기능을 고친 뒤 diff가 여러 파일에 흩어지면 조건 누락이나 예상 밖의 영향 범위를 놓치기 쉽습니다. 커밋 직전 working tree를 한 묶음으로 다시 볼 때 이 흐름이 잘 맞습니다.
Codex CLI 코드 리뷰는 uncommitted changes, base branch diff, 특정 commit 또는 custom review instructions 중 하나를 골라 전용 reviewer에게 맡기는 기능입니다. 이 글에서는 아직 커밋하지 않은 현재 변경을 점검하는
codex review --uncommitted
만 사용합니다.
OpenAI 공식 문서에 따르면 전용 reviewer는 선택한 diff를 읽고 우선순위가 있는 실행 가능한 finding을 보고하며 working tree를 수정하지 않습니다. 산출물은 자동 수정된 코드가 아니라 사람이 확인할 검토 목록입니다.
시작 전에 확인할 조건과 기능 경계
작업 폴더는 Git 저장소여야 합니다. 대화형 CLI의
/review
preset도 열린 프로젝트가 Git 저장소 안에 있을 때 나타납니다. 현재 설치된 Codex CLI와 계정에서 명령이 보이는지 확인하세요. 인용한 공식 문서는 별도 플랜·지역·언어 조건을 명시하지 않습니다.
codex review
에는
--uncommitted
,
--base
,
--commit
과 custom prompt가 있습니다. 공식 명령 레퍼런스는 이 대상들이 서로 충돌한다고 설명합니다. 한 번 실행할 때 review target은 정확히 하나만 선택해야 합니다.
--uncommitted
는 staged, unstaged, untracked 변경을 모두 포함합니다.
.gitignore
로 제외된 파일까지 검토한다고 확대 해석하지 마세요. 실행 전
git status --short
에서 실제 입력 범위를 확인합니다.
이 명령은 working tree를 바꾸지 않지만 리뷰 결과까지 정확하다고 보장하지는 않습니다. 수정 적용, stage, commit, push는 검증을 마친 뒤 별도 단계에서 사람이 결정합니다.
codex review --uncommitted로 커밋 전 변경을 점검하는 순서
1. 저장소와 현재 브랜치를 확인합니다
프로젝트 루트에서 다음 명령으로 현재 범위를 봅니다.
git status --short
git branch --show-current
예상하지 못한 파일이나 다른 작업의 변경이 섞여 있다면 여기서 멈춥니다. 리뷰 전에 작업을 분리하거나 불필요한 변경을 되돌릴지 사람이 판단합니다.
2. diff의 크기와 내용을 먼저 읽습니다
git diff --stat
git diff
git diff --cached
git diff
는 unstaged 변경을,
git diff --cached
는 staged 변경을 확인하는 데 씁니다.
git status --short
에 나온 untracked 파일도 빠짐없이 확인해 이번 리뷰의 입력 목록을 정합니다.
3. --uncommitted review를 실행합니다
codex review --uncommitted
이 명령은 staged·unstaged·untracked 변경을 대상으로 비대화형 리뷰를 실행합니다. custom prompt나
--base
,
--commit
을 같은 실행에 덧붙이지 않습니다.
4. finding을 코드 근거와 대조합니다
각 finding에서 파일 경로, 관련 코드, 실패 조건, 영향 범위를 찾습니다. 설명이 추상적이면 실제 호출부와 테스트를 직접 엽니다. 근거가 확인되지 않은 항목은 바로 수정하지 말고
확인 필요
로 남깁니다.
5. 수정한 뒤 프로젝트 검증 명령을 실행합니다
저장소가 정한 테스트, lint, type check, build 명령을 실행합니다. 명령 이름을 추정하지 말고
README
, 패키지 스크립트, CI 설정에 기록된 실제 명령을 사용합니다.
리뷰 전에 이미 실패한 검사가 있었다면 이번 변경에서 생긴 실패와 구분해 기록합니다. 테스트 통과는 finding 하나를 닫는 근거이지 다른 위험까지 자동으로 없애지는 않습니다.
6. 다시 리뷰하고 사람이 커밋을 승인합니다
수정 뒤
git status --short
와 diff를 다시 보고
codex review --uncommitted
를 한 번 더 실행합니다. 새 finding이 없는지, 기존 finding이 실제로 해결됐는지 확인합니다.
완료 기록에는 검토한 파일, 수용·기각·보류한 finding, 실행한 검증 명령과 결과를 남깁니다. 코드 소유자가 이 기록을 보고 stage와 commit 여부를 승인하면 흐름이 끝납니다.
그대로 복사해 쓸 프롬프트
허용 입력: 현재 Git 저장소의 git status --short, git diff, git diff --cached, Codex review 결과, 저장소의 README·테스트·CI 설정, 사용자가 지정한 변경 목적.
제외 입력: 저장소 밖 파일, 연결하지 않은 서비스, 비밀값, 운영 데이터, 이번 변경과 무관한 리팩터링, 사용자가 승인하지 않은 외부 전송.
출력 형식: finding별로 1) 우선순위 2) 파일과 코드 근거 3) 재현 또는 검증 방법 4) 수용·기각·확인 필요 상태 5) 필요한 최소 수정 6) 실행할 검증 명령을 적는다.
완료 기준: 모든 finding에 상태와 근거가 있다. 변경 파일 목록과 review 대상이 일치한다. 저장소에 실제로 정의된 테스트·lint·type check·build 결과가 기록돼 있다.
추정 금지: 존재하지 않는 파일·함수·테스트 명령·실행 결과를 만들지 않는다. 근거를 찾지 못하면 확인 필요로 표시한다. 코드 수정, stage, commit, push를 자동 실행하지 않는다.
승인 지점: 먼저 검토 목록만 보여 준다. 사용자가 finding별 판단을 승인한 뒤 최소 수정안을 제안한다. 테스트 결과와 최종 diff를 사람이 확인한 뒤에만 commit을 승인한다.
아래 프롬프트는
codex review --uncommitted
에 이어 붙이지 않습니다. 공식 레퍼런스상
--uncommitted
와 custom prompt는 충돌하므로, review 결과를 받은 뒤 별도 대화형 세션에서 finding을 검증할 때 사용합니다.
실전 활용 팁
finding을 수용·기각·보류로 나눠 기록하면 재검토가 빨라집니다. 수용 항목에는 수정 commit 또는 diff 근거를, 기각 항목에는 오탐으로 판단한 코드 경로를 남깁니다. 보류 항목은 담당자와 확인할 조건을 적습니다.
처음에는 한 기능이나 한 버그 수정처럼 작은 diff에 적용하세요. 의존성 업데이트, 대규모 리팩터링, 생성 파일이 한꺼번에 섞이면 finding의 원인과 우선순위를 확인하기 어렵습니다.
지적 범위가 너무 넓으면 별도 대화형 세션에서 근거를 요청하거나 범위를 좁혀 다시 검토합니다. 다만 수정 명령을 실행하기 전에는 현재 권한과 writable root를 다시 확인합니다.
주의할 점
-
--uncommitted는 staged·unstaged·untracked 변경을 검토합니다. 다른 작업의 파일이 섞였는지 먼저 확인합니다. -
--uncommitted,--base,--commit, custom prompt를 한 실행에서 함께 쓰지 않습니다. - Codex가 finding을 보고하지 않았다고 해서 버그가 없다고 결론 내리지 않습니다.
- working tree 비수정은 안전한 출력 형식을 뜻할 뿐, finding의 정확성이나 테스트 통과를 보장하지 않습니다.
- 비밀값, 개인정보, 운영 데이터가 diff에 들어갔다면 리뷰보다 먼저 노출 범위와 저장소 이력을 점검합니다.
- 결제·인증·권한·데이터 삭제처럼 영향이 큰 변경은 코드 소유자와 보안 담당자의 별도 검토를 거칩니다.
- stage, commit, push는 자동 완료 조건에서 제외하고 사람이 최종 승인합니다.
자주 묻는 질문
--uncommitted는 어떤 변경을 검토하나요?
공식 명령 레퍼런스에 따르면 staged, unstaged, untracked 변경을 검토합니다. 실행 전
git status --short
로 실제 파일 목록을 확인하세요.
/review와 codex review --uncommitted는 같은 명령인가요?
둘 다 Codex 코드 리뷰 기능에 들어가지만 진입 방식이 다릅니다. 대화형 CLI의
/review
는 preset을 엽니다.
codex review --uncommitted
는 현재 uncommitted changes를 대상으로 비대화형 리뷰를 실행합니다.
custom review instructions를 --uncommitted 뒤에 붙여도 되나요?
안 됩니다. 공식 레퍼런스는
--uncommitted
,
--base
,
--commit
, custom prompt가 서로 충돌한다고 명시합니다. 대상 review 또는 custom instructions 가운데 하나만 선택하세요.
리뷰 결과가 없으면 바로 커밋해도 되나요?
아닙니다. 최종 diff와 테스트·lint·type check·build 결과부터 확인합니다. 영향이 큰 변경은 코드 소유자나 보안 담당자의 검토를 거친 뒤 사람이 커밋을 승인합니다.
출처
OpenAI 공식 문서: Code review
OpenAI 공식 문서: Codex CLI developer commands
OpenAI 공식 문서: Codex CLI overview
마무리
codex review --uncommitted
는 커밋 전에 working tree를 한 번 더 읽는 검토 단계입니다. staged·unstaged·untracked 범위를 확인하고 실행하면, 사람이 놓친 변경을 점검할 후보 목록을 얻을 수 있습니다.
검토의 끝은 AI 응답이 아니라 근거 확인입니다. finding을 실제 코드와 대조하고 저장소의 검증 명령을 실행한 뒤 사람이 commit 여부를 승인해야 하나의 업무 결과로 마무리됩니다.
