메인 대화의 컨텍스트 윈도우(Context window)는 당신이 가진 가장 희소한 자원입니다. 모든 검색 결과, 모든 로그 덤프(Log dump), "확인만 하려고" 여는 모든 파일은 컨텍스트에 남아 실제 작업과 경쟁하게 됩니다. 단 하나의 부수적인 질문에 답하기 위해 코드베이스를 탐색하고 나면, 원래 기능을 구현하기로 했던 대화창은 다시는 참조하지 않을 내용들로 절반이 채워져 버립니다.

서브에이전트(Subagents)는 이러한 문제, 그리고 메커니즘을 보기 전까지는 관련 없어 보이는 몇 가지 다른 문제들에 대한 Claude Code의 해답입니다. 하지만 규칙 파일(Rules files)이나 훅(Hooks)과 마찬가지로, 서브에이전트 역시 특정한 형태를 가진 도구이며, 제가 목격하는 대부분의 실망은 규칙이나 훅이 적절한 계층(Layer)임에도 불구하고 서브에이전트를 사용하려 할 때 발생합니다.

이 글은 AI 코딩 에이전트의 제어 계층(Control layers)에 관한 시리즈의 네 번째 포스트입니다: 규칙 파일이 실제로 로드되는 방식, 강제 집행으로서의 훅, 그리고 아무것도 하지 않는 규칙 정리하기. 이번에도 동일한 접근 방식을 취하겠습니다: 메커니즘이 실제로 무엇인지 알아보고, 그다음 10초 안에 적용할 수 있는 의사결정 프레임워크를 제시합니다.

서브에이전트의 실제 정체

서브에이전트(Subagent)는 자신만의 컨텍스트 윈도우(Context window), 자신만의 시스템 프롬프트(System prompt), 그리고 **자신만의 도구 허용 목록(Tool allowlist)**을 가진 별도의 에이전트입니다. Claude가 작업을 서브에이전트에게 위임하면, 서브에이전트는 자신의 컨텍스트 내에서 작업을 수행하고 요약본을 반환합니다. 검색 결과, 파일 내용, 막다른 길(Dead ends) 등은 서브에이전트의 윈도우에 머물다 폐기되며, 오직 결론만이 당신의 대화창에 전달됩니다.

구체적으로 말하면, 서브에이전트는 YAML 프론트매터(YAML frontmatter)가 포함된 마크다운(Markdown) 파일입니다. Claude Code가 이를 로드할 수 있는 곳은 다섯 군데(관리 설정, CLI 플래그, 프로젝트, 사용자, 플러그인)가 있지만, 실제로 일상에서 사용하게 될 곳은 두 군데입니다:

• .claude/agents/ — 프로젝트 범위(project-scoped), 버전 관리 시스템(version control)에 포함됨, 팀원과 공유 가능
• ~/.claude/agents/ — 사용자 범위(user-scoped), 머신 내 모든 프로젝트에서 사용 가능

최소한의 구성이면서도 진정으로 유용한 예시는 다음과 같습니다:

---
name: code-reviewer
description: "코드의 정확성, 보안 및 유지보수성을 검토합니다"
...

name과 description만 필수입니다. tools를 생략하면 모든 것을 상속(inherit)받습니다. Read, Grep, Glob을 나열하는 것이 이 리뷰어를 '읽기 전용(read-only)'으로 만드는 핵심이며, 이는 생각보다 매우 중요합니다(자세한 내용은 아래 참조). model은 기본적으로 inherit로 설정되며, 이를 지정하면 메인 대화보다 더 저렴하거나 더 강력한 모델로 작업을 라우팅(routing)할 수 있습니다.

호출(invocation)에 관한 두 가지 사항:

1. 자동 위임(Automatic delegation)은 description 필드에 의해 결정됩니다. Claude는 이 필드를 읽고 언제 작업을 넘길지 결정합니다. "코드를 작성하거나 수정한 후 선제적으로 사용하세요"라는 문구는 문서화가 아니라 라우팅 지침(routing instruction)입니다.
2. 명시적으로 호출할 수 있습니다: "이 diff에 대해 code-reviewer 서브에이전트를 사용해줘"와 같이 요청할 수 있습니다. 만약 자동 위임이 전혀 트리거되지 않는다면, description이 너무 모호하다는 뜻입니다. 이는 가장 흔하게 발생하는 실패 모드입니다.

