Codex Git Hook 통합 PRD
배경 (Background)
현재 Git 훅(pre-push, pr-review.sh)은 claude -p + code-reviewer 에이전트를 단일 AI 백엔드로 사용한다.
두 가지 문제가 있다:
- commit-msg 훅 부재: 커밋 메시지를 수동 작성하므로 컨벤션(
[STK-XX] - type : 제목) 이탈이 잦다. - Claude 단일 장애점:
claude -p호출이 토큰 한도 초과·네트워크 오류·rate limit으로 실패하면 훅 전체가 실패하고 push/PR 생성이 차단된다.
Codex CLI(codex 0.141.0)가 로컬에 설치·복구됐으므로 이를 활용해 두 문제를 해결한다.
요구사항
| ID | 요구사항 | 우선순위 |
|---|---|---|
| R-01 | staged diff를 Codex에 전달해 커밋 메시지를 자동 생성한다 | 높음 |
| R-02 | 생성된 커밋 메시지는 [no-jira] 또는 [STK-XX] + PR 가이드 컨벤션을 따른다 | 높음 |
| R-03 | 사용자가 커밋 메시지를 이미 작성한 경우 Codex가 덮어쓰지 않는다 | 높음 |
| R-04 | Codex 실패 시 commit-msg 훅을 차단하지 않고 fallthrough한다 | 높음 |
| R-05 | pre-push에서 claude -p 실패 시 Codex로 동일 리뷰를 재시도한다 | 높음 |
| R-06 | Codex 리뷰도 REQUEST_CHANGES 패턴을 동일하게 검사해 push를 차단한다 | 높음 |
| R-07 | pre-push에서 Claude·Codex 모두 실패하면 경고 출력 후 push를 허용한다 | 높음 |
| R-08 | pr-review.sh에 R-05~R-07과 동일한 fallback 전략을 적용한다 | 높음 |
| R-09 | Codex 호출은 -q (quiet) 모드로 실행한다 | 중간 |
| R-10 | 토큰 한도 감지는 Claude 출력에 context length, token limit, rate limit 문자열 포함 여부로 판단한다 | 중간 |
| R-11 | 기존 훅 동작(테스트 실행·main 차단)은 변경하지 않는다 | 높음 |
사용자 시나리오
시나리오 1 — 커밋 메시지 자동 생성
개발자가 git commit을 실행하면 commit-msg 훅이 staged diff를 Codex에 전달해 컨벤션에 맞는 커밋 메시지를 자동으로 작성한다. 메시지를 직접 입력한 경우(-m 플래그)에는 덮어쓰지 않는다.
시나리오 2 — AI 리뷰 이중화
개발자가 git push를 실행하면 Claude code-reviewer가 1차 리뷰를 수행한다. Claude가 토큰 한도·네트워크 오류로 실패하면 Codex가 동일 diff를 재리뷰한다. 두 AI 모두 실패하면 경고만 출력하고 push를 허용해 개발 흐름이 차단되지 않는다.
완료 기준
git commit시 commit-msg 훅이 Codex로 메시지를 생성한다.git push시 Claude 실패 → Codex fallback → 성공/실패 순서로 동작한다.gh pr create시 동일 fallback이 작동한다.
범위 외
- Claude CLI 자체의 성능 개선 또는 교체
- Codex 이외 제3의 AI 백엔드 추가
- Git 훅 이외 CI/CD 파이프라인에서의 AI 리뷰