OpenAI2026-05-21

Codex 서브에이전트(Subagent) 완벽 가이드: 병렬 처리로 개발 효율 높이기

Codex 서브에이전트란?

Codex의 서브에이전트(Subagent)는 '자식 에이전트'라고도 불리며, 복잡한 태스크를 여러 서브에이전트로 분할해 병렬 처리하는 기능이다. 각 서브에이전트는 독립된 스레드에서 실행되며, 결론을 메인 스레드에 반환한다.

OpenAI 공식 문서에 따르면, 서브에이전트 워크플로우(Subagent Workflow)는 여러 병렬 에이전트를 실행한 뒤 결과를 통합하는 프로세스로 정의된다. 서브에이전트는 특정 태스크를 담당하는 에이전트이며, 에이전트 스레드(Agent Thread)는 각 에이전트의 실행 스레드로 CLI에서 확인·전환이 가능하다.

이 기능이 해결하는 주요 과제는 다음과 같다:

컨텍스트 오염 방지: 테스트 수정 같은 태스크에서는 대량의 파일 읽기, 명령 실행, 오류 분석이 필요하다. 이 모든 것을 메인 스레드에서 처리하면 판단이 흐려지기 쉽다. 서브에이전트는 서브스레드에서 처리를 완결하고 결론만 반환함으로써 메인 스레드를 깔끔하게 유지한다.
병렬 처리를 통한 효율 향상: PR 리뷰처럼 보안·스타일·테스트 커버리지·동시성·유지보수성 등 다각적인 관점이 필요한 태스크에서는, 하나의 에이전트가 순차 처리하는 것보다 병렬로 처리하는 것이 더 빠르고 빠짐없다.

결론적으로, 서브에이전트는 Codex의 활용 패턴 중 하나다.

적용 시나리오와 부적합 시나리오

단순한 판단 기준은 태스크를 서로 독립적인 작은 블록으로 분할할 수 있느냐다. 분할 가능하면 서브에이전트를 활용하고, 불가능하면 사용하지 않는 것이 좋다.

부적합한 상황:

태스크 자체가 작은 경우
서브태스크 간 밀접한 연동이 필요한 경우
쓰기(write) 범위가 겹치는 경우
분할 방법이 명확하지 않은 경우

서브에이전트가 효과적인 상황:

대규모 코드베이스 탐색
PR의 다차원 리뷰
여러 버그 원인의 동시 조사
보안·성능·테스트·유지보수성의 개별 평가
긴 문서·로그·복잡한 오류의 분할 분석
한 에이전트가 기능을 구현하고, 다른 에이전트가 병렬로 리스크 체크를 수행

공식 권장사항은, 먼저 읽기 중심(read-heavy) 태스크(탐색·테스트·트라이아지·요약 등)부터 시작하는 것이다. 여러 에이전트에 의한 코드 변경은 쓰기 중심(write-heavy)으로 파일 충돌이나 조정 비용이 발생할 위험이 있다.

또한, 각 서브에이전트가 모델과 도구를 독립적으로 실행하기 때문에 토큰 소비량은 단일 에이전트보다 증가한다. 프로젝트가 작으면 눈에 띄지 않지만, 규모가 커지면 두드러진다.

서브에이전트 실행 방법

Codex는 기본적으로 서브에이전트를 자동 실행하지 않는다. 프롬프트에서 실행 수와 각 태스크를 명시적으로 지정해야 한다. 흔히 사용하는 지정 방법은 다음과 같다:

"spawn two agents"
"delegate this work in parallel"
"use one agent per point"

한국어로 지정할 때는 예를 들어 "3개의 서브에이전트를 실행하여 보안·테스트·유지보수성을 각각 검사한다"와 같은 표현도 효과적이다.

아래는 실전에서 자주 사용하는 템플릿 예시다:

병렬 서브에이전트로 현재 브랜치를 리뷰해 주세요.
3개의 서브에이전트를 실행:
1. 보안 리스크 검사
2. 테스트 누락 검사
3. 코드 유지보수성 검사

모든 서브에이전트의 완료를 기다린 후 결과를 통합해 주세요.
출력은 중요도순으로 정렬하고, 파일 경로를 포함해 주세요.

PR 리뷰 구체적 예시

새 기능을 구현한 후의 PR 리뷰에서는 다음과 같은 프롬프트가 효과적이다:

현재 브랜치를 main과의 차이(diff)로 리뷰해 주세요.
1개의 서브에이전트로 잠재적 버그를 검사하고,
1개의 서브에이전트로 테스트 커버리지를 검사하고,
1개의 서브에이전트로 코드 품질과 유지보수성을 검사해 주세요.

각 서브에이전트는 명확한 문제점만 출력하고, 상세한 프로세스는 출력하지 마세요.
3개의 서브에이전트가 모두 완료된 후 다음을 통합해 주세요:
- 고위험 문제
- 중위험 문제
- 최적화 제안
- 우선 수정 권장사항

이 템플릿의 핵심 포인트는 다음과 같다:

각 서브에이전트의 역할을 명확히 분리하여 중복 방지
"모든 서브에이전트 완료 후 통합"을 명시하여 중간 결과로 판단하는 것 방지
출력 형식을 지정하여 리스크 수준별로 정리된 리스트 제공
"우선 수정 권장사항"을 요청함으로써 문제점의 우선순위 지정까지 위임 가능

ShipReady 사례 연구

실제 프로젝트 "ShipReady"(SaaS 랜딩 페이지 감사 MVP)에서의 서브에이전트 활용 사례를 소개한다. 프로젝트 규모는 작으며, 주요 파일은 다음과 같다:

백엔드 API: src/app.js
감사 규칙 및 리라이트: src/audit.js
스토리지: src/store.js
프론트엔드: public/app.js

처음에는 서브에이전트에 코드 변경을 지시하기 쉽지만, 프로젝트가 작을수록 에이 간 파일 충돌이 발생하기 쉽다. 더 안정적인 방법은 먼저 모든 서브에이전트를 읽기 전용(read-only) 모드로 실행하는 것이다.

이 프로젝트에서 서브에이전트 사용을 시도해 주세요.
3개의 읽기 전용 서브에이전트를 실행:
1. runtime-risk-agent: 잠재적 버그, 비동기 오류, API 상태 흐름, 프로덕션 환경 리스크 검사
2. qa-coverage-agent: 테스트 누락, 부족한 유스케이스, 회귀 리스크 검사
3. architecture-agent: 모듈 경계, 중복 로직, 하위 호환성 검사

모든 서브에이전트에서 파일 변경은 금지.
모든 완료 후 메인 스레드에서 결론을 통합하고, 수정 필요 여부를 판단.

이 분할 방법의 장점은 다음과 같다:

3개의 관점이 서로 독립적이어서 대기 시간이 발생하지 않음
모두 읽기 전용이므로 파일 충돌이 발생하지 않음
메인 스레드는 결과를 기다리는 동안에도 프로젝트 구조 분석이나 자체 판단이 가능

실행부터 3개의 결론을 얻기까지의 체감 시간은 수 분 수준이다. 프로젝트 자체가 작기 때문에 절약되는 것은 "파일 읽기의 절대 시간"이 아니라, 메인 스레드가 3가지 종류의 문제(런타임 장애, 테스트 부족, 모듈 분할 필요성)를 동시에 기억할 필요가 없어지는 부하 경감이다. 이 부하 경감은 수 분짜리 태스크에서는 크게 체감되지 않지만, 태스크 규모가 커질수록 뚜렷해진다.

3개 서브에이전트의 결론 중 runtime-risk-agent가 가장 높은 가치를 보여줬다. handleRequest 내 비동기 라우트에서 await가 누락된 점, 바깥쪽 try/catch가 비동기 핸들러의 예외를 잡지 못하는 점을 발견했다. 이 종류의 버그는 해피 패스(happy path) 테스트에서는 감지되지 않으며, 발생하면 요청이 hang되거나 처리되지 않은 예외가 된다. 또한 /api/rewrite에서는 brief의 존재 여부만 판단하고 품질 체크가 누락된 것도 지적했다. 이 발견들은 이후 변경 목록에 직접 반영됐다.

qa-coverage-agent가 열거한 미비점도 실용적이었다: 잘못된 JSON, 공유되지 않은 상태의 share, 너무 빠른 팔로업, 약한 brief로 인한 rewrite 회피 등 주로 해피 패스 이외의 API 네거티브 패스(negative path)다. 이 모든 것을 즉시 수정할 필요는 없지만, 문제점이 한눈에 파악된다.

