Codex Subagents 사용법 정리 2026 글로벌과 프로젝트 에이전트 경로 차이까지 한 번에

Posted on by

AI 코딩 에이전트가 “하나의 만능 비서”였던 건 작년까지 얘기다. 2026년 3월, OpenAI Codex가 서브에이전트를 공식 지원하면서 에이전트 관리 자체가 “구조 설계” 문제로 바뀌었다. 어제까지는 “프롬프트 잘 쓰면 되는 거 아냐?”였다면, 오늘부터는 “이 에이전트 파일을 어디에 두지?”가 첫 번째 질문이 된다. Codex든 AI 코딩 도구든 직접 에이전트를 나눠서 작업하는 사람이라면, 경로 하나 잘못 고르면 다른 프로젝트에서 에이전트가 안 뜨거나, 반대로 안 불러야 할 에이전트가 끼어들는 경우를 겪게 된다.

Codex 서브에이전트는 글로벌 경로(~/.codex/agents/)와 프로젝트 경로(.codex/agents/)로 나뉘고, 이름이 겹치면 프로젝트 에이전트가 우선한다. TOML 형식 하나당 에이전트 하나를 정의하며, 자동 호출이 아니라 프롬프트에서 명시적으로 위임해야만 동작한다. 커뮤니티 컬렉션 Awesome Codex Subagents에는 130개 이상의 역할별 에이전트가 10개 카테고리로 정리돼 있어 바로 복사해서 쓸 수 있다(VoltAgent, 2026년 3월 기준 GitHub 655 스타).

1. 왜 경로부터 정리해야 하는가

평소에 에이전트를 좀 구조화해서 써왔다. 옵시디언 볼트에 .claude/agents/ 아래 19개 이상의 에이전트를 두고, 블로그 파이프라인이나 트레이딩 코치 같은 워크플로를 돌리고 있었다. 그런데 Codex가 서브에이전트를 공식 지원하면서, 구조가 비슷하면서도 결정적으로 다른 점이 보였다.

Claude Code 에이전트 체계는 .claude/agents/에 Markdown 파일로 정의하고, @에이전트명으로 호출한다. 글로벌은 ~/.claude/agents/, 프로젝트는 .claude/agents/. 파일 포맷은 .md.

Codex 서브에이전트 체계는 .codex/agents/에 TOML 파일로 정의하고, 프롬프트에서 명시적으로 위임한다. 글로벌은 ~/.codex/agents/, 프로젝트는 .codex/agents/. 파일 포맷은 .toml.

개념은 같다. 글로벌은 모든 프로젝트에서 쓸 에이전트, 프로젝트는 해당 레포에서만 쓸 에이전트. 차이는 포맷(MD vs TOML)과 호출 방식(@멘션 vs 프롬프트 위임)이다.

근데 진짜 문제는 “어디에 뭘 둘지” 기준이 없으면, 에이전트가 20개 넘어가면서 혼란이 시작된다는 거다. 나도 에이전트 40개 넘게 운영하면서 이 문제를 겪어봤다. 공통 리뷰어를 글로벌에 뒀어야 했는데 프로젝트에 두는 바람에, 다른 레포에서 못 불러온 적이 있다.

2. 글로벌 에이전트 vs 프로젝트 에이전트 — 경로와 우선순위

2.1 경로 비교표

구분 경로 적용 범위 우선순위
글로벌 에이전트 ~/.codex/agents/ 모든 프로젝트 낮음
프로젝트 에이전트 .codex/agents/ 현재 프로젝트만 높음

핵심: 이름이 겹치면 프로젝트 에이전트가 이긴다.

예를 들어, 글로벌에 reviewer.toml이 있고 프로젝트에도 reviewer.toml이 있으면, 그 프로젝트에서는 프로젝트 버전이 우선한다. 글로벌 버전은 무시된다. 다른 프로젝트에서는 글로벌 버전이 쓰인다.

이건 환경변수에서 로컬이 글로벌을 오버라이드하는 것과 같은 원리다. .gitconfig에서 ~/.gitconfig보다 .git/config가 우선하는 것처럼.

2.2 어떤 에이전트를 어디에 둘지 판단 기준

이걸 정리하는 데 시간이 좀 걸렸다. 처음엔 “자주 쓰는 건 글로벌”이라고 생각했는데, 그러면 글로벌이 20개를 넘긴다. 그래서 기준을 다시 잡았다.

