코덱스 툴 사용법 16: Subagents로 조사와 검증 분리하기 | DAKER 커뮤니티
코덱스 툴 사용법 16: Subagents로 조사와 검증 분리하기
큰 작업을 Codex에게 맡길 때 가장 먼저 무너지는 것은 모델의 실력이 아니라 대화의 정리 상태입니다. 로그, 검색 결과, 테스트 출력, 임시 가설이 한 스레드에 쌓이면 중요한 결정이 중간 소음에 묻힙니다.
Codex의 Subagents는 이 문제를 줄이기 위한 병렬 작업 표면입니다. OpenAI Codex 문서 기준으로 subagent workflow는 Codex가 특화된 agent를 병렬로 실행하고, 그 결과를 하나의 응답으로 모으는 방식입니다. 핵심은 “더 많은 agent가 항상 더 좋다”가 아니라, 메인 스레드는 결정과 통합을 맡고 하위 agent는 좁은 조사와 검증을 맡기는 것입니다.
한 줄 요약
Subagents는 작업을 자동으로 대신 쪼개 주는 마법이 아니라, 소음이 많은 read-heavy 작업을 메인 판단 흐름 밖으로 분리하는 도구입니다.
Subagent가 필요한 순간
Codex 문서는 subagent가 특히 exploration, tests, triage, summarization처럼 병렬화하기 쉬운 read-heavy 작업에 잘 맞는다고 설명합니다. 반대로 여러 agent가 동시에 코드를 고치는 write-heavy 작업은 충돌과 조정 비용이 커질 수 있습니다.
상황 | Subagent 적합도 | 이유 |
|---|---|---|
큰 코드베이스에서 관련 파일 찾기 | 높음 | 탐색 출력이 길고 병렬화 가능 |
PR 리뷰를 보안, 테스트, 유지보수성으로 나누기 | 높음 | 관점별로 독립 검토 가능 |
실패 로그 여러 개를 원인 후보별로 읽기 | 높음 | 원자료가 길고 요약 가치가 큼 |
파일 하나의 작은 버그 수정 | 낮음 | 분할 비용이 수정 비용보다 큼 |
같은 파일을 여러 agent가 동시에 수정 | 낮음 | 충돌과 중복 구현 가능성 증가 |
가장 쉬운 기준은 “이 일을 맡기면 중간 출력이 길어지는가?”입니다. 그렇다면 subagent로 분리할 가치가 있습니다. “이 일을 나누면 같은 파일을 서로 고칠 가능성이 높은가?”라면 먼저 단일 agent로 가는 편이 낫습니다.
병렬화 결정 흐름
여기서 중요한 단어는 “명시적으로”입니다. Codex 문서는 Codex가 subagent를 자동으로 띄우지 않으며, 사용자가 subagent 또는 parallel agent 작업을 명시적으로 요청해야 한다고 설명합니다.
좋은 역할 분리
Subagent를 쓸 때는 “3명으로 해줘”보다 “각자 무엇을 보고 무엇을 반환할지”가 더 중요합니다.
역할 | 맡길 일 | 반환 형식 |
|---|---|---|
Explorer | 관련 파일, 호출 흐름, 기존 패턴 찾기 | 파일 경로와 근거 요약 |
Reviewer | 회귀 위험, 보안 위험, 빠진 테스트 찾기 | 심각도와 근거 |
Verifier | 실행 가능한 테스트와 검증 명령 확인 | 실행 결과와 남은 공백 |
Writer | 조사 결과를 문서나 PR 설명으로 정리 | 최종 문안 초안 |
메인 스레드는 이 결과를 받아 “무엇을 채택할지”를 결정합니다. 하위 agent의 원자료 전체를 그대로 합치면 병렬화의 장점이 사라집니다. 요약, 파일 참조, 판단 근거만 받도록 요청하는 편이 좋습니다.
프롬프트 계약
좋은 subagent 프롬프트에는 네 가지가 들어갑니다.
몇 개의 agent를 띄울지
각 agent의 관점과 범위
모두 기다린 뒤 통합할지
어떤 형식으로 요약을 받을지
예시는 이렇게 쓸 수 있습니다.
현재 브랜치를 main과 비교해서 병렬 리뷰해줘.
Subagent를 3개 띄운다.
- Agent 1: 보안과 권한 경계만 본다.
- Agent 2: 테스트 누락과 회귀 위험만 본다.
- Agent 3: 유지보수성과 복잡도만 본다.
모든 agent가 끝날 때까지 기다린 뒤,
심각도순으로 파일 경로, 문제, 근거, 추천 조치만 요약해줘.
원자료 로그 전체는 붙이지 말고, 코드 수정은 아직 하지 마.이 프롬프트의 마지막 줄이 중요합니다. read-heavy 리뷰 단계라면 “코드 수정은 아직 하지 마”를 넣어야 결과가 겹치지 않습니다. 수정은 메인 스레드가 통합 판단을 한 뒤 한 번에 맡기는 편이 안전합니다.
Skills, AGENTS.md와 함께 쓰기
Codex 문서 기준으로 Skills는 재사용 가능한 workflow를 SKILL.md와 선택적 scripts/resources로 패키징하는 방식입니다. AGENTS.md는 저장소별 지속 지침을 레이어링하는 방식입니다.
Subagents는 이 둘과 역할이 다릅니다.
표면 | 쓰임 | 예시 |
|---|---|---|
AGENTS.md | 저장소 전체의 지속 규칙 | 테스트 명령, 리뷰 기준, 금지 작업 |
Skill | 반복 workflow의 실행 절차 | 릴리스 노트 생성, 보안 리뷰, 데이터 리포트 |
Subagent | 한 번의 작업 안에서 병렬 분담 | 보안/테스트/유지보수성 동시 리뷰 |
정리하면, AGENTS.md는 “항상 지킬 규칙”, Skill은 “반복할 절차”, Subagent는 “이번 작업의 병렬 분담”입니다. 세 표면을 섞어 쓰면 Codex에게 더 명확한 작업장을 줄 수 있습니다.
언제 쓰지 말아야 하나
Subagents는 토큰과 시간이 더 듭니다. Codex 문서도 각 subagent가 자기 모델과 도구 작업을 수행하기 때문에 단일 agent 실행보다 더 많은 토큰을 쓴다고 설명합니다.
쓰지 않는 편이 나은 경우는 분명합니다.
작업이 파일 하나와 함수 하나로 좁을 때
모든 판단이 같은 로그 한 덩어리에 의존할 때
여러 agent가 같은 파일을 고칠 가능성이 클 때
결과를 기다리는 시간이 직접 처리보다 길 때
무엇을 나눌지 아직 모를 때
마지막 경우에는 먼저 Explorer 하나에게 “관련 범위만 찾아줘”라고 맡긴 뒤, 그 결과를 보고 병렬화 여부를 결정하면 됩니다.
바로 복사할 프롬프트
복잡한 이슈 분석에는 이 템플릿을 써볼 수 있습니다.
이 작업은 먼저 읽기 전용 subagent 분석으로 시작해줘.
목표:
- <해결하려는 문제>
분담:
- explorer: 관련 파일, 호출 흐름, 기존 패턴을 찾는다.
- reviewer: 회귀 위험, 보안/권한 위험, 빠진 테스트를 찾는다.
- verifier: 현재 저장소에서 실행할 수 있는 검증 명령을 찾는다.
규칙:
- 모든 subagent가 끝날 때까지 기다린다.
- 코드 수정은 아직 하지 않는다.
- 각 agent는 원자료 전체가 아니라 파일 경로와 근거 중심으로 요약한다.
- 메인 스레드는 결과를 통합해 실행 계획과 위험을 정리한다.구현까지 맡길 때는 두 번째 프롬프트로 이어갑니다.
위 subagent 결과를 기준으로 구현은 단일 agent 흐름으로 진행해줘.
공유 파일 충돌을 피하기 위해 한 번에 한 영역만 수정한다.
수정 후 관련 테스트를 실행하고, 실행한 명령과 결과를 보고한다.선임 엔지니어 관점
Subagents를 잘 쓰는 팀은 agent 수를 자랑하지 않습니다. 대신 어떤 판단을 메인 스레드에 남기고, 어떤 소음을 하위 agent에게 보낼지 분명히 합니다.
처음에는 PR 리뷰, 장애 로그 분석, 큰 코드베이스 탐색처럼 읽기 작업부터 시작하세요. 쓰기 작업을 병렬화하고 싶다면 파일 소유권, branch/worktree 전략, 충돌 해결 규칙이 먼저 있어야 합니다. 병렬화의 목적은 바쁘게 보이는 것이 아니라, 메인 판단 흐름을 깨끗하게 유지하는 것입니다.
참고: OpenAI Codex manual의 Subagents, Agent Skills, AGENTS.md 섹션을 기준으로 작성했습니다.