책에 포함된 노트AI 교육 5권 : ChatGPT·Claude·Gemini와 코딩 에이전트 실무: AI 도구 선택부터 자동화 포트폴리오까지

Codex 실무 패턴

2026-05-20Views 58약 7분생성형 AI 활용

Summary

이 장에서 배울 것

이번 장에서는 Codex를 "옆에서 계속 대화하는 코딩 짝꿍"이 아니라 "명확한 티켓을 받아 안전한 환경에서 작업하고 PR이나 diff를 돌려주는 작업자"로 다루는 방법을 배운다.

핵심은 세 가지다.

Codex에 맡길 작업을 PR 단위로 작게 쪼갠다.
작업 지시서에 범위, 수락 기준, 테스트 명령, 금지 영역을 명확히 쓴다.
생성된 diff나 PR은 사람이 요구사항, 테스트, 보안, 롤백 가능성 기준으로 검토한다.

Claude Code가 로컬 터미널에서 함께 탐색하고 조율하는 흐름에 강했다면, Codex는 잘 정의된 이슈를 독립적으로 처리하고 검토 가능한 결과물로 돌려받는 흐름에 잘 맞는다.

Codex 실무 패턴

왜 이 주제가 중요한가

코딩 에이전트를 잘못 쓰는 가장 흔한 방식은 "이 기능 전체 만들어줘"라고 한 번에 맡기는 것이다. 처음에는 편해 보이지만 곧 문제가 생긴다. 요구사항, 로그, 파일 정보, 테스트 결과가 한 대화에 섞이고, 결과 PR은 너무 커져서 사람이 검토하기 어려워진다.

Codex는 저장소를 읽고, 관련 파일을 찾고, 코드를 수정하고, 테스트를 실행할 수 있는 에이전트다. OpenAI의 Codex 문서는 샌드박스를 "Codex가 자율적으로 행동하되 무제한 접근을 갖지 않게 하는 경계"로 설명한다¹. 이 말은 곧 Codex를 믿고 맡길 수 있다는 뜻이 아니라, 안전한 경계 안에서 작은 작업을 시킨 뒤 사람이 검토해야 한다는 뜻이다.

좋은 Codex 워크플로는 개발자를 대체하지 않는다. 개발자가 반복적인 코드 수정, 테스트 추가, 문서 보강을 위임하고, 더 중요한 설계 판단과 리뷰에 시간을 쓰게 해준다.

핵심 개념 설명

Codex의 기본 작업 흐름

Codex 작업은 보통 다음 순서로 진행된다.

사람이 자연어 티켓을 작성한다.
Codex가 저장소 구조와 관련 파일을 탐색한다.
변경 계획을 세운다.
제한된 범위에서 코드를 수정한다.
테스트, 린트, 타입 체크를 실행한다.
diff, 커밋, PR 또는 리뷰 결과를 만든다.
사람이 최종 검토한다.

여기서 가장 중요한 단계는 첫 번째와 마지막이다. 처음 지시가 모호하면 Codex는 스스로 범위를 넓힌다. 마지막 검토가 약하면 AI가 만든 미묘한 로직 오류가 그대로 머지된다.

따라서 Codex에게 줄 작업은 "하나의 PR로 리뷰 가능한 크기"여야 한다. 예를 들어 "결제 모듈 리팩터링"은 너무 크다. "src/payment/validateAmount.ts에서 0 이하 금액을 거부하고, 관련 단위 테스트를 추가하라"는 적절하다.

Codex와 Claude Code의 차이

Claude Code는 지난 장에서 다룬 것처럼 조사, 계획, 수정, 리뷰를 로컬 터미널에서 대화하며 진행하기 좋다. 사람이 중간중간 방향을 바꾸고, "아직 수정하지 말고 계획만 말해줘"처럼 세밀하게 제어하기 쉽다.

