Codex 서브에이전트 — 병렬 실행과 위임 패턴

공식 참고 자료: Subagents · Best Practices · Worktrees

커리큘럼 흐름

1. Codex 시작하기 — 설치, 첫 작업, 체크포인트까지 — 입문 루프
2. Codex 지시문 — AGENTS.md를 진짜 쓸모 있게 만드는 법 — 저장소 규칙
3. Codex 샌드박싱 — 권한, 승인, 클라우드 환경 이해하기 — 권한과 승인
4. Codex 작업 설계 — 소원 말고 이슈처럼 프롬프트 쓰기 — 좋은 task shape 만들기
5. Codex Skills — 반복 프롬프트를 재사용 가능한 워크플로우로 바꾸기 — 반복 워크플로우를 재사용 자산으로 만들기
6. Codex 서브에이전트 — 병렬 실행과 위임 패턴 — 병렬 실행과 위임 ← 현재 문서
7. Codex MCP — 외부 컨텍스트를 복붙 대신 연결하기 — 외부 시스템 연결
8. Codex 리뷰와 자동화 — /review, worktree, 반복 엔지니어링 운영하기 — 반복 작업 운영
9. Codex Worktrees — 브랜치 충돌 없이 병렬 실행하기
10. Codex 핸드오프 — 병렬 레인을 머지 가능한 결과로 연결하기
11. Codex 검증 루프 — 머지 전에 동작을 증명하기
12. Codex 릴리스 준비도 — 프로덕션 전 최종 게이트
13. Codex 첫날 안전 루프 — 초반 실수를 줄이는 입문 워크플로우
14. Codex 팀 딜리버리 플레이북 — 중급 레인 운영
15. Codex 고위험 변경 거버넌스 — 크리티컬 릴리스를 위한 고급 통제
16. Codex 운영 매뉴얼 — 팀의 일/주/릴리스 리듬 정렬하기
17. Codex 사고 복구 플레이북 — 프로덕션 압박 상황에서의 결정론적 대응
18. Codex 사고 후 하드닝 루프 — 복구를 내구성 있는 통제로 전환하기
19. Codex 카오스 복원력 드릴 — 실패가 오기 전에 리허설하기
20. Codex 복원력 지표와 SLO — 실패 전에 신뢰성을 측정하기
21. Codex Ralph 지속 루프 — 긴 작업을 검증 가능한 완료까지 가져가기

이 문서에서 참고한 공식 문서

• 서브에이전트 생성 시점과 방법 — Subagents
• 작업 크기 조절과 분해 — Best Practices
• Git worktree를 이용한 병렬 격리 — Worktrees

서브에이전트가 존재하는 이유

단일 Codex 에이전트는 집중된 순차 작업에 잘 맞습니다. 하지만 어떤 작업은 동시에 여러 가지를 진행하는 것이 효과적입니다.

• 구현 옵션 여러 개를 동시에 탐색한 뒤 하나를 선택
• 코드베이스의 서로 다른 영역을 병렬로 스캔
• 독립적인 검증 단계를 동시에 실행

서브에이전트는 Codex가 여러 병렬 워커로 분기하여 각자 문제의 일부를 처리하게 합니다.

Codex는 요청할 때만 서브에이전트를 생성한다

Subagents 문서는 이 점을 명확히 합니다: Codex는 자동으로 서브에이전트를 생성하지 않습니다. 병렬 실행을 명시적으로 요청해야 합니다.

좋은 프롬프트 예시:

결제 모듈 리팩토링에 대해 세 가지 다른 접근법을 탐색해 줘.
각각 병렬로 실행하고 트레이드오프를 요약해.

다섯 개 서비스 디렉터리에서 deprecated API 사용을 확인해.
병렬로 체크해 줘.

프롬프트에 병렬 처리나 다중 접근법을 언급하지 않으면, Codex는 단일 스레드로 처리합니다.

서브에이전트는 샌드박스 정책을 상속한다

각 서브에이전트는 메인 에이전트와 동일한 샌드박스 설정으로 실행됩니다.

• 메인 에이전트가 workspace-write이면 서브에이전트도 workspace-write
• approval이 필요하면 서브에이전트도 동일하게 approval 필요
• writable roots도 동일하게 적용

이것은 안전 기능입니다. 병렬화가 신뢰 경계를 넓히지 않습니다.

서브에이전트가 가장 효과적인 경우

병렬 탐색

넓은 질문에 대해 여러 각도를 동시에 조사하고 싶을 때.

비교 후 선택

여러 구현안을 독립적으로 생성한 뒤 하나를 고르고 싶을 때.

독립 검증

lint, 테스트, 보안 검사를 순차가 아닌 동시에 실행하고 싶을 때.

