이 글은 교차 게시물입니다 — 원문(및 모든 업데이트)은 broke2builtai.com에서 확인할 수 있습니다.

긴 Claude Code 세션은 매번 똑같은 방식으로 실패합니다. 컨텍스트 윈도우 (Context window)가 검색 결과, 파일 덤프, 막다른 길의 탐색 내용으로 가득 차게 되고, 모델은 정작 날카로운 판단이 필요한 순간에 멍청해집니다. 서브에이전트 (Subagents)는 이를 해결하기 위한 내장된 해결책입니다. 서브에이전트는 자신만의 컨텍스트에서 지저분한 탐색 작업을 수행하고 결론만을 전달하는 별도의 작업자입니다. 실제로 이를 어떻게 사용하는지 알아보겠습니다.

서브에이전트란 정확히 무엇인가

서브에이전트는 Claude Code가 자체적인 컨텍스트 윈도우를 가지고 실행하는 별도의 에이전트 인스턴스입니다. 서브에이전트는 작업을 할당받아 파일을 읽고, grep을 수행하고, 추론하는 등의 작업을 수행한 뒤, 메인 대화에 단 하나의 결과 메시지만 반환합니다. 모든 중간 과정의 노이즈는 서브에이전트의 컨텍스트에 머물며 해당 에이전트와 함께 사라집니다.

이를 통해 세 가지 이점을 얻을 수 있습니다:

• 깨끗한 메인 컨텍스트. 서브에이전트가 탐색을 위해 자체 토큰을 소모하며, 메인 대화는 결론만 전달받습니다. 서브에이전트 측에서 수행한 50번의 파일 읽기는 사용자 측에서는 단 하나의 요약으로 나타납니다.
• 병렬 작업. 여러 개의 서브에이전트를 동시에 실행할 수 있습니다. 세 개의 독립적인 질문에 대해 세 명의 작업자가 순차적이 아닌 동시에 답변을 내놓을 수 있습니다.
• 전문화. 커스텀 서브에이전트는 자체적인 시스템 프롬프트 (System prompt)와 도구 제한 사항을 가집니다. 따라서 전체 세션의 내용을 염두에 두는 일반론적인 모델이 아니라, 집중된 전문가처럼 동작합니다.

트리거하기: 자동 vs 명시적

시작하기 위해 별도로 설정할 필요는 없습니다. Claude는 작업이 광범위한 검색이나 조사처럼 보일 때 스스로 위임 여부를 결정합니다. 예를 들어 "인증 (auth)을 처리하는 모든 곳을 찾아줘"와 같은 작업은 요청받지 않아도 Claude가 서브에이전트에게 맡길 만한 유형입니다.

직접 제어하고 싶다면 명시적으로 요청하세요:

use a subagent to find every place we construct SQL queries by hand

(수동으로 SQL 쿼리를 생성하는 모든 곳을 찾기 위해 서브에이전트를 사용해줘)

spawn an agent to research how the payment webhook flow works, then summarize it

(결제 웹훅 (webhook) 흐름이 어떻게 작동하는지 조사하는 에이전트를 생성한 다음, 이를 요약해줘)

일상적인 언어가 인터페이스입니다. "서브에이전트(subagent)"라고 말하거나 "에이전트를 생성해줘(spawn an agent)"라고 말하며 작업을 설명하기만 하면 됩니다. 나머지는 Claude가 처리합니다.

내부 구조(plumbing)에 대해 알아두어야 할 한 가지는, 서브에이전트의 결과가 사용자에게 직접 전달되는 것이 아니라 _메인 에이전트(main agent)_에게 전달된다는 점입니다. 메인 에이전트가 그 결과를 읽고 답변에 요약하여 제공합니다. 당신은 항상 코디네이터(coordinator)와 대화하며, 작업자(worker)와는 직접 대화하지 않습니다.

커스텀 서브에이전트 구축하기

진정한 강력한 한 수는 자신만의 에이전트를 정의하는 것입니다. 커스텀 서브에이전트는 YAML 프런트매터(frontmatter)가 포함된 하나의 마크다운(Markdown) 파일이며, 다음 두 곳 중 한 곳에 위치합니다:

• .claude/agents/ (레포지토리 내): 프로젝트 수준입니다. 이를 커밋하면 팀 전체가 동일한 전문가를 사용할 수 있습니다.
• ~/.claude/agents/: 개인용이며, 여는 모든 프로젝트에서 사용할 수 있습니다.

다음은 읽기 전용 코드 리뷰어(code reviewer)의 예시입니다:

---
name: code-reviewer
description: "코드가 막 작성되었거나 수정되어 검토가 필요할 때 이 에이전트를 사용하세요. 배포 전 버그, 보안 문제 및 컨벤션(convention) 위반 사항을 확인합니다."
...

네 가지 프런트매터 필드가 중요합니다:

• name — 케밥 케이스(kebab-case) 식별자.
• description — Claude가 언제 이 에이전트를 사용해야 하는지 나타냅니다. 이것이 라우팅 신호(routing signal)입니다. 많은 서브에이전트가 실패하는 지점이므로 아래에서 더 자세히 다루겠습니다.
• tools — 선택 사항인 허용 목록(allowlist)입니다. 목록에 없는 모든 것은 사용할 수 없습니다.
• model — 선택 사항이며, 이 서브에이전트가 실행될 모델을 고정합니다.

프런트매터 아래의 모든 내용은 서브에이전트의 시스템 프롬프트(system prompt)입니다. 만약 AI 에이전트를 위한 시스템 프롬프트 작성법을 읽어보셨다면, 구체적인 규칙, 명시적인 출력 형태, 모호함 배제(no vibes) 등 모든 내용이 여기에 적용됩니다.

파일을 직접 작성하고 싶지 않으신가요? Claude Code 내부에서 /agents를 실행하세요. 서브에이전트를 생성하고 편집할 수 있는 대화형 관리자가 열립니다.

description은 라우팅 신호입니다 — 트리거처럼 작성하세요

Claude는 위임 시점을 결정하기 위해 description 필드를 읽습니다. 따라서 이 필드는 파일에서 가장 중요한 한 줄입니다. 이를 트리거 조건(trigger condition)처럼 작성하세요:

# 약함(Weak) — Claude는 언제 이 에이전트를 호출해야 할지 알지 못함
description: 코드 품질을 위한 유용한 에이전트.

...

"이 에이전트를 ~할 때 사용하세요..." 뒤에 구체적인 상황을 덧붙이는 것이 효과적인 패턴입니다. 만약 서브에이전트(Subagent)가 자동으로 실행되지 않는다면, 다른 무엇을 수정하기 전에 description(설명)부터 수정하세요.

도구 제한 — 이는 편의 기능이 아니라 안전 기능입니다

tools 허용 목록(allowlist)은 전문가(specialist)를 신뢰할 수 있게 만드는 핵심 요소입니다. Read, Grep, Glob 권한만 가진 리뷰어는 아무리 혼란스러워지더라도 실수로 파일을 편집할 수 없습니다. 이는 희망 사항이 아니라 보장된 사항입니다.

각 작업에 맞춰 도구 범위를 제한한 전문가용 적합한 후보들은 다음과 같습니다:

• 코드 리뷰어 (Code reviewer) — 읽기 전용 (read-only).
• 테스트 실행/수정기 (Test runner/fixer) — 명령어를 실행하고 테스트 파일을 편집해야 함.
• 문서 작성기 (Docs writer) — 읽기 및 쓰기 가능, 쉘(shell) 사용 불가.
• 보안 감사관 (Security auditor) — 다시, 읽기 전용.
• 읽기 전용 탐색기 (Read-only explorer) — 부작용(side effects) 가능성을 완전히 차단하고 싶은 "이 코드베이스를 파악하라"와 같은 작업용.

설계 시 고려해야 할 한 가지 구조적 제한 사항은, 서브에이전트가 추가적인 서브에이전트를 생성할 수 없다는 점입니다. 위임(Delegation)은 한 단계 깊이까지만 가능하므로, 메인 에이전트가 항상 작업을 분산하는 코디네이터(coordinator) 역할을 수행합니다. 워크플로우를 구축할 때 이러한 형태를 염두에 두세요.

솔직한 트레이드오프 (Trade-off)

서브에이전트는 공짜가 아닙니다. 각 에이전트는 자체 인스턴스를 구동하므로, 결과를 보기 전까지 추가적인 지연 시간(latency)이 발생하며, 에이전트의 탐색 과정에서 소모되는 토큰은 사용자의 컨텍스트(context)에 포함되지 않더라도 비용을 발생시킵니다. 단일 파일의 빠른 조회를 위해서는 직접 검색하는 것이 훨씬 낫습니다. 한 줄짜리 grep 결과에 답하기 위해 워커(worker)를 생성하지 마세요.

경험 법칙(Rule of thumb): 검색 범위가 넓거나 작업이 **자기 완결적(self-contained)**일 때 위임하세요. 정답이 알려진 단 한 곳에 있다면 직접 처리하는 것이 좋습니다.

토큰 측면 또한 계획 단계에서 고려할 가치가 있습니다. 서브에이전트 (Subagents)가 사용하는 토큰은 사용자의 컨텍스트 (Context)에 포함되지 않더라도 소모되기 때문입니다. 비용이 걱정된다면, Claude Code가 더 저렴한 백엔드 (Backend)를 사용하도록 설정하는 것이 하나의 방법입니다. GLM Coding Plan이 그중 하나이며, Claude Code를 GLM API로 설정하는 방법에서 해당 설정 과정을 설명합니다. 탐색 비용이 저렴해지면, "세 명의 작업자를 생성하라"는 명령은 청구서에 대한 부담 대신 가벼운 선택지가 될 것입니다.