참고 사항: 시중에 나와 있는 대부분의 튜토리얼은 이 기능이 나오기 전의 것이므로 한 가지 주의할 점이 있습니다. v2.1.198 기준으로 /agents 대화형 위저드(wizard)는 사라졌습니다. 이제는 Claude에게 파일을 작성해달라고 요청하거나 직접 작성함으로써 서브에이전트를 생성해야 합니다. 파일 형식과 위치는 변경되지 않았습니다.

3계층 사고 모델 (The three-layer mental model)

이전 포스트들을 읽어보셨다면, 서브에이전트가 어디에 위치하는지 알 수 있습니다:

규칙(Rule)은 특정 동작을 **요청(ask)**합니다. 훅(Hook)은 확인 가능한 조건을 **강제(enforce)**합니다. 서브에이전트(Subagent)는 다른 곳에서 일련의 작업(chunk of work)을 수행하고 결과를 보고합니다.

제가 사용하는 프레임워크는 다음과 같습니다: 규칙(rules)은 선호도(preferences)이고, 훅(hooks)은 제어(controls)이며, 서브에이전트(subagents)는 직원(staff)입니다. 당신은 named export를 선호한다는 사실을 기억하게 하려고 직원을 고용하지 않습니다(그것은 규칙입니다). 또한 테스트가 실행되었는지 확인하기 위해 직원을 고용하지도 않습니다(그것은 훅입니다 — 예/아니오로 결정되는 사실입니다). 당신은 판단(judgment)이 필요하면서도, 당신 앞에서 직접 수행하게 되면 당신의 책상이 업무로 넘쳐날 만한 작업을 위해 직원을 고용합니다.

서브에이전트가 승리하는 네 가지 사례

1. 컨텍스트 격리(Context isolation) — 기본 사유

_중간 출력물(intermediate output)_은 방대하지만 _결론(conclusion)_은 작은 모든 작업이 이에 해당합니다: 코드베이스 탐색(codebase exploration), 의존성 감사(dependency audits), 로그 분석(log analysis), "통화 반올림을 처리하는 모든 위치를 찾아줘"와 같은 작업입니다. 메인 대화(main conversation)에서 이를 수행하면 수십 개의 파일 읽기가 세션 나머지 시간 동안의 컨텍스트를 오염시킵니다. 서브에이전트에서 수행하면 단 하나의 요약 문단으로 끝납니다.

커스텀 서브에이전트를 만들기 전에 알아두어야 할 점: Claude Code는 정확히 이러한 읽기 전용 검색(read-only-search) 케이스를 위해 내장된 Explore 서브에이전트를 제공합니다. 단순히 검색을 넘어 탐색에 대한 특화된 관점(lens) — 예를 들어 접근성 감사관(accessibility auditor)이나 보안 중심의 리더(security-focused reader) — 이 필요할 때 자신만의 서브에이전트를 정의하세요.

2. 제약 조건 강제(Constraint enforcement) — 과소평가된 사유

tools 허용 목록(allowlist)은 제안이 아니라 엄격한 경계입니다. tools: Read, Grep, Glob 권한을 가진 리뷰어는 자신이 리뷰하는 코드를 "도움이 되도록 수정"할 수 없습니다 — 그들의 세계에는 쓰기 도구(write tools)가 존재하지 않기 때문입니다. Bash 권한이 없는 마이그레이션 플래너(migration planner)는 아무것도 실행할 수 없습니다.

이는 파트 2에서 다룬 '산문(prose)보다 훅(hooks)'과 동일한 논리입니다: "리뷰어는 파일을 수정해서는 안 된다"라고 말하는 규칙은 모델이 무시하고 벗어날 수 있는 선호도이지만, 도구 허용 목록은 모델이 벗어날 수 없는 제어(control)입니다. 누군가 "Y를 하는 동안 에이전트가 X를 하지 못하게 하려면 어떻게 해야 하나요?"라고 묻는다면, 그 답은 더 엄격한 프롬프트가 아니라, 도구 목록을 통해 X를 불가능하게 만드는 서브에이전트인 경우가 많습니다.

3. 클린룸 판단(Clean-room judgment)