배치 조사

동일한 분석을 여러 모듈이나 패키지에 걸쳐 반복해야 할 때.

서브에이전트가 맞지 않는 경우

순차 의존성

단계 B가 단계 A의 결과에 의존하면, 병렬화는 오버헤드만 추가합니다.

단순한 단일 파일 작업

파일 하나를 집중 수정하는 데 위임은 불필요합니다.

공유 컨텍스트가 필요한 작업

워커들이 중간 결과를 조율하거나 공유해야 한다면, 단일 에이전트가 보통 더 낫습니다.

서브에이전트 vs 워크트리

둘 다 병렬성을 제공하지만, 해결하는 문제가 다릅니다.

서브에이전트는 병렬 사고입니다. 워크트리는 격리된 병렬 실행입니다.

탐색 작업에는 서브에이전트를 먼저 쓰세요. Git 격리가 필요한 프로덕션 자동화에는 워크트리를 선택하세요. 워크트리 네이밍/수명주기/정리 패턴이 필요하면 Codex Worktrees 문서로 이어서 보세요.

서브에이전트와 skills

서브에이전트는 저장소에서 사용 가능한 skill을 활용할 수 있습니다. 잘 구축된 skill 라이브러리가 서브에이전트 작업을 더 효과적으로 만듭니다:

• 리뷰를 수행하는 서브에이전트가 리뷰 skill을 호출
• 마이그레이션을 담당하는 서브에이전트가 마이그레이션 skill을 따름
• 문서를 생성하는 서브에이전트가 문서 skill을 적용

위임과 인코딩된 절차의 조합이 서브에이전트가 가장 실용적으로 작동하는 지점입니다.

서브에이전트와 AGENTS.md

AGENTS.md의 지시사항은 메인 에이전트와 서브에이전트 모두에 동일하게 적용됩니다. 코딩 표준, 테스트 요구사항, 리뷰 관행을 AGENTS.md에 정했다면 서브에이전트도 이를 따릅니다.

모든 서브에이전트 프롬프트에 프로젝트 규칙을 반복할 필요가 없습니다. 지시 표면이 공유되기 때문입니다.

비용과 토큰 인식

서브에이전트는 공짜가 아닙니다. 각 서브에이전트는 추론과 도구 호출에 자체 토큰 예산을 사용합니다.

• 서브에이전트 2개 = 대략 단일 에이전트의 2배 비용
• 탐색적 실행은 분기 수만큼 비용이 배가
• Best-of-N 패턴은 비용을 품질로 교환

실용적인 원칙: 벽시계 시간 절약이나 품질 향상이 토큰 비용을 정당화할 때 서브에이전트를 사용하세요. 병렬화를 위한 병렬화는 피하세요.

효과적인 위임 프롬프팅

분할을 명확히 하라

목표: 세 개 서비스의 성능 병목을 조사해.
 
작업 분할:
- 에이전트 1: api-gateway/ 분석
- 에이전트 2: payment-service/ 분석
- 에이전트 3: notification-service/ 분석
 
각 에이전트는 핫 패스를 프로파일링하고 상위 3개 병목을 보고해.

반환 결과를 정의하라

병렬 탐색 후 요약:
- 가장 작은 diff를 가진 접근법
- 새 의존성이 필요 없는 접근법
- 기존 테스트를 변경 없이 통과하는 접근법

범위 경계를 설정하라

각 서브에이전트는 할당된 디렉터리의 파일만 읽어야 합니다.
탐색 중에는 파일을 수정하지 마세요.

흔한 함정

명확한 작업 경계 없이 병렬화 요청

"모든 것을 병렬로 조사해"라고만 하면 결과가 산만해집니다.

서브에이전트 간 조율 기대

서브에이전트는 독립적으로 작동합니다. 중간 상태를 공유하지 않습니다. 반복적 개선이 필요하면 메인 에이전트에서 처리하세요.

토큰 비용 망각

간단한 질문에 탐색 서브에이전트 5개를 돌리면 비용 대비 이득이 없습니다.

시작용 체크리스트

서브에이전트를 요청하기 전에 확인하세요:

• 작업이 진짜 병렬 처리 가능한가?
• 각 서브에이전트의 작업 경계가 명확한가?
• 토큰 비용이 시간 또는 품질 이득으로 정당화되는가?
• 샌드박스 정책이 서브에이전트가 필요한 작업을 허용하는가?
• 각 병렬 분기의 유용한 결과가 무엇인지 정의할 수 있는가?

서브에이전트는 Codex를 "한 번에 하나씩"에서 "여러 조사를 동시에"로 바꿔 주는 표면입니다. 명확한 경계와 정의된 결과를 갖추고 의도적으로 사용하세요.