Codex 병렬 에이전트 사용법: 여러 개발 작업 동시에 처리하기

Codex 병렬 에이전트는 하나의 큰 개발 요청을 독립된 하위 작업으로 나누고 여러 에이전트가 동시에 처리하게 하는 기능입니다. 코드베이스 탐색, 테스트 실행, 로그 분석과 보안 검토처럼 서로 결과를 기다리지 않아도 되는 작업에서 시간을 줄일 수 있습니다. 반대로 같은 파일을 여러 에이전트가 수정하게 하면 충돌과 재작업이 커지므로 분할 기준과 최종 통합 책임을 먼저 정해야 합니다.

Codex 병렬 에이전트란 무엇인가

OpenAI 공식 문서에서는 주 에이전트가 특화된 하위 에이전트를 생성하고, 각 결과를 하나의 응답으로 통합하는 방식을 하위 에이전트 워크플로라고 설명합니다. 현재 Codex 릴리스에서는 이 기능이 기본적으로 활성화되어 있으며 ChatGPT 데스크톱 앱, Codex CLI와 IDE 확장에서 활동을 확인할 수 있습니다.

용어	역할
주 에이전트	목표를 해석하고 작업을 분할하며 결과를 통합·검증
하위 에이전트	할당된 범위의 탐색, 구현, 테스트 또는 리뷰 수행
에이전트 스레드	하위 에이전트가 작업하는 독립 대화와 실행 기록
오케스트레이션	생성, 후속 지시, 대기, 중단과 결과 합성 과정

병렬 처리가 효과적인 작업

• 코드베이스 탐색: 프론트엔드, API, 데이터 계층을 각자 읽고 실행 경로를 요약합니다.
• 전문 리뷰: 보안, 테스트 누락, 성능과 유지보수성을 서로 다른 관점에서 검토합니다.
• 테스트 분할: 단위, 통합, E2E 테스트를 독립적으로 실행하고 실패 원인을 정리합니다.
• 로그 분석: 서로 다른 서비스나 시간대의 로그를 나눠 공통 원인을 찾습니다.
• 문서 조사: 여러 공식 문서나 버전별 변경 사항을 분담해 핵심 근거를 모읍니다.
• 독립 모듈 구현: 파일과 공개 인터페이스가 명확히 분리된 모듈을 각각 수정합니다.

작업 사이 의존성이 낮고 결과를 명확한 요약으로 합칠 수 있을수록 병렬 처리에 적합합니다. 순서대로 마이그레이션해야 하는 데이터베이스 변경이나 하나의 핵심 파일을 반복 수정하는 작업은 단일 에이전트가 더 안정적일 수 있습니다.

병렬화하면 안 되는 신호

• 두 작업이 같은 파일이나 같은 함수의 코드를 동시에 바꿔야 합니다.
• 앞 작업의 설계 결정이 나와야 다음 작업을 시작할 수 있습니다.
• 요구사항이 불명확해 에이전트마다 다른 가정을 할 가능성이 큽니다.
• 운영 배포, 데이터 삭제와 외부 전송처럼 중앙 승인 순서가 중요합니다.
• 작업 자체가 작아 생성·요약·통합 비용이 구현 시간보다 큽니다.

병렬 에이전트는 항상 더 빠른 기능이 아닙니다. 공식 문서에 따르면 각 에이전트가 별도의 모델과 도구를 사용하므로 비슷한 단일 에이전트 작업보다 토큰 사용량이 늘어납니다.

가장 간단하게 병렬 에이전트 요청하기

대부분의 추론 수준에서는 프롬프트에서 하위 에이전트 사용을 직접 요청합니다. 적용되는 AGENTS.md나 스킬에 위임 지침이 있는 경우에도 Codex가 병렬 작업을 수행할 수 있습니다.

현재 브랜치를 병렬로 검토해줘.
- 에이전트 1: 인증·권한과 데이터 노출 위험, 읽기 전용
- 에이전트 2: 회귀 테스트 누락과 경계 조건, 읽기 전용
- 에이전트 3: 성능과 동시성 위험, 읽기 전용
모든 에이전트가 끝날 때까지 기다린 뒤,
중복 항목을 합치고 파일·줄 근거와 우선순위별로 요약해줘.
코드는 수정하지 마.