글로벌에 두면 좋은 에이전트:

  • 범용 리뷰어: 어떤 레포든 PR 리뷰 패턴은 비슷하다. reviewer.toml은 글로벌에 하나 두면 된다.
  • 문서 탐색기: docs-researcher.toml처럼 API 문서 MCP를 연결하는 읽기 전용 에이전트. 프로젝트와 무관하게 공통으로 쓸 수 있다.
  • 검색 전문가: search-specialist.toml 같은 코드베이스 탐색용. 어떤 레포든 “이 함수 어디서 쓰이지?” 패턴은 같다.
  • 보안 감사자: security-auditor.toml. 보안 체크리스트는 프로젝트마다 크게 다르지 않다.

프로젝트에 두면 좋은 에이전트:

  • 프레임워크 전문가: nextjs-developer.toml, django-developer.toml 같은 건 해당 프로젝트에서만 필요하다. Next.js 레포에 Django 에이전트가 있으면 혼란만 된다.
  • 도메인 특화: FinTech 프로젝트면 fintech-engineer.toml, 게임이면 game-developer.toml. 프로젝트 특성에 딱 맞는 에이전트.
  • 글로벌 오버라이드: 글로벌 reviewer.toml이 있는데, 특정 프로젝트에서만 리뷰 기준이 다르다면 프로젝트에 같은 이름으로 두면 된다. 해당 프로젝트에서만 커스텀 버전이 쓰인다.
  • 실험용: 이 프로젝트에서만 시험해보고, 괜찮으면 나중에 글로벌로 올리는 에이전트.

2.3 내가 실제로 나눈 방식

참고로 나는 기존 Claude Code 에이전트 체계를 운영하면서 이미 글로벌/프로젝트 분리를 하고 있었다. ~/.claude/agents/에는 범용 워크플로(블로그 파이프라인, URL 요약기 등), .claude/agents/에는 프로젝트별 에이전트(트레이딩 코치, 온톨로지 관리 등)를 두는 방식이다.

Codex로 옮기더라도 원리는 같다. 아래처럼 정리할 수 있다.

~/.codex/agents/          ← 글로벌 (모든 프로젝트 공통)
├── reviewer.toml         ← 범용 PR 리뷰
├── docs-researcher.toml  ← 문서 탐색
├── search-specialist.toml ← 코드 검색
└── security-auditor.toml ← 보안 감사

프로젝트A/.codex/agents/   ← 프로젝트 전용
├── nextjs-developer.toml ← 이 프로젝트만 Next.js
├── reviewer.toml         ← 글로벌 reviewer 오버라이드
└── api-designer.toml     ← 이 프로젝트 API 설계

프로젝트B/.codex/agents/   ← 다른 프로젝트
├── django-developer.toml
└── database-administrator.toml

프로젝트A에서 reviewer를 부르면 프로젝트A의 reviewer.toml이 쓰이고, 프로젝트B에서 reviewer를 부르면 글로벌의 reviewer.toml이 쓰인다. 직관적이다.

3. TOML 파일 구조 — 실전 작성법

3.1 필수 필드 3개

에이전트 하나를 정의하는 데 필요한 최소 필드는 딱 3개다.

name = "reviewer"
description = "PR 리뷰에 집중. 정확성, 보안, 누락된 테스트를 찾는다."
developer_instructions = """
코드를 오너처럼 리뷰해라.
정확성, 보안, 동작 회귀, 누락된 테스트 커버리지를 우선한다.
구체적인 발견을 먼저 쓰고, 재현 단계가 있으면 포함한다.
스타일만의 코멘트는 진짜 버그가 숨어있을 때만.
"""
  • name: Codex가 에이전트를 식별하는 키. 프롬프트에서 이 이름으로 위임한다.
  • description: 사람이 읽는 설명. “이 에이전트를 언제 쓸지”를 한 문장으로.
  • developer_instructions: 실제 동작 지시문. 이게 에이전트의 “성격”과 “능력”을 정의한다.

3개만 있으면 동작한다. 나머지는 전부 선택.

3.2 선택 필드와 의미

