서브에이전트

서브에이전트는 한 런타임 안에서 별도의 컨텍스트와 역할을 가진 보조 작업자다. 큰 요청을 나누거나 메인 작업에 불필요한 탐색 결과를 분리할 때 쓸 수 있다.

분리할수록 좋은 작업

메인 작업과 결과를 나눌 수 있는 읽기 중심 작업부터 맡긴다. 예를 들어 수정 전에 관련 파일을 찾거나, 로그에서 공통 오류를 추리거나, 테스트 결과만 읽고 실패 원인을 정리하게 할 수 있다.

메인 에이전트
  ├─ 기능 구현과 파일 수정
  ├─ 서브에이전트: 관련 API 사용처 조사 (읽기 전용)
  └─ 서브에이전트: 실패 로그에서 원인 후보 정리 (읽기 전용)

요청은 산출물과 범위를 짧게 정한다. "프로젝트를 조사해라"보다 파일·질문·출력 형식을 지정한다.

이 저장소에서 날짜 파싱 함수를 호출하는 위치를 찾아라.
파일은 수정하지 말고, 파일 경로·호출 목적·관련 테스트를 표로 정리해라.
확실하지 않은 부분은 추측하지 말고 표시해라.

별도 컨텍스트를 쓰면 검색 결과와 긴 로그를 메인 대화에 전부 옮기지 않고 요약만 받을 수 있다. 에이전트마다 역할 지침을 달리해 조사, 구현, 검증의 관점을 구별하는 것도 가능하다.

중복과 충돌을 줄이기

서브에이전트가 늘면 각자 같은 파일을 살피거나 같은 검사를 반복할 수 있다. 호출과 조정 자체에도 토큰이 들고, 작업 결과를 합치는 데 시간이 든다. 각 작업에 입력·출력과 파일 범위를 정하고, 독립된 산출물이 있는 경우에만 나눈다.

여러 작업자가 동시에 같은 파일을 수정하면 덮어쓰기나 충돌이 생긴다. 안전한 기본 흐름은 메인 에이전트가 파일을 수정하고, 서브에이전트는 별도 파일이나 읽기 전용 검토를 맡는 방식이다.

좋은 분리
  Worker A: 현재 동작과 호출 지점 조사 (읽기만)
  Worker B: 실패 로그와 테스트 결과 분석 (읽기만)
  Main: 조사 결과를 받아 한 번에 코드 수정

위험한 분리
  Worker A와 B가 같은 설정 파일을 동시에 편집

수정 작업을 병렬화해야 한다면 파일 경계를 서로 겹치지 않게 두고, 메인 작업자가 통합과 최종 검증을 맡는다. 어떤 파일을 누가 소유하는지 요청에 적고, 완료 전에 각 변경을 확인한다.

맡길지 판단하기

작업이 짧고 순서가 정해져 있거나 결과를 합치는 비용이 크면 한 에이전트가 처리하는 편이 단순하다. 독립 조사, 큰 로그 분석처럼 메인 컨텍스트를 많이 차지하는 일은 분리할 가치가 있다.

상황	선택
같은 기능을 여러 파일에서 함께 바꿔야 함	메인 작업자가 순서대로 수정
서로 독립된 API·문서 조사	읽기 전용 서브에이전트로 병렬 조사
구현 결과의 별도 점검	검증 기준을 좁힌 검토 역할 부여
결과를 합치기 어렵거나 중복 위험이 큼	분리하지 않고 한 흐름에서 처리

동시에 실행하는 수에는 상한을 둔다. 작업자 수가 늘면 결과가 비례해 빨라지는 것이 아니라 중복 확인과 통합이 늘 수 있다. 작은 작업 하나를 먼저 맡겨 응답의 깊이와 정확성을 살핀 다음 범위를 넓힌다.

서브에이전트의 결과를 받을 때는 결론뿐 아니라 근거가 있는 경로와 확인한 명령을 요청한다. 검토 역할이라면 수정 대신 발견 사항을 보고하게 해, 검토 과정이 원래 변경과 뒤섞이지 않도록 한다.

