
프론트엔드와 모바일을 오래 해왔고, 지금은 퇴근 후 시간을 쪼개 개인 프로젝트를 굴리고 있습니다. 요즘 손에 붙은 건 LifeTrack과 MyBrainOS 두 개인데, 둘 다 기획부터 배포까지 혼자 해야 하는 물건입니다.
혼자 하면 코드를 짜는 시간보다 "이거 이대로 둬도 되나"를 확인하는 시간이 더 아깝습니다. 예전에는 그 확인을 사람에게 부탁했고, 그게 안 되면 그냥 넘겼습니다. 지금은 확인을 AI에게 시키는데, 구현한 AI와 리뷰하는 AI를 일부러 다르게 씁니다. 구현은 Claude Code, 리뷰는 Codex입니다.
이 글은 그 조합을 실제로 어떻게 굴리는지, 순서대로 쓴 기록입니다. 프롬프트는 그대로 복사해 쓸 수 있는 형태로 붙였습니다.
왜 구현과 리뷰를 다른 AI로 나눴나
처음에는 Claude Code 하나로 다 했습니다. 짜고, 같은 세션에서 "이 코드 리뷰해줘"라고 했습니다. 그런데 이 방식은 생각보다 구멍이 큽니다.
같은 모델, 같은 대화 맥락에서 리뷰를 시키면 자기가 방금 내린 판단을 다시 확인하는 셈이 됩니다. 방금 "이 구조로 가겠습니다"라고 정한 이유가 대화에 그대로 남아 있으니, 리뷰할 때도 그 전제를 의심하지 않습니다. 파일을 잘못 읽은 채로 리뷰를 하면 같은 파일을 같은 방식으로 잘못 읽고, 놓친 예외를 또 놓칩니다.
모델을 바꾸면 이 고리가 끊깁니다. Codex는 제 대화 기록을 모르는 상태에서 코드와 diff만 봅니다. 그래서 "왜 이렇게 짰는지"를 설명하지 않고 넘긴 부분을 정확히 찌릅니다. 실제로 리뷰에서 걸리는 건 실력 문제가 아니라 설명하지 않고 넘어간 맥락인 경우가 많았습니다.
물론 두 모델을 쓰면 비용과 시간이 두 배로 듭니다. 그래서 아무 코드나 다 리뷰에 올리지는 않고, 뒤에 나오는 기준으로 걸러서 올립니다.
이 워크플로우의 전체 그림

