Codex의 Subagent 활용

무엇인가, 왜 등장했는가

Subagent는 메인 에이전트가 혼자 모든 일을 처리하는 대신, 일부 작업을 떼어 별도의 작은 에이전트에게 맡기는 방식이다. 쉽게 말해 한 명의 총괄이 여러 명의 전문 담당자에게 일을 나눠 주는 구조에 가깝다.¹

이 방식이 나온 이유는 단순하다. 코드 작업은 한 번에 한 가지 문제만 푸는 일이 아니라, 분석·수정·검증·문서화처럼 성격이 다른 일을 동시에 다뤄야 하는 경우가 많기 때문이다. 컨텍스트 창이 커졌다고 해도 하나의 에이전트가 모든 세부사항을 끝까지 붙들고 있으면 집중력이 분산되고, 작업 흐름도 길어진다. Subagent는 이런 부담을 나눠서 각 작업을 더 또렷하게 처리하려는 시도라고 볼 수 있다.²

Codex 환경에서 맡는 역할

Codex에서 subagent는 병렬 작업을 위한 실행 단위로 이해하면 된다. 메인 에이전트는 전체 목표를 보고 계획을 세우고, subagent는 그 계획 안에서 특정 조사나 분석, 구현, 검토 같은 하위 업무를 맡는다.³

예를 들어 하나의 PR을 검토할 때 메인 에이전트가 "보안", "버그 가능성", "테스트 취약성", "코드 품질" 같은 항목으로 업무를 나눈 뒤, 각 항목을 subagent에 맡길 수 있다. 그러면 Codex는 여러 에이전트의 결과를 기다렸다가 다시 합쳐서 하나의 응답으로 정리한다.³

중요한 점은 Codex가 subagent를 자동으로 마구 늘리는 것이 아니라, 사용자가 명시적으로 요청할 때 새 에이전트를 띄운다는 점이다. 즉 subagent는 숨겨진 마법이라기보다, 필요할 때 꺼내 쓰는 구조화된 협업 도구에 가깝다.⁴

메인 에이전트와 무엇이 다른가

메인 에이전트는 목표를 해석하고, 작업을 쪼개고, 각 결과를 다시 모아 최종 판단을 내리는 조정자다. 반면 subagent는 주어진 범위 안에서 상대적으로 좁고 선명한 문제를 처리하는 실무 담당자에 가깝다.¹

이 차이는 역할뿐 아니라 시야의 범위에서도 드러난다. 메인 에이전트는 전체 맥락과 우선순위를 본다. subagent는 그중 일부만 깊게 본다. 그래서 메인 에이전트가 방향을 잘못 잡으면 subagent도 효율적으로 틀릴 수 있고, 반대로 메인 에이전트가 작업을 잘게 잘 정의해 주면 subagent는 꽤 높은 집중력으로 결과를 낼 수 있다.¹

장점과 한계

Subagent의 가장 큰 장점은 분업이다. 서로 다른 관점의 작업을 병렬로 진행할 수 있고, 하나의 에이전트가 긴 맥락을 억지로 다 끌고 가는 부담도 줄어든다. 특히 큰 코드베이스나 여러 검토 항목이 얽힌 상황에서 이 방식은 작업을 더 명료하게 만든다.²

또 다른 장점은 전문화다. 테스트만 보는 에이전트, 문서만 보는 에이전트, 특정 모듈만 파는 에이전트처럼 역할을 나누면 결과가 덜 섞이고, 후속 검토도 쉬워진다. AGENTS.md 같은 지침 파일을 함께 쓰면 저장소 규칙이나 팀 관례를 각 작업에 더 안정적으로 반영할 수도 있다.⁵

하지만 한계도 분명하다. subagent는 각자 모델 호출과 도구 사용을 수행하므로, 단일 에이전트보다 토큰과 실행 비용이 더 든다.⁴ 또한 하위 작업을 잘못 나누면 결과가 중복되거나 빠지고, 메인 에이전트가 마지막에 통합하는 부담도 커진다.

결국 subagent는 "항상 더 좋은 방식"이라기보다, 복잡한 일을 구조적으로 처리할 때 힘을 발휘하는 방식이다. 단순한 수정 하나를 위해 여러 에이전트를 띄우는 것은 오히려 과할 수 있다.²

