코덱스 툴 사용법 10: 서브에이전트로 병렬 검토 맡기기 | DAKER 커뮤니티

코덱스 툴 사용법 10: 서브에이전트로 병렬 검토 맡기기

코덱스와 오래 작업하다 보면 한 대화 안에 파일 목록, 테스트 로그, 실패 원인, 리뷰 메모가 계속 쌓인다. 처음에는 도움이 되지만, 어느 순간부터 메인 대화가 너무 시끄러워진다. 요구사항과 결정은 묻히고, 코덱스는 오래된 로그와 현재 목표를 함께 들고 판단해야 한다.

이럴 때 쓰는 도구가 서브에이전트다. OpenAI 공식 Codex 매뉴얼은 서브에이전트를 "전문화된 에이전트를 병렬로 실행해 탐색, 분석, 작업을 동시에 진행하고 결과를 합치는 워크플로"로 설명한다. 핵심은 더 많은 에이전트를 쓰는 것이 아니라, 메인 스레드에는 결정과 통합만 남기는 것이다.

아래 Mermaid 다이어그램은 서브에이전트를 요청할 때의 기본 흐름이다. 게시 본문에서는 같은 원리를 SVG 이미지로도 볼 수 있다.

1. 서브에이전트는 "여러 명에게 시키기"가 아니라 "소음을 분리하기"다

서브에이전트의 가장 좋은 쓰임은 읽기 중심 작업이다. 예를 들어 큰 저장소에서 인증 흐름을 찾는 일, 테스트 실패 로그를 분류하는 일, 현재 PR을 보안/테스트/유지보수 관점으로 나눠 보는 일은 서로 독립적이다.

반대로 한 파일을 여러 에이전트가 동시에 고치는 작업은 위험하다. 충돌이 늘고, 누가 어떤 판단을 했는지 합치기 어려워진다. 공식 매뉴얼도 병렬 쓰기 중심 워크플로는 충돌과 조율 비용이 커질 수 있으니 더 조심하라고 안내한다.

실무 기준은 간단하다.

2. 명시적으로 요청해야 한다

코덱스는 아무 때나 자동으로 서브에이전트를 만들지 않는다. 공식 매뉴얼 기준으로 서브에이전트는 명시적으로 요청했을 때 사용한다. 따라서 "검토해줘"보다 "관점별로 에이전트를 나눠 검토해줘"라고 써야 한다.

바로 쓸 수 있는 요청은 이렇다.

현재 브랜치를 main과 비교해서 병렬로 리뷰해줘.
보안 리스크, 테스트 누락, 유지보수성 관점으로 각각 한 에이전트를 사용해.
모든 에이전트가 끝날 때까지 기다린 뒤, 파일 경로와 우선순위가 있는 통합 요약만 반환해줘.
수정은 아직 하지 말고, 먼저 발견 사항만 보고해줘.

이 프롬프트에는 네 가지가 들어 있다. 나눌 관점, 기다릴 조건, 반환 형식, 쓰기 금지다. 이 네 가지가 없으면 병렬 작업이 빨라져도 결과가 산만해질 수 있다.

3. 좋은 분할 기준은 "역할"보다 "증거 종류"다

"세 명의 에이전트로 해줘"라는 말만으로는 부족하다. 세 명이 같은 파일을 읽고 같은 결론을 내면 토큰만 더 쓴다. 더 좋은 기준은 서로 다른 증거를 보게 하는 것이다.

예를 들어 버그 조사는 이렇게 나눌 수 있다.

리뷰도 마찬가지다.

이렇게 나누면 메인 스레드는 "같은 말 세 번"이 아니라 서로 다른 증거를 받아 비교할 수 있다.

4. 결과 형식을 미리 정해야 메인 스레드가 깨끗해진다

서브에이전트를 쓰는 목적은 메인 스레드를 깨끗하게 유지하는 것이다. 그래서 원시 로그를 그대로 붙여 달라고 하면 장점이 줄어든다. 대신 요약 형식을 지정한다.

각 에이전트는 아래 형식으로만 요약해줘.
- 결론: 한 문장
- 근거 파일: 최대 5개
- 중요한 로그: 최대 3줄

