AI 코딩 덕분에 구현 속도가 점점 빨라지고 있습니다.
아마 많은 분들이 인간이 모든 구현을 리뷰하기에 역부족인 상태에 있을 겁니다.
이에 대한 한 가지 해결책으로, 이 글에서는 Codex 서브 에이전트에 리뷰 역할을 할당하고 중요한 문제가 사라질 때까지 수정과 재리뷰를 반복하는 자체 제작 스킬 codex-review의 최신 버전을 설명합니다.
실제로 6개월 전에 만든 스킬
사실 이 스킬의 기초는 약 6개월 전에 만들어졌습니다. 조금씩 개선해오면서 지금도 꾸준히 사용하고 있습니다.
https://x.com/makaneko_AI/status/2005475035075707092
이전 버전은 Claude Code가 구현을 맡고 Codex를 리뷰어로 호출해 수정과 재리뷰를 반복하는 방식으로 소개되었습니다. 당시에는 Claude Code가 구현 작업에 강했고, Codex는 단순히 "똑똑했기" 때문에 그런 구성이었습니다.
하지만 AI 환경이 완전히 바뀌었습니다. 이제 Codex는 구현에서 더 강력해졌고 더 똑똑해졌으며(Fable 5 제외), 많은 사람들이 Codex만으로 구현 작업을 완료하고 있을 가능성이 높습니다.
이러한 환경에 맞게, 이제는 Codex 내에서 루프가 실행되도록 내용을 새로 고쳤습니다.
최신 버전에서 변경된 세 가지 사항
기본적인 흐름은 이전 버전과 동일합니다.
구현 책임자와 리뷰 책임자를 분리한다 ↓ 리뷰어가 읽기 전용 모드로 확인한다 ↓ 중요한 문제가 제기되면 실패 ↓ 수정 ↓ 동일한 방식으로 재리뷰 ↓ 통과할 때까지 반복
최신 버전의 핵심 포인트는 다음 세 가지입니다.
1. GPT-5.5에 최적화
2. 중요한 문제에 집중
3. 전반적인 정확도 향상
하나씩 설명하겠습니다.
1. GPT-5.5에 최적화
2026년 6월 18일 기준, OpenAI의 최신 GPT-5.5 시리즈는 에이전트 기반 코딩과 실무 작업에 강한 모델로 자리 잡았습니다. 여러 단계의 모호한 작업도 자율적으로 진행할 수 있다고 설명됩니다.
공식 GPT-5.5 가이드를 보면 "세부 절차를 빼곡히 적기보다는 원하는 결과를 간결하게 작성하는 것이 더 잘 작동한다"고 나와 있습니다.
따라서 최신 버전에서는 세부 템플릿을 나열하는 것을 중단하고 리뷰어가 따라야 할 규칙을 강화했습니다.
https://x.com/makaneko_AI/status/2049848091860463995
2. 중요한 문제에 집중
Codex는 좋게 말하면 지능을 활용해 세세한 부분까지 지적하는 경향이 있었습니다.
그래서 최신 버전에서는 리뷰어에게 "P0/P1에 해당하는(최고/높은 우선순위) 문제만 골라내고 사소한 스타일 지적은 하지 말라"고 명시적으로 지시했습니다.
덕분에 불필요한 사소한 수정 반복이 줄어들어 원활하게 진행하기 쉬워졌습니다.
3. 전반적인 정확도 향상
전반적으로 작은 부분에서 정확도를 개선했습니다.
예를 들어, 리뷰가 중간에 중단되었음에도 통과로 표시되는 허점을 막았습니다. 리뷰어가 시작에 실패했거나 반환된 보고서가 손상되어 읽을 수 없는 경우 더 이상 통과로 처리되지 않습니다.
대규모 변경 사항이 여러 리뷰어에게 공유되더라도, 모두가 통과를 반환하고 미리뷰 또는 실패한 리뷰가 없을 때만 전체가 통과됩니다. 이러한 개선으로 리뷰 중 문제를 놓칠 위험이 줄어들었습니다.
권장 사용법
이 스킬은 사양 설계나 중대규모 구현 후에 자동으로 트리거되도록 지시되어 있지만, 사용자가 의도한 시점에 자동 시작하도록 설정하는 것을 권장합니다.
예를 들어, Codex가 항상 먼저 읽는 AGENTS.md 파일에 "...일 때 Codex 리뷰를 실행하세요"를 추가하세요. 또는 구현 계획 형식이 있다면 필수 단계로 포함시키세요.
이전 버전 해설 글에서도 이 부분을 설명하고 있습니다.
https://note.com/makaneko_ai/n/n3cefcec49e2d
스킬 "codex-review" 전문
규모 | 기준 | 전략 |
|---|---|---|
소형 | ≤3 파일, ≤100줄 | diff 1회 실행 |
중형 | 4-10개 파일, 100-500줄 | arch → diff 1회 실행 |
대형 | >10개 파일, >500줄 | arch → diff (병렬 여러 번 실행) → 교차 검증 |
{
"ok": false,
"summary": "리뷰 요약",
"issues": [
{
"file": "src/auth.py",
"lines": "42-45",
"problem": "문제 설명",
"recommendation": "수정 계획",
"verification": "수정 후 검증 방법"
}
],
"notes_for_next_review": "참고 사항"
}
``text
## 수정 루프
ok=false이면 max_iters 횟수만큼 반복합니다. 기본값은 max_iters=5입니다.
1. issues를 분석하여 수정 계획을 수립합니다.
2. 구현자가 최소 diff로 수정합니다(사양 변경은 미해결 이슈로 남깁니다).
3. 변경 위험에 따라 테스트, 린터 또는 대체 검증을 실행합니다. 실행하지 않은 경우 그 이유를 남기고, 중요 경로에서 검증되지 않으면 차단으로 처리합니다.
4. 동일한 모드로 재리뷰합니다.
중단 조건:
- ok=true: 게이트 통과
- max_iters 도달: 게이트 실패
- 테스트가 연속으로 두 번 실패: 게이트 실패
- 리뷰어 실패 / JSON 파싱 실패 / 출력 형식 결함 / 미리뷰 영역 존재: 게이트 실패
게이트 실패로 중단 시, 최종 보고서에 남은 차단 항목, 미리뷰 영역 및 실패한 검증을 미해결로 출력합니다.
## /review 폴백
JSON 게이트가 실패한 경우에만 /review를 사용합니다. /review는 발견 지원 도구이며, 그 출력을 그대로 ok=true의 근거로 사용해서는 안 됩니다.
## 오류 규칙
- 리뷰어 설정에 실패한 경우, 실패 이유, 시도한 리뷰어 경로 및 미리뷰 범위를 최종 보고서에 기록합니다.
- 리뷰어의 읽기 전용 제약을 완화하지 않습니다.
- 입력 과다 또는 타임아웃 발생 시, 범위를 줄이거나 분할하여 재시도할 수 있습니다.
## 최종 보고서 예시
이는 포괄적인 템플릿이 아닌, 미리뷰 영역이 남아 있는 경우의 예시입니다.
``text
Codex Review 결과
- mode: JSON 게이트 또는 /review
- review_scope: 브랜치 diff
- 규모: 대형 (12개 파일, 620줄)
- 병렬 처리: 3개 서브 에이전트
- 리뷰어 경로: 먼저 spawn_agent
- 폴백 증거: 없음
- 반복: 2/5
- 리뷰 게이트: ok=false
- 이유: unreviewed_scope가 비어 있지 않음
- 완료 증거: push/merge/release/작업 완료 등은 별도로 확인됨
수정 내역
- auth.py: 인증 확인 추가
미리뷰
- utils/legacy.py: Codex 타임아웃, 재리뷰 필요
미해결
- main.py: 내용, 위험, 권장 조치 ``` # 요약 codex-review 스킬의 최신 버전은 단순히 이전 버전을 Codex 내에서 실행하도록 만든 것이 아닙니다. 현재의 Codex와 GPT-5.5에 맞춰 불필요한 단계를 제거하고, 리뷰 게이트로서 따라야 할 규칙을 명확히 했습니다. 스스로 리뷰하고 수정해주는 메커니즘은 매우 편리하니, 도입해 보시길 권장합니다. --- 이 글이 도움이 되셨다면 팔로우와 공유를 부탁드립니다. AI를 단순히 사용하는 것이 아니라, AI가 자율적으로 작동하게 하는 방법을 계속 공유하고 있습니다. 관련 게시물 https://x.com/makaneko_AI/status/2058739339606233492 https://x.com/reach_vb/status/2058538305872949490 https://x.com/makaneko_AI/status/2064299466182607161
