사용기 - Codex 에서 Subagents 활용하기

Subagents란, Codex가 하나의 큰 작업을 여러 개의 작은 작업으로 나누어 각각 별도의 보조 에이전트에게 맡긴 뒤, 그 결과를 다시 통합하는 병렬 작업 방식이다. 복잡한 작업, 코드베이스 탐색, PR 리뷰처럼 여러 항목을 동시에 볼 때 특히 유용하다고 한다. OpenAI 개발자 가이드

서브에이전트(subagent)는 언제 어떻게 사용하나

공식 문서에 따르면 컨텍스트 창(에이전트의 스레드 기억 공간)이 크더라도 요구사항, 제약조건, 의사결정 같은 핵심 정보 사이에 탐색 노트, 테스트 로그, 스택 트레이스, 명령 출력 같은 중간 결과가 과도하게 섞이면 모델의 응답 품질과 세션 신뢰성이 점차 떨어질 수 있다고 한다.  이런 문제는 중요한 정보가 잡음에 묻히는 맥락 오염과, 관련 없는 세부 정보가 많아지면서 판단 성능이 저하되는 맥락 왜곡으로 설명할 수 있다. (Context Rot: How Increasing Input Tokens Impacts LLM Performance) 

서브에이전트 워크플로(Codex가 병렬 에이전트를 실행하고 그 결과를 결합하는 워크플로)는 이러한 잡음을 메인 스레드에서 분리하여, 메인 에이전트는 핵심 요구사항과 최종 결과에 집중하고, 탐색·테스트·로그 분석 같은 읽기 중심 작업은 하위 에이전트가 병렬로 처리한 뒤 요약만 반환하도록 돕는다. 다만 병렬 에이전트는 읽기 작업에는 효과적이지만, 여러 에이전트가 동시에 코드를 수정하는 쓰기 중심 작업에서는 충돌과 조정 비용이 커질 수 있으므로 더 신중하게 운영해야 한다.

즉 맥락 오류가 커질수 있는 큰 작업을 여러 덩어리로 나눌 수 있을 때 좋은 결과를 예상할 수 있는데. 예를 들면 “보안”, “버그”, “코드 품질”, “테스트 불안정성”을 각각 따로 검사시키는 식이다. Codex는 사용자가 명시적으로 요청할 때만 서브에이전트(subagent)를 실행한다. 그리고 서브에이전트(subagent)가 늘어나면 그만큼 모델 호출과 도구 사용이 늘어서 토큰 비용도 더 많이 발생한다. 

 Prompt 예시  

다음 작업을 subagent로 분할해줘.
- explorer 1개: 인증 구조 파악
- worker 1개: 로그인 API 구현
- worker 1개: 테스트 추가
- default 1개: 전체 결과 통합 정리
모든 작업이 끝난 뒤 최종 보고서를 작성해.

“명시적으로 요청”한다는 것은, Codex가 알아서 subagent 를 만들 거라고 기대하는 것이 아니라, 프롬프트 안에 spawn, one agent per point, explorer subagent 를 생성, worker를 사용처럼 분업 지시를 직접 써주는 것이다.

 

Codex는 중간 관리자 역할을 수행

어떤 서브에이전트(subagent)를 띄울지, 후속 지시를 어떻게 줄지, 결과를 언제 모을지 등을 Codex가 조율하고 마지막에는 결과를 합쳐서 하나의 응답으로 보여주는 역할을 한다. 

 Prompt 예시  

현재 브랜치와 main을 비교해서 PR을 검토해.
항목별로 subagent를 하나씩 생성해.
모든 subagent의 작업이 끝날 때까지 기다린 뒤, 항목별 결과를 요약해줘.
1. 보안 이슈
2. 코드 품질
3. 버그 가능성
4. 동시성 문제
5. 테스트 불안정성
6. 유지보수성

 이 프롬프트를 받으면 Codex는 다음을 조율한다.

1. 어떤 서브에이전트(subagent)를 띄울지 정한다.
   예를 들어 보안 검토용, 테스트 검토용, 유지보수성 검토용처럼 항목별 서브에이전트(subagent)를 분리한다. 문서상 Codex는 서브에이전트(subagent)를 생성하고 오케스트레이션하는 역할을 한다.

