Claude Subagent 초보자 가이드: 컨텍스트 관리와 병렬 실행의 핵심

Claude Code에게 버그 수정을 요청하면, 그는 의욕 넘치게 코드 읽기를 시작한다 —— src/auth 를 샅샅이 훑고, src/api 를 전부 읽고, src/db 도 훑는다. 테스트 파일조차 놓치지 않는다. 그런데 막상 수정에 착수하려고 보면, 컨텍스트 윈도우(이하 컨텍스트)는 이미 가득 차 있다. 그리고 "망각"이 시작된다 —— 아까 읽었던 중요한 로직이 또렷하게 떠오르지 않고, 수정한 코드의 앞뒤 정합성이 맞지 않게 된다.

이런 상황이 몇 번 반복된 뒤, 한 가지를 깨달았다: 모든 태스크를 메인 대화(main dialog)가 직접 처리해서는 안 된다.

Subagent는 바로 이런 문제를 해결하기 위해 존재한다.

Subagent란 무엇인가

가장 간단한 이해: Subagent는 구체적인 태스크 수행을 위해 파견된 담당자로, 독립된 컨텍스트 윈도우 내에서 동작한다.

비유로 설명하겠다. 메인 대화는 프로젝트 매니저로, 전체를 관리하고 의사결정을 내린다. Subagent는 실제 작업을 담당하는 엔지니어다 —— 독립적으로 작업한 뒤 최종 결론만 보고한다. Subagent가 읽은 50개 파일, 실행한 수천 줄의 로그는 모두 Subagent 자체의 기억에 남고, 메인 대화의 컨텍스트를 오염시키지 않는다.

이 설계에는 양방향 이점이 있다.

첫째, 메인 대화의 컨텍스트가 노이즈로 채워지지 않는다. Subagent가 직접 50개 파일을 처리하고, 메인 대화에는 "이 모듈은 JWT 인증을 사용하며, 검증 로직은 middleware/auth.ts 에 있다"는 한 줄만 전달된다.

둘째, 병렬 실행이 가능해진다. 3개의 Subagent를 동시에 파견해 인증, 데이터베이스, API를 각각 조사시키면, 3개 작업이 병렬로 진행되며 서로 간섭하지 않는다.

기본 탑재 3종

특별한 설정은 필요 없다. Claude Code에는 처음부터 다음과 같은 3개의 Subagent가 내장되어 있다.

** Explore ** —— 읽기 전용 검색 전문가. 기본적으로 Haiku 모델로 실행된다(저렴하고 빠름). "이 프로젝트에서 X가 어떻게 구현되어 있는지 봐줘"라고 요청하면, Claude는 자동으로 "대량의 파일을 읽되 쓰지는 않는" 태스크를 이 Subagent에 위임한다.

** Plan ** —— 실제 작업에 착수하기 전에 아키텍처안을 작성한다. 계획만 수립하고 실행은 하지 않는다. 승인을 받은 뒤 실행한다.

** General-purpose ** —— 특정 목적이 없는 범용 모델. 뭐든 처리할 수 있다.

많은 사람들이 인지하지 못하지만, Claude에게 "조사해줘" "이해해줘"라고 말하면, Claude는 이미 Explore를 사용하고 있는 경우가 많다. 다만 명시적으로 말하지 않을 뿐이다.

나만의 Subagent 만들기

Subagent는 YAML 헤더가 붙은 마크다운 파일에 불과하며, 특별한 마법 같은 것은 없다.

가장 간단한 방법은 Claude Code 안에서 /agents 를 입력하고 가이드를 따르는 것이다. 수동으로 파일을 만들어 .claude/agents/(프로젝트 레벨) 또는 ~/.claude/agents/(글로벌 레벨)에 넣을 수도 있다.

구체적인 예로, 코드 리뷰용 Subagent를 들어보겠다:

---
name: code-reviewer
description: 코드 리뷰 전문가. 코드를 작성하거나 변경한 직후 자동으로 사용한다.
tools: Read, Grep, Glob, Bash
model: inherit
---

당신은 시니어 코드 리뷰어입니다. 호출되면:
1. git diff를 실행해 최근 변경사항 확인
2. 변경된 파일에만 집중
3. 우선순위별 피드백: 치명적 문제 → 경고 → 제안

체크리스트:
- 명명이 명확한가
- 중복은 없는가
- 에러 처리가 충분한가
- 시크릿이 노출되어 있지 않은가
- 테스트가 충분한가

몇 가지 필드를 보충 설명하겠다.

description 은 파일 전체에서 가장 중요한 줄이다. Claude는 이 설명을 기반으로 언제 자동으로 위임할지 판단한다. "코드 어시스턴트"라고만 쓰면, Claude는 언제 사용해야 할지 모른다. "코드를 작성하거나 변경한 직후 자동으로 사용한다"라고 쓰면 —— 트리거 조건과 "자동으로"라는 표현 —— Claude가 비로소 실제로 호출한다. 이 한 줄의 작성 방식에 따라 이 Subagent가 장식물이 될지 실질적인 도구가 될지가 결정된다.