Codex는 조금 다르게 접근하는 편이 좋다. Codex는 잘 정의된 이슈, PR, 샌드박스 환경에서 독립적으로 실행하고 결과물을 리뷰하는 패턴에 잘 맞는다. 즉 "같이 앉아 코드를 보는 동료"라기보다 "티켓을 받아 작업 브랜치를 만들어 오는 동료"에 가깝다.

간단히 나누면 다음과 같다.

작업 유형	더 적합한 방식
낯선 코드베이스를 함께 읽고 방향을 잡기	Claude Code
명확한 버그 수정 티켓 처리	Codex
여러 접근법을 대화로 비교	Claude Code
테스트 추가, 문서 수정, 의존성 업데이트	Codex
대규모 설계 판단	사람 + Claude Code/ChatGPT 보조
PR 단위 자동 리뷰와 반복 점검	Codex

Codex에 맡기기 좋은 작업

Codex에 적합한 작업은 범위가 좁고 검증 기준이 분명한 일이다.

의존성 업데이트 후 깨지는 테스트 수정
기존 함수에 테스트 케이스 추가
README, API 문서, 변경 로그 수정
작은 버그 수정
단일 모듈 리팩터링
실패 로그 기반 수정
타입 오류, 린트 오류 정리
PR의 보안·테스트·유지보수성 리뷰

반대로 다음 작업은 바로 맡기면 위험하다.

제품 방향 결정
대규모 아키텍처 변경
인증, 권한, 결제 로직 변경
데이터 마이그레이션
외부 API 키나 비밀 정보가 관련된 작업
여러 팀의 합의가 필요한 인터페이스 변경

이런 작업은 Codex에게 "구현"을 맡기기 전에 먼저 "조사"나 "계획"만 맡기는 편이 안전하다.

쉬운 비유 또는 사례

Codex를 신입 개발자라고 생각해보자. 신입에게 "회원 시스템 개선해 주세요"라고 말하면 결과를 예측하기 어렵다. 하지만 다음처럼 말하면 성공 확률이 높다.

로그인 실패 메시지가 너무 기술적입니다. src/auth/errorMessage.ts에서 에러 코드별 사용자 메시지를 추가하세요. 기존 API 응답 형식은 바꾸지 마세요. npm test -- auth를 실행하고, 실패하면 원인을 설명하세요. PR 설명에는 변경 파일, 테스트 결과, 남은 위험을 적으세요.

이 지시는 배경, 범위, 금지 사항, 검증 방법, 산출 형식을 모두 포함한다. Codex는 이런 티켓을 받을 때 강해진다.

직접 해보는 실습

실습 1: 샘플 이슈 작성하기

아래 템플릿을 복사해 자신의 프로젝트에 맞게 채워보자.

## 배경
사용자가 잘못된 이메일을 입력해도 가입 폼에서 명확한 오류가 보이지 않는다.

## 문제 상황
`src/features/signup/validateSignup.ts`에서 이메일 형식 검증이 약하다.
현재는 빈 문자열만 막고, `abc` 같은 값은 통과한다.

## 수정 범위
- 수정 가능: `src/features/signup/validateSignup.ts`
- 테스트 추가 가능: `src/features/signup/__tests__/validateSignup.test.ts`
- 수정 금지: API 응답 스키마, DB 스키마, 라우팅 구조

## 수락 기준
- 이메일 형식이 잘못되면 `{ ok: false, code: "INVALID_EMAIL" }`을 반환한다.
- 기존 정상 케이스는 그대로 통과한다.
- 빈 문자열, 공백, `abc`, `a@b` 케이스 테스트를 추가한다.

## 실행할 테스트
npm test -- validateSignup
npm run lint

## PR 설명에 포함할 것
- 변경한 파일 목록
- 추가한 테스트 케이스
- 실행한 명령과 결과
- 남은 위험 또는 확인하지 못한 부분

이 템플릿에서 가장 중요한 줄은 "수정 금지"와 "수락 기준"이다. Codex는 해야 할 일뿐 아니라 하지 말아야 할 일도 알아야 한다.