필드 기본값 설명
model 부모 세션 모델 에이전트별로 다른 모델 지정 가능
model_reasoning_effort 부모 설정 low, medium, high 중 선택
sandbox_mode 부모 설정 read-only 또는 workspace-write
mcp_servers 없음 에이전트 전용 MCP 서버 연결
skills.config 없음 에이전트에 스킬 연결
nickname_candidates 없음 같은 에이전트 여러 개 띄울 때 UI 표시명

여기서 제일 중요한 건 sandbox_mode와 model이다.

sandbox_mode: 리뷰어나 감사자는 read-only로 두는 게 안전하다. 코드를 분석만 하고 수정은 안 한다. 개발자나 수정 에이전트만 workspace-write로 열어준다. 이러면 “리뷰어가 코드를 멋대로 고치는” 사고를 막을 수 있다.

model: Awesome Codex Subagents 컬렉션에서 쓰는 모델 라우팅 전략이 참고할 만하다.

모델 용도 에이전트 예시
gpt-5.4 깊은 추론. 아키텍처 리뷰, 보안 감사, 금융 로직 security-auditor, architect-reviewer
gpt-5.3-codex-spark 빠른 스캔, 검색, 가벼운 리서치 search-specialist, docs-researcher

무거운 에이전트는 비싼 모델, 가벼운 에이전트는 싼 모델. 이걸 에이전트 파일 단위로 정하는 거다. Claude Code 쪽에서 opus/sonnet/haiku로 모델을 나누는 것과 같은 원리다.

3.3 실전 TOML 예시 4개

1) 보안 감사자 (글로벌용)

name = "security-auditor"
description = "보안 취약점 감사. OWASP Top 10, 인증/권한, 입력 검증에 집중."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
developer_instructions = """
보안 관점에서 코드를 분석해라.
OWASP Top 10, 인증/인가 결함, 입력 검증 누락, 비밀정보 노출을 우선 확인한다.
발견된 취약점은 심각도(Critical/High/Medium/Low)와 재현 경로를 함께 보고한다.
코드를 수정하지 않는다. 분석과 보고만 한다.
"""

이건 어떤 프로젝트에서든 쓸 수 있으니까 ~/.codex/agents/에 둔다.

2) Next.js 개발자 (프로젝트용)

name = "nextjs-developer"
description = "Next.js 14+ App Router, Server Components, streaming 전문."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
developer_instructions = """
Next.js 14 이상의 App Router 패턴으로 개발해라.
Server Components를 기본으로 쓰고, 클라이언트 컴포넌트는 'use client'를 명시적으로 붙여라.
데이터 패칭은 서버 컴포넌트에서 직접 하고, 캐싱 전략을 명시해라.
에러 핸들링은 error.tsx, 로딩 상태는 loading.tsx를 활용해라.
"""

이건 Next.js 프로젝트의 .codex/agents/에만 둔다.

3) 문서 탐색기 (글로벌용, MCP 연결)

name = "docs-researcher"
description = "문서 MCP로 API 동작과 프레임워크 사양을 확인하는 읽기 전용 에이전트."
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
문서 MCP 서버로 API, 옵션, 버전별 동작을 확인해라.
간결한 답변에 공식 문서 링크나 정확한 참조를 포함한다.
코드 변경은 하지 않는다. 팩트 확인과 정보 전달만 한다.
"""

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

[mcp_servers] 섹션으로 에이전트 전용 MCP를 붙일 수 있다. 이 에이전트만 이 MCP를 쓴다.

4) 코드 매퍼 (읽기 전용, 탐색 전문)

name = "code-mapper"
description = "코드 경로 매핑, 의존 관계 추적, 소유 경계 분석."
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
주어진 기능이나 버그에 관련된 코드 경로를 추적해라.
파일 간 의존 관계, 호출 체인, 데이터 흐름을 시각적으로 정리해라.
코드를 수정하지 않는다. 지도만 그려라.
"""

4. config.toml — 에이전트 동시 실행 설정

에이전트를 정의했으면, 동시에 몇 개까지 돌릴지도 정해야 한다. .codex/config.toml 또는 글로벌 config.toml의 [agents] 섹션에서 설정한다.

[agents]
max_threads = 6
max_depth = 1
job_max_runtime_seconds = 1800
설정 기본값 의미
max_threads 6 동시에 열 수 있는 에이전트 스레드 상한
max_depth 1 스폰 깊이. 1이면 자식만 허용, 손자는 막음
job_max_runtime_seconds 1800 CSV 배치 워커의 타임아웃 (초)

