Codex Implementer

Codex Implementer (멀티 에이전트 구현)

Overview

Claude가 오케스트레이터로서 작업을 분석하고, Codex CLI를 sub-agent로 호출하여 실제 구현 작업을 수행하는 스킬입니다.

핵심 아이디어:

• Claude: 분석, 설계, 작업 분해, 결과 검토 및 통합
• Codex: 실제 코드 구현, 버그 수정, 리팩토링, 테스트 작성

지원 구현 패턴:

• 단일 구현: 하나의 기능/파일을 Codex가 구현
• 병렬 구현: 여러 파일/기능을 동시에 여러 Codex가 구현
• 점진적 구현: 단계별로 Codex가 순차 구현 + Claude 검토
• 리팩토링: 기존 코드 개선을 Codex에게 위임

Codex의 강점:

• full-auto 모드로 자율적 구현 가능
• 로컬 파일 시스템 직접 접근
• 터미널 명령 실행 가능
• 빠른 반복 작업에 적합

When to Use

이 스킬은 다음 상황에서 활성화됩니다:

명시적 요청:

• "Codex로 구현해줘"
• "구현을 Codex에게 맡겨줘"
• "병렬로 구현해줘"
• "Codex 에이전트로 작업해줘"

권장 상황:

• 구현할 기능이 명확히 정의되었을 때
• 여러 파일을 동시에 수정해야 할 때
• 반복적인 코드 작성 작업이 있을 때
• 빠른 프로토타이핑이 필요할 때

Prerequisites

OpenAI Codex CLI 설치

# npm으로 설치
npm install -g @openai/codex

# 설치 확인
codex --version

환경 변수 설정

# Codex CLI용 OpenAI API 키
export OPENAI_API_KEY="sk-..."

Codex 승인 모드 설정

# --full-auto 모드 권장 (자율 실행, 샌드박스 내)
# --sandbox read-only: 읽기 전용 모드
# --sandbox workspace-write: 작업 디렉토리 쓰기 허용 (기본)
# --full-auto: 자동 승인 + workspace-write 샌드박스 (권장)

Workflow

Mode 1: 단일 구현 (Single Implementation)

하나의 기능을 Codex가 구현합니다.

Step 1: 요구사항 분석

Claude가 구현할 기능을 분석합니다:

사용자: "사용자 로그인 API 엔드포인트를 만들어줘"

Claude 분석:
- 기능: POST /api/auth/login
- 입력: email, password
- 출력: JWT 토큰
- 필요 파일: routes/auth.ts, services/authService.ts

Step 2: Codex 호출

분석 결과를 바탕으로 Codex를 호출합니다:

codex exec --full-auto "다음 기능을 구현해주세요:

## 요구사항
- POST /api/auth/login 엔드포인트 생성
- email, password로 인증
- 성공 시 JWT 토큰 반환
- 실패 시 적절한 에러 응답

## 파일 위치
- routes/auth.ts에 라우트 추가
- services/authService.ts에 인증 로직 구현

## 기존 패턴 참고
- routes/users.ts의 라우트 패턴 따르기
- 기존 에러 핸들링 패턴 유지"

Step 3: 결과 확인

Codex 실행 완료 후 Claude가 결과를 검토합니다:

• 생성/수정된 파일 확인
• 코드 품질 검토
• 테스트 실행 제안

Mode 2: 병렬 구현 (Parallel Implementation)

여러 기능을 동시에 여러 Codex 인스턴스가 구현합니다.

Step 1: 작업 분해

Claude가 작업을 독립적인 단위로 분해합니다:

사용자: "CRUD API를 만들어줘 (users, posts, comments)"

Claude 작업 분해:
- Task 1: users CRUD (routes/users.ts, services/userService.ts)
- Task 2: posts CRUD (routes/posts.ts, services/postService.ts)
- Task 3: comments CRUD (routes/comments.ts, services/commentService.ts)

Step 2: 병렬 Codex 호출

각 작업을 별도의 Codex 프로세스로 실행합니다:

# Terminal 1
codex exec --full-auto "users CRUD API를 구현해주세요..."

# Terminal 2 (동시 실행)
codex exec --full-auto "posts CRUD API를 구현해주세요..."

# Terminal 3 (동시 실행)
codex exec --full-auto "comments CRUD API를 구현해주세요..."

Claude에서 병렬 실행:

Claude가 여러 Bash 명령을 동시에 실행하여 병렬 처리합니다.
각 Codex는 독립적인 파일을 작업하므로 충돌이 없습니다.

Step 3: 통합 및 검토

모든 Codex 완료 후:

• 생성된 코드 간 일관성 확인
• 공통 로직 추출 여부 검토
• 통합 테스트 실행

Mode 3: 점진적 구현 (Incremental Implementation)

복잡한 기능을 단계별로 구현하며 Claude가 각 단계를 검토합니다.

Step 1: 단계 정의