실습 2: Codex에 위임하기

Codex에 다음처럼 요청한다.

아래 이슈를 처리해줘.
먼저 관련 파일을 읽고 변경 계획을 5줄 이내로 제시한 뒤, 범위가 맞으면 구현해줘.
수정 범위 밖의 파일은 건드리지 마.
구현 후 지정된 테스트와 린트를 실행하고, 최종 diff 요약과 PR 설명 초안을 작성해줘.

[여기에 실습 1의 이슈 붙여넣기]

처음부터 "바로 수정해줘"라고 하지 말고, 계획을 먼저 받는 것이 좋다. 계획이 틀렸다면 구현 전에 바로잡을 수 있다.

실습 3: diff 또는 PR 검토하기

Codex가 만든 결과를 아래 체크리스트로 검토한다.

요구사항을 모두 충족했는가?
지시하지 않은 파일을 바꾸지 않았는가?
테스트와 린트가 실제로 통과했는가?
에러 로그나 이슈 설명을 제대로 반영했는가?
스타일이 기존 코드와 맞는가?
보안, 성능, 접근성에 부작용은 없는가?
문제가 생기면 쉽게 롤백할 수 있는가?

필요하면 후속 지시는 짧고 구체적으로 쓴다.

좋아. 다만 `validateSignup.ts`에서 정규식을 직접 두지 말고,
기존 `src/shared/validators/email.ts`의 `isValidEmail`을 재사용해줘.
테스트는 그대로 유지하고 다시 실행해줘.

큰 작업은 어떻게 나눌까

Codex는 병렬 서브에이전트 워크플로를 통해 여러 특화 에이전트를 실행하고 결과를 모을 수 있다². 하지만 병렬화는 만능이 아니다. 파일을 동시에 수정하면 충돌이 생기고, 결과를 합치는 비용이 커진다.

처음에는 읽기 전용 병렬 작업부터 시작하자.

읽기 전용으로 서브에이전트 2개를 병렬로 사용해줘.
에이전트 1은 관련 파일과 호출 흐름을 정리해줘.
에이전트 2는 관련 테스트와 빠진 테스트 케이스를 찾아줘.
파일은 수정하지 마.
두 결과가 모두 나오면 파일 경로와 함께 요약해줘.

큰 작업은 다음처럼 단계화한다.

코드베이스 탐색
원인 분석
테스트 보강
작은 구현
테스트 실행
리뷰와 PR 설명 작성

작업을 나누면 느려 보이지만, 실제로는 리뷰 가능한 결과가 나온다. 코딩 에이전트의 생산성은 "한 번에 많이 고치는 능력"이 아니라 "작게 고치고 검증하는 루프를 빠르게 반복하는 능력"에서 나온다.

AGENTS.md와 반복 규칙 관리

반복해서 말해야 하는 팀 규칙은 매번 프롬프트에 붙이지 말고 저장소 문서로 분리한다. Codex 생태계에서는 보통 AGENTS.md 같은 규칙 파일에 빌드 명령, 테스트 명령, 코딩 컨벤션, PR 형식을 적어둔다.

예시는 다음과 같다.

## Commands
- npm test: 전체 테스트 실행
- npm run lint: 린트 검사
- npm run build: 프로덕션 빌드 확인

## Coding rules
- TypeScript strict mode를 지킨다.
- API 에러 응답 형식은 `{ error, code }`를 유지한다.
- 사용자 식별 정보는 로그에 남기지 않는다.

## Review guidelines
- 인증 미들웨어 누락은 P1로 보고한다.
- `eval` 사용은 P0로 보고한다.
- 새 라우트에는 최소 1개 이상의 테스트가 필요하다.

## Pull request
- 변경 요약, 테스트 결과, 남은 위험을 포함한다.

규칙 파일은 짧을수록 좋다. 너무 길면 Codex가 중요한 규칙을 놓치기 쉽다. 자세한 설계 문서나 도메인 설명은 별도 문서로 두고, AGENTS.md에는 작업할 때 항상 필요한 기준만 남긴다.

