Codex Subagents 사용법: 실행 방법·장단점·AGENTS.md 설정 가이드


메인 에이전트가 코드 탐색, 구현, 독립 리뷰 서브에이전트에 화살표로 작업을 위임하는 구조


Codex Subagents는 하나의 개발 작업을 여러 AI 에이전트에 나누어 맡기고, 메인 에이전트가 결과를 모아 판단하는 기능입니다.
코드 탐색과 리뷰처럼 서로 독립적인 작업에는 유용하지만, 작은 수정까지 무조건 병렬로 처리하면 토큰 사용량과 조정 비용이 늘어날 수 있습니다.

먼저 읽는 핵심 요약

  • 실행: 최신 Codex에서는 Subagents가 기본 활성화되어 있습니다. 채팅에서 역할·작업 범위·결과 형식을 정해 명시적으로 위임하면 됩니다.
  • 장점: 독립적인 작업의 병렬 처리, 메인 대화의 컨텍스트 부담 감소, 별도 관점의 코드 리뷰가 가능합니다.
  • 단점: 전체 토큰 소비 증가, 중복 조사, 파일 충돌, 결과 통합 비용이 생길 수 있습니다.
  • AGENTS.md: “언제 위임할지”와 “어떻게 결과를 검증할지”를 적는 지침 파일입니다. 기능 스위치나 모델 설정 파일은 아닙니다.
  • config.toml: 활성화 여부와 동시 실행 상한 등을 설정합니다. 역할별 동작과 읽기 전용 권한은 사용자 지정 에이전트 TOML에 정의할 수 있습니다.
  • 추천 시작점: 메인 에이전트로 작업하고, 필요할 때만 2~3개 이내의 탐색·리뷰 에이전트를 사용하세요. 이는 운영 권장안이지 제품의 고정 제한은 아닙니다.

이 글은 Codex 서브에이전트 활용에 관한 대화에서 출발해 OpenAI 공식 자료를 대조한 실전 가이드입니다. 단순히 “여러 에이전트를 쓰면 빠르다”는 설명 대신, 실행 방법부터 지침과 설정의 차이, 토큰을 아끼는 분담 기준, 잘못 동작할 때의 점검 순서까지 정리합니다.

목차

  1. Codex Subagents란 무엇인가?
  2. 채팅에서 실행하는 방법
  3. 장점과 단점, 사용 판단 기준
  4. AGENTS.md 설정과 적용 범위
  5. config.toml과 사용자 지정 에이전트
  6. Django 프로젝트 작업 분담 예시
  7. 실행 확인과 문제 해결
  8. 자주 묻는 질문

1. Codex Subagents란 무엇인가?

Subagent(서브에이전트)는 메인 에이전트가 특정 작업을 맡기기 위해 생성하는 별도 에이전트입니다. 메인은 요구사항과 우선순위를 관리하고, 서브에이전트는 정해진 범위의 조사나 구현을 수행한 뒤 결과를 반환합니다. Codex가 생성, 후속 지시, 대기, 스레드 정리 같은 조정 작업을 처리합니다.

예를 들어 프로젝트를 검토할 때 하나는 코드 구조를 조사하고, 다른 하나는 보안 문제를 확인하며, 또 다른 하나는 테스트 누락을 찾게 할 수 있습니다. 메인은 각 결과를 받아 중복을 제거하고 실제 수정 순서를 정합니다.

별도 스레드가 있다는 것과 별도 작업 디렉터리가 있다는 것은 다릅니다. 컨텍스트를 나누었다고 해서 파일 변경까지 자동으로 격리된다고 가정하면 안 됩니다. 여러 에이전트가 같은 파일을 편집하는 상황은 명시적으로 피하거나 별도 작업 공간과 통합 절차를 준비해야 합니다.

내장 에이전트와 사용자 지정 역할 구분하기

  • default: 일반적인 작업을 위한 기본 에이전트입니다.
  • worker: 구현과 수정 같은 실행 중심 작업에 사용합니다.
  • explorer: 코드 탐색 등 읽기 중심 작업에 사용합니다.

reviewer나 tester라는 이름은 이 글에서 설명하는 내장 목록에 포함되지 않습니다. 프롬프트로 리뷰 역할을 요청하거나 사용자 지정 에이전트로 정의해 사용할 수 있습니다. 또한 읽기 중심 역할이라는 설명만으로 강제 읽기 전용 권한이 생기는 것은 아닙니다. 파일 쓰기를 막으려면 샌드박스 설정을 확인해야 합니다.

