Codex Subagent 사용 방법

ChatGPT Pro 대란 때 구입한 이용권을 활용하고자 요즘 Codex를 메인으로 사용하는데 subagent 기능이 유용해서 사용법을 정리해봤습니다.

 

subagent

Codex CLI는 터미널에서 실행하는 OpenAI의 코딩 에이전트입니다. 현재 작업 중인 디렉터리의 코드를 읽고, 수정하고, 명령을 실행할 수 있으며, 복잡한 작업은 여러 역할로 나누어 처리할 수 있습니다. 이때 사용하는 핵심 기능이 바로 subagent입니다. 

subagent는 하나의 Codex 세션 안에서 역할이 다른 보조 에이전트들을 분리해서 실행하는 방식입니다. 예를 들어 코드 탐색 전용 agent, 구현 전용 agent, 문서 검증 전용 agent처럼 역할을 나누면, 메인 agent가 이들을 오케스트레이션하면서 결과를 모아 최종 응답을 정리할 수 있습니다. OpenAI 문서에서도 subagent를 “큰 작업을 병렬화하고, 전문화된 agent에게 위임하는 방식”으로 설명합니다.

또 하나 중요한 점은, Codex가 subagent를 마음대로 자동 생성하지는 않는다는 것입니다. 공식 문서 기준으로 Codex는 사용자가 명시적으로 요청했을 때만 새 subagent를 spawn합니다. 그래서 subagent는 “자동 마법”이라기보다, 사용자가 설계한 작업 분업 구조를 Codex가 실행해주는 기능에 가깝습니다.

 

왜 subagent를 쓰는가

일반적인 단일 agent 방식은 간단한 수정에는 충분하지만, 작업이 길어질수록 한 세션 안에 너무 많은 맥락이 섞이게 됩니다. 반면 subagent를 사용하면 역할을 나눠서 다음과 같은 방식으로 운영할 수 있습니다.

• explorer: 코드 구조 파악, 영향 범위 분석
• worker: 실제 구현 및 수정
• reviewer: 버그, 보안, 테스트 누락 검토
• docs_researcher: 공식 문서나 API 동작 검증

Codex는 기본적으로 default, worker, explorer 같은 내장 agent를 제공하고, 사용자가 직접 custom agent를 추가할 수도 있습니다. custom agent는 글로벌(~/.codex/agents/) 또는 프로젝트 로컬(.codex/agents/)에 TOML 파일로 정의합니다.

탐색과 구현과 검토를 한 agent에게 한꺼번에 시키면 맥락이 뭉개지기 쉽지만, 역할을 분리하면 각 agent가 더 좁고 선명한 책임을 가지게 됩니다. OpenAI 문서도 좁고 명확한 역할을 가진 agent일수록 잘 동작한다고 설명합니다.

 

실제로 subagent를 사용하며 인상적이었던 점은 mainagent가 subagent들을 관리하면서 PM 역할을 해주는 점이었습니다.

여러개의 subagent들이 각각 작업을 수행하는데 결과를 취합하고 또 다른 subagent에게 작업을 지시하는 역할을 중간에 해주니 사용자 입장에서는 수고스러움이 많이 덜어졌습니다.

 

 

subagent를 사용하기 위한 준비사항

1. Codex CLI 설치 및 로그인
2. 프로젝트별 공통 지침 정리
3. agent 역할 파일 분리

 

AGENTS.md로 공통 지침 넣기

subagent를 쓰기 전에 가장 먼저 해두면 좋은 것이 AGENTS.md입니다. Codex는 작업을 시작하기 전에 AGENTS.md를 읽습니다. 글로벌 범위(~/.codex/AGENTS.md)와 프로젝트 범위의 AGENTS.md를 계층적으로 읽어서 작업 지침으로 사용합니다. 

예를 들어 글로벌 기본 규칙은 이렇게 둘 수 있습니다.

mkdir -p ~/.codex

~/.codex/AGENTS.md

# ~/.codex/AGENTS.md

## Working agreements
- 응답은 한국어로 작성한다.
- 코드 수정 후 관련 테스트 명령을 우선 제안한다.
- 새 의존성 추가 전에는 이유를 설명한다.
- 변경 범위가 크면 먼저 영향 범위를 요약한다.

프로젝트별로는 저장소 루트에 AGENTS.md를 두면 됩니다.

./AGENTS.md

# Project guidance

## Repo rules
- 프론트엔드 수정 시 build 결과 영향을 함께 점검한다.
- 백엔드 수정 시 API 스펙 변경 여부를 반드시 확인한다.
- PR 리뷰 시 버그, 테스트 누락, 회귀 가능성을 우선 본다.

이런 초기 설정을 해두면 매번 프롬프트로 반복하지 않아도 되고, 메인 agent뿐 아니라 subagent까지 일관된 작업 기준을 공유할 수 있습니다.

 

subagent 기본 설정 파일 만들기

subagent는 ~/.codex/agents/ 또는 .codex/agents/ 아래에 에이전트별 TOML 파일을 두는 방식으로 설정합니다. 공식 문서 기준 각 파일에는 최소한 아래 3개 필드가 있어야 합니다.

• name
• description
• developer_instructions

또한 필요하면 model, model_reasoning_effort, sandbox_mode, mcp_servers, skills.config, nickname_candidates등을 함께 넣을 수 있습니다. 

먼저 agent 설정 폴더를 만듭니다.

mkdir -p .codex/agents

.codex/config.toml에 subagent 관련 전역 옵션을 추가합니다.