서브에이전트는 사용자의 대화 기록을 전혀 볼 수 없는 상태에서 시작합니다. 서브에이전트는 자신의 시스템 프롬프트(System Prompt)와 Claude가 전달하는 작업 설명(Task Description)만을 봅니다. 이는 제약 사항(아래에서 다룸)이기도 하지만, 동시에 핵심적인 지점이기도 합니다. 사용자의 메인 대화는 사용자의 프레이밍(Framing), 정당화, 그리고 이미 스스로 포기했던 세 가지 접근 방식 등으로 가득 차 있습니다. 이 중 그 어떤 것도 볼 수 없는 리뷰어는 오직 차이점(Diff) 자체의 가치만을 판단합니다. 이를 통해 사용자는 단순한 메아리(Echo)가 아닌, 제2의 의견(Second opinion)에 더 가까운 결과를 얻게 됩니다.

4. 비용 및 지연 시간 라우팅 (Cost and latency routing)

기계적인 스캐닝(TODO 수집, 테스트되지 않은 export 목록화, API 표면 추출 등)을 수행하는 서브에이전트에 model: haiku를 사용하면, 메인 대화는 더 강력한 모델을 유지하면서 대량의 작업은 빠르고 저렴한 모델로 라우팅(Routing)할 수 있습니다. 반대 방향도 가능합니다. 메인 세션은 가볍게 유지하고, 하나의 어려운 검증 작업은 더 높은 노력(Effort)을 투입하는 강력한 모델로 라우팅하는 것입니다.

서브에이전트가 잘못된 도구인 경우

• 작업에 대화의 문맥(Context)이 필요한 경우. 서브에이전트는 백지 상태에서 시작합니다. 만약 위임 프롬프트(Delegation prompt)가 의미를 갖기 위해 세션의 절반을 포함해야 한다면, 그 작업은 세션 내에서 처리되어야 합니다. 결론적으로, 위임을 할 때는 프롬프트가 자기 완결적(Self-contained)이어야 합니다. "우리가 논의했던 버그를 수정해"라는 식의 명령은 서브에이전트에게 아무것도 전달하지 않는 것과 같습니다.
• 빠르고 상호작용적인 편집. 서브에이전트 실행은 전체 에이전트 생명주기(Agent lifecycle)를 따릅니다. 이름 변경이나 세 줄짜리 수정 작업을 위해 위임을 사용하는 것은 순전한 오버헤드(Overhead)입니다.
• Yes/No 조건. "테스트가 통과했는가", "커밋 메시지가 형식과 일치하는가", "이 파일이 금지된 파일인가" — 이것들은 훅(Hook)의 영역입니다. 불리언(Boolean) 값을 확인하기 위해 에이전트를 생성하는 것은 체온계를 읽기 위해 직원을 고용하는 것과 같습니다.
• 일회성 작업. Claude Code는 별도의 커스텀 정의 없이도 범용적인 작업을 수행할 수 있습니다. 만약 동일한 지침을 가진 동일한 작업자를 계속해서 생성하고 있다는 사실을 깨닫는다면, 그때가 바로 서브에이전트 파일을 작성할 신호입니다. 즉, 그 작업은 이름, 튜닝된 프롬프트, 그리고 버전 관리(Version control)를 받을 가치가 있다는 뜻입니다.

실제로 발생하는 실패 모드 (Failure modes)

모호한 설명 (The vague description). description: Helps with code와 같은 설명은 라우터(router)에게 아무런 정보도 제공하지 않기 때문에 절대 자동으로 위임되지 않습니다. 무엇을 하는지, 그리고 언제 사용하는지를 명시하세요: "SQL 인젝션 및 누락된 인덱스를 감사합니다. 스키마 또는 쿼리 변경 사항을 병합하기 전에 사용하세요."

만능 에이전트 (The kitchen-sink agent). 리뷰, 수정, 문서화, 배포를 모두 수행하는 하나의 helper 서브에이전트(subagent)는 라우팅 신호(routing signal)도 없고 의미 있는 도구 경계(tool boundary)도 없습니다. 가치는 전문화(specialization)에서 나옵니다. 날카로운 설명을 가진 여러 개의 작은 에이전트가 하나의 포괄적인(omnibus) 에이전트보다 훨씬 낫습니다.

