Codex 서브에이전트 위임 기준과 모델 검증

정리 기준: 2026-10-27. Codex 서브에이전트는 메인 대화가 조사, 구현, 검토처럼 나눌 수 있는 일을 별도 실행 단위에 맡기고 결과를 받아 통합하는 기능이다. 아래 Sol, Terra, Luna 역할과 작업 순서는 Readiz가 선택한 운영 기준이다. 공식 문서는 에이전트 정의와 호출 동작을 설명하므로, 실제로 지원되는 모델과 설정 형식은 Subagents 문서와 AGENTS.md 문서에서 확인한다.

작업을 나누는 기준

Readiz의 Sol 메인 구성에서는 의미 있는 코드, 설정, 문서 구현을 시작하기 전에 범위와 수용 조건을 정하고 implementer에게 실제로 맡긴다. 짧은 답변과 오탈자, 행동과 영향이 이미 확정된 국소 변경만 메인이 직접 처리한다. 파일 수나 줄 수, 단지 직접 하는 편이 빠르다는 이유로 이 예외를 넓히지 않는다. 그 밖에 수용 조건을 정할 수 있는 구현은 시작 전에 맡기고, 먼저 구현한 뒤 시험 호출하는 것으로 대신하지 않는다.

모델 이름과 Effort는 이 운영안의 예시다. 계정, 클라이언트, 현재 실행 도구에서 실제 선택할 수 있는지 확인한다. 사용자가 선택한 메인 모델과 Effort를 바꾸지 않는다. Astra와 다른 메인 모델은 역할 구성을 참고하되 직접 수행할지, 위임할지, 병렬로 나눌지를 자율적으로 정한다.

Sol은 먼저 요구사항과 수용 조건을 설계한다. 필요한 경우 Terra가 조사하고, 그 결과가 구현의 선행조건이면 조사 후 범위를 확정해 Luna에게 맡긴다. Luna가 구현한 뒤 위험이 큰 변경은 Sol reviewer가 독립 검토하고, 메인이 통합해 최종 검증한다. 조사와 구현이 서로 기다릴 필요가 없으면 독립 작업을 병렬로 나눌 수 있다.

예를 들어 설정 화면에 저장 항목을 추가할 때 Sol은 수정 파일과 저장 후 재진입 같은 수용 조건을 먼저 정하고 Luna에 구현을 맡긴다. 브라우저별 메뉴 겹침을 고칠 때는 Terra가 해당 브라우저에서 실제 화면을 조사하고 재현 조건을 보고한 뒤 Luna가 수정할 수 있다. 인증 경계나 데이터 이관처럼 영향이 큰 변경은 구현 후 Sol reviewer가 독립 검토하고 메인이 최종 결과를 확인한다. 이미 확정된 문구의 오탈자만 고치는 경우에는 메인이 직접 처리할 수 있다.

설정 파일과 공통 지침

기본 Codex 홈을 쓰는 예시 구조는 다음과 같다. 사용자 역할 정의는 ~/.codex/agents/에, 해당 프로젝트에만 적용할 정의는 저장소의 .codex/agents/에 둘 수 있다. CODEX_HOME을 바꾼 환경에서는 실제 홈을 먼저 확인한다.

~/.codex/
├── config.toml
├── AGENTS.md
└── agents/
    ├── browser_researcher.toml
    ├── implementer.toml
    └── reviewer.toml

새 대화의 기본 모델과 하위 에이전트 사용 한도를 ~/.codex/config.toml에 병합하는 예시는 다음과 같다. 파일 전체를 예시로 교체하지 말고 기존 항목과 중복 키를 확인한다.

model = "gpt-6.1-sol"

[agents]
enabled = true
max_concurrent_threads_per_session = 3

새 대화의 기본 추론 강도도 정하려면 최상위에 model_reasoning_effort = "xhigh"를 추가할 수 있다. 이 설정은 현재 대화에서 사용자가 직접 선택한 모델과 Effort보다 우선하는 지시가 아니다. Codex 설정의 계층과 우선순위는 공식 Config 문서를 확인한다.

역할별 TOML은 에이전트의 이름, 설명, 지침, 모델과 Effort를 정의한다. 사용자 AGENTS.md는 어떤 상황에서 역할을 부르고 어떻게 결과를 통합할지 알려주는 공통 작업 지침이다. 역할 TOML을 만들었다고 자동으로 매 작업에서 위임되는 것은 아니며, 공통 지침만으로 해당 역할의 도구 권한이나 샌드박스를 높일 수도 없다. 공식 형식의 필수 항목과 범위는 Subagents 문서를 참고한다.