2. Codex에서 Subagents를 실행하는 방법

가장 쉬운 방법은 채팅에서 “독립적인 작업을 서브에이전트에 나눠 맡겨 달라”고 직접 요청하는 것입니다. 최신 공식 문서는 기본 활성화를 안내하고 있으므로, 처음부터 별도 플러그인이나 Skill을 설치할 필요는 없습니다.

처음에는 코드 수정 없이 읽기 중심의 분석부터 시도하는 편이 좋습니다. 다음처럼 역할, 금지 사항, 대기 조건, 보고 형식을 함께 적어 보세요.

현재 Django 프로젝트를 3개의 서브에이전트로 병렬 분석해줘.

1. 코드 구조 담당: 요청이 URL → View → Service로 흐르는 경로를 조사해줘.
2. 성능 담당: ORM 조회에서 N+1 가능성과 불필요한 반복 조회를 조사해줘.
3. 보안 담당: 인증·권한 검사 누락과 입력 검증 위험을 조사해줘.

모든 에이전트는 코드와 설정을 수정하지 마.
각 결과에는 파일 경로, 관련 함수, 근거, 영향, 미확인 사항을 포함해줘.
추정과 확인된 사실을 구분해줘.
모두 완료되면 메인 에이전트가 중복을 제거하고 우선순위별로 보고해줘.

“알아서 여러 명을 써줘”보다 이 요청이 나은 이유는 결과를 평가할 기준이 분명하기 때문입니다. 파일과 함수 근거가 없으면 메인이 주장을 다시 확인하기 어렵고, 분석과 수정을 함께 허용하면 조사 도중 코드 상태가 바뀔 수 있습니다.

진행 상황도 확인해야 한다

지원되는 클라이언트에서는 메인 대화에 표시되는 서브에이전트 활동에서 각 스레드를 열어 진행 상황과 결과를 볼 수 있습니다. 필요하면 Codex에 해당 에이전트의 작업을 좁히거나 중단하도록 요청할 수 있습니다. UI 표시 방식은 클라이언트와 버전에 따라 다를 수 있으니, 실제 생성된 스레드를 확인하세요.

“병렬로 검토했다”는 최종 문장만 보고 실행을 단정하지 말고, 에이전트 활동과 개별 결과가 있는지도 확인하는 것이 좋습니다.

3. Codex Subagents의 장점과 단점

장점 1: 독립적인 작업을 동시에 진행할 수 있다

보안 리뷰와 문서 확인처럼 서로의 결과가 없어도 시작할 수 있는 작업은 병렬로 진행하기 좋습니다. 다만 코드 구조를 알아야 수정할 수 있고, 수정이 끝나야 회귀 테스트가 가능한 흐름은 단계가 이어져 있습니다. 에이전트 수를 늘려도 이런 의존 관계 자체가 사라지지는 않습니다.

장점 2: 메인 대화의 컨텍스트를 덜 어지럽힌다

긴 탐색 로그, 테스트 출력, 스택 트레이스를 모두 메인 대화에 쌓으면 요구사항과 핵심 결정을 찾기 어려워질 수 있습니다. 서브에이전트가 조사하고 요약만 반환하면 메인은 의사결정에 집중할 수 있습니다. OpenAI는 이를 컨텍스트 오염(context pollution)과 컨텍스트 품질 저하(context rot)를 줄이는 방식으로 설명합니다.

다만 컨텍스트 분리는 정보 전달 비용이 없어지는 것이 아닙니다. 위임할 때 필요한 요구사항을 빠뜨리거나 요약에서 중요한 조건이 누락되면 오히려 재조사가 필요합니다.

장점 3: 구현과 검토를 다른 관점으로 나눌 수 있다

메인이 API를 구현하고 별도 리뷰 에이전트가 권한 검사나 예외 처리를 확인하도록 할 수 있습니다. 이는 구현 과정의 가정에 덜 얽힌 검토를 시도하는 방법입니다. 그러나 같은 유형의 모델이 비슷한 오류를 반복할 수 있으므로, 여러 에이전트의 의견이 일치한다고 정확성이 보장되지는 않습니다.

장점 4: 역할에 맞는 모델과 추론 수준을 선택할 수 있다

단순 경로 탐색에는 빠른 모델을, 복잡한 보안 검토에는 더 강한 추론 설정을 선택하는 전략을 사용할 수 있습니다. 사용 가능한 모델과 추론 수준은 계정과 클라이언트에서 확인해야 하며, 낮은 추론 수준이 언제나 더 나은 비용 대비 결과를 내는 것은 아닙니다.