Phase 1: 기본 구조 생성
Phase 2: 핵심 로직 구현
Phase 3: 에러 처리 추가
Phase 4: 테스트 작성

Step 2: 단계별 실행

# Phase 1
codex exec --full-auto "Phase 1: 기본 파일 구조와 스켈레톤 코드를 생성해주세요..."

# Claude 검토 후...

# Phase 2
codex exec --full-auto "Phase 2: 핵심 비즈니스 로직을 구현해주세요.
기존 파일: [Phase 1에서 생성된 파일 목록]..."

# 반복...

Step 3: 최종 검토

모든 단계 완료 후 전체 코드 리뷰 및 테스트

Mode 4: 리팩토링 위임 (Refactoring Delegation)

기존 코드 개선을 Codex에게 위임합니다.

Step 1: 리팩토링 범위 정의

사용자: "이 파일의 중복 코드를 제거해줘"

Claude 분석:
- 대상 파일: services/userService.ts
- 문제점: validateUser, validateAdmin에 중복 로직
- 해결: 공통 validate 함수 추출

Step 2: Codex 리팩토링 실행

codex exec --full-auto "다음 리팩토링을 수행해주세요:

## 대상 파일
services/userService.ts

## 리팩토링 목표
1. validateUser와 validateAdmin의 공통 로직을 baseValidate로 추출
2. 각 함수에서 baseValidate 호출하도록 수정
3. 기존 테스트가 통과하는지 확인

## 제약 조건
- 외부 인터페이스(함수 시그니처) 유지
- 기존 동작 변경 없음"

Examples

예시 1: 단일 기능 구현

사용자: Codex로 비밀번호 재설정 기능을 구현해줘

Claude: 비밀번호 재설정 기능을 분석하고 Codex에게 구현을 위임합니다.

## 기능 분석
- 이메일로 재설정 링크 발송
- 토큰 기반 인증
- 새 비밀번호 설정

Codex를 호출합니다...

[Codex 실행]
codex exec --full-auto "비밀번호 재설정 기능을 구현해주세요:
1. POST /api/auth/forgot-password - 재설정 이메일 발송
2. POST /api/auth/reset-password - 새 비밀번호 설정
기존 auth 라우트 패턴을 따라주세요."

[실행 완료]

## Codex 구현 결과
- routes/auth.ts: 2개 엔드포인트 추가
- services/authService.ts: resetPassword 로직 추가
- utils/email.ts: sendResetEmail 함수 추가

## 검토 사항
✅ 기존 패턴과 일관성 유지
✅ 토큰 만료 처리 포함
⚠️ 테스트 추가 권장

테스트를 작성할까요?

예시 2: 병렬 구현

사용자: 3개의 Codex 에이전트로 dashboard, settings, profile 페이지를 동시에 만들어줘

Claude: 3개의 Codex 에이전트를 병렬로 실행하여 각 페이지를 구현합니다.