- 추천 다음 행동: 최대 3개
- 확신도: low / medium / high

이 형식은 리뷰에도 잘 맞는다. 파일 경로가 없으면 실행 가능한 발견이 아니고, 확신도가 없으면 바로 고칠지 더 조사할지 판단하기 어렵다.

5. 승인과 샌드박스는 부모 세션을 따라간다

서브에이전트를 쓰면 권한도 새로 열리는 것처럼 느껴질 수 있지만, 그렇게 생각하면 위험하다. 공식 Codex 매뉴얼은 서브에이전트가 현재 샌드박스 정책을 상속한다고 설명한다. 대화 중 바꾼 런타임 권한도 자식 에이전트를 만들 때 다시 적용된다.

따라서 병렬 작업을 요청하기 전에는 권한 경계를 먼저 적는 편이 좋다.

모든 서브에이전트는 읽기 중심으로만 작업해줘.
환경 변수 파일, 배포 명령, 데이터베이스 마이그레이션은 건드리지 마.
수정이 필요하면 어느 파일을 바꿔야 하는지만 제안해줘.

이렇게 하면 조사가 끝난 뒤 메인 스레드에서 수정 범위를 다시 결정할 수 있다. 특히 실제 서비스 저장소에서는 이 한 줄이 사고를 줄인다.

6. /agent는 진행 중인 작업을 들여다보는 창이다

Codex CLI에서는 /agent로 활성 에이전트 스레드를 전환하거나 진행 중인 스레드를 살펴볼 수 있다. 여러 에이전트가 돌고 있을 때 "어느 쪽이 막혔는지", "승인 요청이 어디서 왔는지" 확인할 때 유용하다.

다만 처음부터 모든 서브에이전트 대화를 읽으려고 하면 다시 메인 스레드가 시끄러워진다. 보통은 다음 세 경우에만 들여다보면 충분하다.

  1. 승인 요청이 어떤 작업에서 왔는지 확인할 때

  2. 특정 에이전트가 오래 멈춰 있는 것처럼 보일 때

  3. 최종 요약의 근거가 부족해서 원문 확인이 필요할 때

서브에이전트는 "감시해야 하는 작은 챗봇들"이 아니라, 메인 판단을 돕는 임시 조사원이라고 보면 된다.

7. 바로 붙여 넣는 프롬프트 템플릿

아래 템플릿은 PR 리뷰나 큰 버그 조사에 그대로 쓸 수 있다.

이 작업은 병렬 서브에이전트로 조사해줘.

목표:
{무엇을 알고 싶은지}

분할:
1. {관점 A} 에이전트: {볼 증거}
2. {관점 B} 에이전트: {볼 증거}
3. {관점 C} 에이전트: {볼 증거}

제약:
- 아직 코드는 수정하지 않음
- 환경 변수, 배포, 마이그레이션은 건드리지 않음
- 각 에이전트는 원시 로그 대신 요약만 반환

통합 보고:
- 가장 중요한 발견 3개
- 파일 경로와 근거
- 바로 수정할 것 / 더 조사할 것 구분
- 추천 검증 명령

8. 서브에이전트는 비싼 도구다

서브에이전트는 편하지만 공짜가 아니다. 공식 매뉴얼도 각 서브에이전트가 자기 모델과 도구 작업을 수행하므로, 단일 에이전트보다 토큰을 더 쓴다고 설명한다. 작은 작업에는 오히려 느리고 비쌀 수 있다.

그래서 기준을 이렇게 잡으면 좋다.

Senior takeaway: 서브에이전트는 코덱스를 "더 많이" 쓰는 기능이 아니라, 복잡한 작업에서 메인 판단을 보호하는 기능이다. 독립적인 읽기 작업을 나누고, 요약 형식을 제한하고, 쓰기 범위를 닫으면 병렬 검토가 리뷰 가능한 결정으로 돌아온다.

Redirecting to 코덱스 툴 사용법 10: 서브에이전트로 병렬 검토 맡기기 | DAKER 커뮤니티...