공유 메모리(Shared memory)를 가정하는 오류. "왜 서브에이전트가 우리의 컨벤션(conventions)을 무시했나요?" 그 이유는 당신의 컨벤션이 해당 에이전트가 전혀 보지 못한 대화 속에서 논의되었기 때문입니다. 에이전트가 반드시 준수해야 하는 모든 사항은 시스템 프롬프트(system prompt, Markdown 본문)에 넣거나, 서브에이전트가 로드하는 프로젝트 규칙(project rules) 파일에 넣어야 합니다.

버전 관리되지 않은 프로젝트 에이전트. 당신의 로컬 머신에만 존재하는 .claude/agents/ 디렉토리는 팀원들이 공유하지 못하는 컨벤션입니다. 이를 체크인(check in)하세요. 해당 디렉토리의 변경 사항을 코드처럼 리뷰하세요. 왜냐하면 그것은 도구 접근 권한(tool access)을 가지고 실행되는, 말 그대로 코드이기 때문입니다.

세 가지 실제 요청의 라우팅 (Routing three real requests)

의사결정 프레임워크를 구체화하기 위해, 끊임없이 발생하는 세 가지 요청이 어떻게 라우팅되는지 살펴보겠습니다.

1. "에이전트는 커밋하기 전에 항상 린터(linter)를 실행해야 합니다." 확인 가능하고, 결정론적(deterministic)이며, 이벤트 형태를 띱니다 → 훅(hook). 규칙(rule)은 잊힐 수 있지만, 서브에이전트는 과잉 대응(overkill)입니다.
2. "새로운 코드에서는 상속보다 구성을 선호합니다." 판단이 필요하고, 항상 적용되며, 명시 비용이 저렴합니다 → 규칙(rule). 위임할 것도 없고, 게이트(gate)를 세울 것도 없습니다.
3. "모든 릴리스 전에, 문서화되지 않은 중대한 변경 사항(breaking changes)이 있는지 변경 로그(changelog)와 대조하여 공개 API를 확인하세요." 판단 + 대량의 중간 읽기 작업 + 동일한 지침이 반복됨 → 서브에이전트(subagent), 읽기 전용 도구(read-only tools), 릴리스 체크리스트에서 명시적으로 호출됨.

결정을 내릴 수 없다면, 다음 두 질문을 순서대로 던지세요. 확인 가능한 사실인가? → 훅(hook). 중간 작업 과정이 결론보다 더 큰가? → 서브에이전트(subagent). 그 외의 모든 것은 규칙(rule)으로 시작하며, 파트 3에 따라 자신의 자리를 증명하지 못한다면 나중에 삭제됩니다.

불편한 결론

규칙 파일(rules-file)의 결론과 형태는 같지만, 한 단계 더 높은 차원에서의 결론입니다. 잘 설계된 에이전트 설정의 최종 상태는 바로 _지루함(boring)_입니다. 삭제 테스트를 견뎌낸 짧은 규칙 파일, 검증 가능한 사실을 강제하는 몇 개의 가벼운 훅(hooks), 그리고 실제로 재사용하는 명확한 범위를 가진 두세 개의 서브에이전트(subagents)가 그것입니다. 만약 당신에게 11개의 서브에이전트가 있고 그중 절반이 무엇을 하는지 기억조차 나지 않는다면, 당신은 더 많은 가동 부품(moving parts)을 가진 채로 규칙 파일의 비대화(bloat) 문제를 재현한 것이며, 심지어 각 에이전트는 도구 접근 권한(tool access)을 가진 채 실행됩니다.

하나부터 시작하십시오. 바로 위의 읽기 전용 리뷰어(read-only reviewer)입니다. 이는 격리(isolation), 제약(constraint), 클린룸 판단(clean-room judgment), 모델 라우팅(model routing)이라는 네 가지 이점을 동시에 실현하며, 당신이 매일 호출하게 될 에이전트입니다.

저는 Rulestack을 운영하고 있습니다. 이는 현재의 도구 동작에 맞춰 감사(audit)된 Cursor, Claude Code, Codex용 규칙 팩(rule packs), 훅(hooks), 서브에이전트 패턴을 제공합니다. 이 시리즈가 유용하다면, Bluesky의 @ai-shop.bsky.social에서 작업 노트를 확인하실 수 있습니다.