이 요청은 역할, 범위, 권한, 대기 조건과 출력 형식을 모두 포함합니다. 관련 기능은 Codex 코드리뷰 사용법과 함께 활용하면 PR의 위험을 여러 관점에서 점검하기 좋습니다.

좋은 병렬 프롬프트의 6가지 요소

1. 공통 목표: 최종적으로 무엇을 결정하거나 만들어야 하는지 씁니다.
2. 독립 범위: 각 에이전트가 볼 디렉터리, 위험 축이나 테스트 종류를 나눕니다.
3. 권한: 읽기 전용인지, 어느 파일까지 수정 가능한지 정합니다.
4. 완료 기준: 명령 통과, 근거 수집과 산출물 형식을 명시합니다.
5. 대기 조건: 모든 결과를 기다릴지, 일부 실패해도 통합할지 정합니다.
6. 통합 규칙: 중복 제거, 충돌 판단과 최종 검증 주체를 지정합니다.

기능 개발을 안전하게 나누는 예시

사용자 알림 설정 기능을 준비해줘.
1. explorer: 기존 알림 데이터 흐름과 관련 파일만 조사하고 수정하지 말 것
2. api-reviewer: API 호환성·권한·마이그레이션 위험을 검토하고 근거 반환
3. test-planner: 단위·통합·E2E 테스트 목록과 실패 조건 작성
먼저 세 작업을 병렬 실행해 모두 기다려.
주 에이전트가 결과를 통합해 구현 계획과 파일 소유 범위를 제시한 뒤 멈춰.
내 확인 전에는 코드를 수정하지 마.

설계와 위험을 먼저 병렬로 수집하고 주 에이전트가 인터페이스를 확정한 뒤 구현으로 넘어가는 방식입니다. 불명확한 상태에서 여러 작업자가 바로 코드를 쓰는 것보다 충돌을 줄일 수 있습니다.

여러 구현을 동시에 맡길 때 지켜야 할 기준

분할 기준	좋은 예	위험한 예
파일 소유	API와 UI가 별도 디렉터리	여러 에이전트가 같은 공통 타입 수정
인터페이스	요청·응답 스키마가 먼저 확정됨	각자 다른 필드 이름을 설계
검증	모듈별 독립 테스트 명령 존재	전체 빌드 한 번만으로 판정
통합	주 에이전트가 최종 diff 검토	각 결과를 확인 없이 그대로 합침
실패 처리	부분 실패를 명시하고 중단	누락된 작업을 성공으로 간주

CLI에서 /agent로 진행 상황 확인하기

대화형 Codex CLI에서는 /agent를 사용해 실행 중인 에이전트 스레드를 확인하고 스레드 사이를 전환할 수 있습니다. 앱과 IDE에서는 지원되는 하위 에이전트 또는 백그라운드 에이전트 패널에서 상태와 결과를 확인합니다.

/agent

에이전트가 잘못된 방향으로 가면 주 채팅에서 해당 에이전트의 작업 방향을 조정하거나 중지하도록 요청할 수 있습니다. 완료된 결과도 최종 요약만 보지 말고 근거와 실행 명령을 필요한 범위에서 확인하세요.

권한과 샌드박스는 어떻게 적용되나

공식 문서에 따르면 하위 에이전트는 현재 샌드박스와 권한 모드를 상속합니다. 위임 전에 주 턴에서 필요한 권한 모드를 선택해야 하며, 읽기 전용 역할은 커스텀 에이전트 설정으로 더 제한할 수 있습니다.

• 모든 에이전트에 넓은 쓰기·네트워크 권한을 주지 않습니다.
• 탐색과 리뷰 에이전트는 가능하면 읽기 전용으로 둡니다.
• 삭제·배포·외부 메시지 전송은 주 에이전트의 명시적 승인 단계로 모읍니다.
• 비대화형 실행에서 새 승인이 필요하면 작업이 실패할 수 있으므로 사전 조건을 확인합니다.
• 서로 다른 스레드에서 올라온 승인 요청의 작업명과 대상 경로를 확인합니다.

동시 실행 수와 기본 설정

config.toml의 [agents] 설정으로 멀티 에이전트 활성화, 동시 스레드 수와 기본 모델·추론 강도를 구성할 수 있습니다. 설정하지 않으면 Codex가 기본값을 선택합니다.

[agents]
enabled = true
max_concurrent_threads_per_session = 4
default_subagent_reasoning_effort = "medium"

