개요
OpenAI가 공식 공개한 소프트웨어 엔지니어용 Codex 종합 가이드. Codex는 단순 코드 완성·페어 프로그래밍을 넘어 엔지니어가 대규모 작업을 위임하는 코딩 에이전트 플랫폼. CLI·IDE·앱이 동일 백엔드 공유, SDLC 7단계 전체 커버, agents.md + Skills + Automations로 워크플로우 패키징, 25시간 무중단 작업 가능.
- 출처: academy.openai.com (2026-03)
- 포맷: 58분 웨비나 영상
- CLI 전용 정보: Codex CLI 참고
AI 코딩의 진화 단계
1단계: 코드 완성 (타이핑 속도 ~10% 향상)
↓
2단계: 페어 프로그래밍 (계획·테스트·리포 수정)
↓ "더 나은 협업자"
3단계: 에이전트 위임 ⭐ (Codex의 목표)
↓ "엔지니어가 위임 가능한 자율 에이전트"
모델 발전사
| 시기 | 모델 | 특징 |
|---|---|---|
| 2025-12 | GPT 5.2 Codex | 장시간 무중단 작업 + 조종성 확보 |
| 2026-초 | GPT 5.3 | 빠르고 효율적 |
| 2026 | GPT 5.4 | 최신 |
→ “진정한 에이전트 위임”의 핵심 장벽 = 장시간 정렬 유지 + 대규모 코드베이스 탐색
인터페이스 (단일 백엔드)
| 표면(Surface) | 특징 |
|---|---|
| Codex 앱 | 병렬 작업 시각화 최적, macOS/Windows |
| CLI | codex login → codex |
| IDE 확장 | VS Code 등 |
→ 모든 인터페이스가 동일 백엔드 공유 — 한 곳에서 토글한 설정이 모두 반영
사례: Peter Steinberger (OpenClaw 창시자)
이전: 10개+ CLI 창 동시 관리
지금: Codex 앱 → 병렬 에이전트 시각적 관리
사례: OpenAI 내부 Codex 실험
- 5개월간 수동 코드 작성 없이 내부 베타 구축
- AGENTS.md를 목차로 사용하고 docs/를 지식 베이스로 관리
- 스캐폴딩, 린트, 구조적 테스트, 관측성이 코드보다 중요해짐
- 관련: Codex 내부 실험 (수동 코드 없는 5개월)
다운로드
- macOS/Windows: openai.com/codex
- Windows: Microsoft Store
Codex 앱 핵심 설정
| 설정 | 옵션 |
|---|---|
| 모델 | GPT 5.4 등 |
| 추론 노력 | low / medium / high / extra high |
| Speed 모드 | fast / standard |
| 실행 환경 | 로컬 / Git worktree / 원격 클라우드 컨테이너 |
추론 노력 가이드
low → 간단한 질문
medium → 기본 (균형 최우수)
high → 복잡한 사고
extra → 장시간 깊은 추론
권한 모드
| 모드 | 동작 |
|---|---|
| 기본 ⭐ | 프로젝트 내 읽기/편집, 위험 명령은 승인 요청 |
| 전체 접근 | 컴퓨터 전체 + 네트워크 + 자동 실행 (주의) |
→ 신규 사용자는 기본 권한 권장
SDLC 7단계 전체 커버
OpenAI의 “Building an AI Native Engineering Team” 가이드 기준:
1. Plan (계획)
2. Design (설계)
3. Build (빌드)
4. Test (테스트)
5. Review (리뷰)
6. Document (문서화)
7. Deploy & Maintenance (배포·유지보수)
핵심: 코드 생성이 쉬워질수록 테스트와 리뷰가 더 중요
1. Plan (계획)
/plan 또는 Shift+Tab → Plan 모드 활성화
↓
Codex가 코드베이스 탐색
↓
후속 질문 제시 (인증 방식, 첫 릴리스 범위 등)
↓
가정(assumptions) 명시 → 사용자가 검증·수정
↓
구현 시작
데모: SwiftUI iOS 컴패니언 앱 계획
2. Design (설계) — MCP 연동
MCP (Model Context Protocol) = 외부 도구 컨텍스트 연결
지원 도구:
- Figma (디자인 링크 → 자동 코드 변환)
- Linear (티켓 → 자동 문서화)
- 기타 다수
미설정 시 → Codex가 자동 설치 안내
ChatGPT 앱 통합도 서드파티 연동으로 사용 가능
→ 관련: FigmaToCode, Serena MCP, MCP (Model Context Protocol)
3. Build (빌드)
가장 영향력 큰 단계. 데모 사례:
| 작업 | 결과 |
|---|---|
| N+1 쿼리 수정 + 회귀 테스트 | 자동 수행 |
| API 라우트 인증 누락 감사 | 병렬 실행 |
| NextAuth v4 → Auth.js v5 마이그레이션 | 병렬 실행 |
| Figma 디자인 → 코드 | 10개 파일, 320줄, CSS 수작업 ❌ |
Worktree 기능
로컬 프로젝트 사본 자동 생성
↓
병렬 작업 충돌 방지
↓
별도 리포 복사 불필요
자동 검증
agents.md에 명시한 명령 자동 실행:
- npx tsc (타입 체크)
- npm test (테스트)
- 린트 명령
↓
팀 컨벤션 준수 확인
“빌드 자체는 더 이상 병목이 아님 — 팀 규약 준수가 핵심”
iOS도 Xcode 열지 않고 앱 내에서 xcode build 실행 가능
4-5. Test & Review
/review 명령
- 베이스 브랜치 vs 로컬 미커밋 변경사항 코드 리뷰
- P0/P1 수준 버그 식별 특화 훈련
- 노이즈 적은 고신호 피드백
- PR 전 로컬에서 이슈 조기 발견
GitHub Cloud 네이티브 통합
- PR에 사전(proactive) / 사후(reactive) 자동 리뷰
- regex 규칙 검토 같은 인간이 놓치기 쉬운 P1 포착
- diff 패널에서 코멘트 추가 → 다음 대화 컨텍스트로 자동 반영
다른 SCM
- GitLab, Bitbucket → Codex SDK로 직접 연동 구축
6. Documentation (문서화)
“Codex의 가장 과소평가된 활용 영역”
- 시스템 다이어그램 자동 생성
- 기능 구현 시 문서 자동 업데이트
- Linear MCP 연동: 티켓의 수정사항·회귀 테스트·검증 내역을 Linear 보드에 자동 문서화
7. Deploy & Maintenance
- Codex 앱에서 Commit / Push / PR 생성 버튼 클릭으로 직접 수행
- 스택 트레이스 붙여넣기 → 전체 코드베이스 추론으로 원인 파악
Triage Page Skill
인시던트 ID 입력
↓
세부 정보 수집
↓
인시던트 확인
↓
메트릭·로그 검사
↓
패치까지 원스톱
→ 페이저듀티 대응을 수동 → 에이전트 위임으로 전환
PR Babysitter Skill
- PR의 CI/CD 파이프라인 지속 모니터링
- 문제 발생 시 자동 수정
- 최종 머지까지 자동 완료
- OpenAI 대규모 모노레포에서 실제 사용 중
Skills — 재사용 가능 워크플로우 패키징
구조
my-skill/
├── skill.md (필수: 메타데이터 + 에이전트 지침)
├── scripts/ (선택: 실행 스크립트)
├── docs/ (선택)
└── templates/ (선택)
→ MCP를 skill 내부에 임베드 가능
시스템 스킬
| 스킬 | 기능 |
|---|---|
| Skill Creator | 대화 중 “create a skill to find dead code paths” 요청 시 자동 스캐폴딩 |
| Skill Installer | 생성된 스킬을 로컬 스킬 디렉토리에 즉시 설치 |
활용 예시
긴 대화로 반복될 워크플로우 발견
↓
skill로 변환
↓
다음에는 한 번의 호출로 전체 워크플로우 실행
GitHub Issue Plan PR Skill 예시
하나의 프롬프트
↓ SDLC 전 단계 한 번에:
1. GitHub 이슈 트리아지
2. 계획 수립
3. 편집
4. 문서화
5. 드래프트 PR 생성
→ 관련: GPT-5.4 프론트엔드 디자인 가이드 (Frontend Skill 패키지)
Automations — 스케줄 기반 자동 실행
스킬 + 스케줄 = Automations
예시:
- Sentry 스킬: 매주 목요일 이슈 자동 수정 제안
- "What is everyone up to?": 매일 오전 9시 팀원 활동 요약
- 보안 감사: 매주 일요일 의존성 취약점 점검
→ 사용자 입력 없이 백그라운드에서 지속 작업
agents.md — 에이전트 행동 지침 파일
Cursor의 Rules, Windsurf 설정과 유사한 오픈 포맷 (OpenAI 독점 ❌)
3단계 우선순위 체계
| 우선순위 | 위치 | 용도 |
|---|---|---|
| 글로벌 | ~/.codex/agents.md | 개인 기본 설정 (팀 무관) |
| 리포 루트 | agents.md | 리포 전체 컨벤션 |
| 서브디렉토리 | agents.md | 마이크로서비스/하위 폴더별 |
→ Codex가 루트 → 현재 디렉토리 경로 따라 연결(concatenate), 더 구체적인 파일 우선
권장 항목
- 리포지토리 개요
- 실행 명령 (
npm test,npx tsc등) - 테스트 기대치
- 핵심 모듈 위치
- 커밋/PR 가이드라인
베스트 프랙티스
✓ /init 명령으로 자동 생성 (콜드 스타트 해소)
✓ 100줄 이하로 간결 유지 (OpenAI 내부 모노레포 기준)
✓ 길어지면 분리:
- planning.md
- code-review.md
- architecture.md
→ agents.md에서 참조
자동 개선 패턴
1. 매주 자동화:
Codex가 로컬 세션 로그 분석
→ agents.md 개선안 자동 제안
2. 회고 기반:
대화 끝 "retrospective" 요청
→ gotcha 섹션 또는 참고사항을 agents.md에 자동 반영
컨텍스트 관리
Codex 에이전트의 작동 원리
사용자가 명확한 목표 + 초기 방향 제공
↓
에이전트 루프:
1. 추론
2. 도구 호출
3. 파일 읽기
4. 리포지토리 검색
5. 코드 작성
6. 명령 실행
7. 결과 → 다음 모델 호출 피드백
↓ (반복)
점진적 이해 구축 + 진행
컴팩션 (Compaction)
대화가 컨텍스트 제한 근접
↓
Codex가 초기 부분 압축 (서버사이드)
↓ 원시 사고 체인(chain of thought) 기반
→ 클라이언트사이드보다 작업 실질 내용 더 잘 보존
실제 사례:
25시간 무중단 작업
+ 13~14회 컴팩션
= 컨텍스트 유지 성공 ⭐
OS 수준 샌드박싱
하니스 수준 경량 제한 ❌
↓
운영체제 수준 네트워크·파일 접근 제어 ✅
이유: 모델 발전 → 경량 보호 우회 가능성 대비
지원:
- macOS (네이티브)
- Windows (WSL보다 강화된 네이티브 Windows 샌드박스)
설정
# ~/.codex/config.toml
[approval]
mode = "on_request" # 정상 실행, 권한 상승 시 일시 정지
[sandbox]
mode = "..." # 접근 범위 세부 설정슬래시 명령
| 명령 | 기능 |
|---|---|
/plan | 계획 모드 |
/review | 코드 리뷰 |
/init | agents.md 자동 생성 |
/experimental | 실험적 기능 토글 |
| 파일 멘션 | @ |
| 세션 상태 | 확인 |
| 권한 변경 | 가능 |
→ CLI가 다른 인터페이스보다 약간 앞서 신기능 탑재
효과적 위임 프롬프팅
베스트 프랙티스
1. 최소한의 프롬프트 + 명확한 요소:
✓ 목표
✓ 제약 조건
✓ "완료" 기준
2. 검증 조건 내장:
- 성공 기준
- 실행할 테스트·빌드 명령
3. 오픈엔드 활용:
"성능 개선 아이디어 제안해줘"
"테스트 커버리지 부족 영역 찾아줘"
→ 사고 파트너로 활용
Codex 도입 3가지 핵심 실천
1. agents.md 생성 + 커스텀 설정
→ 일관된 결과의 기반
2. 실제 업무 작업 부여 + MCP 연결
→ 실전 체화
3. 빌드만이 아닌 SDLC 전체 루프 사용
→ 설계부터 배포·유지보수까지
다른 노트와의 연결
| 노트 | 연결점 |
|---|---|
| Codex CLI | CLI 인터페이스 상세 |
| Cursor Composer 2 = Kimi K2.5 RL 사건 | 경쟁 코딩 에이전트 |
| Claude Code CLI | Anthropic의 동급 제품 |
| 코딩 에이전트 하니스 & Hashline | 하니스 = agents.md 같은 역할 |
| Claude 스크린샷 루프 (3D 작업) | 같은 패턴 — AI 자기 검증 인프라 |
| GPT-5.4 프론트엔드 디자인 가이드 | Frontend Skill (Codex 활용) |
| FigmaToCode | Codex와 MCP로 연동 가능 |
| Serena MCP | Codex의 MCP 생태계 |
| OmniCoder-9B | 같은 “에이전트 행동 학습” 메시지 |
메타 패턴
Claude Code, Cursor, Codex 모두 같은 방향:
단순 코드 생성 ❌
↓
계획 + 구현 + 검증 + 자동화 풀스택 ✅
공통 요소:
- 행동 지침 파일 (agents.md, .cursorrules, CLAUDE.md)
- MCP 통합
- 스크린샷·검증 루프
- 멀티 에이전트 병렬 실행
- 코드베이스 인덱싱
→ **“AI 코딩 도구의 표준화”**가 빠르게 진행 중