max_depth = 1이 왜 중요한지 얘기하자면, 이걸 안 잡으면 에이전트가 또 에이전트를 띄우고, 그 에이전트가 또 에이전트를 띄우는 재귀가 가능하다. 토큰이 기하급수적으로 뛴다. 1로 두면 루트가 자식만 직접 관리하고, 손자 세대는 막는다. 대부분의 경우 이걸로 충분하다.

max_threads = 6도 의미가 있다. PR 리뷰를 6개 관점으로 나눈다고 하면 6개 스레드가 동시에 돌아간다. 더 많이 띄우고 싶으면 올릴 수 있지만, 토큰 비용이 선형으로 늘어난다.

직접 써본 결과, PR 리뷰처럼 3~5개 에이전트를 병렬로 돌리는 경우가 대부분이었다. max_threads = 6이면 넉넉하다. 10개 이상 동시에 돌리는 경우는 CSV 배치 작업 정도인데, 그때도 job_max_runtime_seconds로 개별 워커를 제한하는 게 더 중요했다.

5. Awesome Codex Subagents — 130개 이상 컬렉션 활용법

2026년 3월 19일 현재, GitHub에 Awesome Codex Subagents라는 컬렉션이 올라와 있다. VoltAgent가 관리하는 오픈소스로, MIT 라이선스, 655 스타(2026-03-19 기준). 130개 이상의 서브에이전트를 10개 카테고리로 분류해놨다.

5.1 10개 카테고리 요약

번호 카테고리 에이전트 수 대표 에이전트
01 Core Development 12 backend-developer, frontend-developer, api-designer, code-mapper, ui-fixer
02 Language Specialists 25+ python-pro, typescript-pro, rust-engineer, golang-pro, react-specialist
03 Infrastructure 18 cloud-architect, devops-engineer, kubernetes-specialist, terraform-engineer, docker-expert
04 Quality & Security 16 reviewer, security-auditor, test-engineer, performance-analyst
05 Data & AI 12 data-engineer, ml-specialist, analytics-expert
06 Developer Experience 13 documentation-writer, ci-cd-optimizer, workflow-designer
07 Specialized Domains 12 fintech-engineer, game-developer, healthcare-developer
08 Business & Product 11 product-manager, technical-writer, ux-researcher
09 Meta & Orchestration 12 agent-installer, knowledge-synthesizer, refactoring-specialist
10 Research & Analysis 7 search-specialist, docs-researcher, code-archaeologist

처음 보면 “130개를 다 쓸 일이 있나?” 싶다. 실제로는 그중 5~10개만 골라서 쓰는 게 현실적이다.

5.2 바로 쓸 만한 에이전트 5개 추천

컬렉션을 훑어보면서 “이건 거의 모든 프로젝트에서 쓸 수 있겠다” 싶은 것들을 먼저 골랐다.

1) reviewer (04-Quality & Security)
가장 범용적이다. PR 리뷰는 어떤 프로젝트든 한다. sandbox_mode = "read-only"라서 안전하고, gpt-5.4로 깊은 추론을 쓴다. 글로벌에 하나 두면 끝.

2) search-specialist (10-Research & Analysis)
“이 함수 어디서 호출되지?”, “이 패턴이 다른 곳에도 있나?” 같은 코드베이스 검색에 최적화돼 있다. gpt-5.3-codex-spark로 빠르게 돌아가고, read-only라서 부담 없다. 글로벌 추천.

3) docs-researcher (10-Research & Analysis)
MCP로 공식 문서를 연결해서 “이 API가 정말 이렇게 동작하나?” 확인하는 용도. 코드 변경 없이 팩트만 확인하니까 안전하다. 글로벌 추천.

4) code-mapper (01-Core Development)
버그 추적할 때 “관련 파일이 뭐지?” 매핑을 해주는 읽기 전용 에이전트. 복잡한 코드베이스에서 진가 발휘. 글로벌 추천.

5) refactoring-specialist (09-Meta & Orchestration)
리팩토링 계획을 세워주는 에이전트. 실제 코드 변경은 별도 에이전트가 하고, 이건 “어떻게 쪼글지” 플랜만 짠다. 프로젝트별로 두는 게 맞을 수도 있지만, 범용적이라 글로벌에 둬도 된다.

5.3 설치 방법

컬렉션에서 원하는 에이전트를 골라 복사하면 된다.