어떻게 활용할 수 있는가

코드 분석에서는 파일 구조를 훑는 작업, 특정 함수의 호출 흐름 추적, 성능 병목 탐색 같은 일을 각각 subagent에 맡길 수 있다. 이렇게 하면 메인 에이전트는 "시스템 전체를 설명하라"는 막연한 요청보다, 여러 분석 결과를 비교하며 더 납득 가능한 요약을 만들기 쉽다.⁶

테스트 작업에서도 유용하다. 한 subagent는 실패한 테스트 원인을 찾고, 다른 subagent는 회귀 가능성을 점검하고, 또 다른 subagent는 새 테스트 케이스를 제안하도록 나눌 수 있다. 이 구조는 수정과 검증을 분리해 생각하게 해 준다는 점에서 실무적으로 의미가 크다.⁷

문서화에서는 코드 변경 사항을 정리하는 역할과 사용법 예제를 만드는 역할을 분리할 수 있다. 구현을 잘하는 것과 설명을 잘하는 것은 다른 능력인데, subagent는 이 차이를 반영하기 좋다.⁵

리서치에도 맞는다. 예를 들어 외부 라이브러리 교체를 검토할 때, 한 subagent는 현재 의존성 사용처를 찾고, 다른 subagent는 마이그레이션 영향 범위를 정리하고, 또 다른 subagent는 위험 요소를 요약하게 할 수 있다. 이렇게 모은 결과는 메인 에이전트가 최종 의사결정용 메모로 재구성하기 좋다.⁸

실제로 사용할 때 주의할 점

Subagent를 잘 쓰려면 먼저 일을 "병렬화할 수 있는 단위"로 나눠야 한다. 서로 강하게 얽힌 작업을 무리하게 분리하면, 각 에이전트가 비슷한 파일을 다시 읽고 같은 판단을 반복하면서 효율이 떨어진다.²

지시문은 더 구체적일수록 좋다. "한번 리뷰해 줘"보다 "보안 이슈, 경쟁 상태, 테스트 누락을 각각 따로 점검하라"처럼 범위를 잘라 주는 편이 낫다. Subagent는 자율성이 있지만, 그 자율성이 효과를 내는 전제는 메인 에이전트의 작업 설계가 분명하다는 데 있다.³

프로젝트 규칙도 미리 정리해 두는 편이 좋다. Codex는 AGENTS.md를 읽고 작업에 반영하므로, 테스트 실행 규칙이나 문서 작성 기준, 디렉터리별 예외 사항을 적어 두면 subagent가 제각각 다른 방식으로 움직일 가능성을 줄일 수 있다.⁵

마지막으로, subagent의 결과는 초안이 아니라 근거 있는 작업 메모로 받아들이는 태도가 필요하다. 결과를 합치는 최종 판단은 여전히 메인 에이전트와 사용자 몫이다. 특히 코드 수정, 테스트 통과, PR 제안처럼 실제 변경으로 이어지는 작업이라면, 병렬 실행의 편리함보다 검토 가능성과 책임 경계를 더 중요하게 봐야 한다.⁷

정리

Codex의 subagent는 더 똑똑한 한 명을 만드는 기능이라기보다, 여러 작업을 나눠 맡길 수 있는 협업 구조에 가깝다. 메인 에이전트가 방향을 잡고 subagent가 세부 문제를 파고들며, Codex는 그 흐름을 조정하고 결과를 다시 묶는다.¹

그래서 subagent를 이해하는 핵심은 기능 목록을 외우는 데 있지 않다. 어떤 일을 하나로 처리해야 하고, 어떤 일은 나눠야 더 잘 풀리는지 판단하는 데 있다. 그 판단이 맞으면 Codex는 단순한 코드 생성기를 넘어, 실제 소프트웨어 작업을 분업하는 실행 환경으로 보이기 시작한다.²

참고

¹Subagents - Codex | OpenAI Developers

²Subagents - Codex | OpenAI Developers

³Subagents - Codex | OpenAI Developers

⁴Subagents - Codex | OpenAI Developers

⁵Custom instructions with AGENTS.md - Codex | OpenAI Developers

⁶Codex | OpenAI Developers

⁷Introducing Codex | OpenAI

⁸Use Codex with the Agents SDK | OpenAI Developers