예를 들어 다음은 구현 역할 하나를 정의하는 완결된 사용자 범위 TOML이다. 프로젝트 파일에서 사용하려면 .codex/agents/implementer.toml에 둘 수 있다.

~/.codex/agents/implementer.toml

name = "implementer"
description = "부모가 정한 범위와 수용 조건에 따라 구현하고 필요한 검사를 수행합니다."
model = "gpt-6-luna"
model_reasoning_effort = "medium"
developer_instructions = """
부모가 지정한 파일과 수용 조건 안에서 구현합니다.
저장소의 지침을 따르고 무관한 리팩터링이나 다른 작업자의 파일 수정은 피합니다.
필요한 검사를 실행하고 수정 파일, 결과와 미확인 범위를 보고합니다.
설계나 범위가 모호하면 임의로 확대하지 말고 근거와 질문을 부모에게 전달합니다.
"""

사용자 공통 ~/.codex/AGENTS.md에는 다음과 같이 위임 기준을 간결하게 적을 수 있다. 실제 환경의 더 좁은 프로젝트 지침과 관리 정책도 함께 확인한다.

## 서브에이전트 활용

- 사용자가 선택한 메인 모델과 Effort를 유지한다.
- Sol 메인에서는 짧은 답변, 오탈자, 행동과 영향이 확정된 국소 변경만 직접 처리한다. 파일 수나 줄 수, 단지 직접 하는 편이 빠르다는 이유로 예외를 넓히지 않고, 그 외 구현은 범위와 수용 조건을 정해 시작 전에 implementer에게 맡긴다.
- 복잡한 브라우저 재현이나 외부 조사는 browser_researcher에 맡기고, 그 결과가 선행조건이면 범위를 확정한 뒤 구현을 위임한다.
- 현재 대화의 서브에이전트 도구로 실제 위임한다. 별도 CLI 설정 시험으로 현재 대화의 위임을 대신하지 않는다.
- 독립 작업만 병렬화한다. 위험이 큰 변경에만 reviewer를 추가한다.
- 각 요청에 목표, 허용 파일, 수정 금지 범위, 수용 조건, 검사와 반환할 내용을 적는다.
- 실제 모델, 도구, 권한과 상위 정책을 확인한다. 사용할 수 없는 역할은 그렇게 보고하고 위임했다고 주장하지 않는다.
- 메인은 반환 결과와 diff, 검사 근거를 확인해 통합하고 최종 검증한다.
- Astra와 다른 메인 모델은 직접 수행과 위임을 자율적으로 판단한다.

이 공통 지침은 Codex 설정의 AGENTS.md 동작을 사용자 선호에 맞춰 사용하는 예시다. 명시적 위임 요청이나 적용되는 지침에 따라 하위 에이전트가 실행되는 공식 동작과, Readiz가 정한 Sol 위임 기준을 구별한다. 제품 기능의 최신 내용은 공식 Subagents와 AGENTS.md에서 확인한다.

역할 요청과 실행 근거

작업 패킷에는 역할이 독립적으로 움직이고 메인이 결과를 검토하는 데 필요한 정보를 적는다.

목표: 알림 설정값을 화면에서 변경하고 저장한다.
허용 파일: src/settings/notifications.ts, src/settings/NotificationsPanel.tsx
수정 금지 범위: 데이터베이스 스키마와 다른 설정 화면
수용 조건: 선택값이 새로고침 뒤에도 유지되고 기존 기본 동작을 보존한다.
필요한 검사: 관련 단위 검사, 화면에서 저장한 뒤 재진입했을 때 값 확인
반환할 결과: 수정 파일, 구현 요약, 실행한 검사와 결과, 미확인 동작 또는 막힌 점

조사 요청에는 답할 질문과 사용할 수 있는 검색 또는 브라우저 도구를 정하고, 관찰한 사실과 추론을 구분해 달라고 한다. 검토 요청에는 파일 수정 금지와 확인할 위험을 지정한다. 메인은 실제로 어떤 역할이 실행됐는지, 어떤 모델과 Effort가 사용됐는지, 어떤 결과가 반환됐는지 확인한다.