글로벌에 설치:

mkdir -p ~/.codex/agents
cp categories/04-quality-security/reviewer.toml ~/.codex/agents/
cp categories/10-research-analysis/search-specialist.toml ~/.codex/agents/
cp categories/10-research-analysis/docs-researcher.toml ~/.codex/agents/

프로젝트에 설치:

mkdir -p .codex/agents
cp categories/01-core-development/nextjs-developer.toml .codex/agents/
cp categories/07-specialized-domains/fintech-engineer.toml .codex/agents/

설치 후 Codex 세션을 새로 열거나 리프레시하면 인식된다. 그리고 자동으로 안 뜬다. 프롬프트에서 “reviewer한테 이 PR 봐달라고” 같이 명시적으로 위임해야 한다.

5.4 기존 에이전트 체계와의 겹침 체크

나처럼 이미 에이전트 체계를 운영하고 있다면, 무작정 130개를 복사하기 전에 겹침부터 확인해야 한다.

내 기존 Claude Code 에이전트 19개와 Awesome Codex Subagents를 대조해본 결과다.

내 에이전트 Awesome 대응 에이전트 겹침 여부
blog-pipeline-team 대응 없음 (도메인 특화) 없음
trading-coach 대응 없음 (도메인 특화) 없음
inbox-organizer 대응 없음 (도메인 특화) 없음
url-summarizer search-specialist 부분 겹침 일부 겹침
blog-reviewer reviewer 유사 유사

결론: 도메인 특화 에이전트(블로그, 트레이딩, 노트 정리)는 겹치지 않는다. 범용 리뷰어, 검색기 같은 건 겹치거나 보완할 수 있다.

겹침이 있다면 두 가지 전략이 있다.

  • 대체: 기존 에이전트 대신 Awesome 컬렉션 것을 쓴다. 커뮤니티에서 계속 업데이트되니까 유지보수 부담이 줄어든다.
  • 보완: 기존 에이전트는 유지하고, Awesome 것을 참고해서 instructions를 보강한다. 내 도메인 지식은 내 에이전트에만 있으니까.

개인적으로는 범용 에이전트(reviewer, docs-researcher)는 Awesome 컬렉션 것을 복사해서 쓰고, 도메인 에이전트(blog-pipeline, trading-coach)는 내 것을 유지하는 게 효율적이었다.

6. 자동 호출이 아니라 명시 위임인 이유

Codex 서브에이전트를 처음 접하면 “에이전트 파일 두면 알아서 뜨겠지?” 생각하기 쉽다. 근데 아니다. 자동 호출이 아니다. 프롬프트에서 “reviewer한테 맡겨줘”, “code-mapper가 경로를 추적해줘” 같이 명시적으로 위임해야 한다.

왜 이렇게 만들었을까?

비용 문제. 각 서브에이전트가 자기 모델 호출과 도구를 쓴다. 에이전트 하나당 비용이 추가된다. 자동으로 뜬다면, 단순한 질문 하나에도 5개 에이전트가 떠서 토큰이 폭발한다. OpenAI 공식 문서도 “단일 에이전트 대비 3~7배 토큰을 쓸 수 있다”고 경고한다.

컨텍스트 오염 방지. 자동으로 에이전트가 끼어들면, 어떤 에이전트가 어떤 컨텍스트를 보고 있는지 추적이 어려워진다. 명시적 위임이면 “이 에이전트가 이 작업만 한다”가 명확하다.

실제로 프롬프트에서 위임하는 패턴은 이렇다.

이 PR을 리뷰해줘.
reviewer가 정확성과 보안을 보고,
docs-researcher가 의존하는 API 사양을 확인하고,
code-mapper가 영향 받는 코드 경로를 매핑해줘.
다 끝나면 한 번에 요약해줘.

3개 에이전트를 명시적으로 지정했다. 이러면 Codex가 3개를 병렬로 띄우고, 각각의 결과를 수집해서 하나의 요약으로 돌려준다.

근데 솔직히, 이 패턴이 처음엔 번거롭다. “그냥 알아서 해주면 안 되나?” 싶은 순간이 있다. 특히 매번 같은 에이전트 조합을 쓰는 경우에. 그래서 나는 자주 쓰는 위임 패턴을 텍스트 파일로 저장해두고 복사-붙여넣기 한다. 비효율적이지만, 자동 호출로 인한 토큰 폭발보다는 낫다.

