많은 초보자가 Codex의 skill을 먼저 보면서 “이게 그냥 프롬프트 저장이랑 뭐가 다르지?”에서 막히곤 합니다. 그런데 사실 그 전에 봐야 할 건, Codex가 일을 혼자 처리하는지, 아니면 멀티 에이전트처럼 역할을 나눠 처리하는지입니다.

현재 공식 문서 기준으로 Codex는 서브에이전트를 병렬로 띄워서 각각 탐색·분석·구현 같은 일을 나눠 맡길 수 있고, 그 결과를 다시 한 응답으로 합쳐 보여줄 수 있습니다. 또 이 흐름은 현재 기본 활성화되어 있으며, 서브에이전트 활동은 CLI와 Codex 앱에서 먼저 잘 드러나고, IDE 쪽 표시는 확장 중인 흐름으로 안내되고 있습니다.

쉽게 말하면 이런 느낌입니다. 한 명에게 “코드도 읽고, 버그도 찾고, 문서도 확인하고, 수정안도 내고, 테스트 포인트도 정리해줘”를 한 번에 던지는 대신, 메인 에이전트가 팀장처럼 움직이면서 일을 나눠 맡기는 방식입니다. 그래서 skill을 이해하기 전에 서브에이전트를 먼저 보면, 나중에 “누가 일하느냐”와 “어떻게 일하느냐”를 훨씬 쉽게 분리해서 이해할 수 있습니다.

이번 글에서 먼저 잡아둘 핵심
용어 초보자식 한 줄 설명 왜 중요한가
멀티 에이전트 일을 한 명이 다 하는 대신, 여러 에이전트가 나눠서 처리하는 방식 Codex를 “채팅창”이 아니라 “작업 팀”처럼 이해하게 해줍니다
서브에이전트 메인 에이전트가 하위 작업을 맡기기 위해 따로 띄운 보조 작업자 PR 리뷰, 버그 분석, 문서 확인처럼 역할 분리를 이해하는 출발점입니다
커스텀 에이전트 내가 직접 역할과 규칙을 정해 만든 전용 에이전트 “리뷰 담당”, “문서 확인 담당”처럼 일을 분업하기 쉬워집니다
skill 특정 작업을 잘 수행하게 해주는 전용 작업 매뉴얼 다음 글에서 다룰 내용이고, 서브에이전트와 역할이 다릅니다

이번 글의 핵심 한 줄
서브에이전트는 누가 일을 나눠서 하는가에 관한 개념이고, skill은 그 일을 어떤 방식으로 하게 만들 것인가에 더 가깝습니다.

왜 skill보다 먼저 서브에이전트를 이해하는 게 좋은가

skill부터 보면 자칫 이렇게 받아들이기 쉽습니다. “아, Codex에게 지시문을 더 잘 먹게 만드는 기능이구나.” 이 말이 완전히 틀린 건 아니지만, 조금 평면적입니다. 공식 문서 기준으로 skill은 instructions, resources, optional scripts를 묶어 특정 작업을 안정적으로 수행하게 만드는 구성이고, 반대로 서브에이전트는 역할이 다른 에이전트를 병렬로 돌려 일 자체를 분담하는 쪽에 가깝습니다. 즉, skill은 매뉴얼이고, 서브에이전트는 작업자 쪽에 더 가깝습니다.

이 차이를 먼저 잡아두면, 뒤에서 skill을 볼 때도 훨씬 덜 꼬입니다. 예를 들어 “리뷰 담당 서브에이전트”와 “리뷰 체크리스트 skill”은 이름이 비슷해 보여도 역할이 다릅니다. 전자는 누가 리뷰하느냐이고, 후자는 리뷰를 어떤 기준으로 하느냐에 가깝습니다.

