Sub-Agent Usage Details — Codex-Focused
Codex CLI / Codex Desktop App에서 "서브에이전트"에 해당하는 작업을 수행하고, 순차 실행하고, 자동화 단위로 확장하는 방법을 Codex 계열에 한정해 정리한 상세 문서 | 공통 개념은 4장 §1 레퍼런스에서, Claude 계열은 4장 §1-A에서, Antigravity 계열은 4장 §1-B에서 다룬다.
codex --version · Codex Desktop App: 앱 내 정보 화면1. 역할 정의하기
Codex CLI와 Codex Desktop App은 정의 파일을 사전에 만들 필요가 없다. 대신 워크스페이스 루트의 agents/<name>.md에 이미 있는 각 전문 에이전트의 정의 파일을 PM이 세션 시작 시 읽어들여 역할 컨텍스트로 사용한다. Claude 계열의 .claude/agents/*.md와 형식은 비슷하지만 용도가 다르다 — Claude에서는 호출 시점에 subagent_type으로 참조되는 "실행 가능한 정의"지만, Codex에서는 PM이 참고 문서로 불러와 그 역할처럼 사고하기 위한 자료다.
Codex Desktop App agents/<name>.md — 읽기 전용 역할 컨텍스트
Codex Desktop App에서 PM은 워크스페이스의 agents/reviewer.md 같은 파일을 대화 중에 직접 불러와 "이 역할이 정의한 방식대로 작업하겠다"고 선언한다. 파일 자체는 Claude 계열과 같은 frontmatter 형식을 공유할 수 있지만, Codex가 이를 실행 가능한 서브에이전트로 스폰하지는 않는다 — 그냥 참조되는 문서다. Codex CLI에서도 완전히 같은 파일이 완전히 같은 방식으로 사용된다 — 둘 사이에 역할 정의 방식의 차이는 없다.
agents/reviewer.md 내용 (Claude용과 동일한 형식일 수 있음): --- name: reviewer description: 텍스트 파일의 오탈자와 논리적 허점을 검토한다. --- 너는 리뷰어 역할이다. 주어진 파일을 읽고 개선점을 목록으로 정리해 보고한다.
Codex CLI — Codex Desktop App과 동일한 agents/<name>.md
Codex Desktop App에서 쓴 것과 완전히 같은 agents/<name>.md 파일을 그대로 참조한다. Desktop App과 CLI 사이에 역할 정의 방식의 차이는 없다.
| 비교 항목 | Claude 계열 (.claude/agents) | Codex 계열 (agents/<name>.md) |
|---|---|---|
| 파일 위치 | .claude/agents/*.md (플랫폼 전용 폴더) |
agents/<name>.md (워크스페이스 공통 폴더 — 플랫폼 전용 사본 없음) |
| 용도 | 실행 가능한 서브에이전트 정의 — subagent_type으로 호출 |
읽기 전용 역할 컨텍스트 — PM이 참고해 그 역할처럼 사고 |
| 호출 메커니즘 | Agent/Task 툴 |
없음 — PM이 파일을 읽고 "이 역할을 수행하겠다"고 선언할 뿐 |
2. 역할 수행/전환하기
Codex CLI와 Codex Desktop App 모두 별도 컨텍스트를 가진 서브에이전트를 스폰하는 대신, PM이 같은 세션 안에서 역할을 갈아입는다. "지금은 설계자 역할로 이 파일을 분석하고, 다음은 구현자 역할로 코드를 작성한다"는 식으로 단계를 순서대로 밟는다.
Codex Desktop App — PM의 순차 역할 전환
Codex Desktop App에서 PM에게 여러 전문성이 필요한 작업을 요청하면, PM은 각 단계에서 해당 역할의 정의 파일을 불러와 그 역할의 관점으로 작업한 뒤 다음 역할로 넘어간다. 병렬로 동시에 여러 역할이 존재하지 않으며, 각 단계는 이전 단계의 결과를 이어받는다. Codex CLI에서도 완전히 같은 순차 전환 방식이 그대로 동작한다 — 채팅창 대신 터미널에서 같은 요청을 하면 동일하게 처리된다.
사용자: "src/auth/login.ts의 세션 만료 처리 로직을 검토하고, 버그가 있으면 고쳐줘." PM 내부 진행 (한 세션 안에서 순차): 1. agents/reviewer.md를 역할 컨텍스트로 불러와 코드를 검토 2. 발견한 문제를 정리 3. agents/automation-engineer.md로 역할을 전환해 수정 사항을 구현
Codex CLI — Codex Desktop App과 동일한 순차 전환
Codex Desktop App과 완전히 같은 순차 역할 전환 방식이다. 터미널에서 자연어로 요청하면 동일한 방식으로 PM이 역할을 갈아입으며 작업한다.
3. 병렬 실행
Codex 계열은 세션 내부 병렬 실행을 지원하지 않는다. 모든 역할 전환이 하나의 선형 세션 안에서 순서대로 일어난다.
Codex Desktop App — 여러 창으로 세션 간 병렬
Codex Desktop App에서 서로 다른 작업을 동시에 진행하려면 앱 창(또는 탭)을 여러 개 열어 각각 별도의 세션으로 작업한다. 같은 파일을 여러 세션이 동시에 건드리지 않는 한 충돌하지 않는다. Codex CLI에서도 같은 원리로 터미널을 여러 개 열어 세션 간 병렬을 구현한다.
Codex CLI — 여러 터미널로 세션 간 병렬
Codex Desktop App과 완전히 같은 원리다. 한 codex 세션이 API 레이어를 리팩터링하는 동안 다른 세션이 테스트를 작성해도, 같은 파일을 건드리지 않는 한 충돌하지 않는다.
| 항목 | Codex Desktop App | Codex CLI |
|---|---|---|
| 병렬 실행 단위 | 세션 내부 병렬 없음 / 여러 창으로 세션 간 병렬만 가능 | 세션 내부 병렬 없음 / 여러 터미널로 세션 간 병렬만 가능 |
4. 자동화/훅
Codex 계열에서 자동화·훅은 Desktop App과 CLI 사이에 차이가 없다 — 둘 다 워크스페이스 훅 스위트를 전혀 실행하지 않는다.
Codex Desktop App — 훅 미실행, 프롬프트로 자체 강제
Claude Code의 PostToolUse/TeammateIdle/TaskCompleted 같은 자동 발화 이벤트에 대응하는 장치가 Codex Desktop App에는 없다. 감사 스크립트 실행이나 게이트 규칙 같은 거버넌스는 CODEX.md에 명시된 지침을 PM이 매 세션 스스로 인지하고 실행하는 방식(프롬프트 자체 강제)으로 대신한다. Codex CLI도 완전히 같다 — 훅 메커니즘 자체가 없다.
Codex CLI — Codex Desktop App과 동일하게 훅 없음
Codex Desktop App과 완전히 같다. CODEX.md에 적힌 지침(예: "파일을 수정한 뒤에는 bun scripts/audit.ts를 실행하라")을 PM이 세션 안에서 스스로 인지하고 실행해야 한다 — 이벤트에 반응해 자동으로 실행되는 장치는 없다.
# CODEX.md에 적힌 지침 예시 (자동 발화 아님, PM이 직접 인지·수행): # "파일을 Write/Edit한 뒤에는 항상 # bun scripts/audit.ts를 실행해 감사한다." bun scripts/audit.ts
참고 링크
- 📖 Codex — 공식 문서
- ⚙️ 4장 §1 공통 레퍼런스 — 04_Practice_Manual.html
- ⚙️ 4장 §1-A Claude 중심 — 04_Practice_Manual_A.html
- ⚙️ 4장 §1-B Antigravity 중심 — 04_Practice_Manual_B.html
- ⚙️ 도구 비교 §3 — Codex Desktop App vs Codex CLI
Codex CLI/Desktop App 기준 | 2026년 9월