최근 OpenAI Codex에 "서브에이전트(subagents)"가 정식으로 들어오면서, 한 명이 하던 일을 여러 명에게 쪼개 던지는 방식이 쉬워졌습니다1. 이제는 "원인 재현 담당, 코드 추적 담당, 최소 수정 담당"처럼 역할을 나눠 병렬로 굴릴 수 있어, 큰 코드베이스에서 특히 체감이 큽니다.
이 글에서는 Codex 서브에이전트가 무엇인지, 커스텀 에이전트를 어떻게 쓰는지, 그리고 CLI 실전 워크플로우까지 한 번에 정리해봅니다.
Codex 서브에이전트란? "한 번에 여러 갈래로 파고들기"
서브에이전트는 간단히 말해, 메인 에이전트가 일을 쪼개서 "별도의 작업 스레드"로 동시에 처리하게 만드는 기능입니다. 예를 들어 버그를 고칠 때 사람은 보통 "재현→원인 추적→수정→검증"을 순서대로 하죠. 서브에이전트를 쓰면 재현과 추적을 동시에 진행하고, 추적 결과가 나오자마자 수정 담당이 바로 최소 패치를 만들게 할 수 있습니다.
Codex 쪽 기본 역할로는 explorer/worker/default 같은 프리셋이 언급되는데, 감각적으로는 explorer는 탐색(파일/구조 파악), worker는 잔업을 다량 병렬 처리하는 쪽에 가깝습니다1. 즉 "한 번에 많이"가 필요할수록 서브에이전트의 값이 올라갑니다.
다만 병렬이 무조건 정답은 아닙니다. 서로 같은 파일을 만지는 작업을 동시에 시키면 충돌 비용이 커집니다. "독립적으로 나뉘는 일"부터 나누는 게 핵심입니다.
커스텀 에이전트: 내 팀원(역할·규칙·모델)을 TOML로 저장하기
서브에이전트가 "여러 명을 동시에 부르는 버튼"이라면, 커스텀 에이전트는 "각자 직무기술서가 있는 팀원"입니다. Codex는 ~/.codex/agents/ 아래에 TOML로 에이전트를 정의해, 특정 지시문(규칙)과 특정 모델을 고정해둘 수 있습니다1.
여기서 재미있는 포인트는 모델까지 역할에 맞춰 고를 수 있다는 겁니다. 예를 들어 "초고속 잔업 처리"는 gpt-5.3-codex-spark 같은 빠른 모델로, "감사(audit)·보안 리뷰"는 더 신중한 설정으로 분리하는 식이죠. 그러면 프롬프트에서 사람 이름 부르듯 에이전트를 지목해 조합할 수 있습니다. 문서 예시도 딱 그 느낌입니다. "재현은 A, 코드 경로 추적은 B, 수정은 C"처럼요1.
결국 커스텀 에이전트는 프롬프트를 길게 쓰는 대신, "우리 팀 규칙"을 파일로 빼서 재사용하는 장치입니다. 반복 업무일수록 효과가 커집니다.
Codex CLI 실전: 자동화는 '권한'과 '세션' 설계가 반이다
현장에서 Codex를 제대로 굴리려면 기능 자체보다 운영 감각이 더 중요합니다. Codex CLI는 인터랙티브(TUI)로도 쓰고, codex exec로 스크립트처럼도 돌릴 수 있어 자동화 접점이 넓습니다2.
여기서 꼭 챙길 건 권한(Approval/Sandbox)입니다. 탐색 단계에서는 Read Only에 가깝게, 확실한 수정 단계에서만 write/auto를 주는 식으로 "단계별로 권한을 올리는" 습관이 안전합니다2. 그리고 긴 작업은 세션을 이어가는 게 효율적이라 resume 같은 흐름을 워크플로우에 넣어두면 컨텍스트 낭비가 줄어듭니다2.
또 한 가지. Codex CLI 쪽 서브에이전트는 기본 동시 실행 수에 대한 제약 이야기도 커뮤니티에서 나옵니다. 기본값(예: 6개)을 더 늘리고 싶다는 요청이 올라올 정도로, 병렬 처리 니즈가 실제로 크다는 뜻이죠3. 즉 팀/프로젝트 규모가 커질수록 "몇 명까지 동시에 돌릴 건지"가 성능 튜닝 포인트가 됩니다.
시사점: 서브에이전트는 '속도'보다 '구조'를 바꾼다
Codex 서브에이전트와 커스텀 에이전트의 진짜 가치는, 코딩을 더 빨리 하는 게 아니라 "일을 나누는 방식"을 표준화한다는 점입니다. 재현/추적/수정/검증 같은 역할을 고정해두면, 다음 버그에서도 같은 조합으로 출발할 수 있습니다.
처음 적용할 때는 작게 시작하는 게 좋습니다. "탐색 담당 1명 + 수정 담당 1명"처럼 최소 조합으로 패턴을 만들고, 그다음에 테스트 작성, 리뷰, 성능 점검까지 역할을 늘리세요. 그리고 병렬화는 독립 작업부터. 이 원칙만 지켜도 Codex 서브에이전트는 단순 기능이 아니라, 여러분 팀의 개발 리듬을 바꾸는 도구가 됩니다.
참고
1Use subagents and custom agents in Codex
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.