.codex/config.toml

[agents]
max_threads = 6
max_depth = 1

 

• max_threads: 동시에 열릴 수 있는 agent thread 최대 수
• max_depth: subagent의 중첩 생성 깊이

 

아래는 3가지 역할의 Agent 설정 예시입니다. 원하는 역할이 있다면 해당 역할로 정의하시면 되고, 아래 링크의 Collection을 활용해서 Agent를 생성해도됩니다.

awesome-codex-subagents

 

Explorer Agent

코드 구조를 탐색하고 영향 범위를 정리하는 역할입니다.

.codex/agents/explorer.toml

name = "explorer"
description = "코드베이스를 읽고 관련 파일, 흐름, 영향 범위를 파악하는 읽기 전용 탐색 agent"
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
항상 탐색에 집중한다.
관련 파일, 함수, 진입점, 호출 흐름을 정리한다.
수정안 제시는 최소화하고, 먼저 근거를 수집한다.
"""

코드 구조를 탐색하고 영향 범위를 정리하는 역할입니다.

 

Worker agent

실제 구현을 담당하는 역할입니다.

.codex/agents/worker.toml

name = "worker"
description = "구현과 수정 작업을 수행하는 실행 중심 agent"
model = "gpt-5.4"
model_reasoning_effort = "medium"
developer_instructions = """
구현 작업에 집중한다.
영향 범위를 벗어난 리팩토링은 자제한다.
필요한 파일만 수정하고, 변경 이유를 짧게 설명한다.
"""

 

Reviewer agent

버그, 보안, 테스트 누락을 검토하는 역할입니다.

.codex/agents/reviewer.toml

name = "reviewer"
description = "정확성, 보안, 회귀 가능성, 테스트 누락을 검토하는 리뷰 agent"
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
코드를 소유자 관점에서 검토한다.
정확성, 보안, 회귀 가능성, 테스트 누락을 우선순위로 본다.
스타일 지적보다 실제 문제를 먼저 제시한다.
"""

 

display nickname 설정하기

여러 subagent를 동시에 돌릴 때, 화면에 같은 이름만 반복되면 헷갈릴 수 있습니다. 이를 위해 nickname_candidates를 설정할 수 있습니다. 이 값은 UI 표시용 별칭이며, 실제 agent 식별은 name으로 이뤄집니다. 

name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
developer_instructions = """
Review code like an owner.
"""
nickname_candidates = ["Atlas", "Delta", "Echo"]

이렇게 해두면 CLI나 앱에서 좀 더 읽기 쉬운 이름으로 표시될 수 있습니다. 특히 같은 유형의 agent를 여러 개 spawn할 때 유용합니다. 

설정이 완료되면 아래와 같이 Codex CLI에서 Subagent를 언급한 프롬프트를 입력하면 Subagent를 활용한 작업을 시작합니다.

현재 브랜치를 기준으로 작업해줘.
먼저 explorer agent를 사용해서 영향 범위를 분석하고,
그 다음 worker agent가 수정안을 만들고,
마지막으로 reviewer agent가 회귀 가능성과 테스트 누락을 검토해줘.
모든 결과를 기다린 뒤 최종 요약을 한국어로 정리해줘.

 

 

현재 세션의 Subagent 확인

› /agent
 
  /agent  switch the active agent thread


  Subagents
  Select an agent to watch. ⌥ + ← previous, ⌥ + → next.
 
› 1. • Main [default] (current)  019a2erwqd1f85-86asewraeswr2f-73rtew61-adyh473
  2. • Huygens [explorer]        019a2erwqd1f85-86asewraeswr2f-73rtew61-adyh473
  3. • Hilbert [explorer]        019a2erwqd1f85-86asewraeswr2f-73rtew61-adyh473
  4. • Fermat [worker]           019a2erwqd1f85-86asewraeswr2f-73rtew61-adyh473
  5. • Sartre [explorer]         019a2erwqd1f85-86asewraeswr2f-73rtew61-adyh473
  6. • Hume [explorer]           019a2erwqd1f85-86asewraeswr2f-73rtew61-adyh473

 

토큰 잔량 확인

/status

╭────────────────────────────────────────────────────────────────────────────────────────╮
│  >_ OpenAI Codex (v0.116.0)                                                            │
│                                                                                        │
│ Visit https://chatgpt.com/codex/settings/usage for up-to-date                          │
│ information on rate limits and credits                                                 │
│                                                                                        │
│  Model:                       gpt-5.3-codex (reasoning none, summaries auto)           │
│  Directory:                   ~/WebstormProjects/pg                                    │
│  Permissions:                 Custom (workspace-write, on-request)                     │
│  Agents.md:                   AGENTS.md                                                │
│  Account:                     ai@taeseong.me (Pro)                                     │
│  Collaboration mode:          Default                                                  │
│  Session:                     019a2erwqd1f85-86asewraeswr2f-73rtew61-adyh473           │
│                                                                                        │
│  Context window:              22% left (203K used / 258K)                              │
│  5h limit:                    [████████████████████] 99% left (resets 14:13)           │
│  Weekly limit:                [████████████████████] 99% left (resets 22:56 on 3 Apr)  │
│  GPT-5.3-Codex-Spark limit:                                                            │
│  5h limit:                    [████████████████████] 100% left (resets 16:04)          │
│  Weekly limit:                [████████████████████] 100% left (resets 11:04 on 4 Apr) │
╰────────────────────────────────────────────────────────────────────────────────────────╯