동시 실행 수를 크게 올린다고 작업이 비례해 빨라지지는 않습니다. 저장소 I/O, 테스트 자원, 외부 API 제한과 통합 부담을 고려해 두세 개의 독립 작업부터 측정하세요. 모델 이름과 제공 범위는 바뀔 수 있으므로 최신 공식 설정 문서를 확인하는 편이 안전합니다.

커스텀 에이전트 역할 만들기

로컬 Codex에서는 개인용 역할을 ~/.codex/agents/, 프로젝트 전용 역할을 .codex/agents/의 TOML 파일로 만들 수 있습니다. 기본 제공 역할에는 범용 default, 구현 중심 worker, 읽기 중심 explorer가 있습니다.

name = "security_reviewer"
description = "Read-only reviewer for authentication, authorization, and data exposure risks."
sandbox_mode = "read-only"
model_reasoning_effort = "high"
developer_instructions = """
Review only security-relevant behavior.
Cite files and symbols for every finding.
Separate observed evidence from hypotheses.
Do not edit files or run deployment commands.
"""

커스텀 역할에는 name, description, developer_instructions가 필요합니다. 역할을 좁게 유지하고 사용해야 할 상황과 하지 말아야 할 행동을 모두 적으세요.

AGENTS.md와 Skills에 위임 규칙 넣기

모든 작업에서 반복할 프로젝트 원칙은 AGENTS.md에, 특정 반복 절차는 Codex Skills에 둘 수 있습니다.

## Parallel work
- Delegate only independent, bounded tasks.
- Prefer read-only exploration, testing, and review.
- Do not let multiple agents edit the same file.
- Wait for all requested agents before integration.
- The main agent must run the final lint, test, and build checks.

위임을 항상 강제하기보다 병렬화가 유리한 조건과 금지 조건을 함께 적는 것이 좋습니다. 작은 수정까지 여러 에이전트로 나누면 시간과 토큰만 늘어날 수 있습니다.

결과 통합 시 반드시 확인할 항목

1. 요청한 모든 에이전트가 완료됐는지, 실패하거나 중단된 스레드가 있는지 확인합니다.
2. 서로 다른 결과에서 중복된 문제와 상충하는 결론을 구분합니다.
3. 파일 경로, 코드 줄, 로그와 테스트 결과로 핵심 주장을 재확인합니다.
4. 각 구현의 공개 인터페이스와 데이터 형식이 일치하는지 봅니다.
5. 주 에이전트가 전체 diff를 검토하고 lint, typecheck, 테스트와 빌드를 다시 실행합니다.
6. 실행하지 못한 검사와 남은 위험을 최종 보고에 남깁니다.

병렬 작업이 실패하는 대표 원인

증상	원인	해결
서로의 변경을 덮어씀	파일 소유 범위 중복	한 명만 쓰게 하거나 디렉터리 분리
결론이 서로 다름	공통 요구사항·용어 누락	인터페이스와 판단 기준 먼저 고정
주 채팅이 먼저 종료됨	대기 조건 불명확	모든 에이전트를 기다리라고 명시
승인 대기 후 실패	비대화형 실행에서 새 권한 필요	권한과 필요한 명령을 시작 전 확인
토큰만 많이 사용	작거나 의존적인 작업까지 분할	독립적이고 읽기 많은 작업만 위임
최종 빌드가 깨짐	부분 결과만 검증	통합 후 전체 검증을 주 에이전트가 실행

속도와 품질을 측정하는 방법

병렬 에이전트의 효과는 에이전트 수가 아니라 전체 완료 시간과 재작업으로 판단해야 합니다. 같은 유형의 작업을 몇 차례 수행하며 다음 지표를 기록해 보세요.

• 요청부터 검증 완료까지 걸린 실제 시간
• 하위 작업 수와 실패·중단 횟수
• 동일 파일 충돌과 수동 병합 시간
• 최종 테스트에서 새로 발견된 통합 오류
• 토큰 또는 사용량 증가 대비 절약한 작업 시간
• 사람이 수정한 잘못된 결론과 오탐 수

병렬 실행 시간이 짧아도 통합과 재검증에 더 오래 걸렸다면 분할 방식이 적절하지 않은 것입니다.

실전 템플릿: 구현 전 조사