단점: 토큰, 충돌, 통합 비용을 함께 계산해야 한다

  • 토큰 증가: 각 에이전트가 별도의 모델·도구 작업을 하므로, 비슷한 단일 에이전트 작업보다 전체 토큰 소비가 늘어날 수 있습니다. 공식 문서도 이 점을 명시합니다.
  • 중복 조사: 분담 범위가 겹치면 같은 파일을 여러 번 읽고 비슷한 보고서를 만들 수 있습니다.
  • 파일 충돌: 같은 파일을 동시에 수정하면 변경을 잃거나 불일치가 생길 수 있습니다.
  • 통합 부담: 서로 다른 전제를 사용한 결과를 메인이 조정해야 합니다.
  • 검증 누락: 개별 작업이 끝나도 전체 프로그램이 정상 동작한다는 뜻은 아닙니다.

시간 단축과 토큰 절약은 같은 목표가 아닙니다. 병렬로 끝나는 시간이 줄어도 총 작업량은 늘 수 있습니다. 실제 이득은 자신의 프로젝트에서 결과 품질, 완료 시간, 사용량을 함께 비교해야 알 수 있습니다. 특정 배수의 속도 향상이나 절약률을 일반화하기는 어렵습니다.

어떤 작업에서 Subagent가 효과적일까?

작업이 크다는 이유만으로 서브에이전트가 필요한 것은 아닙니다. 서로의 결과를 기다리지 않고 조사할 수 있는 일이 있는지가 더 중요합니다. OpenAI는 코드 탐색·테스트·문제 분류·요약 같은 읽기 중심 작업부터 병렬화하고, 여러 에이전트가 코드를 동시에 수정하는 흐름은 충돌과 조정 비용에 주의하라고 안내합니다. OpenAI 공식 Subagents 문서

이 기준을 실제 개발 작업에 적용하면 다음처럼 구분할 수 있습니다. 아래 사례는 공식 원칙을 풀어 쓴 운영 예시이며, 특정 속도 향상을 측정한 결과는 아닙니다.

서브에이전트 활용을 고려할 만한 경우

  • 넓은 코드베이스의 실행 경로를 조사할 때: 화면의 진입점, 서버의 처리 흐름, 데이터 접근 경로를 나누어 추적하고 메인이 하나의 호출 흐름으로 합칠 수 있습니다. 각 담당자가 어디까지 조사할지 정하면 중복 탐색을 줄이기 쉽습니다.
  • 변경사항을 여러 기준으로 검토할 때: 한 에이전트는 인증·권한과 입력 검증, 다른 에이전트는 성능 위험, 또 다른 에이전트는 테스트 누락을 확인하게 할 수 있습니다. 코드 수정 없이 근거를 모으는 리뷰는 파일 충돌 위험도 낮습니다. 성능 문제는 추정과 실제 측정 결과를 구분해야 합니다.
  • 오류 원인이 여러 계층에 걸쳐 있을 때: 화면 재현, 서버 로그, 외부 API 문서 확인을 독립적으로 진행한 뒤 결과를 대조할 수 있습니다. 다만 모두 같은 전제를 반복하면 도움이 적으므로, 담당 범위나 검증할 가설을 구체적으로 나누는 편이 좋습니다.
  • 큰 변경을 시작하기 전에 영향을 파악할 때: API 계약, 데이터 구조, 호출하는 모듈, 관련 테스트를 각각 조사해 빠뜨리기 쉬운 의존성을 모을 수 있습니다. 조사 결과를 합친 뒤 수정 순서를 결정하는 방식이지, 처음부터 모든 모듈을 동시에 고치는 방식은 아닙니다.

메인 에이전트 하나로 시작하는 편이 나은 경우

  • 수정 위치와 원인이 이미 좁혀진 작은 변경: 한 함수의 조건식 수정, 문구 변경, 제한된 필드 추가처럼 조사 범위가 작다면 작업 설명·위임·결과 통합에 드는 비용이 실제 수정 비용보다 커질 수 있습니다.
  • 앞 단계의 결정이 다음 작업을 좌우하는 흐름: 요구사항을 확정해야 API를 설계하고, API가 확정되어야 화면을 구현할 수 있다면 병렬화할 여지가 작습니다. 먼저 순차적으로 결정하고, 독립적인 검토만 분리하는 편이 자연스럽습니다.
  • 같은 파일이나 공통 설정을 반복해서 고치는 작업: 여러 에이전트가 하나의 서비스 파일, 의존성 파일, 공통 타입을 함께 수정하면 변경이 겹치거나 서로 다른 전제를 반영할 수 있습니다. 한 담당자가 수정하고 다른 에이전트는 읽기 전용으로 검토하도록 나누는 편이 안전합니다.
  • 위임할 경계와 완료 기준이 불명확한 작업: 모두에게 “전체를 개선해 달라”고 요청하면 비슷한 탐색을 반복하고 상충하는 수정안을 만들기 쉽습니다. 메인이 먼저 범위를 좁힌 뒤, 분리 가능한 부분만 위임하세요.

