dpdpdndn 블로그

Codex Git Hook 통합 TDD

NEW5 min read

Codex Git Hook 통합 TDD

Background

Git 훅에 Codex CLI를 통합해 커밋 메시지 자동화와 AI 리뷰 이중화를 달성한다.

Overview

  • 신규: commit-msg 훅 — Codex가 staged diff로 커밋 메시지 자동 생성
  • 수정: pre-push, pr-review.sh — Claude 실패 시 Codex fallback 추가

Terminology

용어설명
CodexOpenAI Codex CLI (/opt/homebrew/bin/codex)
ClaudeAnthropic Claude Code CLI (claude -p)
fallback1차 AI 실패 시 2차 AI로 재시도하는 패턴
commit-msg커밋 메시지를 수정할 수 있는 Git 훅 단계
REQUEST_CHANGEScode-reviewer 에이전트가 출력하는 차단 verdict

Define Problem

AS-IS

commit → pre-commit(main 차단)
push   → pre-push(테스트 → claude code-reviewer → 차단/허용)
pr     → pr-review.sh(claude code-reviewer → 차단/허용)

문제:

  1. commit-msg 단계 없음 → 컨벤션 이탈 커밋 메시지
  2. claude 단일 장애점 → 토큰 한도/장애 시 push·PR 전체 차단

TO-BE

commit → pre-commit(main 차단)
       → commit-msg(Codex 메시지 생성, 실패 시 pass)

push   → pre-push(테스트 → claude code-reviewer
                         → [실패 시] codex review
                         → [둘 다 실패] 경고 후 허용)

pr     → pr-review.sh(claude code-reviewer
                     → [실패 시] codex review
                     → [둘 다 실패] 경고 후 허용)

Possible Solutions

Fallback 전략 비교

방안설명왜 채택미채택
Claude → Codex 순차 fallback1차 Claude, 실패 시 Codex단순, 기존 훅 최소 수정—
Claude + Codex 병렬 실행둘 다 동시 실행, 먼저 완료된 결과 사용—비용·시간 낭비, 복잡도 증가
Codex 단독 교체Claude 제거—기존 code-reviewer 에이전트 못 활용

commit-msg 생성 전략

방안설명왜 채택미채택
staged diff → Codex -qgit diff --cached 파이프간단, 빠름—
Claude commit-msgclaude -p 호출—상대적으로 느리고 비쌈

Detail Design

Component Diagram

flowchart LR
    subgraph Git["Git Hooks"]
        CM[commit-msg]
        PP[pre-push]
        PR[pr-review.sh]
    end
    subgraph AI["AI 백엔드"]
        CL[Claude code-reviewer]
        CO[Codex CLI]
    end
    CM -->|diff| CO
    PP -->|1차| CL
    PP -->|fallback| CO
    PR -->|1차| CL
    PR -->|fallback| CO

fallback 함수 (공통 셸 로직)

pre-push와 pr-review.sh에 동일하게 적용:

run_claude_review() {
  local branch="$1" base="$2"
  claude \
    --agent code-reviewer \
    --allowedTools "Read" "Grep" "Glob" "Bash(git *)" "Bash(cat *)" \
    --add-dir "$REPO_ROOT" \
    -p "브랜치 '$branch' (base: $base) 변경사항을 리뷰해줘. git diff $base...HEAD로 확인하고 code-review-criteria.md 기준 터미널 출력 형식으로 결과를 보여줘." \
    2>/dev/null
}
 
run_codex_review() {
  local branch="$1" base="$2"
  git diff "$base"..."$branch" | codex -q \
    "아래 git diff를 code-review-criteria.md 기준(p0~p2 위반 시 'REQUEST_CHANGES' verdict 포함)으로 리뷰해줘. 터미널 출력 형식으로 결과를 출력해줘."
}
 
is_claude_token_error() {
  echo "$1" | grep -qiE "context length|token limit|rate limit|maximum context"
}

commit-msg 훅 로직

1. $1 파일(커밋 메시지 파일) 내용이 비어있지 않으면(사용자 직접 입력) exit 0
2. git diff --cached 로 staged diff 획득
3. diff가 비어있으면 exit 0 (빈 커밋)
4. codex -q 로 커밋 메시지 생성
5. 생성 성공 시 $1 파일에 기록
6. 실패 시 경고만 출력하고 exit 0 (차단 안 함)

토큰 한도 감지

Claude 출력에 다음 패턴 중 하나라도 포함 시 fallback 트리거:

  • context length
  • token limit
  • rate limit
  • maximum context
  • 출력이 완전히 비어있는 경우

Testing Plan

  • staged diff가 있고 메시지 파일이 비어있으면 Codex가 커밋 메시지를 생성해 파일에 기록한다
  • git commit -m "수동" 시 기존 메시지를 Codex가 덮어쓰지 않는다
  • Claude 실패(빈 출력 또는 토큰 한도 감지) 시 Codex fallback이 호출된다
  • Codex fallback에서 REQUEST_CHANGES 감지 시 push/PR 생성이 차단된다
  • Claude·Codex 둘 다 실패 시 경고 출력 후 push/PR 생성이 허용된다

Release Scenario

  1. .githooks/commit-msg 신규 생성 → chmod +x
  2. .githooks/pre-push 수정 (fallback 로직 추가)
  3. .githooks/pr-review.sh 수정 (fallback 로직 추가)
  4. 수동 smoke test (커밋 → push → PR 생성 순서)
  5. 롤백: 각 훅 파일 git revert (훅 파일은 레포에 포함)

Project Information

  • 담당: biuea
  • 의존 과제: 없음 (독립)

그래프 뷰