7. 실수 TOP 5: 경로와 설정에서 흔히 하는 실수

7.1 글로벌에 프로젝트 전용 에이전트 두기

nextjs-developer.toml을 ~/.codex/agents/에 두면, Django 프로젝트에서도 불러올 수 있다. 에이전트가 Next.js 관점으로 Django 코드를 분석하면 엉뚱한 제안이 나온다. 프레임워크 전문가는 해당 프로젝트에만 두자.

7.2 이름 충돌 모르고 방치하기

글로벌에 reviewer.toml이 있는데, 프로젝트에도 reviewer.toml을 만들면 프로젝트 것이 우선한다. 의도적이면 괜찮지만, 모르고 같은 이름을 썼다가 “왜 리뷰 기준이 다르지?” 하고 헤맬 수 있다. 네이밍을 체계적으로 관리해야 한다.

7.3 sandbox_mode 안 잡기

기본값이 부모 세션 설정을 따르니까, 리뷰어한테도 write 권한이 열릴 수 있다. 리뷰 전용 에이전트에는 반드시 sandbox_mode = "read-only"를 명시하자. “분석만 하라”고 instructions에 적어도, sandbox가 write면 실수로 코드를 건드릴 수 있다.

7.4 max_depth 안 잡아서 에이전트 재귀

max_depth를 안 두면 에이전트가 또 에이전트를 띄울 수 있다. 토큰이 기하급수적으로 뛰고, 어디서 뭘 하는지 추적이 안 된다. max_depth = 1로 잡아두면 안전하다.

7.5 130개 다 복사하기

Awesome 컬렉션이 130개라고 다 복사하면, 글로벌 에이전트 목록이 130개가 된다. 이러면 Codex가 “어떤 에이전트를 쓸지” 혼란스러워지고, 프롬프트에서 일일이 지정하기도 번거롭다. 실제로 쓸 5~10개만 골라서 설치하고, 나머지는 필요할 때 추가하자.

8. 내가 느낀 점

Awesome Codex Subagents를 보면서 충격받은 건 두 가지다.

첫째, 에이전트 관리가 “폴더 구조 설계” 문제가 됐다는 거다. 예전에는 프롬프트 하나로 만능 AI를 돌렸다. 지금은 에이전트를 역할별로 나누고, 글로벌과 프로젝트로 경로를 분리하고, 모델과 sandbox 권한을 에이전트별로 따로 설정한다. 이건 소프트웨어 아키텍처에서 마이크로서비스를 설계하는 것과 비슷한 뉘앙스다. “하나의 모놀리스”에서 “역할별 서비스 분리”로 가는 흐름.

둘째, 커뮤니티 컬렉션의 등장 속도가 빠르다는 거다. OpenAI가 서브에이전트를 공식 지원한 지 며칠 만에 130개 이상의 에이전트가 정리됐다. 이건 npm 패키지나 VS Code 확장 생태계가 초기에 폭발적으로 성장하던 때와 비슷한 양상이다.

내 질문은 이거였다. “이 구조를 내 기존 에이전트 체계에 어떻게 합칠 수 있지?”

결론부터 말하면, 도구가 다르더라도 원리는 같다. Claude Code든 Codex든, “글로벌 = 범용, 프로젝트 = 특화”라는 분리 원리, “파일 하나 = 에이전트 하나”라는 정의 원리, “명시적 호출”이라는 실행 원리가 공통이다. 포맷(TOML vs MD)과 호출 방식(@멘션 vs 프롬프트 위임)은 다르지만, 설계 원칙은 이식 가능하다.

9. 솔직한 마음과 방향

두려운 점도 있다. 에이전트가 많아지면 “누가 뭘 나눠서 하고 있는지” 파악 자체가 일이 된다. 19개 에이전트를 운영하는 것도 가끔 헷갈리는데, 130개 컬렉션에서 골라 쓰기 시작하면 관리 오버헤드가 늘어날 수 있다.

그리고 토큰 비용이 눈에 보이게 오른다. 서브에이전트를 3개 띄우면 단일 에이전트의 3배 이상이다. “역할 분리가 품질을 올린다”는 건 맞지만, 모든 작업에 서브에이전트를 쓸 필요는 없다. 한 줄짜리 수정에 에이전트 5명을 투입하면 낭비다.