흔한 실수와 오류 분석

첫째, 작업 범위가 너무 크다. "관리자 기능 개선" 같은 지시는 결과가 커지고 리뷰가 어려워진다. "사용자 목록 페이지의 빈 상태 메시지와 테스트 추가"처럼 줄인다.

둘째, 테스트 명령을 적지 않는다. Codex가 알아서 추측할 수도 있지만, 프로젝트마다 명령이 다르다. npm test, pnpm test, pytest, go test ./...처럼 정확히 적는다.

셋째, 금지 영역을 쓰지 않는다. 인증, 결제, DB 스키마, 공개 API는 실수 비용이 크다. 바꾸면 안 되는 영역을 명시해야 한다.

넷째, diff를 읽지 않고 머지한다. AI가 만든 코드는 그럴듯해 보일수록 위험하다. 변수명은 좋아졌지만 실제 정책이 바뀌었을 수 있다.

다섯째, 병렬 에이전트를 너무 많이 쓴다. 병렬 작업은 비용과 대기 시간이 늘고, 같은 파일을 건드리면 충돌이 난다. 처음에는 읽기 전용 2개 관점부터 시작한다.

요약

Codex는 코드 자동완성 도구가 아니라 위임형 코딩 에이전트다. 잘 정의된 티켓을 받아 저장소를 탐색하고, 제한된 범위에서 수정하고, 테스트를 실행하고, 검토 가능한 diff나 PR을 돌려주는 방식에 강하다.

좋은 Codex 활용의 기준은 명확하다.

작업은 PR 단위로 작게 나눈다.
지시서에는 배경, 범위, 수락 기준, 테스트 명령, 금지 영역을 쓴다.
팀 규칙은 AGENTS.md 같은 문서로 재사용한다.
큰 작업은 조사, 분석, 테스트, 구현, 리뷰로 나눈다.
최종 판단은 사람이 한다.

퀴즈

Codex에 "전체 결제 시스템을 개선해줘"라고 맡기는 것이 위험한 이유는 무엇인가?
좋은 Codex 작업 지시서에 들어가야 할 항목을 세 가지 이상 말해보자.
Codex에 맡기기 좋은 작업과 사람이 직접 설계해야 하는 작업을 각각 하나씩 들어보자.
병렬 서브에이전트를 처음 사용할 때 읽기 전용 작업부터 시작하는 이유는 무엇인가?
Codex가 테스트를 통과했다고 말했을 때 사람이 추가로 확인해야 할 것은 무엇인가?

체크리스트

작업 범위가 하나의 PR로 리뷰 가능한가?
관련 파일, 로그, 이슈 링크를 지시서에 넣었는가?
수정 가능 영역과 수정 금지 영역을 분리했는가?
수락 기준이 테스트 가능한 문장으로 되어 있는가?
실행할 테스트와 린트 명령을 적었는가?
Codex가 만든 diff에서 불필요한 변경을 확인했는가?
보안, 성능, 롤백 가능성을 검토했는가?
반복 규칙을 AGENTS.md나 저장소 문서로 분리했는가?

다음 장 연결

다음 장에서는 AI 워크플로의 검증과 비용 관리를 다룬다. Codex와 Claude Code를 쓰기 시작하면 작업 속도는 빨라지지만, 동시에 토큰 비용, 병렬 실행 비용, 테스트 비용, 리뷰 비용이 생긴다. 이제 중요한 질문은 "AI가 코드를 만들 수 있는가?"가 아니라 "AI가 만든 결과를 어떤 기준과 비용 안에서 신뢰할 수 있는가?"이다.

참고

¹Sandbox - Codex | OpenAI Developers

²Subagents - Codex | OpenAI Developers

책 목록

AI 교육 5권 : ChatGPT·Claude·Gemini와 코딩 에이전트 실무: AI 도구 선택부터 자동화 포트폴리오까지

전체 목차 보기