이 기능을 구현하기 전에 세 개의 읽기 전용 하위 에이전트를 병렬 실행해줘.
A: 관련 코드 경로와 현재 동작을 파일·심볼 근거로 정리
B: 테스트 구조와 누락된 실패 시나리오 정리
C: API 호환성, 보안, 데이터 마이그레이션 위험 정리
각 결과는 관찰 사실, 가정, 미확인 항목으로 나눠 반환해.
모두 끝난 뒤 주 에이전트가 중복과 충돌을 해결해 하나의 구현 계획을 작성해.
아직 파일은 수정하지 마.

실전 템플릿: 독립 모듈 구현

확정된 인터페이스를 기준으로 두 작업을 병렬 처리해줘.
에이전트 A는 apps/web/만 수정하고 UI와 컴포넌트 테스트를 담당해.
에이전트 B는 services/api/만 수정하고 API와 통합 테스트를 담당해.
공용 타입과 lockfile은 누구도 수정하지 말고 필요하면 주 에이전트에 보고해.
각자 변경 파일과 실행한 검사를 반환해.
모두 완료되면 주 에이전트가 전체 diff를 검토하고 전체 lint·test·build를 실행해.

편집부 결론

Codex 병렬 에이전트를 잘 쓰는 핵심은 많은 에이전트를 만드는 것이 아니라 독립성과 통합 기준을 설계하는 일입니다. 먼저 읽기 중심의 탐색·테스트·리뷰를 나누고, 구현은 파일 소유와 인터페이스가 분명할 때만 병렬화하세요. 주 에이전트가 모든 결과를 기다리고 전체 diff와 검증을 책임지게 해야 속도 향상이 품질 저하로 이어지지 않습니다.

이 글은 2026년 9월 4일 OpenAI 공식 문서를 분석해 작성했으며 특정 프로젝트의 장기간 성능 비교나 비용 절감 실험은 아닙니다. 계정, 클라이언트와 Codex 버전에 따라 제공 범위와 설정이 달라질 수 있으므로 최신 공식 문서와 실제 화면을 함께 확인하세요.

공식 문서와 함께 읽을 글

Codex와 Claude Code 병렬 개발 방식 비교하기

OpenAI Codex 하위 에이전트 공식 문서 확인하기

Claude Code Subagent 병렬 처리 방식과 비교하기

Windows에서 Codex 앱과 CLI 설정하기

병렬 관점으로 Codex 코드리뷰 진행하기

Codex Skills로 반복 개발 절차 만들기

AGENTS.md에 프로젝트와 병렬 작업 규칙 설정하기

자주 묻는 질문

Codex 병렬 에이전트는 무엇인가요?

주 에이전트가 독립된 작업을 여러 하위 에이전트에 나눠 동시에 실행하고 결과를 하나로 통합하는 워크플로입니다.

하위 에이전트 기능을 별도로 켜야 하나요?

공식 문서 기준 현재 Codex 릴리스에서는 기본 활성화되어 있습니다. 구성의 agents.enabled로 비활성화할 수 있습니다.

병렬 에이전트를 어떻게 요청하나요?

“탐색, 테스트, 보안을 각각 별도 에이전트에 병렬 위임하고 모두 기다린 뒤 요약해줘”처럼 역할·범위·대기·출력 조건을 직접 작성하세요.

CLI에서 실행 중인 에이전트를 볼 수 있나요?

대화형 Codex CLI에서 /agent를 사용하면 활성 스레드를 확인하고 전환할 수 있습니다.

여러 에이전트가 같은 파일을 수정해도 되나요?

가능하면 피해야 합니다. 변경 충돌과 통합 오류가 늘기 때문에 한 에이전트만 쓰게 하거나 파일·디렉터리 소유 범위를 분리하세요.

병렬 에이전트를 쓰면 항상 더 빠른가요?

아닙니다. 작업이 작거나 서로 의존하면 조정 비용이 더 커질 수 있으며, 단일 에이전트보다 토큰도 더 많이 사용합니다.

하위 에이전트도 같은 권한을 사용하나요?

하위 에이전트는 현재 샌드박스와 권한 모드를 상속합니다. 탐색·리뷰 역할은 가능하면 읽기 전용으로 제한하세요.

최종 테스트는 누가 실행해야 하나요?

각 에이전트의 부분 검사와 별개로 주 에이전트가 통합된 전체 diff에 대해 lint, typecheck, 테스트와 빌드를 다시 실행해야 합니다.