서브 Agent: 언제 나눠야 하고, 언제 나누면 안 되는가

Claude Code에는 Agent 도구가 있어서, 대화 도중 독립적인 서브 Agent를 띄워 작업을 맡길 수 있다. 서브 Agent는 자체 컨텍스트를 가지고 작업을 수행한 뒤, 결과를 메인 Agent에게 돌려준다.

강력해 보이지만, 실제로 사용해 보면 대부분의 경우 필요 없다. 이 글에서는 서브 Agent를 나누는 게 정말 효과적인 경우와, 오히려 방해가 되는 경우를 정리한다.

서브 Agent의 동작 방식

CLAUDE.md나 슬래시 커맨드에서 Agent 도구를 직접 호출할 수는 없다. Claude Code가 내부적으로 사용 여부를 판단하는 도구이기 때문이다. 다만 프롬프트를 통해 그 판단에 영향을 줄 수는 있다.

작동 흐름:

메인 Agent가 서브 Agent를 시작하고 프롬프트를 전달한다
서브 Agent는 독립된 컨텍스트에서 실행되며, 대부분의 도구(파일 읽기, 검색, 명령 실행 등)를 사용할 수 있다
서브 Agent가 완료되면 결과를 하나의 메시지로 메인 Agent에 반환한다
메인 Agent는 그 결과를 받아서 작업을 이어간다

핵심 특성:

독립된 컨텍스트: 서브 Agent는 메인 대화 이력을 볼 수 없고, 시작 시 전달받은 프롬프트만 볼 수 있다
결과 압축: 서브 Agent가 내부에서 아무리 많은 파일을 읽고 명령을 실행해도, 메인 Agent에 돌아오는 건 요약뿐이다
병렬 실행: 여러 서브 Agent를 동시에 띄워서 병렬로 실행할 수 있다

서브 Agent를 써야 하는 세 가지 상황

1. 병렬 검색과 조사

가장 대표적인 활용 사례다. Claude Code에 어떤 문제를 조사하게 하는데, 여러 방향을 동시에 살펴봐야 하는 상황이다.

예를 들어 "이 프로젝트의 인증 구조가 어떻게 구현되어 있어?"라고 물었다고 하자.

서브 Agent 없이는 Claude Code가 순차적으로 처리한다: auth controller 읽기 → middleware 읽기 → routes 읽기 → model 읽기 → config 읽기... 하나씩 하나씩, 느리다.

서브 Agent를 사용하면:

3개의 서브 Agent를 동시에 시작:
- Agent 1: controller와 middleware 계층의 인증 로직 조사
- Agent 2: model 계층의 사용자 및 세션 설계 조사
- Agent 3: 설정 파일과 환경 변수의 인증 관련 설정 조사

세 방향을 동시에 조사하고 결과를 통합한다. CLAUDE.md에서 이렇게 유도할 수 있다:

## 조사 유형 작업
여러 모듈에 걸친 문제를 조사할 때는 여러 서브 Agent를 병렬로 띄워
각각 다른 영역을 조사하게 하고, 마지막에 결론을 통합할 것.

2. 메인 컨텍스트 보호

Claude Code의 컨텍스트 윈도우는 한정되어 있다. 어떤 하위 작업이 파일을 대량으로 읽어야 하지만 최종적으로 필요한 건 결론뿐이라면, 서브 Agent를 사용해서 "과정의 쓰레기"를 메인 컨텍스트 밖으로 밀어낼 수 있다.

대표적인 예시:

50개 파일에서 특정 API의 모든 호출 위치를 찾아 패턴을 분석하기
대형 설정 파일을 분석하되, 필요한 건 핵심 값 몇 개뿐인 경우
테스트 파일 묶음을 검토해서 커버리지가 충분한지 판단하기

이런 작업의 공통점은 입력은 크고, 출력은 작다는 것이다. 서브 Agent가 내부에서 대량의 정보를 소화하고, 핵심만 돌려준다.

3. 위험한 작업의 격리

결과가 어떻게 될지 확신할 수 없는 작업도 있다. 서브 Agent에 isolation: "worktree" 파라미터를 붙여 사용하면, 독립된 git worktree에서 작업이 이루어진다. 망가져도 현재 작업 디렉토리에는 영향이 없다.

## 고위험 리팩터링
대규모 리팩터링에는 worktree 격리가 적용된 서브 Agent를 사용할 것.
결과가 올바른지 확인한 후에만 병합할 것.

적합한 상황:

탐색적 리팩터링: 어떤 접근 방식이 통하는지 확실하지 않을 때, 서브 Agent에 먼저 시도시키기
병렬 방식 비교: 두 가지 방식을 동시에 구현해서 결과 비교
코드 생성: 대량의 보일러플레이트를 생성하고, 리뷰 후 머지

서브 Agent를 쓰면 안 되는 경우

단순하고 직접적인 작업

"이 함수 이름을 camelCase에서 snake_case로 바꿔줘" — 이런 건 그냥 바로 하면 된다. 서브 Agent를 띄우는 오버헤드(컨텍스트 구성, 반환 대기, 결과 파싱)가 직접 하는 것보다 오히려 느리다.

판단 기준: Grep 한 번 + Edit 한 번이면 해결되는 일이라면, Agent로 나누지 말 것.

강한 의존성이 있는 순차 작업

"설정을 읽고 → 설정에 맞게 코드 수정 → 수정에 맞게 테스트 업데이트"

이런 체인 형태의 작업은 각 단계가 이전 단계의 결과에 의존한다. 서브 Agent로 나누면 중간 결과를 프롬프트로 주고받아야 하는데, 번거롭고 정보가 누락되기 쉽다. 그냥 순차적으로 실행하면 된다.

정밀한 제어가 필요한 수정

서브 Agent가 반환하는 건 요약 텍스트이지, 구조화된 데이터가 아니다. 서브 Agent에게 정밀한 수정을 시키고 싶다면(예: 47번째 줄에 특정 코드 삽입), 메인 Agent가 직접 하는 편이 더 확실하다.

서브 Agent는 "조사해서 결론을 돌려주는" 데 적합하다. "정확한 수정을 실행하는" 데는 적합하지 않다.

컨텍스트에 아직 여유가 있을 때

대화가 막 시작되어서 컨텍스트 윈도우가 텅 비어 있다면, "컨텍스트 보호"를 위해 Agent를 나눌 이유가 없다. 대화가 길어지고 메인 Agent가 이력 메시지를 압축하기 시작할 때, 그때 무거운 작업을 서브 Agent에 맡기는 걸 고려하면 된다.

실제 효과 비교

구체적인 예시를 보자: Rails 프로젝트에서 before_action을 사용하는 모든 controller를 조사하고, 인증 및 인가 구현 패턴을 분석하는 작업이다.

서브 Agent 미사용:

Claude Code가 controller 파일을 하나씩 읽으며, 읽을 때마다 메인 컨텍스트를 소비한다. controller가 20개라면, 파일 내용만으로도 상당한 양의 토큰을 소모할 수 있다. 최종 분석 결과를 낼 때쯤이면, 앞서 읽은 세부 내용이 컨텍스트 압축으로 유실되었을 수 있다.

서브 Agent 사용:

서브 Agent 시작: "app/controllers/ 아래의 모든 controller를 읽고,
모든 before_action 콜백을 찾아서, 인증과 인가 패턴을 분석하고,
분류별 요약을 반환해라."

서브 Agent가 자체 컨텍스트에서 모든 파일을 읽고, 정리된 요약을 반환한다. 메인 Agent의 컨텍스트는 거의 소비되지 않고, 결론을 받아서 바로 다음 단계로 나아갈 수 있다.

CLAUDE.md에서 서브 Agent 사용을 유도하기

Claude Code에게 서브 Agent 사용 여부를 강제할 수는 없지만, CLAUDE.md를 통해 선호를 전달할 수 있다:

## Agent 사용 방침

### 서브 Agent에 적합한 작업
- 모듈 간 조사 (3개 이상의 디렉토리를 동시에 탐색)
- 대규모 코드 검색 및 통계
- 탐색적 리팩터링 (worktree 격리 적용)

### 서브 Agent를 사용하지 않을 작업
- 단일 파일 수정
- 순서 의존성이 있는 다단계 작업
- 수정 위치가 이미 명확한 버그 수정

한 줄 판단법

이 작업의 "과정"이 "결론"보다 훨씬 큰가?

그렇다면 — 서브 Agent를 쓴다. 과정을 소화시키고, 결론만 받는다.
아니라면 — 직접 한다. 중간 계층을 끼우지 않는다.

서브 Agent는 많을수록 좋은 게 아니다. 동시성 프레임워크가 아니라 컨텍스트 관리 도구다. 잘 쓰면 대규모 프로젝트에서도 Claude Code의 판단력을 유지할 수 있고, 잘못 쓰면 시작 시간만 낭비할 뿐이다.