## 작업 분배
- Agent 1: Dashboard 페이지 (pages/dashboard/*)
- Agent 2: Settings 페이지 (pages/settings/*)
- Agent 3: Profile 페이지 (pages/profile/*)

## 병렬 실행 중...

[Agent 1 - Dashboard] 실행 중...
[Agent 2 - Settings] 실행 중...
[Agent 3 - Profile] 실행 중...

✓ Agent 1 완료 (45초)
✓ Agent 3 완료 (52초)
✓ Agent 2 완료 (58초)

## 구현 결과 요약

### Dashboard (Agent 1)
- pages/dashboard/index.tsx
- pages/dashboard/components/StatsCard.tsx
- pages/dashboard/hooks/useDashboardData.ts

### Settings (Agent 2)
- pages/settings/index.tsx
- pages/settings/components/SettingsForm.tsx
- pages/settings/hooks/useSettings.ts

### Profile (Agent 3)
- pages/profile/index.tsx
- pages/profile/components/ProfileCard.tsx
- pages/profile/hooks/useProfile.ts

## 통합 검토
✅ 컴포넌트 네이밍 일관성
✅ 공통 레이아웃 사용
✅ 라우팅 설정 완료

빌드 및 테스트를 실행할까요?

예시 3: 버그 수정 위임

사용자: 이 버그를 Codex로 수정해줘: "장바구니에서 수량 변경 시 총액이 업데이트되지 않음"

Claude: 버그를 분석하고 Codex에게 수정을 위임합니다.

## 버그 분석
- 증상: 수량 변경 후 totalPrice가 갱신되지 않음
- 관련 파일: components/Cart.tsx, hooks/useCart.ts
- 원인 추정: useEffect 의존성 배열 누락

Codex를 호출합니다...

[Codex 실행]
codex exec --full-auto "다음 버그를 수정해주세요:

## 버그 설명
장바구니에서 상품 수량 변경 시 총액(totalPrice)이 업데이트되지 않음

## 관련 파일
- components/Cart.tsx
- hooks/useCart.ts

## 수정 후 확인 사항
- 수량 변경 시 총액 즉시 반영
- 기존 테스트 통과
- 새로운 테스트 케이스 추가"

[실행 완료]

## 수정 결과
- hooks/useCart.ts: useEffect 의존성 배열에 items 추가
- components/Cart.tsx: 불필요한 로컬 상태 제거
- tests/Cart.test.tsx: 수량 변경 테스트 추가

✅ 테스트 통과
✅ 버그 수정 완료

Configuration

Codex 실행 옵션

# 권장 설정
codex_options:
  full_auto: true             # --full-auto 플래그 사용 (권장)
  sandbox: "workspace-write"  # 샌드박스 모드
  model: "gpt-5.2-codex"      # 또는 다른 모델
  timeout: 300                # 5분 타임아웃

# 모드별 설정
modes:
  single:
    max_files: 5
    timeout: 180

  parallel:
    max_agents: 5
    timeout: 300

  incremental:
    phases: 4
    review_between_phases: true

병렬 실행 설정

parallel:
  max_concurrent: 3      # 동시 실행 Codex 수
  wait_strategy: "all"   # all: 전체 완료 대기, any: 하나라도 완료 시
  conflict_check: true   # 파일 충돌 사전 검사

Best Practices

DO:

• 구현 전 Claude에게 충분한 컨텍스트 제공
• 병렬 구현 시 작업 간 파일 충돌 없도록 분리
• Codex 실행 후 Claude 검토 단계 포함
• 점진적 구현으로 복잡한 기능 분해
• 기존 코드 패턴을 프롬프트에 명시

DON'T:

• 모호한 요구사항으로 Codex 호출
• 동일 파일을 여러 Codex가 동시 수정
• Codex 결과를 검토 없이 사용
• 너무 많은 병렬 에이전트 (5개 이상)
• 전체 프로젝트 리팩토링을 한 번에 위임

Codex CLI Quick Reference

# 기본 실행 (대화형)
codex "프롬프트"

# Full-auto 모드 (자동 승인 + workspace-write 샌드박스)
codex --full-auto "프롬프트"

# 샌드박스 모드 지정
codex --sandbox read-only "프롬프트"
codex --sandbox workspace-write "프롬프트"
codex --sandbox danger-full-access "프롬프트"

# 비대화형 실행 (exec 서브커맨드) - 스크립트에서 권장
codex exec "프롬프트"

# 조합 예시 (대화형 + full-auto)
codex --full-auto "구현 프롬프트"

# 조합 예시 (비대화형 + full-auto - 스크립트에서 사용)
codex exec --full-auto "구현 프롬프트"

# 모델 지정
codex exec --full-auto -m gpt-4o "프롬프트"

# 작업 디렉토리 지정
codex exec --full-auto -C /path/to/project "프롬프트"

Troubleshooting

Codex CLI 오류

# 설치 확인
codex --version

# API 키 확인
echo $OPENAI_API_KEY

# 직접 테스트 (비대화형)
codex exec --full-auto "Hello, world를 출력하는 Python 코드를 작성해"

# Git 레포지토리가 아닌 곳에서 실행 시
codex exec --skip-git-repo-check --full-auto "프롬프트"

병렬 실행 시 파일 충돌

• 작업 분해 시 파일 의존성 확인
• 동일 파일을 여러 Codex가 수정하지 않도록 분리
• 공통 파일은 마지막에 별도 Codex로 통합

타임아웃 발생

• 작업 범위 축소
• 단계별 구현으로 전환
• 모델을 더 빠른 것으로 변경 (o4-mini)

Codex가 잘못된 파일 수정

• 프롬프트에 파일 경로 명시
• 기존 파일 구조 설명 추가
• working directory 지정

Integration with Claude

Claude의 역할

1. 분석: 요구사항 분석, 작업 분해
2. 오케스트레이션: Codex 호출 시점/방법 결정
3. 검토: Codex 결과 품질 검토
4. 통합: 여러 Codex 결과 통합
5. 커뮤니케이션: 사용자에게 진행 상황 보고

Codex의 역할

1. 구현: 실제 코드 작성
2. 수정: 기존 코드 변경
3. 실행: 테스트, 빌드 등 명령 실행
4. 탐색: 코드베이스 탐색 (필요시)

협업 흐름

사용자 요청
    ↓
Claude 분석 (요구사항 파악)
    ↓
Claude 설계 (작업 분해)
    ↓
Codex 구현 (병렬/순차)
    ↓
Claude 검토 (품질 확인)
    ↓
결과 보고 + 추가 작업 제안

Resources

• ./templates/implementation_prompt.md: Codex 호출용 프롬프트 템플릿
• ./references/parallel_patterns.md: 병렬 구현 패턴 가이드
• ./scripts/orchestrator.sh: 병렬 Codex 실행 오케스트레이터
• ./config/settings.yaml: 기본 설정 파일
• OpenAI Codex CLI: Codex CLI 공식 저장소