architecture-agent는 가장 판단이 어려운 결과였다. src/app.js의 책임이 너무 많다는 점, src/audit.js를 page-extract/checks/brief/rewrite의 4개로 분할해야 한다는 점, 프론트엔드와 백엔드에서 audit label과 brief ready의 판단을 중복 관리하고 있다는 점을 지적했다. 판단은 맞지만, 당시 태스크(테스트 작성 + 버그 수정)에는 규모가 너무컸다. 이 단계에서 코어 파일을 변경하면 리스크가 확산되므로, 이 제안은 전혀 채택하지 않고 다음 과제로 기록했다.

3개 서브에이전트 간 직접적인 모순은 없었지만, 우선순위가 달랐다: runtime-risk는 서버사이드 수정, qa-coverage는 테스트 추가, architecture는 경계 정리를 우선시했다. 메인 스레드의 역할은 3표를 평균내는 것이 아니라, 확실성이 높고 변경 범위가 작으며 테스트로 고정할 수 있는 문제를 우선 처리하는 것이다.

최종적으로 수행한 수정 사항은 다음과 같다:

비동기 라우트 분기에 await를 통일하고, 바깥쪽 에러 핸들링을 활성화
/api/rewrite에서 briefReady(record.brief) 체크를 필수화
/api/brief/follow-up에 "brief 미제출"과 "잘못된 필드" 2종류의 유효성 검사 추가
readJson에 body 크기 제한을 추가하고, 잘못된 JSON에는 400 에러 반환
node:test 기반 회귀 테스트를 추가하여 상태 흐름을 고정

검증 실행:

npm run check
npm test

가장 흥미로운 순간은 runtime-risk-agent가 비동기 핸들러 버그를 보고하는 동시에, qa-coverage-agent가 API 네거티브 패스 테스트 추가를 제안한 것이다. 두 결론을 결합하여 완전한 수정 방안이 도출됐다. 한쪽이 문제점을 지적하면 다른 쪽이 재발 방지책을 제시하는 형태다. 메인 스레드는 프로젝트 전체를 다시 리뷰할 필요 없이, 이 문제를 지금 수정할 가치가 있는지를 판단하고 코드 변경·테스트 추가·검증을 실행하기만 하면 됐다.

이것이 서브에이전트의 본질적 역할이다. 메인 스레드의 대신 판단하는 것이 아니라, 여러 관점의 결론을 동시에 제시하여 메인 스레드의 의사결정을 가속화하는 것이다.

실행 후 관리 방법

Codex CLI에서는 /agent 명령어로 에이전트 스레드의 표시·전환이 가능하다. 명령어뿐 아니라 자연어로 특정 서브에이전트의 중지나 완료된 스레드의 정리를 지시할 수도 있다.

초보자가 기억해야 할 기본 명령어는 다음과 같다:

/agent

에이전트 스레드 표시 및 전환.

성능 분석 담당 서브에이전트를 중지해 주세요.

특정 서브태스크가 이탈했거나 불필요해졌을 때 직접 중지.

완료된 에이전트 스레드를 정리해 주세요.

완료된 스레드는 불필요하므로 수시로 정리.

초보자용 연습 순서

처음부터 5개의 에이전트로 프로젝트 전체를 변경하는 것은 권장하지 않는다. 리스크가 낮은 단계부터 연습을 시작해야 한다:

병렬 읽기: 여러 서브에이전트에 다른 모듈의 이해를 담당시키고, 최종 통합은 직접 수행
병렬 리뷰: 버그/보안/테스트/유지보수성을 분리하여 검사
단일 변경 + 다중 리뷰: 메인 에이전트 또는 1개의 워커가 코드를 변경하고, 다른 서브에이전트가 리뷰
소규모 병렬 변경: 모듈 경계가 명확해지면, 여러 워커에 다른 모듈을 동시에 변경시키기

다음으로 Codex에서 PR 리뷰를 수행할 때는 아래 템플릿을 시도해 보길 바란다:

3개의 서브에이전트로 현재 PR을 병렬 검사해 주세요:
1개는 버그를, 1개는 테스트를, 1개는 유지보수성을 확인.
모든 완료 후 리스크 수준별로 통합하여 보고해 주세요.

이 튜토리얼을 읽었다면, 실제 프로젝트에서 직접 체험해 보는 것을 추천한다.

공유:X Hatena

로딩 중...

블로그 목록으로