입문자에게 이 구분이 중요한 이유는 간단합니다. 처음부터 모든 걸 한 덩어리로 이해하려 하면, Codex가 똑똑한 채팅창인지, 자동화 도구인지, 작은 팀인지 감이 흐려지기 쉽기 때문입니다. 서브에이전트를 먼저 이해하면 Codex를 “역할을 나눠 일하는 작업 환경”으로 보게 되고, 그다음 skill이 왜 필요한지도 자연스럽게 이어집니다.

Codex 멀티 에이전트는 정확히 무엇인가

공식 개념 문서 기준으로 Codex의 서브에이전트 워크플로는, 여러 특화 에이전트를 병렬로 띄워 탐색·분석·검증 같은 일을 동시에 진행한 뒤 메인 흐름으로 요약 결과를 되돌리는 방식입니다. 여기서 핵심은 “여러 명이 동시에 일한다”는 것보다, 메인 대화를 지저분하게 만들지 않는다는 데 있습니다. 공식 문서도 중간 탐색 로그, 테스트 로그, 스택 트레이스가 메인 대화에 계속 섞이면 컨텍스트 오염이나 컨텍스트 로트가 생길 수 있다고 설명합니다.

쉽게 비유하면, 책상 하나에 모든 서류를 다 펼쳐놓고 일하는 대신, 사람마다 맡은 자료만 들고 따로 검토한 뒤 핵심만 보고받는 구조에 가깝습니다. 그래서 멀티 에이전트의 장점은 단순히 “병렬이라 빠를 수 있다”에서 끝나지 않습니다. 중간 잡음을 메인 흐름 밖으로 빼는 것 자체가 꽤 큰 장점입니다.

공식 문서가 쓰는 핵심 용어를 초보자 말로 옮기면 이렇습니다. 서브에이전트 워크플로는 일을 나눠 돌리는 전체 구조이고, 서브에이전트는 그 안에서 실제 하위 작업을 맡는 개별 작업자입니다. 또 에이전트 스레드는 각 에이전트가 따로 움직이는 작업 줄기라고 이해하면 됩니다.

한 명에게 다 시키는 경우와 서브에이전트로 나누는 경우
방식 이럴 때 괜찮다 주의할 점
한 에이전트로 처리 작업 범위가 작고, 파일 몇 개 안에서 끝나는 수정 탐색·검증·수정이 한 대화에 몰리면 흐름이 탁해질 수 있습니다
서브에이전트로 분업 리뷰 포인트가 여러 개이거나, 코드·브라우저·문서를 같이 봐야 하는 작업 각 서브에이전트가 따로 모델·도구 작업을 하므로 토큰과 시간이 더 들 수 있습니다

특히 마지막 줄은 꼭 기억해둘 만합니다. 공식 문서도 서브에이전트 워크플로는 각 에이전트가 따로 모델과 도구 작업을 하기 때문에, 비슷한 단일 에이전트 실행보다 토큰을 더 쓸 수 있다고 분명히 적고 있습니다. 그러니 작은 작업까지 무조건 멀티 에이전트로 가는 게 정답은 아닙니다.

Codex 안에서 실제로는 어떻게 움직이나

초보자가 가장 오해하기 쉬운 지점이 여기입니다. “Codex가 알아서 똑똑하게 여러 에이전트를 띄워주겠지?”라고 생각하기 쉬운데, 공식 문서 기준으로 Codex는 서브에이전트를 자동으로 막 생성하지 않습니다. 사용자가 분명하게 요청했을 때만 새 에이전트를 띄우는 쪽입니다. 다시 말해, 그냥 “검토해줘”라고 쓰는 것보다 “보안, 버그, 테스트 관점으로 한 항목당 한 서브에이전트를 나눠 병렬 검토해줘”처럼 적는 편이 훨씬 명확합니다.

메인 에이전트는 이 과정에서 조율자처럼 움직입니다. 공식 문서 설명대로라면 새로운 서브에이전트를 띄우고, 추가 지시를 전달하고, 결과를 기다리고, 끝난 스레드를 닫는 일까지 메인 흐름이 관리합니다. 그리고 여러 결과가 다 모이면 마지막에 한 번에 정리된 응답으로 돌려줍니다.