간단한 API 추가나 필드 변경도 예외는 있습니다. 권한·호환성·데이터 이전에 영향을 주는 변경이라면 구현은 메인이 맡되, 위험 검토만 별도 에이전트에 맡길 수 있습니다. 작업 이름보다 영향 범위와 독립적인 검증의 필요성을 기준으로 판단하세요.

여러 에이전트가 동일 파일을 수정하면 충돌을 풀고 변경을 대조하는 데 시간이 들어 병렬 처리의 이점이 사라질 수 있습니다. 별도 worktree나 브랜치는 작업 디렉터리를 격리하는 데 도움이 되지만, 나중의 병합 충돌이나 설계 불일치까지 없애지는 않습니다. 동시 구현이 꼭 필요하다면 파일 소유권을 나누고, 메인이 최종 Diff와 통합 테스트를 확인해야 합니다.

실전 기본값은 ‘조사는 병렬, 수정은 담당자 중심, 검증은 통합’입니다. 읽기 중심 조사부터 활용하고, 실제 이점이 확인된 작업만 병렬 구현으로 넓히는 편이 합리적입니다.

사용 여부를 결정하는 세 가지 질문

  1. 독립적인 하위 작업이 둘 이상 있는가? 앞 단계가 끝나야 다음을 시작할 수 있다면 순차 처리가 더 자연스럽습니다.
  2. 범위와 결과물을 명확하게 지정할 수 있는가? 파일 경로, 함수, 재현 조건처럼 확인 가능한 결과를 요구할 수 있어야 합니다.
  3. 위임과 통합 비용보다 얻는 이점이 큰가? 한 함수 수정, 오타 교정, 단순 API 변경은 메인 하나로 시작하세요.

세 질문에 모두 “예”라면 서브에이전트 활용을 검토할 만합니다. 애매하다면 메인이 먼저 작은 범위를 탐색한 뒤, 실제로 독립적인 조사가 필요한 부분만 나누는 방식이 안전합니다.

4. AGENTS.md에 Subagents 활용 규칙 설정하기

AGENTS.md는 Codex에게 작업 원칙과 프로젝트 맥락을 전달하는 파일입니다. 서브에이전트를 항상 켜는 실행 파일이 아니라, 어떤 상황에서 위임할지 판단하도록 돕는 지침입니다. 최신 공식 문서는 직접 요청뿐 아니라 적용되는 AGENTS.md 또는 Skill 지침에 따른 위임도 안내합니다.

어디에 작성해야 할까?

  • 전역 지침: ~/.codex/AGENTS.md에 여러 프로젝트에서 공통으로 사용할 원칙을 작성합니다. CODEX_HOME을 지정했다면 실제 Codex 홈 위치가 달라집니다.
  • 프로젝트 지침: 저장소 루트의 AGENTS.md에 해당 프로젝트의 규칙을 작성합니다.
  • 하위 경로 지침: 특정 서비스나 폴더에는 별도 지침을 둘 수 있습니다. 현재 작업 디렉터리를 기준으로 어떤 파일이 로드되는지 확인해야 합니다.

공식 문서에 따르면 Codex는 전역 지침을 확인한 뒤 프로젝트 루트에서 현재 작업 디렉터리까지 내려가며 지침을 합칩니다. 같은 디렉터리에서는 AGENTS.override.md, AGENTS.md, 설정된 대체 파일 이름 순서로 확인하고, 디렉터리마다 최대 한 파일을 포함합니다. 더 가까운 디렉터리의 지침은 앞선 지침보다 우선할 수 있습니다.

전역 지침에 서브에이전트 사용 규칙을 적어도 프로젝트에서 이를 제한한다면 예상과 다르게 동작할 수 있습니다. 모든 하위 폴더의 파일이 무조건 한꺼번에 로드된다고 가정하지 마세요.

복사해서 조정할 수 있는 토큰 효율 중심 지침