검증 역할을 맡아라.
지정한 파일과 요구사항만 읽고, 파일은 수정하지 마라.
문제가 있으면 위치, 재현 조건, 영향, 근거를 보고해라.
문제를 찾지 못했으면 실행한 확인 항목을 적어라.

메인 작업자는 이 보고를 그대로 받아들이지 말고, 중요한 항목을 직접 확인한다. 조사 범위가 좁을수록 결과를 재검토하고 실제 변경에 반영하기 쉽다.

여러 읽기 작업이 서로 의존하지 않는지 살핀다. 첫 조사 결과를 알아야 다음 조사의 질문을 정할 수 있다면 순차 실행이 낫다. 독립된 파일 목록 조사와 테스트 로그 요약처럼 결과가 서로 영향을 주지 않는 일은 병렬로 맡길 수 있다.

병렬 실행이 끝나면 중복된 결과를 합치고 서로 다른 결론을 확인한다. 같은 오류를 여러 작업자가 보고했다면 한 항목으로 통합하고, 상충하는 보고는 재현이나 추가 검색으로 판별한다.

메인 작업자는 분배한 일과 남은 일을 기억할 수 있게 간단한 작업 목록을 둔다. 요청한 결과가 돌아왔는지, 후속 질문이 필요한지, 실제 변경에 반영했는지를 기록한다.

결과가 계획한 범위보다 넓거나 요청한 파일을 수정했다면 그 사실을 먼저 확인한다. 조사 역할에 파일 수정을 허용하지 않았다면 변경 내용을 검토하고 원래 작업과 섞이지 않도록 정리한다.

작업을 나눌 때는 기다리는 시간도 고려한다. 금방 끝날 작업을 맡기고 결과를 통합하느라 더 오래 걸린다면 분리의 이점이 없다. 반복되는 긴 조사나 독립적으로 끝낼 수 있는 작업부터 분리 효과를 살핀다.

서브에이전트에게 작업의 완료를 맡기더라도 최종 책임은 메인 작업자에게 있다. 통합 전에는 요구사항과 파일 변경을 확인하고, 관련 테스트를 다시 실행한다.

작업 지침의 파일 범위와 출력 형식을 먼저 확인하면, 여러 결과를 비교해도 같은 기준으로 검토할 수 있다.

완료 뒤에는 역할을 종료하고 결과를 통합해, 사용하지 않는 작업이 컨텍스트와 사용량을 계속 쓰지 않게 한다.

분담한 이유가 사라지면 남은 일을 메인 작업으로 되돌려 전체 흐름을 단순하게 유지한다.

런타임 단위로 나누는 방법

서브에이전트는 한 런타임 안의 컨텍스트·역할 분리에 유용하다. 반면 서로 다른 런타임을 조합하면 모델, 도구, 사용량을 역할별로 배치할 수 있다. 직접 사용하면서는 herdr 같은 런타임 오케스트레이션이 등장한 뒤 서브에이전트를 덜 쓰게 됐지만, 이를 보편적인 기술 추세로 단정할 수는 없다. 단일 런타임 아래에서 룰과 컨텍스트를 나누는 장점은 남아 있다.

보충: 런타임별 권장과 비용

Claude Code 서브에이전트는 별도 컨텍스트와 요약 반환을 이용해 검색·로그·파일 읽기 같은 곁가지 일을 분리하는 방법을 설명한다. 에이전트 설명도 컨텍스트를 차지한다. Anthropic의 멀티에이전트 리서치 시스템은 해당 실험에서 챗 방식보다 약 15배 토큰을 썼다고 보고했지만, 이는 Claude Code 서브에이전트의 일반적인 비용 배수가 아니다.

Codex 서브에이전트는 탐색, 테스트, 로그 분석처럼 나눠 실행할 수 있는 작업을 들며 읽기 중심 병렬을 권한다. 동시 편집은 충돌과 조정 비용을 만들 수 있다. agents.max_concurrent_threads_per_session 설정으로 주 스레드 외에 생성할 수 있는 스레드 수를 제한한다.

두 런타임 모두 컨텍스트 분리와 읽기 중심 병렬의 이점을 다루며, 병렬 실행은 추가 토큰을 쓴다. 기준일: 2026-09-30.