CLI에서는 이 흐름을 보는 감이 비교적 직접적입니다. /agent 명령으로 활성화된 에이전트 스레드를 오가며 확인할 수 있고, 진행 중인 서브에이전트를 멈추거나 추가 지시를 주는 것도 가능합니다. 반면 Codex 앱은 여러 프로젝트와 작업 스레드를 병렬로 다루는 데 초점이 맞춰져 있어서, 여러 에이전트를 한꺼번에 감독하는 감이 더 잘 살아납니다.

또 하나 실전에서 중요한 점은 샌드박스와 승인 정책입니다. 공식 문서에 따르면 서브에이전트는 현재 세션의 샌드박스 정책을 상속하고, CLI에서 상호작용 중일 때는 메인 스레드를 보고 있어도 다른 서브에이전트에서 승인 요청이 올라올 수 있습니다. 처음 보면 “왜 갑자기 승인창이 뜨지?” 싶을 수 있는데, 꼭 현재 보고 있는 창에서만 나온 요청은 아닐 수 있다는 뜻입니다.

초보자 주의 포인트
서브에이전트는 “알아서 많이 띄우는 기능”이 아니라, 내가 분명하게 역할 분담을 요청했을 때 켜지는 기능에 가깝습니다.

입문자가 가장 쉽게 감을 잡을 수 있는 프롬프트는 이런 식입니다.

현재 브랜치를 main과 비교해서 검토해줘. 
보안, 버그, 테스트 취약성, 유지보수성 항목마다 서브에이전트 1개씩 나눠 병렬로 확인하고,
모든 결과가 모이면 항목별 핵심만 요약해줘.

이 프롬프트가 좋은 이유는 두 가지입니다. 하나는 “나눠라”가 명확하고, 다른 하나는 “마지막엔 요약만 달라”가 분명하다는 점입니다. 공식 예시도 비슷하게 항목별 검토를 각각의 에이전트로 분리해서 다시 합치는 방식을 보여줍니다. 

초보자가 먼저 써보기 좋은 서브에이전트 패턴

서브에이전트는 멋져 보여서 쓰는 기능이 아니라, 일이 나뉘는 모양이 분명할 때 쓰는 기능입니다. 공식 문서의 예시도 이 점이 아주 분명합니다. 특히 아래 세 가지는 초보자도 비교적 감을 잡기 쉽습니다.

  • 하나의 PR을 여러 관점으로 동시에 리뷰할 때
  • 브라우저 재현, 코드 경로 추적, 실제 수정 작업을 나눠서 처리할 때
  • 문서 확인과 코드 검토를 분리해서 보고 싶을 때

예를 들어 PR 리뷰는 서브에이전트와 꽤 잘 맞습니다. 보안, 코드 품질, 버그 가능성, 테스트 누락처럼 서로 다른 관점은 동시에 볼 수 있기 때문입니다. 공식 문서도 코드 경로를 먼저 훑는 역할, 실제 위험을 찾는 역할, 외부 문서를 확인하는 역할을 분리한 예시를 제공합니다.

또 UI 버그도 잘 맞습니다. 브라우저에서 실제로 재현하는 사람, 코드 경로를 좁히는 사람, 최소 수정으로 고치는 사람을 나눠 생각해보면 왜 그런지 바로 보입니다. 공식 예시에서도 코드 매핑, 브라우저 재현, 수정 담당을 분리하는 흐름을 보여줍니다. 

설정 모달이 저장되지 않는 이유를 찾아줘. 
1) 한 서브에이전트는 브라우저에서 실제 재현 
2) 한 서브에이전트는 관련 코드 경로 추적 
3) 마지막 서브에이전트는 원인이 확인된 뒤 최소 수정안 제안 이 순서로 진행하고, 최종 답변에는 원인과 수정 후보만 깔끔하게 정리해줘.

