코덱스 서브에이전트 제대로 쓰는 법: 병렬 작업이 오히려 느려지는 이유

에이전트를 셋 띄우면 무조건 세 배 빨라질 것 같지만 실제 병목은 분할과 통합이다. 세 작업이 서로의 결과를 기다리거나 같은 코드를 수정하면 병렬 시간이 짧아도 충돌 해결이 길어진다.

OpenAI 공식 문서는 첫 사용 기준으로 코드 탐색, 테스트, 트리아지, 로그 분석, 요약 같은 읽기 중심 작업을 추천하고 동시 코드 수정에는 더 신중하라고 안내한다. 핵심은 에이전트 수가 아니라 독립성이다.

서브에이전트가 해결하는 것은 컨텍스트 오염이다

대규모 저장소 탐색, 긴 테스트 로그, 여러 문서 비교 결과를 모두 메인 스레드에 넣으면 요구사항과 결정이 중간 출력에 묻힌다. 공식 문서는 이를 context pollution과 context rot 관점에서 설명한다.

서브에이전트는 noisy work를 별도 스레드에서 수행하고 요약만 반환한다. 메인 에이전트는 사용자 요구, 경계, 최종 통합과 결정을 유지한다.

병렬화하기 좋은 일과 나쁜 일

작업 A가 작업 B의 결과를 몰라도 끝낼 수 있고, 서로 다른 파일이나 읽기 전용 표면을 다루며, 결과 형식이 정해져 있다면 좋은 후보다.

동일 컴포넌트 수정, 순차 마이그레이션, 하나의 설계 결정을 계속 공유해야 하는 일은 메인 에이전트가 직렬로 처리하거나 먼저 설계를 확정한 뒤 나누는 편이 낫다.

• 좋음: 모듈별 탐색, 독립 테스트, 문서군 요약, 여러 가설 검증
• 주의: 같은 파일 수정, 공통 스키마 변경, 선행 결과가 필요한 작업, 작은 단일 수정

좋은 위임은 작고 경계가 닫혀 있다

“이 프로젝트를 분석해”는 메인 작업과 중복된다. 각 서브에이전트에게 질문, 읽을 범위, 수정 권한, 반환 형식을 준다. 쓰기 작업이면 서로 다른 소유 파일을 지정한다.

메인 에이전트가 무엇을 결정할지 남겨두는 것도 중요하다. 서브에이전트는 근거와 선택지를 반환하고, 최종 제품 판단과 충돌 조정은 메인이 맡는다.

에이전트 A: 인증 관련 파일과 테스트만 읽고 로그인 실패 경로를 표로 정리. 수정 금지.
에이전트 B: 실패한 통합 테스트를 재현하고 최소 재현 명령과 로그 핵심 10줄 반환. 수정 금지.
에이전트 C: 공식 라이브러리 문서에서 현재 버전의 세션 만료 동작만 확인.
메인: 세 결과를 비교해 하나의 원인을 선택하고 구현·검증한다.

속도와 토큰 비용은 별개다

각 서브에이전트는 자체 모델 호출과 도구 사용을 하므로 같은 일을 한 에이전트가 처리할 때보다 총 토큰이 늘 수 있다. 병렬화의 이익은 벽시계 시간과 컨텍스트 격리다.

세부 작업이 너무 작으면 시작·요약·통합 오버헤드가 실제 작업보다 커진다. 5분짜리 수정 하나를 세 조각으로 나누지 말고, 수십 분의 독립 탐색 세 개처럼 의미 있는 덩어리를 나눈다.

병렬 쓰기가 필요하면 소유권을 먼저 나눠라

동시 수정이 불가피하면 에이전트별 파일·패키지 소유권을 겹치지 않게 한다. 공용 타입이나 루트 설정은 메인 에이전트가 나중에 통합한다.

서브에이전트가 만든 변경을 그대로 신뢰하지 말고 diff, 테스트, 인터페이스 호환성을 메인이 확인한다. 병렬화는 검증 책임을 없애지 않는다.

30초 결정 규칙

“두 결과가 서로 기다려야 하는가?”가 예라면 순차 처리한다. “같은 파일을 고치는가?”가 예라면 소유권을 다시 나눈다. “요약 형식을 한 문장으로 정의할 수 있는가?”가 아니면 위임 범위를 좁힌다.

독립성이 높은 읽기 중심 작업부터 시작하고, 실제로 병목이 줄었을 때만 쓰기 병렬화를 늘리는 편이 안전하다.

자주 묻는 질문