"Context pollution: useful information gets buried under noisy intermediate output. Context rot: performance degrades as the conversation fills up with less relevant details."
(번역) "컨텍스트 오염: 유용한 정보가 불필요한 중간 출력에 묻혀 버린다. 컨텍스트 부식: 덜 관련된 세부 정보로 대화창이 채워지면서 성능이 점점 저하된다."
Context pollution은 말 그대로 "대화창이 지저분해지는 현상"이다. 파일 탐색 메모, 테스트 로그, 스택 트레이스(오류가 어디서 시작됐는지 보여주는 긴 기록)가 쌓이면서 정작 중요한 요구사항이 뒤로 밀린다.
Context rot은 그 결과로 답변 품질이 서서히 나빠지는 상태다. 쉽게 말해, 대화창이 너무 어수선해져서 Codex가 처음 목표를 잊어버리는 것이다.
해결 방향은 단순하다. 메인 스레드, 즉 내가 계속 보고 있는 중심 대화창에는 "요구사항·결정·최종 출력"만 남긴다.
파일 탐색이나 테스트처럼 로그가 많이 나오는 일은 서브에이전트에게 따로 맡기면 된다.
이 두 개념을 굳이 나누는 이유도 실전에서는 꽤 중요하다. context pollution은 지금 당장 "로그가 너무 많이 쌓였네" 하고 알아차릴 수 있다. 반면 context rot은 한참 뒤에 "왜 답이 점점 엉뚱해지지?"라는 식으로 드러난다. 먼저 오염을 줄이고, 길어진 대화에서는 품질 저하가 생기지 않는지 확인해야 한다.
"Subagent workflow: A workflow where Codex runs parallel agents and combines their results. Subagent: A delegated agent that Codex starts to handle a specific task. Agent thread: The CLI thread for an agent, which you can inspect and switch between with /agent."
(번역) "서브에이전트 워크플로: Codex가 여러 에이전트를 병렬로 실행하고 결과를 합치는 흐름. 서브에이전트: 특정 작업을 담당하도록 Codex가 시작한 보조 에이전트. 에이전트 스레드: /agent 명령으로 전환하거나 확인할 수 있는 에이전트별 CLI 작업창."
subagent workflow는 Codex가 여러 에이전트를 병렬로 실행하고 결과를 합치는 흐름이다.
subagent는 특정 작업을 맡기기 위해 Codex가 시작한 보조 에이전트이고, agent thread는 /agent로 전환하거나 확인할 수 있는 에이전트별 작업창이다.
ex) /agent
서브에이전트 워크플로(Subagent workflow): Codex가 여러 보조 에이전트를 실행하고 결과를 합치는 전체 흐름이다.
서브에이전트(Subagent): 특정 작업을 담당하도록 Codex가 따로 띄운 보조 에이전트다.
에이전트 스레드(Agent thread): CLI에서 각 에이전트가 일하는 개별 작업창이다. /agent 명령으로 전환하거나 확인할 수 있다.
관계는 이렇게 보면 쉽다. 하나의 작업 흐름 안에 여러 보조 작업자가 있고, 각 보조 작업자는 자기 대화창을 따로 가진다.
여기서 중요한 것은 에이전트 스레드다. 서브에이전트는 안 보이는 곳에서 잠깐 실행되고 끝나는 기능이 아니다. CLI에서 직접 들어가 볼 수 있는 독립된 작업창으로 남는다. 그래서 /agent 명령으로 실행 중인 서브에이전트의 중간 상태를 확인하거나 추가 지시를 줄 수 있다.
2.2 언제 필요한가
두 가지 상황에서 서브에이전트가 유용하다.
첫째, 대화창이 복잡해지기 시작할 때다. 메인 스레드에 요구사항과 탐색 로그가 뒤섞이면, 파일 조사 같은 작업을 서브에이전트로 빼는 편이 낫다.
둘째, 한 번에 읽기 어려울 만큼 큰 작업이다. 예를 들어 문서나 코드가 너무 많으면 Codex가 모든 내용을 한 대화 안에서 안정적으로 다루기 어렵다. 이때는 여러 서브에이전트가 각자 일부를 읽고, 핵심 요약만 메인 스레드로 돌려보내게 만들 수 있다(서브에이전트 문서 참조).
3. 서브에이전트 생성하기
3.1 명시적 지시만 가능하다
서브에이전트 생성에는 중요한 전제가 있다. 공식 문서는 이를 명확히 못 박는다.
"Codex doesn't spawn subagents automatically, and it should only use subagents when you explicitly ask for subagents or parallel agent work."
(번역) "Codex는 서브에이전트를 자동으로 생성하지 않으며, 사용자가 명시적으로 서브에이전트 또는 병렬 에이전트 작업을 요청할 때만 사용한다."
Codex는 서브에이전트를 마음대로 만들지 않는다.
사용자가 "병렬 에이전트를 써라", "이 일을 나눠서 맡겨라"처럼 직접 지시해야 한다.이 제한은 오히려 초보자에게 좋다.
나도 모르는 사이에 여러 에이전트가 실행되면 비용, 속도, 작업 흐름을 파악하기 어려워지기 때문이다.
3.2 지시 표현 예시
공식 문서는 다음과 같은 표현을 직접 지시의 예로 든다. 이 표현만 되는 것은 아니고, 핵심은 "일을 나눠서 병렬 에이전트에게 맡긴다"는 의도가 분명해야 한다는 점이다.
"spawn two agents", "delegate this work in parallel", "use one agent per point"
(번역) "에이전트 두 개를 띄워라", "이 작업을 병렬로 위임해라", "항목마다 에이전트 하나씩 써라"
핵심은 "병렬로", "에이전트를 따로", "항목별로 나눠서" 같은 말을 프롬프트에 직접 넣는 것이다.
그냥 "검토해 줘"라고 쓰면 보통 하나의 메인 스레드에서 처리된다.
비교 — 같은 PR 리뷰 요청, 지시 방식에 따라 결과가 다르다
프롬프트 원문: "이 PR을 다각도로 리뷰해줘"
서브에이전트 지시 없을 때
이 PR을 다각도로 리뷰해줘.
→ 보안·테스트·유지보수성이 한 응답에 섞여 나옴 → 각 관점의 깊이가 얕아지고, "다각도"의 범위는 Codex가 임의로 결정 → 어느 관점에서 뭘 말하는지 구분 안 됨
ex) 가장 최신 pr을 다각도로 리뷰해줘.
- 싱글 에이전트가 단독으로 계쏙 리뷰해 나가는 모습
병렬 서브에이전트 명시 후
Spawn one agent for security risks,
one for test gaps,
one for maintainability.
Wait for all three, then summarize by category with file references.
한국어로도 동일하게 동작한다:
보안 리스크를 볼 에이전트, 테스트 빈틈을 볼 에이전트, 유지보수성을 볼 에이전트를 각각 하나씩 띄워라.
세 결과가 모두 나오면 파일 경로와 함께 카테고리별로 요약하라.
→ 각 에이전트가 한 관점만 깊이 분석 → 결과가 카테고리별로 정리되어 합치기 쉬움 → 완료 기준이 "세 에이전트 모두 반환"으로 명확
ex) 가장 최신 pr을 보안 리스크를 볼 에이전트, 테스트 빈틈을 볼 에이전트, 유지보수성을 볼 에이전트를 각각 하나씩 띄워라. 세 결과가 모두 나오면 파일 경로와 함께 카테고리별로 요약하라.
- 최신 커밋은 1개의 에이전트가 확인
- 이후 지시사항대로 3개의 에이전트를 각각 띄워 작업을 시키는것을 볼 수 있다.
3.3 실전 프롬프트 예시
예시 1 — 읽기 전용 조사
Use two parallel subagents for read-only exploration.
One subagent should map the changed files.
The other should find related tests.
Do not edit files. Return short summaries with file paths.
한국어 버전:
읽기 전용 조사에 서브에이전트 2개를 병렬로 써라.
에이전트 1: 변경된 파일 목록을 정리해라.
에이전트 2: 관련 테스트 파일을 찾아라.
파일 수정 금지. 파일 경로가 포함된 짧은 요약만 돌려줘.
처음에는 이렇게 2개 정도의 읽기 전용 서브에이전트로 시작하는 편이 좋다. "수정하지 말라", "파일 경로를 포함해 짧게 요약하라"를 함께 적어 두면 결과를 확인하기 쉽다.
예시 2 — 브랜치 병렬 리뷰
Review this branch with parallel subagents.
Spawn one subagent for security risks, one for test gaps,
and one for maintainability.
Wait for all three, then summarize the findings by category
with file references.
한국어 버전:
이 브랜치를 병렬 서브에이전트로 리뷰해라.
보안 리스크를 볼 에이전트, 테스트 빈틈을 볼 에이전트, 유지보수성을 볼 에이전트를 각각 하나씩 띄워라.
세 결과가 모두 나오면 파일 경로와 함께 카테고리별로 요약하라.
세 가지 관점(보안·테스트·유지보수성)을 각각의 서브에이전트에 맡기고, 모든 결과를 기다린 뒤 카테고리별로 정리하게 하는 예시다. 여기서도 "누가 무엇을 볼지", "모든 결과를 기다릴지", "어떤 형식으로 요약할지"를 노골적으로 적는 것이 중요하다.
예시 3 — PR 6개 관점 분산 리뷰
I would like to review the following points on the current PR
(this branch vs main).
Spawn one agent per point, wait for all of them, and summarize
the result for each point.
1. Security issue
2. Code quality
3. Bugs
4. Race
5. Test flakiness
6. Maintainability of the code
한국어 버전:
현재 PR(이 브랜치 vs main)을 아래 관점으로 리뷰해라.
항목마다 에이전트를 하나씩 띄우고, 모두 끝나면 항목별로 결과를 요약하라.
1. 보안 이슈
2. 코드 품질
3. 버그
4. 경쟁 조건 (race condition: 동시 실행 시 순서가 꼬이는 문제)
5. 테스트 불안정성 (test flakiness: 가끔만 실패하는 테스트)
6. 코드 유지보수성
체크리스트 형태로 관점을 적으면 Codex가 항목마다 서브에이전트를 하나씩 배정할 수 있다.
다만 6개 에이전트는 기초 실습으로는 많다. (토큰 낭비로 이어질수도 있다.)
큰 PR에서 비용과 대기 시간을 감수할 만할 때만 쓰고, 평소에는 2~3개 관점부터 시작하는 편이 낫다(서브에이전트 문서 참조).
Goal / Constraints / Completion을 더 정밀하게: prompt-blocks
위 패턴이 익숙해졌다면 XML 블록으로 각 역할을 명시적으로 분리하는 방식으로 한 단계 올릴 수 있다. 긴 프롬프트에서 에이전트가 Goal과 Constraints를 혼동하는 경우에 효과적이다.
<task>
이 브랜치의 보안 리스크와 테스트 갭을 병렬로 분석한다.
</task>
<action_safety>
파일 수정 금지. 읽기만 허용.
</action_safety>
<completeness_contract>
두 서브에이전트 결과가 모두 반환되면 완료.
파일 경로와 줄 번호를 포함해 요약한다.
</completeness_contract>
<task>는 Goal, <action_safety>는 Constraints, <completeness_contract>는 Completion과 대응된다. 처음에는 위 자연어 패턴이 충분하다. 프롬프트가 길어지고 에이전트 동작이 예상과 달라질 때 이 구조로 바꿔보면 된다.
3.4 /agent 명령으로 스레드 확인하기
서브에이전트가 실행 중일 때 /agent 슬래시 명령을 쓰면 각 에이전트의 작업창으로 이동할 수 있다. 슬래시 명령은 Codex CLI 안에서 /로 시작하는 명령어다.
공식 슬래시 명령 문서에 따르면 /agent의 역할은 다음과 같이 정의되어 있다.
"/agent — Switch the active agent thread. Inspect or continue work in a spawned subagent thread."
(번역) "/agent — 활성 에이전트 스레드를 전환한다. 생성된 서브에이전트 스레드의 작업을 확인하거나 이어서 진행할 수 있다."
여러 서브에이전트가 동시에 실행될 때는 현재 CLI 세션 안에서 각 스레드에 들어가 중간 상태를 보거나 추가 지시를 줄 수 있다.
처음에는 꼭 필요한 경우에만 확인하면 된다. 너무 자주 끼어들면 병렬 작업의 장점이 줄어든다(CLI 슬래시 명령 문서 참조).
ex) 상기 예시중 3개의 서브 에이전트를 띄운 상황에서 /agent 입력
- 메인 에이전트 이외에 3개의 에이전트가 확인된다.
- 이중 3번째 code-reviewer 를 선택하면 실제 작업 중인 내역도 확인 가능하.
승인 요청이 뜨면 먼저 출처를 확인한다
서브에이전트가 여러 개일 때는 내가 보고 있지 않은 에이전트 스레드에서 명령 승인 요청이 올라올 수 있다. 이때는 바로 허용하지 말고 /agent로 해당 스레드를 열어 어떤 작업 중인지 확인한 뒤 승인한다. 특히 파일 수정, 네트워크 접근, 테스트 실행처럼 부작용이 있을 수 있는 명령은 이 확인 절차가 중요하다.
현재 공식 문서는 서브에이전트 활동을 Codex 앱과 CLI에서 확인할 수 있고, IDE에서의 가시성은 별도로 안내 중이라고 설명한다. 그래서 이 글의 실습은 CLI 기준으로 설명한다.
3.5 따라 해보는 실전 멀티 에이전트 프롬프트 4가지
개념만 읽으면 "언제 써야 하지?"가 막연하다.
바로 복붙해서 써볼 수 있는 프롬프트를 준비했다.
실습 내용은 가장 안전한 읽기 전용 예시이고, 예시 A에서 C로 갈수록 에이전트 협업 복잡도가 올라간다.
직접 해보자 — 바이브 코딩 버전
구조 몰라도 된다. 이 한 줄을 그대로 Codex에 붙여넣어 보자.
main 브랜치와 비교해서 바뀐 파일들을 보안 리스크와 테스트 갭, 두 관점으로 병렬로 분석해줘. 파일 수정 금지. 파일 경로와 줄 번호 포함해서 각각 요약해줘.
두 개의 에이전트가 뜨고, 결과가 "보안 리스크 / 테스트 갭" 두 섹션으로 나눠 오면 이 편의 핵심을 이해한 것이다.
ex) 실제 의도 파악을 하는지 테스트 하였고 그 결과
- 읽기 전용 및 보인/테스크 갭 분리하여 2개의 병렬 검토 진행 성공
실전 예시에 공통으로 들어가는 패턴
Goal: 에이전트가 달성할 결과를 한 문장으로
Setup: 컨텍스트 — 저장소, 브랜치, 파일 경로
Subagents: 에이전트별 역할과 산출 형식 명시
Constraints: 금지 사항 — 특히 쓰기 제한
Completion: 완료 판단 기준
에이전트가 많을수록 빠를까?
멀티스레딩 경험이 있는 개발자라면 본능적으로 "에이전트 수 = 속도"라고 느낀다. 틀린 직관이다.
프롬프트가 명확한 에이전트 하나 > 역할이 흐릿한 에이전트 셋. 분담이 모호하면 세 방향으로 흩어질 뿐이다.
대표적으로 효과가 나는 경우는 세 가지다. 독립적인 읽기 전용 탐색, 같은 산출물에 다른 관점을 동시에 적용하는 리뷰, 가벼운 탐색과 무거운 최종 판단을 나누는 흐름이다.
첫 실습 — 현재 저장소를 읽기만 해서 요약하기
가장 먼저 해볼 실습은 파일을 수정하지 않는 저장소 탐색이다. 아래 프롬프트는 현재 작업 폴더에서 구조, 테스트 위치, 패키지 관리 흔적만 읽고 짧게 요약하게 한다.
Use two parallel subagents for read-only exploration.
Do not edit files and do not run install commands.
Agent 1: inspect the top-level folders and summarize the project structure in 5 lines.
Agent 2: find test folders and package manager files, then summarize them in 5 lines.
Wait for both agents and return:
1. Project structure summary
2. Test/package summary
3. One next command I should run manually to verify the project
ex) 2개의 읽기 전용 서브에이전트를 띄워 일하는 모습
기대 결과
좋은 결과는 길지 않다. 예를 들어 "src는 앱 코드, tests는 회귀 테스트, package.json 기준 npm 프로젝트, 다음 확인 명령은 npm test"처럼 짧은 구조 요약과 수동 검증 명령 하나가 나오면 충분하다. 처음부터 파일 수정까지 맡기지 않는 이유는, 서브에이전트가 어떻게 결과를 합치는지 먼저 확인하기 위해서다.
예시 A — 낯선 저장소 첫 탐색: 구조·테스트·의존성 동시에
새 프로젝트에 처음 들어갔을 때 "디렉토리 구조가 어떻게 되지? 테스트는 어디까지 있지? 외부 의존성은 뭐가 있지?"를 순서대로 확인하면 시간이 꽤 걸린다. 세 에이전트가 동시에 읽어서 요약하면 전체 그림을 더 빨리 잡을 수 있다. 세 에이전트 모두 읽기만 하므로 충돌 가능성이 낮다.
Goal: 낯선 저장소의 전체 그림을 빠르게 파악한다.
Setup:
저장소: github.com/example/myproject (로컬 클론 완료)
브랜치: main
Subagents:
- structure-agent: src/ 하위 디렉토리 구조와 주요 파일 역할을
3~5줄 요약으로 돌려줘. 파일을 수정하면 안 된다.
- test-agent: tests/ 또는 __tests__/ 폴더를 훑어서 테스트가
어느 모듈까지 커버하는지 3줄로 요약해 줘. 파일을 수정하면 안 된다.
- deps-agent: package.json 또는 requirements.txt를 읽고
핵심 외부 의존성 5개와 용도를 정리해 줘. 파일을 수정하면 안 된다.
Constraints:
- 세 에이전트 모두 파일 수정, 실행, 설치 금지
- 요약은 각 에이전트 역할 범위 안에서만
Completion:
세 에이전트 요약을 모아 "저장소 첫인상 보고서"를 한 블록으로 출력한다.
프롬프트 줄별 해설
Subagents 에이전트별 이름: 이름이 없으면 /agent로 추적하기 어렵다. 어느 에이전트가 어떤 역할인지 Codex도, 사람도 헷갈린다.
각 에이전트 지시 안에 "파일을 수정하면 안 된다" 반복: Constraints 블록만으로는 부족하다. 에이전트별 지시 안에도 직접 적어야 더 잘 지킨다.
출력 형식을 줄 수로 제한: "3~5줄", "3줄"처럼 길이를 못 박으면 각 에이전트가 과도한 맥락을 쏟아내지 않는다. 통합 단계가 훨씬 깔끔해진다.
Completion에 통합 주체 명시: "세 에이전트 요약을 모아"처럼 누가 결과를 합치는지 적지 않으면 각자 결과만 출력하고 끝날 수 있다.
예시 A의 구조를 그림으로 보면 한눈에 들어온다. orchestrator가 작업을 fan-out으로 분배하고, 각 에이전트가 자기 범위만 읽은 뒤 결과를 fan-in으로 합치는 형태다.
┌─────────────────────────────────────────────────────┐
│ orchestrator │
│ (목표 설정 · 결과 검토 · 다음 지시) │
└──────────────┬───────────────────────────────────────┘
│ fan-out (작업 분배)
┌───────┼───────┐
▼ ▼ ▼
[탐색 agent] [테스트 agent] [리뷰 agent]
│ │ │
└───────┼───────┘
│ fan-in (결과 합산)
▼
최종 보고서
이 구조가 머릿속에 그려지면 다음 예시들도 같은 틀의 변주로 읽힌다. 예시 B는 같은 틀에 "관점별 모델 차등"을 더한 형태다.
예시 B — PR 셀프 리뷰: 보안·성능·가독성을 동시에
PR 리뷰를 혼자 할 때 보안, 성능, 가독성을 한 번에 보려면 시각이 섞인다. 관점별로 에이전트를 따로 두면 각자 다른 렌즈로 같은 코드를 본다. 리뷰 깊이가 다른 관점엔 모델 설정도 다르게 줄 수 있다.
Goal: feature/auth-refactor 브랜치 PR을 세 관점으로 동시 리뷰한다.
Setup:
대상: src/auth/ 변경분 (main 브랜치 대비)
범위: 신규 파일 + 수정 파일만
Subagents:
# 모델 ID 참고: https://platform.openai.com/docs/codex
- security-agent (model: o3, effort: high):
인증 우회, 세션 고정, 입력값 미검증 패턴만 찾아서
파일명:줄번호 형식으로 목록화해 줘.
- perf-agent (model: codex-mini-latest, effort: medium):
N+1 쿼리, 루프 안 DB 호출, 불필요한 await를 찾아서
파일명:줄번호 형식으로 목록화해 줘.
- readability-agent (model: codex-mini-latest, effort: low):
함수 길이 30줄 초과, 인자 5개 초과, 중복 로직을 찾아서
파일명:줄번호 형식으로 목록화해 줘.
Constraints:
- 파일 수정 금지. 리뷰 의견만 출력
- 관점 범위 밖 이슈는 언급하지 않는다
Completion:
세 에이전트 결과를 "보안 / 성능 / 가독성" 섹션으로 나눠서 출력한다.
프롬프트 줄별 해설
에이전트별 다른 model/effort: 보안처럼 놓치면 위험한 검토는 강한 모델과 높은 추론 설정으로 시작하고, 단순 스캔은 가벼운 모델로 시작할 수 있다. 이것은 공식 규칙이 아니라 비용과 위험을 함께 보는 실무 출발점이다.
"관점 범위 밖 이슈는 언급하지 않는다": 이 줄이 없으면 각 에이전트가 다른 관점의 이슈까지 포함해서 결과가 3배로 중복된다.
출력 형식을 "파일명:줄번호"로 통일: 자유 형식으로 두면 에이전트마다 양식이 달라져서 통합이 어렵다.
Completion의 섹션 구분: 사소해 보이지만, 통합 에이전트가 섹션 헤더를 인식하고 결과를 분류하는 데 도움이 된다.
A와 B는 모두 한 번에 fan-out하는 단순 구조였다. 예시 C는 한 단계 더 나아가, 직렬과 병렬을 섞은 다단계 흐름을 다룬다.
예시 C — 라이브러리 업그레이드 영향 분석: 직렬 → 병렬 → 통합
큰 의존성을 올릴 때 "어디가 깨지는지"를 보려면 먼저 전체 사용처를 파악해야 한다.
그 다음에 영역별로 나눠서 동시에 분석하고, 마지막에 합친다. A·B와 달리 에이전트 실행 순서가 있다.
Goal: lodash 4 -> 6 업그레이드 시 영향 범위를 분석한다.
Setup:
저장소: 현재 작업 디렉토리
대상 패키지: lodash (4.x -> 6.x)
Phase 1 (직렬):
- scan-agent: lodash를 import하는 파일 전체 목록을 출력하고
reports/lodash-usage.md 에 저장해 줘.
Phase 2 (병렬, Phase 1 완료 후 실행):
- api-agent: reports/lodash-usage.md를 읽고 lodash 6에서
제거되거나 시그니처가 바뀐 함수만 정리해 줘.
결과를 reports/api-changes.md 에 저장해 줘.
- test-agent: reports/lodash-usage.md를 읽고 lodash 관련
테스트 파일을 찾아서 커버리지 갭을 요약해 줘.
결과를 reports/test-gaps.md 에 저장해 줘.
- type-agent: reports/lodash-usage.md를 읽고 TypeScript 타입
불일치 가능성이 있는 파일을 목록화해 줘.
결과를 reports/type-risks.md 에 저장해 줘.
Phase 3 (직렬, Phase 2 완료 후 실행):
- merge-agent: reports/ 아래 세 파일을 읽어서 파일별 대응
우선순위를 "위험도: 높음/중간/낮음" 기준으로 정리해 줘.
Constraints:
- scan-agent, api-agent, test-agent, type-agent: 파일 수정 금지
- merge-agent: reports/ 파일만 읽고, 코드 파일 수정 금지
Completion:
merge-agent 결과가 콘솔에 출력되면 완료.
프롬프트 줄별 해설
Phase 1/2/3 명시적 분리: Codex가 순서를 추론하게 두면 Phase 1 완료 전에 Phase 2가 실행될 수 있다. "Phase 1 완료 후 실행"을 직접 적어야 한다.
시그니처: 함수의 이름, 매개변수(입력), 반환 타입을 합친 외형 정보다. "시그니처가 바뀐 함수"란 호출 방법이 달라진 함수를 뜻한다. 업그레이드 후 이전 코드가 그대로 동작하지 않는 원인이 된다.
커버리지 갭: 테스트가 실행하지 않는 코드 영역이다. "커버리지 갭을 요약해 줘"는 lodash를 쓰는 코드 중 테스트가 없는 부분을 찾아 달라는 뜻이다.
중간 산출을 파일로 남기기 (reports/*.md): Phase 2 에이전트가 Phase 1 결과를 메모리에서만 받는 방식은 불안정하다. 파일에 쓰고 읽게 하면 각 단계를 독립적으로 검증할 수 있다.
merge-agent 읽기 범위를 "reports/ 파일만"으로 제한: 범위를 적지 않으면 전체 저장소를 다시 읽는다. 통합 에이전트는 중간 산출물만 보면 충분하다.
Completion: 마지막 에이전트 기준으로 명시: "모든 에이전트 완료 후"처럼 모호하게 적으면 완료 판단이 흔들린다. 마지막 단계 에이전트를 명시해야 Codex가 종료 시점을 정확히 안다.
세 예시에서 반복된 패턴
에이전트마다 역할과 산출 형식을 따로 적었다 — "요약해 줘"보다 "3줄로 파일명:줄번호 형식으로"가 낫다
쓰기를 허용한 에이전트는 쓸 파일 경로를 명시했다 — 경로 없이 허용하면 어디에 저장할지 임의로 정한다
Constraints의 파일 수정 금지를 에이전트 지시 안에도 반복했다 — 블록 하나로는 부족하다
Completion에 통합 주체 또는 마지막 에이전트를 명시했다 — 이 줄이 없으면 언제 끝나는지 모호해진다
4. 병렬 실행 — 읽기와 쓰기를 구분하라
4.1 읽기 중심 작업에 먼저 적용한다
공식 서브에이전트 문서는 병렬 에이전트가 코드베이스 탐색이나 여러 단계가 있는 기능 계획처럼 나누기 쉬운 작업에 잘 맞는다고 설명한다. 초보자에게는 이 말을 "먼저 읽기 중심 작업부터 나눠 보라"는 운영 기준으로 받아들이는 편이 안전하다.
탐색(exploration, 파일과 구조를 살펴보는 일), 테스트 실행, 이슈 트리아지(문제의 원인과 우선순위를 가르는 일), 요약처럼 파일을 읽고 분석하는 작업은 병렬화에 적합하다. 서로 다른 에이전트가 같은 파일을 동시에 수정하지 않기 때문에 코드 충돌 가능성이 낮다.
테스트 실행은 완전한 읽기 작업이 아닐 수 있다
실제 테스트는 캐시 파일을 만들거나 스냅샷을 갱신하거나 데이터베이스를 건드릴 수 있다. 그래서 "테스트 실행 에이전트"를 둘 때는 프로덕션 DB, 실서비스 API 키, 외부 결제·메일 발송 같은 부작용이 없는지 먼저 확인해야 한다.
예를 들어 오래된 프로젝트에 처음 들어갔다고 해 보자. 디렉토리 구조를 보는 에이전트, 사용 중인 라이브러리를 정리하는 에이전트, 테스트가 어디까지 있는지 확인하는 에이전트를 동시에 실행할 수 있다. 세 작업 모두 읽기 전용이라 충돌이 거의 없다. 각 에이전트가 짧은 요약만 돌려주면, 메인 에이전트는 그 요약을 모아 전체 그림을 만든다. 직접 하나씩 읽는 것보다 대화창도 훨씬 깔끔하게 유지된다.
4.2 쓰기 작업은 충돌에 주의한다
병렬 쓰기는 다르다.
여러 에이전트가 동시에 코드를 고치면 충돌과 조율 비용이 커질 수 있다. 그래서 쓰기 병렬화는 처음부터 조심해야 한다.
여러 에이전트가 동시에 같은 파일을 고치면 충돌 가능성이 매우 높다. 나중에 어느 변경을 살릴지 다시 정리해야 하므로, 병렬화로 아낀 시간을 되돌려 쓰게 된다. 쓰기 작업은 파일 단위로 작업 영역을 나누거나, 아예 순서대로 처리하는 방식이 더 현실적이다.
읽기 vs 쓰기 판단 기준
각 서브에이전트가 "읽고 분석해서 요약을 돌려준다"면 병렬화하기 좋다. "특정 파일을 직접 수정한다"면 누가 어떤 파일을 고칠지 먼저 나눠야 한다.
4.3 작업 조율은 Codex가 도와준다
여러 서브에이전트가 실행되는 동안 생성, 작업 배정, 대기, 결과 취합 같은 조율은 Codex가 도와준다. 이런 조율을 오케스트레이션이라고 부르지만, 초보자는 "여러 작업자를 관리하는 일" 정도로 이해하면 충분하다. 다만 이것이 사용자의 검증 책임까지 대신한다는 뜻은 아니다. 파일 소유권, 완료 기준, 결과 형식은 사용자가 분명히 적어야 하고, 마지막 검증도 직접 해야 한다(서브에이전트 문서 참조).
5. 모델 배분 전략
서브에이전트마다 모델을 다르게 줄 수 있지만, 초보자가 처음부터 모델 카탈로그를 외울 필요는 없다.
기본값으로 시작하고, 느리거나 비싸거나 위험한 작업이 반복될 때만 역할별 조정을 한다.
모델 이름과 제공 범위는 계정과 시점에 따라 달라질 수 있으므로 실제 선택 전에는 Codex Models 문서와 CLI의 모델 선택기를 함께 확인한다.
( 하기 내용은 실제 codex 사용하시는 분들이 아닌 api 방식으로 사용하는 분들이, 비용 대비 성능 최적화를 하기 위해 사용하는 전략이니, 가볍게 보고 어렵다면 데충 넘어가는것을 추천한다. )
서브에이전트 모델 선택을 위한 실무 기준
상황
운영 기준
이유
처음 쓰는 작업
세션 기본 모델 사용
모델 선택보다 역할·범위·완료 기준이 더 중요하다
파일 목록 수집, 구조 요약
가벼운 모델과 낮은 reasoning effort(생각의 깊이 — 높을수록 느리고 비싸다)로 시작
깊은 추론보다 빠른 스캔과 짧은 요약이 중요하다
보안, 설계, 최종 통합 판단
가능한 강한 모델과 높은 effort로 시작
가정 검증과 엣지 케이스 탐색 실패 비용이 크다
비용이나 속도가 부담될 때
모델보다 에이전트 수를 먼저 줄인다
서브에이전트는 단일 실행보다 토큰 사용과 대기 시간이 늘 수 있다
실무 출발점
가벼운 읽기 전용 서브에이전트에는 codex-mini-latest 같은 효율 모델을, 복잡한 리뷰나 최종 판단에는 o3 같은 강한 모델을 배정하는 식으로 시작할 수 있다. 이것은 공식 규칙이 아니라 비용, 속도, 작업 위험을 함께 보는 운영 기준이다.
o3: 복잡한 추론이 필요한 작업에 쓴다. 보안 분석, 설계 결정, 최종 통합 판단처럼 한 번 틀리면 비용이 큰 단계에 배정한다. 느리지만 정확하다.
codex-mini-latest: 빠른 탐색·분류 작업에 쓴다. 파일 목록 수집, 디렉토리 구조 요약, 단순 패턴 스캔처럼 단순 작업에 최적이다. 빠르지만 깊은 추론에는 약하다.
CLI에서는 실행 중에 /model 명령으로 모델을 바꿀 수 있고, 새 CLI 세션이나 codex exec(프롬프트를 인수로 전달해 대화 없이 한 번만 실행하는 서브명령)에서는 -m 또는 --model 플래그를 쓴다. 반복해서 같은 모델을 쓰고 싶을 때만 config.toml 기본값을 조정한다.
요금과 플랜도 함께 봐야 한다. 여러 서브에이전트는 "한 명의 Codex가 더 빨리 생각한다"가 아니라 여러 모델 호출이 동시에 늘어나는 구조다. 공식 Pricing 문서를 확인하고, 현재 계정의 사용 가능 모델, 플랜 한도, API 키 사용 여부를 먼저 본다.
6. 워크플로 설계 원칙
처음엔 이 순서로 생각하면 편하다. 각 원칙을 하나씩 살펴보자.
왜 네 가지인가? 멀티 에이전트가 망가지는 지점은 대부분 같은 자리에서 반복된다. 분리되지 않은 일을 분리한 척 시키거나, 같은 파일을 동시에 고치게 두거나, 결과를 합치는 사람이 없거나, 중간 결과를 확인할 방법이 없거나.
그래서 이 네 자리에 각각 가드레일을 세운 것이 아래 4원칙이다. 세부 구현보다 이 네 가지가 실수를 막는다.
멀티 에이전트 협업 4원칙
분리 가능성을 먼저 검증한다 — 진짜 독립 작업인가, 아니면 숨은 순서가 있는가. 숨은 의존성을 무시하면 Phase 2가 Phase 1 결과를 받지 못한다.
읽기는 병렬, 쓰기는 직렬 — race condition은 여러 작업이 동시에 같은 대상을 건드릴 때 생기는 실행 순서 문제다. 같은 파일을 동시에 고치게 두면 충돌 가능성이 높다.
통합 책임을 명시한다 — 누가 결과를 모으고 최종 판단하는지 적지 않으면, 각 에이전트가 자기 결과만 출력하고 아무도 합치지 않는다.
검증 가능한 산출을 남긴다 — 파일, 요약, 테스트 결과처럼 명시적 artifact(산출물: 에이전트가 남긴 확인 가능한 결과)가 없으면 중간 단계를 나중에 확인할 방법이 없다.
원칙이 어떻게 실수를 막는지 두 가지로 비교해 봤다.
문제 있는 지시
"api-agent와 test-agent가 동시에 src/auth/session.ts를 수정해 줘."
이렇게 바꾸자
"api-agent는 탐색만, 수정은 merge-agent 단독으로 Phase 2에서 진행한다."
해설: 같은 파일을 동시에 수정하면 충돌 가능성이 높다. 탐색 단계를 분리하면 사고를 줄일 수 있다.
"Codex works best when you treat it like a teammate with explicit context and a clear definition of 'done.'"
(번역) "명확한 컨텍스트와 '완료' 기준이 함께 주어지면 Codex는 팀원처럼 가장 잘 작동한다."
팀원에게 일을 맡길 때처럼 배경과 완료 기준을 함께 적어야 한다. "이 PR을 리뷰해 줘"보다 "main 브랜치와 비교해서 보안 위험만 파일 경로와 함께 정리해 줘"가 훨씬 좋은 지시다. PR은 코드 변경 검토 요청이고, main 브랜치는 보통 기준이 되는 기본 브랜치다. 무엇을 봐야 하는지, 결과를 어떤 형태로 돌려줘야 하는지가 분명할수록 결과도 좋아진다.
Workflows를 적용하기 전에는 Prompting 문서의 기본 원칙도 같이 보는 게 낫다. 서브에이전트도 결국 프롬프트 품질에 좌우되기 때문이다. 어떤 파일을 봐야 하는지, 어떤 결과를 돌려줘야 하는지, 무엇을 하면 안 되는지를 적지 않으면 병렬로 빨라지는 대신 여러 방향으로 엇나갈 수 있다.
CLI에서는 파일 경로를 더 명확히 적어야 한다
공식 Workflows 문서에 따르면 IDE 확장은 열린 파일을 자동 컨텍스트로 포함하지만, CLI에서는 보통 파일 경로를 직접 언급하거나 /mention과 @ 경로 자동완성을 사용해야 한다. 초보자는 "이 프로젝트를 봐줘"보다 "src/auth/session.ts와 tests/auth를 기준으로 봐줘"처럼 적는 편이 안전하다.
6.2 오케스트레이터 패턴
복잡한 작업 흐름은 총괄 담당 1명과 역할별 작업자 여러 명으로 나누면 이해하기 쉽다.
메인 에이전트가 전체 목표와 완료 기준을 잡고, 서브에이전트가 각자 좁은 범위를 조사한 뒤 결과를 돌려주는 구조다.
"Review this branch against main. Have pr_explorer map the affected code paths, reviewer find real risks, and docs_researcher verify the framework APIs that the patch relies on."
(번역) "이 브랜치를 main과 비교해서 리뷰해라. pr_explorer가 영향받는 코드 경로를 파악하고, reviewer가 실제 위험을 찾고, docs_researcher가 패치가 의존하는 프레임워크 API를 공식 문서와 대조해서 확인한다."
pr_explorer는 바뀐 코드가 어디에 영향을 주는지 찾고, reviewer는 실제 위험을 찾고, docs_researcher는 사용한 API가 공식 문서와 맞는지 확인한다. API는 프로그램끼리 서로 기능을 호출하는 약속이라고 보면 된다. 역할이 분명하면 마지막에 결과를 합치기도 쉽다(서브에이전트 문서 참조).
실제 프로덕션 에이전트 해부: codex-rescue
오케스트레이터 패턴의 실제 구현체가 궁금하다면 superpowers 플러그인의 codex-rescue 에이전트가 좋은 참고 사례다. 이 에이전트는 세 가지 규칙만으로 설계되어 있다.
단일 책임: Codex CLI 호출 하나만 담당한다. 저장소를 직접 탐색하거나 파일을 분석하는 일은 하지 않는다. 터미널 출력(stdout)을 그대로 돌려주는 것이 전부다.
도구 제한: Bash 도구만 허용한다. 권한을 최소화하면 예상치 못한 부작용이 줄어든다. 에이전트가 할 수 있는 일을 적게 정의할수록 결과를 예측하기 쉽다.
모델 라우팅: 작업 복잡도에 따라 --model과 --effort를 조합한다. 무거운 모델을 모든 작업에 쓰지 않는다.
같은 원칙을 직접 만드는 에이전트 TOML에 적용하면 다음과 같다.
# 모델 ID 참고: https://platform.openai.com/docs/codex
name = "pr_reviewer"
description = "Security and test gap reviewer. Read-only."
model = "codex-mini-latest"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Review only. Do not edit files.
Report findings with file path and line number.
Return a summary under 200 words.
"""
superpowers 플러그인은 Claude Code 마켓플레이스에서 /install
superpowers로 설치하면 바로 확인할 수 있다. 이 단일 책임·도구 최소화·모델 라우팅 세 원칙은 오픈소스 에이전트 생태계에서 반복적으로 나타나는 패턴이다. Part 5 (MCP · Plugins · Skills)에서는 이 원칙을 직접 플러그인으로 만들어 배포하는 법을 다룬다.
6.3 커스텀 에이전트 파일 정의
처음부터 커스텀 에이전트를 만들 필요는 없다. 기본 에이전트로도 충분히 실습할 수 있다.
다만 같은 역할을 계속 반복한다면 TOML 파일로 에이전트를 정의해 재사용할 수 있다. TOML은 설정 파일 형식이고, 여기서는 "이 에이전트의 이름, 설명, 지시문을 파일로 저장해 둔다" 정도로 이해하면 된다.
커스텀 에이전트를 만들지 판단하는 기준
상황
판단
한 번 해보는 저장소 탐색
프롬프트에 직접 역할을 적는다
매 PR마다 같은 보안 리뷰를 반복
커스텀 에이전트 후보
팀 전체가 같은 역할을 재사용
.codex/agents/에 두고 버전 관리 검토
공식 문서 기준으로 커스텀 에이전트의 필수 필드는 name, description, developer_instructions다. 전역 에이전트는 ~/.codex/agents/, 프로젝트 에이전트는 .codex/agents/에 둔다.
아주 작은 예시는 다음과 같다. 다만 에이전트 파일의 sandbox_mode = "read-only"만으로 항상 읽기 전용 실행이 보장된다고 이해하면 안 된다. 서브에이전트는 현재 세션의 권한·승인 설정 영향을 받으므로, 처음에는 현재 CLI 권한을 확인하고 프롬프트에도 Do not edit files.를 함께 적는 편이 안전하다.
# 모델 ID 참고: https://platform.openai.com/docs/codex
name = "docs_researcher"
description = "Official documentation checker for API and framework behavior."
model = "codex-mini-latest"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Use official documentation first.
Return concise findings with source links.
Do not edit files.
"""
에이전트 수 제한도 안전장치다
공식 Config Reference 기준으로 agents.max_threads의 기본값은 6, agents.max_depth의 기본값은 1이다. 동시에 너무 많은 스레드가 열리거나, 서브에이전트가 다시 하위 에이전트를 계속 만드는 일을 제한하기 위한 값이다. 초보자는 이 값을 올리기보다 작업을 더 작게 나누는 편이 안전하다.
6.4 결과 취합은 요약으로 돌려받는다
서브에이전트의 가공되지 않은 긴 로그나 추적 기록 전체를 메인 스레드로 가져오면 다시 대화창이 지저분해진다. 그래서 프롬프트에 "핵심만 요약해 줘", "중요한 결론만 돌려줘"라고 명시하는 것이 좋다. 영어 프롬프트를 쓴다면 "summarize the findings"나 "return distilled takeaways"처럼 적으면 된다.
6.5 결과를 믿기 전에 확인할 것
서브에이전트가 여러 개면 결과도 그럴듯해 보이기 쉽다. 하지만 요약이 깔끔하다고 해서 바로 맞는 것은 아니다. 최소한 아래 네 가지는 확인한다.
파일 경로와 줄 번호가 실제로 존재하는지 확인한다.
테스트를 실행했다면 어떤 명령을 실행했고, 성공/실패 결과가 무엇인지 확인한다.
API나 프레임워크 동작을 말한다면 공식 문서 링크가 붙어 있는지 확인한다.
서로 다른 서브에이전트의 결론이 충돌하면, 메인 스레드에서 다시 근거를 비교한 뒤 결정한다.
7. 정리 및 실전 적용 가이드
7.1 언제 서브에이전트를 쓸 것인가
마지막 사용 판단표
상황
권장 행동
이유
탐색·문제 분류·요약 작업
읽기 전용이면 권장
대부분 읽기 전용이라 충돌이 적다
PR(코드 변경 요청) 다각도 리뷰
관점별 역할이 분명할 때 권장
보안, 버그, 테스트를 따로 볼 수 있다
대용량 문서 분석
범위를 나눠 사용
큰 내용을 나눠 읽고 요약만 합칠 수 있다
동일 파일 동시 수정
초보자는 피함
같은 줄을 고치면 충돌 정리가 필요하다
단순 단일 파일 편집
메인 스레드에서 처리
나눠 맡기는 비용이 더 클 수 있다
한 줄로 정리하면 이렇다. 읽고 분석해 요약을 돌려주는 작업은 병렬 서브에이전트에 맡기고, 파일을 직접 고치는 단순 작업은 메인 스레드에서 처리하는 편이 안전하다.
7.2 다음 편 예고
Part 4: AGENTS.md · Rules
이번 편에서 서브에이전트에게 역할별 지시를 줬다면, 그 지시를 파일로 굳혀 팀 전체가 재사용하는 법이 Part 4의 주제다.
Constraints 블록을 AGENTS.md로 옮기면 매 프롬프트마다 반복하지 않아도 된다
전역 규칙 · 저장소 규칙 · 폴더별 규칙을 어떻게 나눌지
Karpathy 4원칙을 AGENTS.md 템플릿으로 만들어 바로 쓰는 방법
Part 5: MCP · Plugins · Skills
오늘 해부한 codex-rescue처럼 에이전트를 플러그인으로 만들어 배포하는 법을 다룬다. 오케스트레이터 패턴이 외부 서비스(Slack, GitHub, Jira)와 연결되면 사람 없이 돌아가는 워크플로가 된다.
"Context pollution: useful information gets buried under noisy intermediate output. Context rot: performance degrades as the conversation fills up with less relevant details."
(번역) "컨텍스트 오염: 유용한 정보가 불필요한 중간 출력에 묻혀 버린다. 컨텍스트 부식: 덜 관련된 세부 정보로 대화창이 채워지면서 성능이 점점 저하된다."
Context pollution은 말 그대로 "대화창이 지저분해지는 현상"이다. 파일 탐색 메모, 테스트 로그, 스택 트레이스(오류가 어디서 시작됐는지 보여주는 긴 기록)가 쌓이면서 정작 중요한 요구사항이 뒤로 밀린다.
Context rot은 그 결과로 답변 품질이 서서히 나빠지는 상태다. 쉽게 말해, 대화창이 너무 어수선해져서 Codex가 처음 목표를 잊어버리는 것이다.
해결 방향은 단순하다. 메인 스레드, 즉 내가 계속 보고 있는 중심 대화창에는 "요구사항·결정·최종 출력"만 남긴다.
파일 탐색이나 테스트처럼 로그가 많이 나오는 일은 서브에이전트에게 따로 맡기면 된다.
이 두 개념을 굳이 나누는 이유도 실전에서는 꽤 중요하다. context pollution은 지금 당장 "로그가 너무 많이 쌓였네" 하고 알아차릴 수 있다. 반면 context rot은 한참 뒤에 "왜 답이 점점 엉뚱해지지?"라는 식으로 드러난다. 먼저 오염을 줄이고, 길어진 대화에서는 품질 저하가 생기지 않는지 확인해야 한다.
"Subagent workflow: A workflow where Codex runs parallel agents and combines their results. Subagent: A delegated agent that Codex starts to handle a specific task. Agent thread: The CLI thread for an agent, which you can inspect and switch between with /agent."
(번역) "서브에이전트 워크플로: Codex가 여러 에이전트를 병렬로 실행하고 결과를 합치는 흐름. 서브에이전트: 특정 작업을 담당하도록 Codex가 시작한 보조 에이전트. 에이전트 스레드: /agent 명령으로 전환하거나 확인할 수 있는 에이전트별 CLI 작업창."
subagent workflow는 Codex가 여러 에이전트를 병렬로 실행하고 결과를 합치는 흐름이다.
subagent는 특정 작업을 맡기기 위해 Codex가 시작한 보조 에이전트이고, agent thread는 /agent로 전환하거나 확인할 수 있는 에이전트별 작업창이다.
ex) /agent
서브에이전트 워크플로(Subagent workflow): Codex가 여러 보조 에이전트를 실행하고 결과를 합치는 전체 흐름이다.
서브에이전트(Subagent): 특정 작업을 담당하도록 Codex가 따로 띄운 보조 에이전트다.
에이전트 스레드(Agent thread): CLI에서 각 에이전트가 일하는 개별 작업창이다. /agent 명령으로 전환하거나 확인할 수 있다.
관계는 이렇게 보면 쉽다. 하나의 작업 흐름 안에 여러 보조 작업자가 있고, 각 보조 작업자는 자기 대화창을 따로 가진다.
여기서 중요한 것은 에이전트 스레드다. 서브에이전트는 안 보이는 곳에서 잠깐 실행되고 끝나는 기능이 아니다. CLI에서 직접 들어가 볼 수 있는 독립된 작업창으로 남는다. 그래서 /agent 명령으로 실행 중인 서브에이전트의 중간 상태를 확인하거나 추가 지시를 줄 수 있다.
2.2 언제 필요한가
두 가지 상황에서 서브에이전트가 유용하다.
첫째, 대화창이 복잡해지기 시작할 때다. 메인 스레드에 요구사항과 탐색 로그가 뒤섞이면, 파일 조사 같은 작업을 서브에이전트로 빼는 편이 낫다.
둘째, 한 번에 읽기 어려울 만큼 큰 작업이다. 예를 들어 문서나 코드가 너무 많으면 Codex가 모든 내용을 한 대화 안에서 안정적으로 다루기 어렵다. 이때는 여러 서브에이전트가 각자 일부를 읽고, 핵심 요약만 메인 스레드로 돌려보내게 만들 수 있다(서브에이전트 문서 참조).
3. 서브에이전트 생성하기
3.1 명시적 지시만 가능하다
서브에이전트 생성에는 중요한 전제가 있다. 공식 문서는 이를 명확히 못 박는다.
"Codex doesn't spawn subagents automatically, and it should only use subagents when you explicitly ask for subagents or parallel agent work."
(번역) "Codex는 서브에이전트를 자동으로 생성하지 않으며, 사용자가 명시적으로 서브에이전트 또는 병렬 에이전트 작업을 요청할 때만 사용한다."
Codex는 서브에이전트를 마음대로 만들지 않는다.
사용자가 "병렬 에이전트를 써라", "이 일을 나눠서 맡겨라"처럼 직접 지시해야 한다.이 제한은 오히려 초보자에게 좋다.
나도 모르는 사이에 여러 에이전트가 실행되면 비용, 속도, 작업 흐름을 파악하기 어려워지기 때문이다.
3.2 지시 표현 예시
공식 문서는 다음과 같은 표현을 직접 지시의 예로 든다. 이 표현만 되는 것은 아니고, 핵심은 "일을 나눠서 병렬 에이전트에게 맡긴다"는 의도가 분명해야 한다는 점이다.
"spawn two agents", "delegate this work in parallel", "use one agent per point"
(번역) "에이전트 두 개를 띄워라", "이 작업을 병렬로 위임해라", "항목마다 에이전트 하나씩 써라"
핵심은 "병렬로", "에이전트를 따로", "항목별로 나눠서" 같은 말을 프롬프트에 직접 넣는 것이다.
그냥 "검토해 줘"라고 쓰면 보통 하나의 메인 스레드에서 처리된다.
비교 — 같은 PR 리뷰 요청, 지시 방식에 따라 결과가 다르다
프롬프트 원문: "이 PR을 다각도로 리뷰해줘"
서브에이전트 지시 없을 때
이 PR을 다각도로 리뷰해줘.
→ 보안·테스트·유지보수성이 한 응답에 섞여 나옴 → 각 관점의 깊이가 얕아지고, "다각도"의 범위는 Codex가 임의로 결정 → 어느 관점에서 뭘 말하는지 구분 안 됨
ex) 가장 최신 pr을 다각도로 리뷰해줘.
- 싱글 에이전트가 단독으로 계쏙 리뷰해 나가는 모습
병렬 서브에이전트 명시 후
Spawn one agent for security risks,
one for test gaps,
one for maintainability.
Wait for all three, then summarize by category with file references.
한국어로도 동일하게 동작한다:
보안 리스크를 볼 에이전트, 테스트 빈틈을 볼 에이전트, 유지보수성을 볼 에이전트를 각각 하나씩 띄워라.
세 결과가 모두 나오면 파일 경로와 함께 카테고리별로 요약하라.
→ 각 에이전트가 한 관점만 깊이 분석 → 결과가 카테고리별로 정리되어 합치기 쉬움 → 완료 기준이 "세 에이전트 모두 반환"으로 명확
ex) 가장 최신 pr을 보안 리스크를 볼 에이전트, 테스트 빈틈을 볼 에이전트, 유지보수성을 볼 에이전트를 각각 하나씩 띄워라. 세 결과가 모두 나오면 파일 경로와 함께 카테고리별로 요약하라.
- 최신 커밋은 1개의 에이전트가 확인
- 이후 지시사항대로 3개의 에이전트를 각각 띄워 작업을 시키는것을 볼 수 있다.
3.3 실전 프롬프트 예시
예시 1 — 읽기 전용 조사
Use two parallel subagents for read-only exploration.
One subagent should map the changed files.
The other should find related tests.
Do not edit files. Return short summaries with file paths.
한국어 버전:
읽기 전용 조사에 서브에이전트 2개를 병렬로 써라.
에이전트 1: 변경된 파일 목록을 정리해라.
에이전트 2: 관련 테스트 파일을 찾아라.
파일 수정 금지. 파일 경로가 포함된 짧은 요약만 돌려줘.
처음에는 이렇게 2개 정도의 읽기 전용 서브에이전트로 시작하는 편이 좋다. "수정하지 말라", "파일 경로를 포함해 짧게 요약하라"를 함께 적어 두면 결과를 확인하기 쉽다.
예시 2 — 브랜치 병렬 리뷰
Review this branch with parallel subagents.
Spawn one subagent for security risks, one for test gaps,
and one for maintainability.
Wait for all three, then summarize the findings by category
with file references.
한국어 버전:
이 브랜치를 병렬 서브에이전트로 리뷰해라.
보안 리스크를 볼 에이전트, 테스트 빈틈을 볼 에이전트, 유지보수성을 볼 에이전트를 각각 하나씩 띄워라.
세 결과가 모두 나오면 파일 경로와 함께 카테고리별로 요약하라.
세 가지 관점(보안·테스트·유지보수성)을 각각의 서브에이전트에 맡기고, 모든 결과를 기다린 뒤 카테고리별로 정리하게 하는 예시다. 여기서도 "누가 무엇을 볼지", "모든 결과를 기다릴지", "어떤 형식으로 요약할지"를 노골적으로 적는 것이 중요하다.
예시 3 — PR 6개 관점 분산 리뷰
I would like to review the following points on the current PR
(this branch vs main).
Spawn one agent per point, wait for all of them, and summarize
the result for each point.
1. Security issue
2. Code quality
3. Bugs
4. Race
5. Test flakiness
6. Maintainability of the code
한국어 버전:
현재 PR(이 브랜치 vs main)을 아래 관점으로 리뷰해라.
항목마다 에이전트를 하나씩 띄우고, 모두 끝나면 항목별로 결과를 요약하라.
1. 보안 이슈
2. 코드 품질
3. 버그
4. 경쟁 조건 (race condition: 동시 실행 시 순서가 꼬이는 문제)
5. 테스트 불안정성 (test flakiness: 가끔만 실패하는 테스트)
6. 코드 유지보수성
체크리스트 형태로 관점을 적으면 Codex가 항목마다 서브에이전트를 하나씩 배정할 수 있다.
다만 6개 에이전트는 기초 실습으로는 많다. (토큰 낭비로 이어질수도 있다.)
큰 PR에서 비용과 대기 시간을 감수할 만할 때만 쓰고, 평소에는 2~3개 관점부터 시작하는 편이 낫다(서브에이전트 문서 참조).
예시 4 — React 컴포넌트 스타일 버그 병렬 탐색
Use two parallel subagents for read-only exploration.
One subagent should find all files that import or use the broken Button component.
The other should check the Button's CSS module and styled-component for conflicting styles.
Do not edit files. Return short summaries with file paths.
한국어 버전:
읽기 전용 조사에 서브에이전트 2개를 병렬로 써라.
에이전트 1: Button 컴포넌트를 import하거나 사용하는 파일 전체를 목록화해라.
에이전트 2: Button의 CSS 모듈 또는 styled-component에서 충돌 가능성 있는 스타일을 찾아라.
파일 수정 금지. 파일 경로가 포함된 짧은 요약만 돌려줘.
React 프로젝트에서 특정 컴포넌트에 스타일 버그가 생겼을 때 유용한 패턴이다. 사용처와 스타일 정의를 동시에 훑어야 원인을 빨리 좁힐 수 있고, 두 에이전트 모두 읽기만 하므로 부작용이 없다.
Goal / Constraints / Completion을 더 정밀하게: prompt-blocks
위 패턴이 익숙해졌다면 XML 블록으로 각 역할을 명시적으로 분리하는 방식으로 한 단계 올릴 수 있다. 긴 프롬프트에서 에이전트가 Goal과 Constraints를 혼동하는 경우에 효과적이다.
<task>
이 브랜치의 보안 리스크와 테스트 갭을 병렬로 분석한다.
</task>
<action_safety>
파일 수정 금지. 읽기만 허용.
</action_safety>
<completeness_contract>
두 서브에이전트 결과가 모두 반환되면 완료.
파일 경로와 줄 번호를 포함해 요약한다.
</completeness_contract>
<task>는 Goal, <action_safety>는 Constraints, <completeness_contract>는 Completion과 대응된다. 처음에는 위 자연어 패턴이 충분하다. 프롬프트가 길어지고 에이전트 동작이 예상과 달라질 때 이 구조로 바꿔보면 된다.
3.4 /agent 명령으로 스레드 확인하기
서브에이전트가 실행 중일 때 /agent 슬래시 명령을 쓰면 각 에이전트의 작업창으로 이동할 수 있다. 슬래시 명령은 Codex CLI 안에서 /로 시작하는 명령어다.
공식 슬래시 명령 문서에 따르면 /agent의 역할은 다음과 같이 정의되어 있다.
"/agent — Switch the active agent thread. Inspect or continue work in a spawned subagent thread."
(번역) "/agent — 활성 에이전트 스레드를 전환한다. 생성된 서브에이전트 스레드의 작업을 확인하거나 이어서 진행할 수 있다."
여러 서브에이전트가 동시에 실행될 때는 현재 CLI 세션 안에서 각 스레드에 들어가 중간 상태를 보거나 추가 지시를 줄 수 있다.
처음에는 꼭 필요한 경우에만 확인하면 된다. 너무 자주 끼어들면 병렬 작업의 장점이 줄어든다(CLI 슬래시 명령 문서 참조).
ex) 상기 예시중 3개의 서브 에이전트를 띄운 상황에서 /agent 입력
- 메인 에이전트 이외에 3개의 에이전트가 확인된다.
- 이중 3번째 code-reviewer 를 선택하면 실제 작업 중인 내역도 확인 가능하.
승인 요청이 뜨면 먼저 출처를 확인한다
서브에이전트가 여러 개일 때는 내가 보고 있지 않은 에이전트 스레드에서 명령 승인 요청이 올라올 수 있다. 이때는 바로 허용하지 말고 /agent로 해당 스레드를 열어 어떤 작업 중인지 확인한 뒤 승인한다. 특히 파일 수정, 네트워크 접근, 테스트 실행처럼 부작용이 있을 수 있는 명령은 이 확인 절차가 중요하다.
현재 공식 문서는 서브에이전트 활동을 Codex 앱과 CLI에서 확인할 수 있고, IDE에서의 가시성은 별도로 안내 중이라고 설명한다. 그래서 이 글의 실습은 CLI 기준으로 설명한다.
3.5 따라 해보는 실전 멀티 에이전트 프롬프트 4가지
개념만 읽으면 "언제 써야 하지?"가 막연하다.
바로 복붙해서 써볼 수 있는 프롬프트를 준비했다.
실습 내용은 가장 안전한 읽기 전용 예시이고, 예시 A에서 C로 갈수록 에이전트 협업 복잡도가 올라간다.
직접 해보자 — 바이브 코딩 버전
구조 몰라도 된다. 이 한 줄을 그대로 Codex에 붙여넣어 보자.
main 브랜치와 비교해서 바뀐 파일들을 보안 리스크와 테스트 갭, 두 관점으로 병렬로 분석해줘. 파일 수정 금지. 파일 경로와 줄 번호 포함해서 각각 요약해줘.
두 개의 에이전트가 뜨고, 결과가 "보안 리스크 / 테스트 갭" 두 섹션으로 나눠 오면 이 편의 핵심을 이해한 것이다.
ex) 실제 의도 파악을 하는지 테스트 하였고 그 결과
- 읽기 전용 및 보인/테스크 갭 분리하여 2개의 병렬 검토 진행 성공
실전 예시에 공통으로 들어가는 패턴
Goal: 에이전트가 달성할 결과를 한 문장으로
Setup: 컨텍스트 — 저장소, 브랜치, 파일 경로
Subagents: 에이전트별 역할과 산출 형식 명시
Constraints: 금지 사항 — 특히 쓰기 제한
Completion: 완료 판단 기준
에이전트가 많을수록 빠를까?
멀티스레딩 경험이 있는 개발자라면 본능적으로 "에이전트 수 = 속도"라고 느낀다. 틀린 직관이다.
프롬프트가 명확한 에이전트 하나 > 역할이 흐릿한 에이전트 셋. 분담이 모호하면 세 방향으로 흩어질 뿐이다.
대표적으로 효과가 나는 경우는 세 가지다. 독립적인 읽기 전용 탐색, 같은 산출물에 다른 관점을 동시에 적용하는 리뷰, 가벼운 탐색과 무거운 최종 판단을 나누는 흐름이다.
첫 실습 — 현재 저장소를 읽기만 해서 요약하기
가장 먼저 해볼 실습은 파일을 수정하지 않는 저장소 탐색이다. 아래 프롬프트는 현재 작업 폴더에서 구조, 테스트 위치, 패키지 관리 흔적만 읽고 짧게 요약하게 한다.
Use two parallel subagents for read-only exploration.
Do not edit files and do not run install commands.
Agent 1: inspect the top-level folders and summarize the project structure in 5 lines.
Agent 2: find test folders and package manager files, then summarize them in 5 lines.
Wait for both agents and return:
1. Project structure summary
2. Test/package summary
3. One next command I should run manually to verify the project
ex) 2개의 읽기 전용 서브에이전트를 띄워 일하는 모습
기대 결과
좋은 결과는 길지 않다. 예를 들어 "src는 앱 코드, tests는 회귀 테스트, package.json 기준 npm 프로젝트, 다음 확인 명령은 npm test"처럼 짧은 구조 요약과 수동 검증 명령 하나가 나오면 충분하다. 처음부터 파일 수정까지 맡기지 않는 이유는, 서브에이전트가 어떻게 결과를 합치는지 먼저 확인하기 위해서다.
예시 A — 낯선 저장소 첫 탐색: 구조·테스트·의존성 동시에
새 프로젝트에 처음 들어갔을 때 "디렉토리 구조가 어떻게 되지? 테스트는 어디까지 있지? 외부 의존성은 뭐가 있지?"를 순서대로 확인하면 시간이 꽤 걸린다. 세 에이전트가 동시에 읽어서 요약하면 전체 그림을 더 빨리 잡을 수 있다. 세 에이전트 모두 읽기만 하므로 충돌 가능성이 낮다.
Goal: 낯선 저장소의 전체 그림을 빠르게 파악한다.
Setup:
저장소: github.com/example/myproject (로컬 클론 완료)
브랜치: main
Subagents:
- structure-agent: src/ 하위 디렉토리 구조와 주요 파일 역할을
3~5줄 요약으로 돌려줘. 파일을 수정하면 안 된다.
- test-agent: tests/ 또는 __tests__/ 폴더를 훑어서 테스트가
어느 모듈까지 커버하는지 3줄로 요약해 줘. 파일을 수정하면 안 된다.
- deps-agent: package.json 또는 requirements.txt를 읽고
핵심 외부 의존성 5개와 용도를 정리해 줘. 파일을 수정하면 안 된다.
Constraints:
- 세 에이전트 모두 파일 수정, 실행, 설치 금지
- 요약은 각 에이전트 역할 범위 안에서만
Completion:
세 에이전트 요약을 모아 "저장소 첫인상 보고서"를 한 블록으로 출력한다.
프롬프트 줄별 해설
Subagents 에이전트별 이름: 이름이 없으면 /agent로 추적하기 어렵다. 어느 에이전트가 어떤 역할인지 Codex도, 사람도 헷갈린다.
각 에이전트 지시 안에 "파일을 수정하면 안 된다" 반복: Constraints 블록만으로는 부족하다. 에이전트별 지시 안에도 직접 적어야 더 잘 지킨다.
출력 형식을 줄 수로 제한: "3~5줄", "3줄"처럼 길이를 못 박으면 각 에이전트가 과도한 맥락을 쏟아내지 않는다. 통합 단계가 훨씬 깔끔해진다.
Completion에 통합 주체 명시: "세 에이전트 요약을 모아"처럼 누가 결과를 합치는지 적지 않으면 각자 결과만 출력하고 끝날 수 있다.
예시 A의 구조를 그림으로 보면 한눈에 들어온다. orchestrator가 작업을 fan-out으로 분배하고, 각 에이전트가 자기 범위만 읽은 뒤 결과를 fan-in으로 합치는 형태다.
┌─────────────────────────────────────────────────────┐
│ orchestrator │
│ (목표 설정 · 결과 검토 · 다음 지시) │
└──────────────┬───────────────────────────────────────┘
│ fan-out (작업 분배)
┌───────┼───────┐
▼ ▼ ▼
[탐색 agent] [테스트 agent] [리뷰 agent]
│ │ │
└───────┼───────┘
│ fan-in (결과 합산)
▼
최종 보고서
이 구조가 머릿속에 그려지면 다음 예시들도 같은 틀의 변주로 읽힌다. 예시 B는 같은 틀에 "관점별 모델 차등"을 더한 형태다.
예시 B — PR 셀프 리뷰: 보안·성능·가독성을 동시에
PR 리뷰를 혼자 할 때 보안, 성능, 가독성을 한 번에 보려면 시각이 섞인다. 관점별로 에이전트를 따로 두면 각자 다른 렌즈로 같은 코드를 본다. 리뷰 깊이가 다른 관점엔 모델 설정도 다르게 줄 수 있다.
Goal: feature/auth-refactor 브랜치 PR을 세 관점으로 동시 리뷰한다.
Setup:
대상: src/auth/ 변경분 (main 브랜치 대비)
범위: 신규 파일 + 수정 파일만
Subagents:
# 모델 ID 참고: https://platform.openai.com/docs/codex
- security-agent (model: o3, effort: high):
인증 우회, 세션 고정, 입력값 미검증 패턴만 찾아서
파일명:줄번호 형식으로 목록화해 줘.
- perf-agent (model: codex-mini-latest, effort: medium):
N+1 쿼리, 루프 안 DB 호출, 불필요한 await를 찾아서
파일명:줄번호 형식으로 목록화해 줘.
- readability-agent (model: codex-mini-latest, effort: low):
함수 길이 30줄 초과, 인자 5개 초과, 중복 로직을 찾아서
파일명:줄번호 형식으로 목록화해 줘.
Constraints:
- 파일 수정 금지. 리뷰 의견만 출력
- 관점 범위 밖 이슈는 언급하지 않는다
Completion:
세 에이전트 결과를 "보안 / 성능 / 가독성" 섹션으로 나눠서 출력한다.
프롬프트 줄별 해설
에이전트별 다른 model/effort: 보안처럼 놓치면 위험한 검토는 강한 모델과 높은 추론 설정으로 시작하고, 단순 스캔은 가벼운 모델로 시작할 수 있다. 이것은 공식 규칙이 아니라 비용과 위험을 함께 보는 실무 출발점이다.
"관점 범위 밖 이슈는 언급하지 않는다": 이 줄이 없으면 각 에이전트가 다른 관점의 이슈까지 포함해서 결과가 3배로 중복된다.
출력 형식을 "파일명:줄번호"로 통일: 자유 형식으로 두면 에이전트마다 양식이 달라져서 통합이 어렵다.
Completion의 섹션 구분: 사소해 보이지만, 통합 에이전트가 섹션 헤더를 인식하고 결과를 분류하는 데 도움이 된다.
A와 B는 모두 한 번에 fan-out하는 단순 구조였다. 예시 C는 한 단계 더 나아가, 직렬과 병렬을 섞은 다단계 흐름을 다룬다.
예시 C — 라이브러리 업그레이드 영향 분석: 직렬 → 병렬 → 통합
큰 의존성을 올릴 때 "어디가 깨지는지"를 보려면 먼저 전체 사용처를 파악해야 한다.
그 다음에 영역별로 나눠서 동시에 분석하고, 마지막에 합친다. A·B와 달리 에이전트 실행 순서가 있다.
Goal: lodash 4 -> 6 업그레이드 시 영향 범위를 분석한다.
Setup:
저장소: 현재 작업 디렉토리
대상 패키지: lodash (4.x -> 6.x)
Phase 1 (직렬):
- scan-agent: lodash를 import하는 파일 전체 목록을 출력하고
reports/lodash-usage.md 에 저장해 줘.
Phase 2 (병렬, Phase 1 완료 후 실행):
- api-agent: reports/lodash-usage.md를 읽고 lodash 6에서
제거되거나 시그니처가 바뀐 함수만 정리해 줘.
결과를 reports/api-changes.md 에 저장해 줘.
- test-agent: reports/lodash-usage.md를 읽고 lodash 관련
테스트 파일을 찾아서 커버리지 갭을 요약해 줘.
결과를 reports/test-gaps.md 에 저장해 줘.
- type-agent: reports/lodash-usage.md를 읽고 TypeScript 타입
불일치 가능성이 있는 파일을 목록화해 줘.
결과를 reports/type-risks.md 에 저장해 줘.
Phase 3 (직렬, Phase 2 완료 후 실행):
- merge-agent: reports/ 아래 세 파일을 읽어서 파일별 대응
우선순위를 "위험도: 높음/중간/낮음" 기준으로 정리해 줘.
Constraints:
- scan-agent, api-agent, test-agent, type-agent: 파일 수정 금지
- merge-agent: reports/ 파일만 읽고, 코드 파일 수정 금지
Completion:
merge-agent 결과가 콘솔에 출력되면 완료.
프롬프트 줄별 해설
Phase 1/2/3 명시적 분리: Codex가 순서를 추론하게 두면 Phase 1 완료 전에 Phase 2가 실행될 수 있다. "Phase 1 완료 후 실행"을 직접 적어야 한다.
시그니처: 함수의 이름, 매개변수(입력), 반환 타입을 합친 외형 정보다. "시그니처가 바뀐 함수"란 호출 방법이 달라진 함수를 뜻한다. 업그레이드 후 이전 코드가 그대로 동작하지 않는 원인이 된다.
커버리지 갭: 테스트가 실행하지 않는 코드 영역이다. "커버리지 갭을 요약해 줘"는 lodash를 쓰는 코드 중 테스트가 없는 부분을 찾아 달라는 뜻이다.
중간 산출을 파일로 남기기 (reports/*.md): Phase 2 에이전트가 Phase 1 결과를 메모리에서만 받는 방식은 불안정하다. 파일에 쓰고 읽게 하면 각 단계를 독립적으로 검증할 수 있다.
merge-agent 읽기 범위를 "reports/ 파일만"으로 제한: 범위를 적지 않으면 전체 저장소를 다시 읽는다. 통합 에이전트는 중간 산출물만 보면 충분하다.
Completion: 마지막 에이전트 기준으로 명시: "모든 에이전트 완료 후"처럼 모호하게 적으면 완료 판단이 흔들린다. 마지막 단계 에이전트를 명시해야 Codex가 종료 시점을 정확히 안다.
세 예시에서 반복된 패턴
에이전트마다 역할과 산출 형식을 따로 적었다 — "요약해 줘"보다 "3줄로 파일명:줄번호 형식으로"가 낫다
쓰기를 허용한 에이전트는 쓸 파일 경로를 명시했다 — 경로 없이 허용하면 어디에 저장할지 임의로 정한다
Constraints의 파일 수정 금지를 에이전트 지시 안에도 반복했다 — 블록 하나로는 부족하다
Completion에 통합 주체 또는 마지막 에이전트를 명시했다 — 이 줄이 없으면 언제 끝나는지 모호해진다
예시 D — Next.js 기능 추가 전 탐색: 컴포넌트·API·테스트 패턴 동시에
새 페이지나 기능을 붙이기 전에 기존 코드의 패턴을 먼저 파악하지 않으면, 팀 컨벤션과 어긋나는 코드를 짜게 된다. 특히 Next.js App Router 프로젝트는 Server Component 사용 방식, 데이터 패칭 방법, 테스트 도구가 프로젝트마다 다르다.
세 에이전트가 각자 한 영역만 읽고 요약을 돌려주면, 코드를 짜기 전에 "이 프로젝트에서 어떻게 해야 하나"를 빠르게 정리할 수 있다. A·B·C가 리뷰·분석 중심이었다면, 예시 D는 신규 기능을 구현하기 전 "탐색 단계"에 서브에이전트를 쓰는 패턴이다.
Goal: /dashboard 페이지 추가 전에 Next.js 프로젝트의 기존 패턴을 파악한다.
Setup:
저장소: 현재 작업 디렉토리 (Next.js App Router 기반)
목적: 신규 대시보드 페이지 구현 전 코드 컨벤션 파악
Subagents:
- component-agent: app/ 디렉토리의 기존 페이지 컴포넌트를 읽어라.
Server Component와 Client Component("use client") 구분 기준,
공통 레이아웃 파일(layout.tsx)이 어디 있는지 3~5줄로 요약해라.
파일 수정 금지.
- api-agent: app/api/ 또는 lib/ 아래 데이터 패칭 패턴을 찾아라.
fetch, axios, React Query 중 어떤 방식을 쓰는지,
인증 처리(middleware.ts 또는 세션 확인 로직)가 어디서 이루어지는지 3줄로 요약해라.
파일 수정 금지.
- test-agent: __tests__/ 또는 *.test.tsx, *.spec.tsx 파일을 찾아서
테스트 도구(jest, vitest, RTL 등)와 기존 테스트 파일 위치를 3줄로 요약해라.
파일 수정 금지.
Constraints:
- 세 에이전트 모두 파일 수정, 설치, 실행 금지
- 각 에이전트는 자기 담당 범위 안에서만 요약
Completion:
세 에이전트 결과를 모아 "대시보드 페이지 추가 시작점 보고서"를 한 블록으로 출력한다.
보고서 형식: 컴포넌트 패턴 / API 연동 / 테스트 위치 세 섹션.
프롬프트 줄별 해설
왜 코드 짜기 전에 탐색부터?: Next.js 프로젝트마다 "use client" 쓰는 위치, 데이터 패칭 방식, 테스트 도구가 다르다. 탐색 없이 바로 짜면 기존 패턴과 달라져 나중에 리팩토링 비용이 생긴다.
component-agent에 "Server vs Client 구분 기준" 명시: App Router에서 가장 자주 틀리는 지점이다. "use client"가 어느 깊이에서 선언되는지 파악해 두면 새 페이지를 짤 때 실수를 줄인다.
api-agent에 "인증 처리 위치" 추가: 대시보드는 보통 로그인이 필요하다. 기존 middleware.ts나 세션 확인 로직을 먼저 알아야 같은 패턴을 새 페이지에 적용할 수 있다.
Completion의 섹션 분리: "컴포넌트 / API / 테스트" 세 섹션으로 강제하면, 이후 실제 구현 프롬프트에서 섹션별로 참조하기 쉽다. 예시 A·B와 마찬가지로 통합 주체를 명시해야 각자 결과만 내고 끝나는 것을 막는다.
직접 해보자 — 바이브 코딩 버전
구조 몰라도 된다. 이 한 줄을 그대로 Codex에 붙여넣어 보자.
이 Next.js 프로젝트에 대시보드 페이지를 추가하려고 해. 코드 짜기 전에 서브에이전트 3개로 병렬 탐색해줘. 하나는 기존 컴포넌트 패턴, 하나는 API 연동 방식, 하나는 테스트 위치. 파일 수정 금지. 결과는 세 섹션으로 나눠서 요약해줘.
세 개의 에이전트가 뜨고, 결과가 "컴포넌트 패턴 / API 연동 / 테스트 위치" 세 섹션으로 나눠 오면 이 패턴을 이해한 것이다.
예시 D는 신규 기능 추가 전 "탐색 → 구현" 2단계 흐름의 첫 단계다. 탐색 결과 보고서가 나오면 그 내용을 컨텍스트로 붙여 구현 프롬프트로 넘어가면 된다. 익숙해지면 탐색·구현·테스트 생성을 직렬로 이어 붙이는 3단계 워크플로로 확장할 수 있다.
4. 병렬 실행 — 읽기와 쓰기를 구분하라
4.1 읽기 중심 작업에 먼저 적용한다
공식 서브에이전트 문서는 병렬 에이전트가 코드베이스 탐색이나 여러 단계가 있는 기능 계획처럼 나누기 쉬운 작업에 잘 맞는다고 설명한다. 초보자에게는 이 말을 "먼저 읽기 중심 작업부터 나눠 보라"는 운영 기준으로 받아들이는 편이 안전하다.
탐색(exploration, 파일과 구조를 살펴보는 일), 테스트 실행, 이슈 트리아지(문제의 원인과 우선순위를 가르는 일), 요약처럼 파일을 읽고 분석하는 작업은 병렬화에 적합하다. 서로 다른 에이전트가 같은 파일을 동시에 수정하지 않기 때문에 코드 충돌 가능성이 낮다.
테스트 실행은 완전한 읽기 작업이 아닐 수 있다
실제 테스트는 캐시 파일을 만들거나 스냅샷을 갱신하거나 데이터베이스를 건드릴 수 있다. 그래서 "테스트 실행 에이전트"를 둘 때는 프로덕션 DB, 실서비스 API 키, 외부 결제·메일 발송 같은 부작용이 없는지 먼저 확인해야 한다.
예를 들어 오래된 프로젝트에 처음 들어갔다고 해 보자. 디렉토리 구조를 보는 에이전트, 사용 중인 라이브러리를 정리하는 에이전트, 테스트가 어디까지 있는지 확인하는 에이전트를 동시에 실행할 수 있다. 세 작업 모두 읽기 전용이라 충돌이 거의 없다. 각 에이전트가 짧은 요약만 돌려주면, 메인 에이전트는 그 요약을 모아 전체 그림을 만든다. 직접 하나씩 읽는 것보다 대화창도 훨씬 깔끔하게 유지된다.
4.2 쓰기 작업은 충돌에 주의한다
병렬 쓰기는 다르다.
여러 에이전트가 동시에 코드를 고치면 충돌과 조율 비용이 커질 수 있다. 그래서 쓰기 병렬화는 처음부터 조심해야 한다.
여러 에이전트가 동시에 같은 파일을 고치면 충돌 가능성이 매우 높다. 나중에 어느 변경을 살릴지 다시 정리해야 하므로, 병렬화로 아낀 시간을 되돌려 쓰게 된다. 쓰기 작업은 파일 단위로 작업 영역을 나누거나, 아예 순서대로 처리하는 방식이 더 현실적이다.
읽기 vs 쓰기 판단 기준
각 서브에이전트가 "읽고 분석해서 요약을 돌려준다"면 병렬화하기 좋다. "특정 파일을 직접 수정한다"면 누가 어떤 파일을 고칠지 먼저 나눠야 한다.
4.3 작업 조율은 Codex가 도와준다
여러 서브에이전트가 실행되는 동안 생성, 작업 배정, 대기, 결과 취합 같은 조율은 Codex가 도와준다. 이런 조율을 오케스트레이션이라고 부르지만, 초보자는 "여러 작업자를 관리하는 일" 정도로 이해하면 충분하다. 다만 이것이 사용자의 검증 책임까지 대신한다는 뜻은 아니다. 파일 소유권, 완료 기준, 결과 형식은 사용자가 분명히 적어야 하고, 마지막 검증도 직접 해야 한다(서브에이전트 문서 참조).
5. 모델 배분 전략
서브에이전트마다 모델을 다르게 줄 수 있지만, 초보자가 처음부터 모델 카탈로그를 외울 필요는 없다.
기본값으로 시작하고, 느리거나 비싸거나 위험한 작업이 반복될 때만 역할별 조정을 한다.
모델 이름과 제공 범위는 계정과 시점에 따라 달라질 수 있으므로 실제 선택 전에는 Codex Models 문서와 CLI의 모델 선택기를 함께 확인한다.
( 하기 내용은 실제 codex 사용하시는 분들이 아닌 api 방식으로 사용하는 분들이, 비용 대비 성능 최적화를 하기 위해 사용하는 전략이니, 가볍게 보고 어렵다면 데충 넘어가는것을 추천한다. )
서브에이전트 모델 선택을 위한 실무 기준
상황
운영 기준
이유
처음 쓰는 작업
세션 기본 모델 사용
모델 선택보다 역할·범위·완료 기준이 더 중요하다
파일 목록 수집, 구조 요약
가벼운 모델과 낮은 reasoning effort(생각의 깊이 — 높을수록 느리고 비싸다)로 시작
깊은 추론보다 빠른 스캔과 짧은 요약이 중요하다
보안, 설계, 최종 통합 판단
가능한 강한 모델과 높은 effort로 시작
가정 검증과 엣지 케이스 탐색 실패 비용이 크다
비용이나 속도가 부담될 때
모델보다 에이전트 수를 먼저 줄인다
서브에이전트는 단일 실행보다 토큰 사용과 대기 시간이 늘 수 있다
실무 출발점
가벼운 읽기 전용 서브에이전트에는 codex-mini-latest 같은 효율 모델을, 복잡한 리뷰나 최종 판단에는 o3 같은 강한 모델을 배정하는 식으로 시작할 수 있다. 이것은 공식 규칙이 아니라 비용, 속도, 작업 위험을 함께 보는 운영 기준이다.
o3: 복잡한 추론이 필요한 작업에 쓴다. 보안 분석, 설계 결정, 최종 통합 판단처럼 한 번 틀리면 비용이 큰 단계에 배정한다. 느리지만 정확하다.
codex-mini-latest: 빠른 탐색·분류 작업에 쓴다. 파일 목록 수집, 디렉토리 구조 요약, 단순 패턴 스캔처럼 단순 작업에 최적이다. 빠르지만 깊은 추론에는 약하다.
CLI에서는 실행 중에 /model 명령으로 모델을 바꿀 수 있고, 새 CLI 세션이나 codex exec(프롬프트를 인수로 전달해 대화 없이 한 번만 실행하는 서브명령)에서는 -m 또는 --model 플래그를 쓴다. 반복해서 같은 모델을 쓰고 싶을 때만 config.toml 기본값을 조정한다.
요금과 플랜도 함께 봐야 한다. 여러 서브에이전트는 "한 명의 Codex가 더 빨리 생각한다"가 아니라 여러 모델 호출이 동시에 늘어나는 구조다. 공식 Pricing 문서를 확인하고, 현재 계정의 사용 가능 모델, 플랜 한도, API 키 사용 여부를 먼저 본다.
6. 워크플로 설계 원칙
처음엔 이 순서로 생각하면 편하다. 각 원칙을 하나씩 살펴보자.
왜 네 가지인가? 멀티 에이전트가 망가지는 지점은 대부분 같은 자리에서 반복된다. 분리되지 않은 일을 분리한 척 시키거나, 같은 파일을 동시에 고치게 두거나, 결과를 합치는 사람이 없거나, 중간 결과를 확인할 방법이 없거나.
그래서 이 네 자리에 각각 가드레일을 세운 것이 아래 4원칙이다. 세부 구현보다 이 네 가지가 실수를 막는다.
멀티 에이전트 협업 4원칙
분리 가능성을 먼저 검증한다 — 진짜 독립 작업인가, 아니면 숨은 순서가 있는가. 숨은 의존성을 무시하면 Phase 2가 Phase 1 결과를 받지 못한다.
읽기는 병렬, 쓰기는 직렬 — race condition은 여러 작업이 동시에 같은 대상을 건드릴 때 생기는 실행 순서 문제다. 같은 파일을 동시에 고치게 두면 충돌 가능성이 높다.
통합 책임을 명시한다 — 누가 결과를 모으고 최종 판단하는지 적지 않으면, 각 에이전트가 자기 결과만 출력하고 아무도 합치지 않는다.
검증 가능한 산출을 남긴다 — 파일, 요약, 테스트 결과처럼 명시적 artifact(산출물: 에이전트가 남긴 확인 가능한 결과)가 없으면 중간 단계를 나중에 확인할 방법이 없다.
원칙이 어떻게 실수를 막는지 두 가지로 비교해 봤다.
문제 있는 지시
"api-agent와 test-agent가 동시에 src/auth/session.ts를 수정해 줘."
이렇게 바꾸자
"api-agent는 탐색만, 수정은 merge-agent 단독으로 Phase 2에서 진행한다."
해설: 같은 파일을 동시에 수정하면 충돌 가능성이 높다. 탐색 단계를 분리하면 사고를 줄일 수 있다.
"Codex works best when you treat it like a teammate with explicit context and a clear definition of 'done.'"
(번역) "명확한 컨텍스트와 '완료' 기준이 함께 주어지면 Codex는 팀원처럼 가장 잘 작동한다."
팀원에게 일을 맡길 때처럼 배경과 완료 기준을 함께 적어야 한다. "이 PR을 리뷰해 줘"보다 "main 브랜치와 비교해서 보안 위험만 파일 경로와 함께 정리해 줘"가 훨씬 좋은 지시다. PR은 코드 변경 검토 요청이고, main 브랜치는 보통 기준이 되는 기본 브랜치다. 무엇을 봐야 하는지, 결과를 어떤 형태로 돌려줘야 하는지가 분명할수록 결과도 좋아진다.
Workflows를 적용하기 전에는 Prompting 문서의 기본 원칙도 같이 보는 게 낫다. 서브에이전트도 결국 프롬프트 품질에 좌우되기 때문이다. 어떤 파일을 봐야 하는지, 어떤 결과를 돌려줘야 하는지, 무엇을 하면 안 되는지를 적지 않으면 병렬로 빨라지는 대신 여러 방향으로 엇나갈 수 있다.
CLI에서는 파일 경로를 더 명확히 적어야 한다
공식 Workflows 문서에 따르면 IDE 확장은 열린 파일을 자동 컨텍스트로 포함하지만, CLI에서는 보통 파일 경로를 직접 언급하거나 /mention과 @ 경로 자동완성을 사용해야 한다. 초보자는 "이 프로젝트를 봐줘"보다 "src/auth/session.ts와 tests/auth를 기준으로 봐줘"처럼 적는 편이 안전하다.
6.2 오케스트레이터 패턴
복잡한 작업 흐름은 총괄 담당 1명과 역할별 작업자 여러 명으로 나누면 이해하기 쉽다.
메인 에이전트가 전체 목표와 완료 기준을 잡고, 서브에이전트가 각자 좁은 범위를 조사한 뒤 결과를 돌려주는 구조다.
"Review this branch against main. Have pr_explorer map the affected code paths, reviewer find real risks, and docs_researcher verify the framework APIs that the patch relies on."
(번역) "이 브랜치를 main과 비교해서 리뷰해라. pr_explorer가 영향받는 코드 경로를 파악하고, reviewer가 실제 위험을 찾고, docs_researcher가 패치가 의존하는 프레임워크 API를 공식 문서와 대조해서 확인한다."
pr_explorer는 바뀐 코드가 어디에 영향을 주는지 찾고, reviewer는 실제 위험을 찾고, docs_researcher는 사용한 API가 공식 문서와 맞는지 확인한다. API는 프로그램끼리 서로 기능을 호출하는 약속이라고 보면 된다. 역할이 분명하면 마지막에 결과를 합치기도 쉽다(서브에이전트 문서 참조).
실제 프로덕션 에이전트 해부: codex-rescue
오케스트레이터 패턴의 실제 구현체가 궁금하다면 superpowers 플러그인의 codex-rescue 에이전트가 좋은 참고 사례다. 이 에이전트는 세 가지 규칙만으로 설계되어 있다.
단일 책임: Codex CLI 호출 하나만 담당한다. 저장소를 직접 탐색하거나 파일을 분석하는 일은 하지 않는다. 터미널 출력(stdout)을 그대로 돌려주는 것이 전부다.
도구 제한: Bash 도구만 허용한다. 권한을 최소화하면 예상치 못한 부작용이 줄어든다. 에이전트가 할 수 있는 일을 적게 정의할수록 결과를 예측하기 쉽다.
모델 라우팅: 작업 복잡도에 따라 --model과 --effort를 조합한다. 무거운 모델을 모든 작업에 쓰지 않는다.
같은 원칙을 직접 만드는 에이전트 TOML에 적용하면 다음과 같다.
# 모델 ID 참고: https://platform.openai.com/docs/codex
name = "pr_reviewer"
description = "Security and test gap reviewer. Read-only."
model = "codex-mini-latest"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Review only. Do not edit files.
Report findings with file path and line number.
Return a summary under 200 words.
"""
superpowers 플러그인은 Claude Code 마켓플레이스에서 /install
superpowers로 설치하면 바로 확인할 수 있다. 이 단일 책임·도구 최소화·모델 라우팅 세 원칙은 오픈소스 에이전트 생태계에서 반복적으로 나타나는 패턴이다. Part 5 (MCP · Plugins · Skills)에서는 이 원칙을 직접 플러그인으로 만들어 배포하는 법을 다룬다.
6.3 커스텀 에이전트 파일 정의
처음부터 커스텀 에이전트를 만들 필요는 없다. 기본 에이전트로도 충분히 실습할 수 있다.
다만 같은 역할을 계속 반복한다면 TOML 파일로 에이전트를 정의해 재사용할 수 있다. TOML은 설정 파일 형식이고, 여기서는 "이 에이전트의 이름, 설명, 지시문을 파일로 저장해 둔다" 정도로 이해하면 된다.
커스텀 에이전트를 만들지 판단하는 기준
상황
판단
한 번 해보는 저장소 탐색
프롬프트에 직접 역할을 적는다
매 PR마다 같은 보안 리뷰를 반복
커스텀 에이전트 후보
팀 전체가 같은 역할을 재사용
.codex/agents/에 두고 버전 관리 검토
공식 문서 기준으로 커스텀 에이전트의 필수 필드는 name, description, developer_instructions다. 전역 에이전트는 ~/.codex/agents/, 프로젝트 에이전트는 .codex/agents/에 둔다.
아주 작은 예시는 다음과 같다. 다만 에이전트 파일의 sandbox_mode = "read-only"만으로 항상 읽기 전용 실행이 보장된다고 이해하면 안 된다. 서브에이전트는 현재 세션의 권한·승인 설정 영향을 받으므로, 처음에는 현재 CLI 권한을 확인하고 프롬프트에도 Do not edit files.를 함께 적는 편이 안전하다.
# 모델 ID 참고: https://platform.openai.com/docs/codex
name = "docs_researcher"
description = "Official documentation checker for API and framework behavior."
model = "codex-mini-latest"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
Use official documentation first.
Return concise findings with source links.
Do not edit files.
"""
에이전트 수 제한도 안전장치다
공식 Config Reference 기준으로 agents.max_threads의 기본값은 6, agents.max_depth의 기본값은 1이다. 동시에 너무 많은 스레드가 열리거나, 서브에이전트가 다시 하위 에이전트를 계속 만드는 일을 제한하기 위한 값이다. 초보자는 이 값을 올리기보다 작업을 더 작게 나누는 편이 안전하다.
6.4 결과 취합은 요약으로 돌려받는다
서브에이전트의 가공되지 않은 긴 로그나 추적 기록 전체를 메인 스레드로 가져오면 다시 대화창이 지저분해진다. 그래서 프롬프트에 "핵심만 요약해 줘", "중요한 결론만 돌려줘"라고 명시하는 것이 좋다. 영어 프롬프트를 쓴다면 "summarize the findings"나 "return distilled takeaways"처럼 적으면 된다.
6.5 결과를 믿기 전에 확인할 것
서브에이전트가 여러 개면 결과도 그럴듯해 보이기 쉽다. 하지만 요약이 깔끔하다고 해서 바로 맞는 것은 아니다. 최소한 아래 네 가지는 확인한다.
파일 경로와 줄 번호가 실제로 존재하는지 확인한다.
테스트를 실행했다면 어떤 명령을 실행했고, 성공/실패 결과가 무엇인지 확인한다.
API나 프레임워크 동작을 말한다면 공식 문서 링크가 붙어 있는지 확인한다.
서로 다른 서브에이전트의 결론이 충돌하면, 메인 스레드에서 다시 근거를 비교한 뒤 결정한다.
7. 정리 및 실전 적용 가이드
7.1 언제 서브에이전트를 쓸 것인가
마지막 사용 판단표
상황
권장 행동
이유
탐색·문제 분류·요약 작업
읽기 전용이면 권장
대부분 읽기 전용이라 충돌이 적다
PR(코드 변경 요청) 다각도 리뷰
관점별 역할이 분명할 때 권장
보안, 버그, 테스트를 따로 볼 수 있다
대용량 문서 분석
범위를 나눠 사용
큰 내용을 나눠 읽고 요약만 합칠 수 있다
동일 파일 동시 수정
초보자는 피함
같은 줄을 고치면 충돌 정리가 필요하다
단순 단일 파일 편집
메인 스레드에서 처리
나눠 맡기는 비용이 더 클 수 있다
한 줄로 정리하면 이렇다. 읽고 분석해 요약을 돌려주는 작업은 병렬 서브에이전트에 맡기고, 파일을 직접 고치는 단순 작업은 메인 스레드에서 처리하는 편이 안전하다.
7.2 다음 편 예고
Part 4: AGENTS.md · Rules
이번 편에서 서브에이전트에게 역할별 지시를 줬다면, 그 지시를 파일로 굳혀 팀 전체가 재사용하는 법이 Part 4의 주제다.
Constraints 블록을 AGENTS.md로 옮기면 매 프롬프트마다 반복하지 않아도 된다
전역 규칙 · 저장소 규칙 · 폴더별 규칙을 어떻게 나눌지
Karpathy 4원칙을 AGENTS.md 템플릿으로 만들어 바로 쓰는 방법
Part 5: MCP · Plugins · Skills
오늘 해부한 codex-rescue처럼 에이전트를 플러그인으로 만들어 배포하는 법을 다룬다. 오케스트레이터 패턴이 외부 서비스(Slack, GitHub, Jira)와 연결되면 사람 없이 돌아가는 워크플로가 된다.