반대로, 파일 한두 개만 보면 되는 작은 수정은 굳이 서브에이전트까지 갈 필요가 없는 경우가 많습니다. 그냥 메인 에이전트 하나로 빠르게 처리하는 편이 단순하고, 토큰도 덜 쓰고, 추적도 쉽습니다. 멀티 에이전트는 “항상 더 좋은 상위 기능”이 아니라, 일이 분리될 때 좋은 기능이라고 보는 편이 현실적입니다.

원하면 직접 역할을 나눈 커스텀 에이전트도 만들 수 있다

조금 익숙해지면 여기서 한 단계 더 갈 수 있습니다. 공식 문서 기준으로 Codex에는 기본 제공 에이전트가 있고, 여기에 내가 직접 만든 커스텀 에이전트를 추가할 수도 있습니다. 기본 제공 에이전트는 일반용 default, 구현·수정 중심의 worker, 탐색 중심의 explorer가 안내되어 있습니다.

커스텀 에이전트 파일은 개인용이면 ~/.codex/agents/, 프로젝트 전용이면 .codex/agents/ 아래에 두는 방식입니다. 그리고 각 파일에는 최소한 name, description, developer_instructions가 들어가야 합니다. 나머지 모델, 샌드박스, MCP, skills 설정 등은 필요할 때만 얹는 식입니다.

입문자라면 처음부터 거창하게 만들 필요는 없습니다. 아래 정도만 있어도 “리뷰만 하는 전용 작업자”라는 감은 충분히 잡힙니다.

< config.toml >

# .codex/config.toml 
[agents]
max_threads = 4 
max_depth = 1

# .codex/agents/reviewer.toml name = "reviewer" 
description = "현재 브랜치의 실제 위험을 찾는 리뷰 전용 에이전트"
developer_instructions ="스타일 취향보다 버그, 보안, 테스트 누락을 먼저 본다. 가능하면 근거가 되는 파일과 재현 힌트를 함께 적는다."
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "read-only"

여기서 max_depth = 1은 특히 초보자에게 중요합니다. 공식 문서도 기본값이 1이고, 이 값은 직계 하위 에이전트까지만 허용합니다. 괜히 이 숫자를 올리면 에이전트가 또 다른 에이전트를 낳는 식으로 fan-out이 커질 수 있고, 그만큼 토큰 사용량, 지연 시간, 로컬 자원 소비도 커질 수 있다고 안내합니다. 처음에는 기본값을 그대로 두는 편이 좋습니다.

아주 사소하지만 재밌는 팁도 하나 있습니다. 공식 문서에는 nickname_candidates를 넣어 같은 종류의 에이전트가 많이 뜰 때 더 읽기 쉬운 표시 이름을 줄 수 있다고 나옵니다. 꼭 필요한 기능은 아니지만, 여러 리뷰 에이전트를 돌릴 때 화면이 덜 복잡하게 느껴질 수 있습니다.

입문자 추천선
처음에는 역할 하나, 에이전트 하나만 만드세요. “리뷰용”, “문서 확인용” 정도면 충분합니다. 한 파일에 욕심을 많이 넣기 시작하면 오히려 왜 그 에이전트를 만든 건지 흐려집니다.

서브에이전트와 skill은 어떻게 다른가

이제 다음 글과 연결되는 핵심입니다. 공식 문서 기준으로 skill은 특정 작업을 안정적으로 수행하게 해주는 구성 묶음이고, SKILL.md를 중심으로 instructions와 자료, 선택적인 스크립트를 담습니다. Codex는 skill의 이름과 설명 같은 메타데이터를 먼저 보고, 필요할 때만 본문을 읽는 방식으로 동작합니다. 반면 서브에이전트는 “어떤 역할의 작업자를 몇 명 둘 것인가”에 더 가깝습니다.