다음은 공유 대화의 원칙을 바탕으로, 결과 검증과 파일 충돌 방지를 보강한 예시입니다. 기존 AGENTS.md를 통째로 덮어쓰지 말고 필요한 섹션을 추가하세요.

## Subagent 사용 원칙

- 기본적으로 메인 에이전트가 작업한다.
- 단순한 버그 수정, 작은 리팩터링, 단일 파일 편집,
  순차 의존성이 큰 작업에는 서브에이전트를 생성하지 않는다.
- 독립적인 병렬 조사가 속도, 품질 또는 컨텍스트 관리에
  실질적인 도움이 될 때만 서브에이전트를 사용한다.
- 좋은 사용 사례는 큰 코드베이스 탐색, 원인별 오류 조사,
  여러 모듈의 보안·성능 리뷰, 독립적인 테스트 누락 검토다.
- 처음에는 동시에 2~3개 이내로 제한하고 불필요하게 늘리지 않는다.
- 각 작업의 목표, 읽기/쓰기 범위, 완료 기준을 명확히 전달한다.
- 여러 에이전트가 같은 파일을 동시에 수정하지 않게 한다.
- 탐색과 리뷰는 코드 수정 없이 수행하도록 요청한다.
- 결과는 확인된 사실, 파일/함수 근거, 미확인 사항을 구분해 반환한다.
- 지원되는 경우 단순 작업에는 가벼운 모델을 사용하되,
  복잡한 설계·보안 검토에는 충분한 추론 수준을 사용한다.
- 런타임에서 확인되지 않은 모델 변경을 수행했다고 주장하지 않는다.
- 메인 에이전트는 결과를 통합하고 실제 변경사항과 테스트를 최종 검증한다.

“복잡하면 알아서 사용”이라는 한 줄보다 위 지침이 유용한 이유는 사용하지 않을 조건까지 함께 정하기 때문입니다. 다만 자연어 규칙은 기술적 상한이나 접근 제어를 대체하지 못합니다. 동시 실행 제한과 권한은 아래 설정을 함께 사용하세요.

5. config.toml과 사용자 지정 에이전트 설정