2. 각 서브에이전트(subagent)에 후속 지시를 전달한다.
   예를 들어 “보안 서브에이전트(subagent)는 인증/인가 흐름을 보라”, “테스트 서브에이전트(subagent)는 누락된 테스트를 찾으라”처럼 작업을 나눠 보낸다. 공식 문서도 Codex가 follow-up instructions를 라우팅한다고 설명한다.

3. 결과를 기다린다.
   여러 서브에이전트(subagent)가 동시에 돌고 있으면 Codex는 요청한 결과가 모두 준비될 때까지 기다린다.

4. 마지막에 하나로 합친다.
   각 서브에이전트(subagent)의 결과를 항목별로 묶어 최종 응답으로 정리해 보여준다. 공식 문서에서는 consolidated response로 설명한다.

Codex 내장 서브에이전트(subagent)

default(범용), worker(구현/수정 중심), explorer(읽기 중심 탐색) 같은 기본 agent가 이미 제공되고 있다. 

• default: 특별히 역할을 안 나눴을 때 쓰는 범용 담당
• worker: 실제 수정, 구현, 정리, 반복 작업 담당
• explorer: 파일 찾기, 구조 파악, 원인 추적 전 단계 담당

 Prompt 예시  

worker를 사용해서 로그인 API를 구현해줘.
요구사항:
- 이메일/비밀번호 로그인
- JWT 발급 포함
- 기존 SecurityFilterChain 구조를 유지
- Controller, Service, DTO까지 구현
- 관련 테스트도 함께 추가
결과는 변경 파일 목록과 함께 요약해줘.

 

커스텀 서브에이전트(subagent)

TOML 파일로 “이 agent는 PR 리뷰 전용”, “이 agent는 문서 조사 전용”처럼 역할을 따로 정의할 수 있다. (최소한 name, description, developer_instructions 필요.)  좋은 서브에이전트(subagent)는 공식 문서에 따르면 “좁고 명확한 역할을 가져야 한다”고 설명하고 있다. 즉, 하나의 서브에이전트(subagent)가 다 하게 하기보다 “코드 탐색용”, “보안 리뷰용”, “문서 조사용”처럼 나누는 게 좋다.

용자 정의 서브 에어전트를 사용하기 위해서 특정 개발 작업을 위해 설계된 특수 AI 보조 도구인 Codex 서브에이전트 의 최종 모음집 저장소 Awesome Codex Subagents 을 활용했다. 

최종적으로는 AI 지원 개발을 일관된 규칙, 템플릿, 자동화 스크립트로 표준화해 배포할 수 있게 만든 DevOps 정책 템플릿 저장소를 구성하여 사용했다. ( https://github.com/andang72/devops-policy-template ) 

먼저 세부 계획을 병렬로

서브에이전트 1: 현재 패키지/모듈 구조 분석 서브에이전트 2: 중복 책임, 순환 의존, 경계 위반 탐지 서브에이전트 3: 테스트 영향 범위와 회귀 위험 분석 서브에이전트 4: 후보 리팩토링 포인트 요약

를 통해서 수립해줘.

이렇게 프롬프르를 작성하면 코덱스는 병렬작업에 맞게 작업 계획을 수립한다. 

계획이 수립되면 이슈를 등록하게 하고 순서대로 작업을 아래와 같이 특정 서브에이전트에게 진행을 요청한다. 

서브에이전트에 의한 작업은 좌측 스레드 목록이나 하단의 작업 목록 아래의 background agents (@ to tag agents ) 를 통하여 확인 할 수 있다. 

좌측 메뉴

하단 메뉴

서브에이전트를 도입하면 단순 오류 수정이 아닌 기존 코드를 분석하여 기능을 수정하거나 추가하는 경우 확연하게 결과가 개선되는 것을 확인할 수 있었다. 다만 서브에이전트를 사용하는 경우 토큰 소비가 크게 증가하기 때문에 이부분에 대한 사전 고려가 필요할 것 같다.