헷갈리기 쉬운 개념 정리
구성 요소 무엇을 정하나 쉬운 비유
서브에이전트 누가 어떤 역할로 일할지 리뷰 담당, 탐색 담당, 수정 담당
skill 그 역할이 어떤 절차로 일할지 체크리스트, 작업 매뉴얼, 전용 레시피
MCP 외부 도구를 무엇에 연결할지 브라우저, 문서 서버, 로그 도구 연결

이렇게 보면 skill을 먼저 안 다뤄도 되는 이유가 보입니다. 서브에이전트를 먼저 이해하면, skill은 그 위에 얹는 행동 방식으로 훨씬 자연스럽게 들어옵니다. 다음 글에서 skill을 설명할 때도 “스킬이 에이전트를 대체한다”가 아니라 “에이전트가 더 일관되게 움직이게 만든다”는 식으로 이해하면 덜 헷갈립니다.

짤막한 팁과 자주 하는 실수

  • 처음에는 두세 개 정도로만 나눠보는 편이 좋습니다. 서브에이전트가 늘수록 정리해야 할 결과도 늘고, 토큰 비용과 지연도 같이 커집니다.
  • 탐색이나 리뷰 역할은 먼저 read-only에 가깝게 두는 편이 안전합니다. 공식 예시도 탐색용·리뷰용 에이전트를 읽기 중심으로 두는 흐름이 많습니다. 
  • “병렬로 봐줘”만 쓰지 말고, 각 에이전트가 맡을 관점을 적어주는 편이 훨씬 낫습니다. 보안, 버그, 테스트, 문서 확인처럼 역할을 또렷하게 나눌수록 결과가 읽기 쉬워집니다. 
  • 가벼운 서브에이전트에는 더 빠른 모델을 붙이는 선택지도 있습니다. 공식 모델 문서는 gpt-5.4-mini를 반응성이 중요한 코딩 작업과 서브에이전트에 잘 맞는 빠른 모델로 소개합니다.
  • CLI에서 승인 요청이 갑자기 뜨면, 지금 보고 있는 메인 스레드 말고 다른 서브에이전트 쪽 요청일 수도 있습니다. 당황하지 말고 어느 스레드에서 올라왔는지 먼저 확인하는 습관이 좋습니다.
  • 깊이부터 키우지 마세요. max_depth를 높이면 “에이전트가 에이전트를 또 낳는” 구조가 생길 수 있고, 초보자에겐 추적이 금방 어려워집니다. 공식 문서도 기본값 유지 쪽을 권하는 흐름입니다.

실전 팁 하나
처음에는 “보안 1명, 버그 1명”처럼 사람 나누듯 프롬프트를 써보세요. 멀티 에이전트는 개념을 추상적으로 이해하는 것보다, 역할을 말로 분리해보는 순간 훨씬 빨리 체감됩니다.

마무리

Codex의 서브에이전트를 이해한다는 건, 결국 Codex를 “대답 잘하는 한 명”으로 보는 시선에서 “역할을 나눠 일할 수 있는 작업 팀”으로 보는 시선으로 옮겨가는 일에 가깝습니다. 그래서 이 개념을 먼저 잡아두면, 뒤에서 skill을 볼 때도 훨씬 편해집니다.

정리하면 이렇습니다. 서브에이전트는 역할 분담이고, skill은 작업 방식입니다. 이 순서만 머리에 들어오면, Codex가 왜 점점 “프롬프트 도구”보다 “작업 환경”에 가까워지는지 감이 잡히기 시작합니다.

다음 글에서는 바로 그 다음 단계인 skill로 넘어가 보겠습니다. 이번 글에서 “누가 일하느냐”를 정리했다면, 다음에는 “그 일을 어떤 순서와 기준으로 하게 만들 것인가”를 보게 될 겁니다.

'AI에이전트 > Chatgpt' 카테고리의 다른 글

[ChatGPT] Codex skill과 서브에이전트, 헷갈리는 지점만 다시 정리  (0) 2026.03.26
[ChatGPT] Codex 스킬이 뭐길래? CLI·IDE·윈도우 앱 입문 가이드  (0) 2026.03.25