방향은 이렇게 잡았다.

  • 작게 시작한다. 글로벌에 3~4개만 두고, 실제로 PR 리뷰 하나를 서브에이전트로 돌려본다.
  • 비용을 추적한다. 서브에이전트 쓸 때마다 대략적인 토큰/비용을 기록해서, “이 정도 작업에 이 정도 비용” 패턴을 파악한다.
  • 겹침이 생기면 통합한다. Claude Code 에이전트와 Codex 서브에이전트가 같은 역할이면 하나로 합친다.

10. 앞으로 내가 할 것들

  1. 글로벌에 최소 세트 설치: reviewer, docs-researcher, search-specialist 3개만 ~/.codex/agents/에 두고 실제 PR 리뷰에 돌려본다.
  2. 기존 에이전트와 비교 실험: 같은 PR을 Claude Code @blog-reviewer와 Codex reviewer 서브에이전트로 각각 리뷰해보고, 품질 차이를 기록한다.
  3. 비용 메모 시작: 서브에이전트 조합별 대략적 토큰 사용량을 MEMORY에 기록한다.
  4. 경로 규칙 문서화: 내 프로젝트별 “글로벌 에이전트 목록”과 “프로젝트 에이전트 목록”을 명시적으로 정리한다. 이름 충돌 방지 차원.
  5. Awesome 컬렉션 업데이트 추적: 현재 130+ → 시간이 지나면 더 늘어날 거다. 월 1회 정도 새로운 에이전트가 추가됐는지 확인한다.

FAQ

Q: Codex 서브에이전트와 Claude Code 에이전트, 뭐가 다른가요?

A: 핵심 개념은 같다. 에이전트 파일 하나당 하나의 AI 역할을 정의하고, 글로벌/프로젝트 경로로 범위를 나누고, 명시적으로 호출한다. 차이는 포맷(Codex는 .toml, Claude Code는 .md), 호출 방식(Codex는 프롬프트 위임, Claude Code는 @멘션), 지원 모델(Codex는 GPT 계열, Claude Code는 Claude 계열)이다.

Q: 글로벌에 둔 에이전트를 특정 프로젝트에서 안 쓰게 할 수 있나요?

A: 직접적인 “제외” 설정은 현재(2026년 3월) 없다. 대신 같은 이름으로 프로젝트에 빈 에이전트(instructions 없는)를 두면 오버라이드돼서 사실상 비활성화할 수 있다. 다만 이건 공식 권장 방법이 아니라 우회다. 보통은 프롬프트에서 해당 에이전트를 위임하지 않으면 뜨지 않으니까 큰 문제는 안 된다.

Q: TOML 파일에 오타가 있으면 어떻게 되나요?

A: Codex가 파싱에 실패하면 해당 에이전트를 무시한다. 에러 메시지가 뜨지 않는 경우도 있어서, 에이전트를 만들고 나서 실제로 불러보는 테스트를 한 번은 해봐야 한다. “reviewer한테 이 파일 봐달라고” 같이 간단한 위임으로 확인할 수 있다.

Q: 에이전트 파일을 Git에 커밋해도 되나요?

A: 프로젝트 에이전트(.codex/agents/)는 커밋하면 팀원도 같은 에이전트를 쓸 수 있어서 추천한다. 글로벌 에이전트(~/.codex/agents/)는 내 로컬에만 있으니까 커밋 대상이 아니지만, dotfiles 레포로 관리하면 기기 간 동기화가 된다.

Q: Awesome Codex Subagents 컬렉션은 품질이 보장되나요?

A: MIT 라이선스이고, README에 “We do not audit or guarantee the security or correctness of any subagent. Review before use”라고 명시돼 있다. 커뮤니티 기여물이니까 품질이 들쭉날쭉할 수 있다. 쓰기 전에 developer_instructions 내용을 직접 읽어보고, 자기 환경에 맞게 수정해서 쓰는 게 맞다.

Q: 서브에이전트를 쓰면 토큰 비용이 얼마나 느나요?

A: OpenAI 공식 문서에 “단일 에이전트 대비 3~7배” 수준이라고 돼 있다. 에이전트 수, 모델 종류, reasoning effort에 따라 다르다. gpt-5.3-codex-spark 같은 가벼운 모델로 돌리면 비용 폭을 줄일 수 있다. 모든 에이전트를 gpt-5.4로 돌리면 비싸진다.

출처