지침 파일과 설정 파일의 역할은 다르다

  • AGENTS.md: 위임 기준, 프로젝트 규칙, 결과 보고 방식 같은 행동 지침.
  • config.toml: 기능 활성화, 동시 실행 상한, 서브에이전트 기본 모델·추론 설정.
  • .codex/agents/*.toml: 이름을 가진 사용자 지정 에이전트의 역할과 세부 설정.

사용자 전역 설정은 보통 ~/.codex/config.toml, 프로젝트 설정은 .codex/config.toml에 작성합니다. 프로젝트 설정의 적용에는 신뢰 설정 등 환경 조건이 영향을 줄 수 있으므로, 설정을 작성한 뒤 실제 로드 여부를 확인하세요.

최신 문서 기준의 최소 설정 예시

[agents]
enabled = true
max_concurrent_threads_per_session = 3

enabled는 현재 문서 기준 기본값이 true이므로 기본 기능만 쓴다면 반드시 추가할 필요는 없습니다. max_concurrent_threads_per_session은 메인 에이전트를 제외한, 동시에 열려 있는 생성 에이전트 스레드의 상한입니다. “항상 3개를 만들라”는 뜻은 아닙니다.

기존 파일에 [agents] 섹션이 있다면 그 안에 필요한 키만 합치세요. 같은 TOML 테이블을 중복 선언하면 설정 오류가 날 수 있습니다.

기본 모델을 정하고 싶다면

최신 문서에는 default_subagent_model과 default_subagent_reasoning_effort도 안내되어 있습니다. 아래는 구조 설명용 템플릿이므로, 모델 자리표시자를 그대로 실행하지 마세요.

[agents]
enabled = true
max_concurrent_threads_per_session = 3
# 아래 모델 ID를 계정에서 사용 가능한 실제 값으로 교체하세요.
default_subagent_model = "AVAILABLE_MODEL_ID"
# 선택한 모델이 이 추론 수준을 지원할 때만 사용하세요.
default_subagent_reasoning_effort = "medium"

모델과 추론 수준을 별도로 정하지 않으면 부모 에이전트의 설정을 상속하는 것이 기본입니다. 명시적인 생성 요청, 전역 서브에이전트 기본값, 사용자 지정 에이전트 파일의 설정 사이에는 우선순위가 있으므로, 단순히 프롬프트에 “가벼운 모델”이라고 적었다고 실제 모델이 바뀌었다고 단정하면 안 됩니다.

AGENTS.md는 메인 에이전트의 모델을 자동 전환하는 장치가 아닙니다. 메인 모델은 해당 클라이언트의 모델 선택이나 지원되는 런타임 설정에서 확인해야 합니다. 특정 모델 이름을 고정하기보다, 현재 계정에서 사용 가능한 모델을 선택하고 생성된 스레드의 실제 설정을 확인하세요.

읽기 전용 reviewer 만들기

프로젝트 전용 역할을 만들려면 .codex/agents/reviewer.toml에 다음 내용을 저장할 수 있습니다. 개인 공통 역할은 ~/.codex/agents/ 아래에 둘 수 있습니다. 최신 형식의 필수 항목은 name, description, developer_instructions입니다.

name = "reviewer"
description = "Python/Django 변경사항의 정확성, 보안, 테스트 누락을 검토한다."
sandbox_mode = "read-only"
developer_instructions = """
코드를 수정하지 말고 변경사항을 검토한다.
인증·권한, 데이터 무결성, 예외 처리, 회귀 위험을 우선한다.
각 문제에는 파일 경로, 관련 함수, 근거와 재현 조건을 포함한다.
확인된 문제와 추가 확인이 필요한 가설을 구분한다.
표현이나 스타일만 다른 사항은 중요한 문제처럼 보고하지 않는다.
문제를 찾지 못한 경우 검토 범위와 남은 불확실성을 설명한다.
"""

이 예시에는 특정 모델을 고정하지 않았습니다. 필요하면 지원되는 model과 model_reasoning_effort를 추가할 수 있습니다. 파일 이름을 역할 이름과 맞추면 관리하기 쉽지만, Codex가 역할을 식별하는 기준은 파일 내부의 name입니다.

설정을 적용한 새 세션에서 다음처럼 요청하세요.

reviewer 서브에이전트를 사용해서 현재 브랜치의 Python 변경사항을 검토해줘.
기준 브랜치는 main이야. 코드 수정 없이 문제점과 근거만 보고해줘.
검토가 끝나면 메인 에이전트가 실제 diff와 대조해서 결과를 요약해줘.

서브에이전트는 기본적으로 부모의 권한·샌드박스 정책을 상속합니다. 리뷰 역할은 위처럼 read-only로 명시하는 편이 안전합니다. 지침에 “수정하지 마”라고 적는 것과 실행 환경에서 파일 쓰기를 제한하는 것은 서로 다른 보호 장치입니다.

예전 설정 글과 다른 이유

과거 가이드에서 [features] multi_agent = true나 /experimental 활성화 절차를 볼 수 있습니다. 최신 공식 문서는 기본 활성화를 안내하며, 전역 설정에 [agents] 항목을 설명합니다. 또한 agents.max_threads는 최신 문서에서 기존 설정을 위한 별칭으로 안내됩니다. 오래된 예시와 새 형식을 한 파일에 무작정 섞지 말고 설치 버전과 공식 설정 참조를 먼저 대조하세요.

6. Django 프로젝트에서 안전하게 작업 나누기

예를 들어 “주문 목록 API가 느리다”는 문제를 조사한다고 가정해 보겠습니다. 처음부터 여러 에이전트에게 동시에 수정 권한을 주기보다, 다음처럼 조사는 병렬, 수정은 통제, 검증은 통합하는 흐름이 좋습니다.

  1. 메인이 증상 고정: 재현 요청, 데이터 규모, 느린 구간, 변경 금지 범위를 정리합니다.
  2. 탐색 담당: URL·View·Serializer·Service의 호출 흐름과 관련 파일을 찾습니다.
  3. 성능 담당: 반복 조회와 select_related·prefetch_related 적용 가능성을 조사합니다. 쿼리 수를 측정하지 않았다면 “N+1 확정”이 아니라 가설로 보고합니다.
  4. 검증 담당: 사용자별 데이터 접근 권한과 테스트 누락을 확인합니다.
  5. 메인이 수정 계획 결정: 실제 근거를 비교하고 작은 변경 범위를 선택합니다.
  6. 수정 후 전체 검증: 프로젝트에서 정한 테스트와 동일 조건의 재현을 실행하고, 성능 변화와 회귀 여부를 확인합니다.

여기서 탐색과 성능 조사의 범위가 겹친다면 두 역할을 합치는 편이 낫습니다. 에이전트를 채우기 위해 일을 나누는 것이 아니라, 중복 없이 필요한 조사를 수행하는 것이 목적입니다.

동시 구현이 필요하다면 파일 소유권부터 정하기

백엔드와 프론트엔드를 병렬로 만들 때는 요청·응답 형식을 먼저 합의하세요. 예를 들어 백엔드는 orders/api/, 프론트엔드는 frontend/orders/만 수정하도록 나누고, 공통 타입·설정·의존성 파일은 메인이 관리하도록 정할 수 있습니다.

Django 마이그레이션처럼 순서와 공통 상태가 중요한 파일도 동시에 생성·수정하지 않도록 조정하는 편이 좋습니다. 분리된 파일에서 작업하더라도 API 계약이나 데이터 구조가 달라질 수 있으므로, 마지막에는 통합 테스트가 필요합니다.

서브에이전트 결과의 최소 보고 형식

- 검토 범위:
- 확인된 사실:
- 파일 경로와 관련 함수:
- 문제의 영향과 근거:
- 재현 또는 확인 방법:
- 실행한 테스트와 결과:
- 실행하지 못한 테스트와 이유:
- 추가 확인이 필요한 가설:
- 변경한 파일: 없음 / 실제 목록

이 형식은 “잘 검토했다”는 추상적인 답변을 줄이고, 메인이 사실과 미확인 사항을 빠르게 나누는 데 도움이 됩니다. 개별 에이전트가 보고한 테스트 결과도 최종 변경 상태와 맞는지 확인해야 합니다.

7. Subagents 실행 확인과 문제 해결

서브에이전트가 생성되지 않을 때

  1. 설치된 Codex 버전과 클라이언트에서 해당 기능을 지원하는지 확인합니다. CLI라면 codex --version으로 버전을 확인할 수 있습니다.
  2. 현재 설정에서 agents.enabled = false처럼 기능을 비활성화한 항목이 없는지 확인합니다.
  3. “서브에이전트 2개를 생성해 역할별로 조사하라”처럼 명시적으로 요청합니다. 단순히 관점을 나눠 설명하는 것과 실제 에이전트 생성은 다릅니다.
  4. 적용 중인 AGENTS.md에 작은 작업의 위임을 제한하는 규칙이 있는지 확인합니다.
  5. 설정을 바꿨다면 해당 디렉터리에서 새 세션을 시작하고 실제 활동 표시를 확인합니다.

AGENTS.md가 반영되지 않을 때

의도한 저장소와 작업 디렉터리인지, 파일이 비어 있지 않은지, 같은 위치의 AGENTS.override.md가 우선하는지 확인하세요. 공식 문서의 지침 합산 기본 한도는 32 KiB이며, 너무 긴 지침은 project_doc_max_bytes에 의해 제한될 수 있습니다. 중요한 원칙은 간결하게 유지하는 편이 좋습니다. [2]

새 세션에서 다음처럼 확인을 요청할 수 있습니다.

현재 적용된 지침 파일의 경로를 알려줘.
서브에이전트 사용 조건, 사용하지 않을 조건, 파일 수정 범위,
최종 검증 책임을 각각 요약해줘.
아직 코드를 수정하거나 에이전트를 생성하지 마.

이 응답은 지침 인식 여부를 확인하는 출발점입니다. 모델의 설명만 믿기보다 실제 파일 위치와 에이전트 생성 동작을 함께 대조하세요.

사용량이 예상보다 빠르게 늘어날 때

같은 범위를 중복 조사하는지, 결과에 긴 로그 전체를 반환하는지, 작은 작업까지 위임하는지부터 확인하세요. 동시 실행 상한을 낮추고, 범위와 출력 길이를 줄이며, 도움이 되지 않는 에이전트는 중단하는 방법을 고려할 수 있습니다.

ChatGPT 기반 Codex의 사용량 한도는 플랜과 작업 특성에 영향을 받습니다. API 토큰 비용과 구독 플랜의 사용량 한도를 동일한 개념으로 계산하거나, 모든 사용자에게 하나의 고정 시간 제한이 적용된다고 단정하지 마세요. 자신의 계정에 표시되는 사용량과 최신 플랜 안내를 기준으로 판단하는 것이 좋습니다.

8. Codex Subagents 자주 묻는 질문

Q. Subagents를 사용하려면 별도 Skill을 설치해야 하나요?

최신 공식 문서 기준으로 기본 서브에이전트 기능에 별도 Skill 설치는 필요하지 않습니다. Skill은 반복 작업 절차를 보강하는 수단이며, 서브에이전트 생성 기능 자체와는 다릅니다.

Q. AGENTS.md에 규칙을 쓰면 항상 자동 실행되나요?

아닙니다. 최신 버전에서는 적용되는 지침에 따라 위임할 수 있지만, 작업 조건과 기능 설정에 따라 달라집니다. “필요할 때만 사용”이라는 규칙이라면 작은 작업에서 생성되지 않는 것이 정상일 수 있습니다.

Q. 서브에이전트가 많을수록 빠르고 정확한가요?

아닙니다. 독립적인 큰 작업은 병렬 처리의 이점을 얻을 수 있지만, 중복 조사와 결과 조정이 늘면 오히려 비효율적입니다. 여러 에이전트의 결론이 같아도 실제 코드·테스트 검증은 필요합니다.

Q. AGENTS.md만으로 모델과 권한을 강제로 바꿀 수 있나요?

자연어 지침만으로 실제 모델 전환이나 접근 제한을 보장할 수 없습니다. 모델은 지원되는 설정과 런타임에서 확인하고, 읽기 전용 제한은 샌드박스 설정으로 적용하세요.

Q. reviewer는 Codex의 내장 에이전트인가요?

이 글에서 확인한 최신 내장 목록은 default, worker, explorer입니다. reviewer는 리뷰 역할을 요청하거나 사용자 지정 TOML로 정의해 사용할 수 있습니다.

Q. 서브에이전트를 쓰면 토큰이 줄어드나요?

메인 대화에 쌓이는 중간 출력은 줄일 수 있지만, 전체 토큰 소비가 줄어든다는 뜻은 아닙니다. 공식 문서는 유사한 단일 에이전트 실행보다 더 많은 토큰을 사용할 수 있다고 안내합니다.

결론: 기본은 메인 하나, 필요한 조사만 분리하기

Codex Subagents의 핵심은 에이전트 수를 늘리는 것이 아니라 작업을 올바르게 나누는 것입니다. 작은 수정은 메인이 처리하고, 독립적인 탐색이나 별도 리뷰가 유용할 때만 제한적으로 위임하는 방식부터 시작해 보세요.

AGENTS.md에는 위임 기준과 최종 검증 책임을 적고, config.toml에는 실행 상한을 설정하며, 사용자 지정 에이전트에는 좁고 명확한 역할을 부여하면 됩니다. 이후 자신의 프로젝트에서 사용량, 완료 시간, 결과 품질을 비교해 병렬화가 실제로 도움이 되는 범위만 넓히는 것이 합리적입니다.

참고 자료와 작성 기준

공식 제품 설명과 이 글의 운영 권장안을 구분했습니다. 2~3개부터 시작하기, 파일 소유권 정하기, 보고 형식 통일하기는 충돌과 낭비를 줄이기 위한 권장안이며, 검증된 성능 수치나 필수 제품 사양이 아닙니다.

  1. OpenAI 공식 Subagents 문서: 기본 활성화, 위임 방식, 내장 역할, 사용자 지정 에이전트, 모델·권한 설정.
  2. OpenAI 공식 AGENTS.md 문서: 전역·프로젝트 지침 탐색 순서, override 우선순위, 지침 크기 제한.
  3. OpenAI Codex 설정 레퍼런스: 설치 환경의 설정 항목을 대조할 때 참고.

함께 읽으면 좋은 글

서브에이전트의 작업 절차를 재사용하고, 여러 에이전트의 코드 변경을 안전하게 관리하려면 다음 글을 함께 참고하세요.

  • 바이브 코딩에 유용한 핵심 AI 스킬 8가지와 생성 프롬프트
    반복되는 설계·디버깅·테스트·리뷰 절차를 Skill로 정리하는 방법을 다룹니다. AGENTS.md의 작업 원칙과 재사용 가능한 스킬을 구분하고 활용할 때 도움이 됩니다.
  • AI Coding Agent 시대의 Git 활용법
    여러 에이전트의 작업을 Git worktree와 브랜치로 분리하고, 작은 커밋·Diff·테스트·리뷰로 검증하는 흐름을 설명합니다. 병렬 구현에서 파일 충돌을 줄이고 결과를 통합할 때 참고할 수 있습니다.

#Codex #서브에이전트 #AGENTSmd #AI코딩

댓글

이 블로그의 인기 게시물

클로드 Gmail 연동 방법: 이메일 분류·요약·답장 자동화

바이브 코딩에 유용한 핵심 AI 스킬 8가지와 생성 프롬프트

Claude Code 토큰 절약 가이드