tools 는 권한 게이트이다. 읽기 전용 태스크라면 Read, Grep, Glob 만 부여하고, Edit, Write 는 주지 않는다. 이는 간결함뿐만 아니라, Subagent가 권한을 넘어 변경을 가하는 것을 막는 안전장치이기도 하다.

model 은 단계별로 구분해 사용할 수 있다. 탐색 같은 저렴한 태스크에는 Haiku를, 깊은 리뷰에는 Sonnet이나 Opus를 사용해 상황에 맞게 지불하고 비싼 모델을 낭비하지 않는다.

사용 방법

호출 방법은 3가지가 있다. 각각 다른 상황에 활용한다.

자연어로 직접 지시: "code-reviewer 로 auth 모듈을 봐줘". 자연스럽지만, Claude가 다른 Subagent를 선택할 가능성이 있다.

@code-reviewer 로 최근 변경사항 확인. @로 지정한 것은 반드시 사용되며, 엇나가는 일이 없다.

claude --agent code-reviewer. 세션 전체를 이 Subagent에 고정한다. 특정 작업만 수행하고 싶을 때 적합하다.

자주 쓰이는 3가지 시나리오

테스트 실행이나 로그 처리처럼 "대량 출력"이 수반되는 작업. npm test 를 실행하면 수천 줄의 출력이 나오고, 이를 메인 대화에 흘려보내면 혼란을 초래한다. Subagent에 위임하자: "테스트 스위트를 실행하고, 실패한 테스트와 에러만 보고해줘" —— Subagent가 모든 노이즈를 처리하고 시그널만 전달해준다.

병렬 조사. "3개의 독립된 Subagent를 사용해 인증, 데이터베이스, API 모듈을 동시에 조사" —— 순차적 조사보다 확실히 빠르며, 3개 모듈의 세부 사항이 서로 섞이지도 않는다.

연쇄 워크플로. "code-reviewer 로 성능 문제를 발견한 뒤, optimizer 로 수정". 앞 Subagent의 출력을 뒤 Subagent의 입력으로 사용할 수 있어 결론을 수동으로 전달할 필요가 없다.

Subagent와 Skill의 혼동을 피하자

이 두 개념은 Claude Code 내에서 가장 혼동되기 쉽다. 정리하면 다음과 같다:

	Skill	Subagent
본질	재사용 가능한 지시 패키지	독립된 컨텍스트를 가진 워커
실행 환경	메인 대화의 컨텍스트 내	자체적인 독립 컨텍스트 윈도우
사용 시점	메인 대화 내에서 일련의 프로세스를 재사용하고 싶을 때	컨텍스트를 분리하고 병렬 실행이나 권한 제어를 하고 싶을 때

암기법: 분리가 필요하면 Subagent, 재사용이 필요하면 Skill.

빠지기 쉬운 2가지 함정

Subagent는 다시 Subagent를 파견할 수 없다. 재귀적 호출은 불가능하다. 중첩된 위임이 필요한 경우, 프로세스를 Skill로 작성하거나 메인 대화에서 수동으로 여러 Subagent를 연쇄시켜야 한다.

description 이 너무 추상적인 것은 없는 것과 같다. 초보자가 가장 많이 범하는 실수다. "general purpose helper" 같은 설명으로는 Claude가 자발적으로 호출하는 일이 영원히 없을 것이다 —— 언제 등장시켜야 할지 이해하지 못하기 때문이다. 구체적일수록 좋다. 예를 들어 "PR 제출 전에 자동으로 코드를 리뷰하며, 자동으로 사용한다"처럼 트리거 시나리오를 직접 명시하라.

심화: Subagent에게 기억 부여하기

YAML 헤더에 다음 줄을 추가한다:

memory:
  scope: project

이렇게 하면 Subagent는 매번 발견한 프로젝트의 패턴, 마주친 버그, 아키텍처 약속을 기록한다. 다음에 호출될 때 Subagent는 이미 프로젝트를 "알고 있는" 상태가 된다.

본문에 다음 문장을 추가한다:

태스크 완료 후, 학습한 내용을 기억에 저장해주세요.

일정 기간 운영하면 이 Subagent는 프로젝트 내 "베테랑 직원"으로 변모한다 —— 리뷰 품질이 향상된다. 과거에 문제가 발생했던 위치를 파악하고 있기 때문이다.

정리

도입부의 컨텍스트 부족 문제로 돌아가자. 이후 이런 상황에서는 "코드 읽기" 단계를 Explore에 위임하면, 메인 대화에는 결론만 전달된다: "문제는 middleware/auth.ts 에 있으며, 토큰 파싱 시 빈 헤더가 처리되지 않고 있다". 그 뒤에는 적절한 부분을 수정하기만 하면 된다.

Subagent의 핵심 가치는 주로 세 가지에 있다: 메인 대화의 컨텍스트를 보호하고, 병렬 실행을 가능하게 하며, 권한을 제어한다.

처음부터 복잡하게 생각할 필요 없다. 가장 간단한 코드 리뷰 Subagent부터 시작해, 커밋할 때마다 자동으로 실행시켜보자. 익숙해지면 자연스럽게 다음 아이디어가 떠오를 것이다 —— "이 작업도 담당자에게 맡기는 게 좋겠다"라고.