한 바퀴 도는 순서
1. 자르기 — 사람이 한다. 한 번에 리뷰 가능한 크기로 작업을 쪼갠다.
2. 구현 — Claude Code. 계획 모드로 방향을 확인한 뒤 실제로 고친다.
3. 리뷰 — Codex. 커밋 전 워킹트리 상태에서 돌린다.
4. 처리 — 사람이 한다. 지적을 등급으로 나눠 반영할 것만 반영한다.
5. 검증·커밋 — 타입 체크·테스트·린트를 돌리고 커밋한다.
중요한 건 3번과 4번 사이입니다. 리뷰 결과를 그대로 Claude Code에 붙여넣고 "다 고쳐"라고 하면 안 됩니다. 그러면 리뷰어가 제안한 수정을 구현자가 검증 없이 적용하고, 판단은 다시 사람에게 돌아옵니다. 이 부분은 아래에서 따로 길게 씁니다.
단계별로 남기는 것
| 단계 | 하는 일 | 도구 | 끝나고 남아 있어야 하는 것 |
| 1. 자르기 | 작업을 한 커밋 크기로 분해 | 사람(에디터) | 한 줄짜리 작업 정의 |
| 2. 구현 | 계획 확인 후 코드 수정 | Claude Code | 계획 요약 + 변경된 파일 목록 |
| 3. 리뷰 | diff 기준 결함 지적 | Codex | 지적 목록(등급 포함) |
| 4. 처리 | 반영/보류 판단 | 사람 | 보류한 지적과 그 이유 |
| 5. 검증 | 타입, 테스트, 린트 | 터미널 | 통과 로그 + 커밋 |
이 표에서 "남아 있어야 하는 것"이 핵심입니다. AI 작업은 대화가 닫히면 근거가 같이 사라집니다. 그래서 각 단계마다 다음 단계가 읽을 수 있는 형태로 한 줄씩 남기는 습관을 들였습니다.
준비: 두 도구에게 같은 규칙을 읽히기
CLAUDE.md와 AGENTS.md
두 도구는 각자 읽는 지침 파일 이름이 다릅니다. Claude Code는 CLAUDE.md, Codex는 AGENTS.md를 프로젝트 루트에서 찾습니다. 둘 다 "매 세션 시작할 때 자동으로 읽는 마크다운 파일"이라는 성격은 같습니다.
| 항목 | CLAUDE.md | AGENTS.md |
| 읽는 도구 | Claude Code | Codex |
| 위치 | 프로젝트 루트(하위 폴더에도 가능) | 프로젝트 루트 |
| 로드 시점 | 세션 시작 시 자동 | 세션 시작 시 자동 |
| 주 용도 | 코딩 규칙, 빌드, 테스트 명령, 금지 사항 | 같은 내용 + 리뷰 정책 |
| 이 글에서의 역할 | 구현자가 지킬 규칙 | 리뷰어가 판단할 기준 |
두 파일을 따로 관리하면 반드시 갈라집니다. Codex에는 Claude Code 쪽 설정을 가져오는 /import가 있지만, 한 번 가져온 다음부터는 각자 고치면서 다시 어긋납니다. 그래서 규칙 본문은 한 곳에만 두고, 나머지 한쪽은 그걸 가리키게 하는 편이 오래 갑니다.
<!-- AGENTS.md -->
프로젝트 규칙은 CLAUDE.md를 따른다.
리뷰 정책은 아래를 따른다.
- 동작 변경이 있는데 테스트가 없으면 지적한다.
- 스타일 취향은 지적하지 않는다.
<!-- CLAUDE.md (앞부분) -->
## 스택
Next.js + TypeScript. 패키지 매니저는 pnpm 고정.
## 검증 명령
- 타입: pnpm tsc --noEmit
- 린트: pnpm lint
- 테스트: pnpm test
커밋 전에 위 세 개를 순서대로 돌린다.
## 금지
- any 타입으로 오류 회피하지 않는다.
- 설정 파일(.env, next.config)은 물어보고 고친다.
규칙을 쓸 때 제일 효과가 컸던 건 검증 명령을 양쪽에 똑같이 적는 것입니다. 구현자와 리뷰어가 같은 기준으로 코드를 보게 되고, "테스트를 돌려보지 않은 리뷰"가 줄어듭니다.
1단계: 작업을 자르기 (사람이 하는 일)
AI에게 일을 맡길 때 결과가 나빠지는 가장 흔한 이유는 모델 성능이 아니라 요청 크기입니다. "대시보드 만들어줘"는 리뷰도 검증도 불가능한 요청입니다. 제 기준으로 diff가 500줄을 넘어가면, 진짜 결함과 구조 이야기가 뒤섞여서 지적의 신뢰도가 떨어집니다.
그래서 시작 전에 작업을 이렇게 쪼갭니다.
· 한 번에 파일 5개 이내, diff 한 화면에서 두세 번 스크롤 정도
· 한 덩어리마다 검증 가능한 문장 하나가 붙어야 함 ("저장 후 새로고침해도 값이 남는다")
· 스키마 변경과 화면 변경은 다른 덩어리로 분리 (섞으면 리뷰에서 원인 추적이 안 됩니다)
이건 AI에게 시키는 게 아니라 제가 하는 일입니다. 여기를 대충 하면 뒤의 모든 단계가 무너집니다.
2단계: Claude Code로 구현
계획 모드로 먼저 방향 확인
터미널에서 claude로 세션을 열고, 바로 코드를 고치게 하지 않습니다. 먼저 계획 모드로 들어갑니다. 파일을 읽고 분석만 하고, 편집은 하지 않는 읽기 전용 모드입니다. Shift+Tab으로 모드를 순환하거나 /plan으로 바로 진입할 수 있습니다.
계획을 받으면 세 가지만 확인합니다.
1. 고치겠다고 한 파일이 내가 예상한 파일인가 — 엉뚱한 파일을 건드리려 하면 여기서 잡힙니다.
2. 검증 방법을 계획에 넣었는가 — "테스트는 어떻게 확인할 건가"가 계획에 없으면 그대로 실행해도 확인을 안 합니다.
3. 기존 코드를 재사용하는가, 새로 만드는가 — 새로 만드는 쪽으로 흘러가면 계획 단계에서 되돌립니다.
여기서 방향이 맞으면 계획을 승인하고 구현으로 넘깁니다.
구현 프롬프트 템플릿
제가 반복해서 쓰는 형태입니다. 그대로 복사해서 프로젝트에 맞게 고치시면 됩니다.
작업: [한 문장으로 된 작업 정의]
범위: [건드려도 되는 파일/폴더]
금지: [건드리면 안 되는 것 - 설정 파일, 마이그레이션, 공용 컴포넌트 등]
끝났다고 말하기 전에 아래를 직접 확인해줘.
1. pnpm tsc --noEmit
2. pnpm lint
3. pnpm test
확인 결과를 그대로 붙여줘. 실패했으면 실패했다고 말하고, 통과했다고
추측해서 쓰지 마. 확인하지 못한 항목은 "미검증"이라고 따로 적어줘.
마지막 세 줄이 이 템플릿의 핵심입니다. AI는 확인하지 않은 것도 확인한 것처럼 매끄럽게 씁니다. 그래서 확인한 것 / 추측한 것 / 못 한 것을 분리해서 쓰라고 요구하면, 제가 다시 검증할 대상이 명확해집니다.
권한과 승인
Claude Code는 기본적으로 컴퓨터에 영향을 주는 작업 전에 승인을 요청합니다. 승인 모드를 다루는 방식은 사람마다 다른데, 제 기준은 이렇습니다.
· 파일 편집: 프로젝트 안에서만 자동 승인
· 셸 명령: 승인 요청 유지 (rm, git reset, 배포 명령이 여기로 들어옵니다)
· 프로젝트 밖 경로·설정 파일: 항상 확인
편해 보인다고 셸까지 전부 자동 승인으로 열어두면, 되돌릴 수 없는 명령이 검토 없이 지나갑니다. 1인 개발에서는 되돌릴 사람이 저밖에 없어서, 이 선은 안 열었습니다.
긴 작업은 /clear로 세션을 정리하고 새로 시작합니다. 한 세션에 여러 작업을 쌓으면 앞 작업의 맥락이 뒤 작업 판단에 섞입니다. /compact는 대화를 요약해 공간을 확보하는 명령인데, 요약되면 세부가 사라지므로 리뷰 직전에는 요약보다 새 세션을 씁니다.
3단계: Codex로 리뷰
세 가지 리뷰 경로
같은 리뷰를 상황에 따라 세 가지 방식으로 돌립니다.
| 방식 | 명령 | 언제 쓰나 | 특징 |
| 대화형 리뷰 | codex 실행 후 /review | 앉아서 결과를 읽으며 바로 질문하고 싶을 때 | 지적 목록을 보며 /diff로 실제 변경 확인 가능 |
| 비대화형 리뷰 | codex review --uncommitted | 결과를 파일로 남기고 싶을 때 | 대화 없이 한 번 리뷰하고 종료 |
| 기준점 지정 리뷰 | codex review --base main | 브랜치 전체를 한 번에 볼 때 | 베이스 브랜치 대비 diff |
--uncommitted는 아직 커밋하지 않은 변경을, --base는 지정한 브랜치와 비교한 변경을, --commit은 특정 커밋 하나를 리뷰합니다. 이 세 가지와 자유 프롬프트는 한 번에 하나만 쓸 수 있습니다. 리뷰 지시를 매번 다르게 주고 싶으면 지시를 AGENTS.md에 넣어두는 쪽이 안정적입니다.
결과를 남길 때는 이렇게 씁니다.
# 커밋 전 워킹트리 리뷰를 파일로 남기기
codex review --uncommitted > review-$(date +%Y%m%d-%H%M).md 2>&1
파일로 남기는 이유는 두 가지입니다. 첫째, 고친 뒤에 "무엇을 지적받았고 무엇을 반영했는지"를 나중에 대조할 수 있습니다. 둘째, 리뷰 결과를 그대로 Claude Code 세션에 붙여넣을 때 지적 번호를 붙여서 넘길 수 있습니다.
리뷰 요청 시 같이 주는 정보
Codex는 제 대화를 모릅니다. 그래서 리뷰 품질은 얼마나 맥락을 붙여주느냐에 달려 있습니다. 프롬프트를 따로 줄 때는 이 네 줄을 꼭 넣습니다.
이번 변경의 의도: [한 문장]
의도적으로 하지 않은 것: [예: 이번엔 에러 UI를 안 만든다]
확인해야 할 위험: [예: 기존 저장 포맷과의 호환]
리뷰하지 말 것: [예: 네이밍, 포매팅, 주석 유무]
세 번째 줄이 특히 중요합니다. "확인해야 할 위험"을 알려주지 않으면 리뷰어는 일반론을 늘어놓습니다. 네 번째 줄을 빼면 지적의 절반이 취향 이야기로 채워집니다.
권한은 리뷰어에게 최소로
codex review는 대화를 열지 않고 한 번 리뷰하고 끝납니다. 리뷰는 읽고 지적하는 일이니, 리뷰어에게 코드를 고칠 권한을 줄 이유가 없습니다. 세션 중 권한을 조정해야 하면 /permissions로 바꿀 수 있지만, 리뷰 세션에서는 그대로 두는 편이 안전합니다.
리뷰를 스크립트나 반복 루틴에 묶을 때는 codex exec를 씁니다. --json을 붙이면 진행 상황이 줄 단위 이벤트로 나오고, -o(또는 --output-last-message)로 최종 메시지만 파일에 받을 수 있어서 결과를 쌓아두기 좋습니다.
4단계: 리뷰 결과 처리
여기가 이 워크플로우에서 제일 손이 많이 가는 곳입니다. 리뷰 결과를 그대로 넘기면 안 되는 이유는, AI 리뷰어도 틀리기 때문입니다. 없는 문제를 있다고 하거나, 코드 맥락을 몰라서 정상 동작을 결함으로 분류합니다.
그래서 지적을 네 가지로 나눕니다.
| 등급 | 판단 기준 | 처리 |
| 실제 결함 | 재현 경로를 말할 수 있다 | 반드시 수정, 테스트 추가 |
| 위험 | 지금은 안 터지지만 조건이 바뀌면 터진다 | 수정하거나, 보류하면 이유를 커밋 메시지에 남김 |
| 설계 의견 | 취향이 아니라 구조 이야기 | 다음 작업으로 분리 |
| 오판 | 코드를 잘못 읽었거나 이미 처리된 것 | 무시, 필요하면 리뷰어에게 맥락 보강 |
실제로 지적의 상당수는 세 번째와 네 번째에 들어갑니다. 이걸 다 반영하면 코드가 리뷰어 취향으로 수렴하고, 정작 진짜 결함은 diff에 묻힙니다.
반영할 때는 이렇게 넘깁니다.
아래는 Codex 리뷰 결과야. 1, 3, 5번만 반영해줘.
2번은 이번 범위가 아니라서 보류, 4번은 코드를 잘못 읽은 것 같아서 무시.
반영한 뒤에 각 항목별로 무엇을 바꿨는지 한 줄씩 적어줘.
항목 번호로 지정하는 것이 핵심입니다. 리뷰 전문을 통째로 붙이고 "고쳐"라고 하면, 어떤 지적이 반영됐고 어떤 게 무시됐는지 아무도 추적하지 못합니다.
5단계: 검증하고 커밋
리뷰 반영이 끝나면 커밋 전에 직접 돌립니다. AI가 돌렸다고 말한 것과 제가 돌린 결과가 다른 경우가 실제로 있습니다. 그래서 마지막 확인은 터미널에서 직접 합니다.
pnpm tsc --noEmit && pnpm lint && pnpm test
커밋 메시지에는 무엇을 했는지와 무엇을 일부러 안 했는지를 같이 남깁니다. 나중에 이 커밋을 리뷰하거나 되돌릴 때, 보류한 이유가 없으면 같은 논의를 처음부터 다시 합니다.
feat: 저장 시 서버 저장 실패를 재시도 큐로 위임
- 낙관적 업데이트 유지, 실패 시 3회 재시도 후 큐로 이동
- 에러 UI는 이번 범위 아님(다음 작업)
- Codex 리뷰 2번 지적은 현 구조에서 재현 불가로 보류
인터페이스: 터미널만 고집하지 않는 이유
기본은 터미널입니다. 빠르고, 파이프로 넘기고, 로그를 파일로 남기기 좋습니다. 그런데 상황에 따라 데스크톱 앱을 씁니다.
| 상황 | 쓰는 인터페이스 | 이유 |
| 작업을 잘라서 바로 구현 | Claude Code 터미널 | 계획, 구현, 검증을 한 흐름으로 돌리기 좋음 |
| 여러 세션을 동시에 굴릴 때 | Claude Code 데스크톱 앱 | 세션을 눈으로 나눠 보고 오가기 편함 |
| 리뷰 결과를 읽으며 질문 | Codex 터미널(/review) | 이어서 물어보고 /diff로 확인하기 좋음 |
| 긴 지적 목록, diff 훑기 | Codex 데스크톱 앱 | 스크롤하며 읽는 쪽이 편함 |
한 인터페이스에 몰아두면 그 인터페이스가 불편해질 때 작업 자체가 느려집니다. 그래서 같은 도구를 터미널과 앱 양쪽에 열어두고, 그날 손에 맞는 쪽을 씁니다. 설정 파일이 프로젝트 안에 있으니 인터페이스를 바꿔도 규칙은 그대로 따라옵니다 — 이게 두 도구를 나눠 쓰면서도 일관성이 유지되는 이유입니다.
PR 없이 가는 흐름, 무엇을 잃고 무엇으로 메우나
혼자 하는 프로젝트에서 PR 절차는 대체로 형식만 남습니다. 셀프 PR에 셀프 승인을 하면 리뷰가 한 번도 안 일어난 것과 같습니다. 그래서 브랜치는 쓰되 PR은 생략하고, 리뷰를 Codex로 대체합니다.
다만 PR이 원래 해주던 일이 있습니다. 그걸 의식적으로 메꿔야 합니다. 정리하면 이렇습니다.
· 리뷰 강제 → 커밋 전 codex review --uncommitted를 루틴으로 고정
· diff 시각화 → /diff 또는 git diff를 커밋 전에 직접 확인
· 테스트 게이트 → 타입, 린트, 테스트를 한 줄로 묶어 커밋 전 실행
· 변경 이력 → 커밋 메시지에 의도와 보류 사유 기록
· 되돌리기 단위 → 작업을 애초에 커밋 크기로 자름
이 중 다섯 번째가 제일 중요합니다. PR이 없으면 커밋 하나가 곧 복구 단위입니다. 그래서 1단계에서 작업을 자르는 겁니다.
이 조합에서 자주 무너지는 지점
실제로 굴려보면 몇 군데서 반복적으로 걸립니다. 미리 알아두면 그만큼 덜 헤맵니다.
1) 리뷰어가 코드를 잘못 읽고 단정한다.
파일 일부만 보고 "이 변수는 여기서 항상 null"이라고 단정하는 경우입니다. 지적의 근거가 되는 파일과 줄을 확인하고, 틀렸으면 그 사실을 다음 리뷰 프롬프트에 적어 둡니다. 같은 오판이 반복되면 AGENTS.md에 "이 파일은 이런 구조"를 한 줄 추가합니다.
2) 구현자가 리뷰 지적을 과하게 반영한다.
"이 함수가 너무 길다"는 지적에 함수 분리와 추상화, 인터페이스 도입까지 하면 다음 리뷰에서 그 추상화를 또 지적합니다. 지적 하나에 한 번에 한 가지 변경만 대응합니다.
3) 두 도구가 같은 파일을 동시에 만진다.
리뷰가 도는 중에 구현을 이어가면 리뷰 대상이 계속 바뀝니다. 리뷰는 작업을 멈추고 돌립니다. 커밋 전 스냅샷 하나를 고정하는 셈입니다.
4) 세션이 길어져 앞 맥락이 뒤 판단을 오염시킨다.
한 세션에서 기능 A를 만들고 이어서 B를 만들면, A의 가정이 B에 그대로 들어갑니다. 작업 단위가 바뀌면 /clear로 끊습니다.
■ 1인 개발 리뷰 체크리스트
매번 이 순서로 확인합니다. 길지 않아서 실제로 돌아갑니다.
☐ 작업을 한 커밋 크기로 잘랐는가
☐ 계획 모드에서 고칠 파일과 검증 방법을 확인했는가
☐ 구현 결과에 "확인/추측/미검증"이 구분돼 있는가
☐ 커밋 전 워킹트리에서 리뷰를 돌렸는가
☐ 리뷰 지적을 등급으로 나눠 반영/보류를 정했는가
☐ 보류한 지적의 이유를 커밋 메시지에 남겼는가
☐ 타입·린트·테스트를 직접 돌렸는가
☐ 다음 작업으로 넘길 항목을 한 줄로 적었는가
■ 정리
이 워크플로우의 핵심은 좋은 모델을 두 개 쓰는 게 아니라, 역할을 물리적으로 분리하는 것입니다. 구현하는 쪽은 맥락을 많이 알아야 하고, 리뷰하는 쪽은 맥락을 몰라야 합니다. 같은 모델에 둘 다 맡기면 두 번째 조건이 깨집니다.
효과가 확실한 것 세 가지만 꼽으라면 이렇습니다.
1. 커밋 전 리뷰를 루틴으로 고정 — 의지에 맡기면 반드시 건너뜁니다.
2. 지적을 번호로 지정해 반영 — 무엇을 안 했는지 남아야 다음에 안 헤맵니다.
3. 검증 명령을 두 도구의 규칙 파일에 똑같이 — 구현자와 리뷰어의 기준을 맞춥니다.
도구 이름과 명령은 계속 바뀝니다. 이 글에 적은 명령도 버전이 올라가면 달라질 수 있으니, 실제로 쓰기 전에 --help로 한 번 확인하시길 권합니다. 바뀌지 않는 건 순서입니다. 자르고, 만들고, 남의 눈으로 보고, 직접 확인한다 — 이 네 단계는 도구가 바뀌어도 그대로입니다.
다음 글에서는 옵시디언 볼트를 AI 에이전트용으로 분리하는 구상을 정리해 볼 예정입니다.
참고한 공식 문서
· Claude Code 명령·기능: https://code.claude.com/docs/ko/commands
명령 - Claude Code Docs
기본 제공 명령과 번들 스킬을 포함하여 Claude Code에서 사용할 수 있는 명령에 대한 전체 참조입니다.
code.claude.com
· Claude Code 확장(CLAUDE.md·서브에이전트·훅): https://code.claude.com/docs/ko/features-overview
Claude Code 확장하기 - Claude Code Docs
CLAUDE.md, Skills, subagents, hooks, MCP, 플러그인을 언제 사용할지 이해합니다.
code.claude.com
· Claude Code 치트시트: https://support.claude.com/ko/articles/14553413
Claude Code 치트시트 | Anthropic 지원 센터
support.claude.com
· Codex CLI 명령(개발자 명령·exec·review): https://learn.chatgpt.com/docs/developer-commands.md?surface=cli