codex의 서브에이전트는 메인 작업을 여러 개의 독립 에이전트 스레드로 나눠 실행하고 결과 요약을 다시 모으는 방식이다. 대형 코드베이스 탐색, 테스트 공백 찾기, 여러 문서 요약처럼 읽기 중심 작업을 빠르게 끝내는 데 적합하다. 각 에이전트가 별도 모델·도구 작업을 수행하므로, 단일 에이전트보다 토큰을 더 사용한다는 점도 함께 고려해야 한다.
언제 나눌지 판단한다
| 상황 | 권장 방식 | 이유 |
|---|---|---|
| 보안·테스트·유지보수 검토 | 역할별 서브에이전트 병렬 실행 | 서로 다른 파일·관점에서 독립적으로 조사 가능 |
| 여러 문서·모듈 탐색 | 범위별 병렬 실행 | 메인 스레드에 긴 탐색 로그가 쌓이지 않음 |
| 한 파일을 동시에 크게 수정 | 단일 에이전트 또는 작업 공간 분리 | 충돌과 조정 비용이 이득을 넘기기 쉬움 |
| 최종 설계 결정 | 메인 에이전트가 통합 | 요구사항·trade-off를 한곳에서 관리해야 함 |
요청 형식을 구체적으로 쓴다
Codex에 독립 작업의 분할 기준, 완료를 기다릴지 여부, 기대하는 보고 형식을 함께 준다.
이 브랜치를 서브에이전트로 검토해줘.
1) 보안 위험, 2) 테스트 공백, 3) 유지보수성으로 나누고
세 에이전트가 모두 끝날 때까지 기다려줘.
마지막에는 심각도·파일 경로·근거·권장 조치를 표로 합쳐줘.운영 원칙
- 읽기 중심부터 병렬화한다. 탐색, triage, 로그 분석, 요약은 충돌 위험이 낮다.
- 쓰기 작업은 소유자를 나눈다. 파일·디렉터리 또는 worktree 단위로 경계를 정하고, 같은 파일을 둘 이상에게 맡기지 않는다.
- 메인 스레드는 결정과 통합에 쓴다. 원시 로그 대신 요약을 받아 요구사항, 우선순위, 검증 결과를 유지한다.
- 검증을 별도 역할로 둔다. 구현 담당과 테스트·리뷰 담당을 나누면 자기 검증의 편향을 줄일 수 있다.
사용자 지정 에이전트
로컬 Codex 클라이언트에서는 작업별 지침과 모델 구성이 다른 사용자 지정 에이전트를 정의할 수 있다. 단, 먼저 기본 에이전트로 반복되는 병목을 확인한 뒤에 역할을 고정하는 편이 낫다. 너무 세분화한 역할은 컨텍스트 전달과 조정 비용만 늘릴 수 있다.
관련 문서
- agent-harness — 에이전트 실행 환경의 구성 요소와 검증 루프
- rtk — 셸 출력 컨텍스트를 줄이는 CLI 프록시
- git-worktrees-tips-ai-development — 병렬 쓰기 작업을 worktree로 분리하는 방법
참고 자료
- Subagents — OpenAI 공식 문서 (2026-08-18)