설정 파일이 저장됐다는 사실은 역할이 현재 대화에서 실행됐다는 증거가 아니다. 별도 CLI의 /subagents 또는 설정 시험은 그 CLI 설정을 확인한 결과다. 현재 대화의 실제 위임은 대화에 연결된 네이티브 서브에이전트 실행과 반환 결과로 확인한다. 역할 지침에 브라우저 조사를 적어도 실제 브라우저 도구가 연결되고 화면을 관찰한 경우에만 브라우저 재현을 확인했다고 보고한다. 문서 검색만 했다면 조사 범위를 문서로 한정한다.

하위 실행은 부모의 권한과 연결 도구, 샌드박스 및 상위 정책 범위 안에서 이뤄진다. 역할 지침은 실행 권한을 부여하지 않는다. 모델이나 Effort를 지정할 수 없거나 도구와 권한이 없으면 그 제한과 미실행 범위를 밝힌다. 확인하지 않은 대체 모델로 조용히 바꾸거나 실행하지 않은 위임을 완료로 기록하지 않는다. 초기 상속 컨텍스트와 하위 역할이 실제로 사용한 실행 컨텍스트를 구분하고, 로그 형식은 클라이언트 버전에 따라 확인한다. 특정 스키마에 관한 과거 보고가 현재 모든 버전의 제약을 증명하지는 않는다. 관련 사례는 GPT-5.6 Sol cannot specify subagent models 이슈에서 볼 수 있다.

공개 사례와 성과 비교

공개 사례는 역할 구성의 아이디어로 읽고 보편적인 성능이나 절감 보장으로 바꾸지 않는다.

• 한 Reddit 사용자는 Astra Ultra를 메인으로 두고 기본 하위 역할에 Sol xhigh, 쉬운 작업에는 Luna xhigh 또는 max를 권하는 구성을 공유했다. 실제 위임 여부는 Astra가 판단한다. 작성자는 통제된 벤치마크를 하지 않았다고 명시했다. Astra Ultra with Sol/Luna subagents has been working really well for me
• codex_workflow는 Light 작업은 직접 처리하고 Heavy 작업은 Executor와 Tester가 구현과 검증을 맡으며, Explorer와 Investigator, Archivist가 조사 역할을 나누는 공개 구성이다. 저장소의 절감과 속도 설명은 제작자의 주장과 초기 사례로 읽는다.
• codex-astra-luna-orchestrator는 Astra와 Sol, Luna의 메인 프로필, Luna의 Explorer, Worker, Researcher, Tester 역할, 상위 검토 뒤 메인 통합 흐름을 제시한다. 설치를 권하기보다 역할 구성과 토큰 사용량 측정 가이드의 측정 범위를 참고한다.

직접 처리와 위임 방식을 비교하려면 동일한 저장소 상태와 대표 작업을 정하고 여러 번 반복한다. 모델, Effort, 도구, 검사 범위와 시작 시점의 변경을 기록하고 실행 순서는 가능하면 섞는다. 결과의 품질과 수용 조건 통과, 결함의 수와 심각도, 총 경과 시간, 조사와 대기 시간, 재작업, 되돌린 변경을 함께 비교한다. 호출된 역할과 모델, 호출 수 및 결과도 기록한다.

토큰 보고서에는 캐시를 읽은 입력과 캐시를 쓴 입력, 캐시되지 않은 입력과 출력이 각각 포함되는지, 반복 실행이 합산되는지, 계기판이 어떤 범위를 집계하는지 구분해 적는다. 토큰 수는 계정 전체 사용량 변화와 같은 지표가 아니다. 같은 계정의 5시간 창과 주간 사용량을 시작과 종료 시점에 적고, 다른 세션이나 동시 작업이 있었는지도 함께 기록한다. 다른 작업이 같은 시간에 돌았다면 계정 사용량 차이를 한 실험에 귀속하지 않는다. 작업 품질, 시간, 재작업과 사용량을 같이 살펴보고 한 번의 결과를 일반화하지 않는다. 정형 보고는 비교 실험이나 요청이 있을 때 작성하면 된다.

Readiz 운영 기준과 역할별 설정 예시는 Codex 모델과 에이전트 운영 문서, 작업 유형별 예시와 측정 방법은 Codex 에이전트 분담 패턴을 참고한다. 정리 시점 이후에는 모델 목록과 설정 동작이 달라질 수 있으므로 실제 환경에서 선택 가능한 값을 확인한다.