클로드 코드 서브 에이전트: AI에게 일을 시키는 AI

클로드 코드로 작업하다 보면 하나의 요청이 여러 단계로 나뉘는 경우가 많습니다. 테스트를 돌려서 실패하는 항목을 파악하고 관련 코드를 탐색한 다음 수정 방안을 정리해서 실제 코드를 고치는 식이죠. 이 과정에서 Claude의 컨텍스트 윈도우에는 테스트 출력이며 탐색 결과며 온갖 정보가 쌓이면서 정작 중요한 맥락이 밀려나 버립니다. 🤯

이런 문제를 해결하려고 Claude Code는 서브 에이전트(Sub-agent)라는 구조를 도입했습니다. 메인 대화에서 특정 작업을 별도의 에이전트에게 위임하면 그 에이전트가 독립된 컨텍스트 윈도우에서 작업을 처리하고 결과만 돌려주는 방식인데요. 이 글에서는 서브 에이전트의 동작 원리와 직접 만들어서 활용하는 방법을 살펴보겠습니다.

서브 에이전트가 필요한 이유

서브 에이전트의 핵심은 컨텍스트 관리입니다. Claude Code의 메인 대화는 하나의 컨텍스트 윈도우 안에서 진행되는데, 작업이 복잡해질수록 이 공간이 빠르게 소모됩니다.

“테스트를 돌리고 실패하는 것들을 고쳐줘”라고 요청하면 어떻게 될까요? 테스트 출력 전체가 메인 컨텍스트에 들어옵니다. 수백 줄짜리 테스트 로그가 그대로 쌓이면서 이전에 논의했던 설계 방향이나 코드 구조 같은 맥락이 밀려나 버리죠. 서브 에이전트에게 이 작업을 맡기면 테스트 출력은 서브 에이전트 쪽에만 남고, 메인 대화에는 “3개 테스트 실패, 원인은 타입 불일치”처럼 요약된 결과만 돌아옵니다.

컨텍스트 보존 말고도 이점이 있습니다. 서브 에이전트마다 쓸 수 있는 도구를 제한할 수 있어서 읽기 전용 탐색 에이전트에게는 파일 수정 권한을 안 주는 식으로 안전하게 운용할 수 있고요. 서브 에이전트별로 다른 모델을 지정하는 것도 됩니다. 간단한 파일 탐색은 빠르고 저렴한 Haiku에게 맡기고, 복잡한 코드 리뷰는 Opus에게 시키는 거죠.

기본 제공 서브 에이전트

Claude Code에는 상황에 따라 자동으로 쓰이는 내장 서브 에이전트가 있습니다.

Explore는 코드베이스 탐색 전용입니다. Haiku 모델을 써서 빠르고 읽기 전용 도구만 쓸 수 있어서 파일이 수정될 걱정이 없죠. Claude가 코드베이스를 파악해야 할 때 알아서 위임합니다.

Plan은 설정 가이드에서 다룬 계획 모드를 켤 때 동작합니다. 메인 대화의 모델을 그대로 사용하고 역시 읽기 전용이에요. 코드베이스를 조사한 뒤 그 결과를 바탕으로 실행 계획을 세워줍니다.

General-purpose는 탐색과 코드 수정을 모두 할 수 있는 범용 서브 에이전트입니다. 여러 단계를 거쳐야 하거나 탐색 결과를 보고 곧바로 수정해야 하는 경우에 쓰여요.

이 밖에도 Bash 명령을 별도 컨텍스트에서 실행하는 Bash 에이전트나, Claude Code 기능에 대한 질문에 답하는 Claude Code Guide 에이전트가 있습니다.

커스텀 서브 에이전트 만들기

기본 제공 에이전트만으로 부족하면 직접 만들면 됩니다. /agents 슬래시 명령어로 대화형으로 쉽게 만들 수도 있고 마크다운 파일을 직접 작성해도 돼요.

서브 에이전트 파일은 YAML frontmatter에 메타데이터를 적고 본문에 시스템 프롬프트를 작성하는 구조입니다.

code-reviewer.md

---
name: code-reviewer
description: 코드 변경사항을 리뷰합니다. 코드 작성 직후 자동으로 사용합니다.
tools: Read, Grep, Glob, Bash
model: sonnet
---

시니어 코드 리뷰어로서 코드 품질과 보안을 검토합니다.

호출되면:
1. git diff로 최근 변경사항을 확인
2. 수정된 파일에 집중
3. 즉시 리뷰 시작

리뷰 항목:
- 코드가 명확하고 읽기 쉬운지
- 보안 취약점이 없는지
- 에러 처리가 적절한지
- 테스트 커버리지가 충분한지

여기서 description 필드가 중요합니다. Claude가 이 설명을 보고 어떤 작업에 이 서브 에이전트를 쓸지 판단하거든요. “코드 작성 직후 자동으로 사용합니다”처럼 언제 쓸지를 명시해두면 Claude가 코드 수정 후 알아서 리뷰를 맡깁니다.

tools 필드로는 서브 에이전트가 쓸 수 있는 도구를 제한합니다. 코드 리뷰어에게는 Read, Grep, Glob, Bash만 허용하고 Write나 Edit는 빼서 읽기 전용으로 만드는 식이죠. model 필드에서는 sonnet, opus, haiku 중 하나를 고를 수 있고 생략하면 메인 대화 모델을 그대로 씁니다.

서브 에이전트의 저장 위치

서브 에이전트 파일은 어디에 저장하느냐에 따라 적용 범위가 달라집니다.

.claude/agents/ 디렉토리에 넣으면 해당 프로젝트에서만 쓰입니다. Git에 커밋해서 팀 전체가 함께 쓸 수 있어서 프로젝트 전용 서브 에이전트를 공유하기 좋죠.

~/.claude/agents/ 디렉토리에 넣으면 내 모든 프로젝트에서 쓸 수 있습니다. 개인적으로 자주 쓰는 서브 에이전트를 여기에 두면 됩니다.

CLI에서 --agents 플래그로 JSON 형태로 전달하면 해당 세션에서만 사용됩니다. 빠른 테스트나 자동화 스크립트에서 쓰기 좋아요.

claude --agents '{
  "db-reader": {
    "description": "읽기 전용 데이터베이스 쿼리 실행",
    "prompt": "SELECT 쿼리만 실행하여 데이터를 분석합니다.",
    "tools": ["Bash"],
    "model": "sonnet"
  }
}'

같은 이름의 서브 에이전트가 여러 위치에 있으면 CLI 인자 > 프로젝트 > 사용자 순으로 우선순위가 적용됩니다.

권한 모드

서브 에이전트의 permissionMode 필드로 권한 처리 방식을 제어할 수 있습니다.

default — 표준 권한 확인 방식으로, 필요할 때마다 사용자에게 승인을 요청합니다
acceptEdits — 파일 편집을 자동 승인합니다
dontAsk — 권한 프롬프트를 자동으로 거부합니다 (명시적으로 허용된 도구는 정상 동작)
plan — 읽기 전용 탐색만 허용하는 계획 모드입니다
bypassPermissions — 모든 권한 확인을 건너뜁니다

bypassPermissions는 모든 권한 검사를 우회하기 때문에 신중하게 써야 합니다. 보통은 dontAsk으로 설정하고 필요한 도구만 tools 필드에 명시하는 게 안전합니다.

Skills 주입

서브 에이전트에게 Skills를 미리 로드해줄 수 있습니다. skills 필드에 스킬 이름을 나열하면 서브 에이전트가 시작될 때 해당 스킬 내용이 통째로 컨텍스트에 들어갑니다.

api-developer.md

---
name: api-developer
description: API 엔드포인트를 팀 컨벤션에 맞게 구현합니다.
skills:
  - api-conventions
  - error-handling-patterns
---

API 엔드포인트를 구현합니다. 주입된 스킬의 컨벤션과 패턴을 따릅니다.

주의할 점은 서브 에이전트가 메인 대화의 스킬을 상속받지 않는다는 겁니다. 필요한 스킬은 명시적으로 나열해야 해요. SKILL.md 작성 가이드에서 스킬을 만드는 방법을 참고하세요.

영속적 메모리

memory 필드를 설정하면 서브 에이전트에게 세션을 넘어서 유지되는 메모리 디렉토리가 생깁니다. 작업하면서 발견한 코드베이스 패턴이나 디버깅 노하우를 기록해두면 다음 세션에서 바로 써먹을 수 있죠.

code-reviewer.md

---
name: code-reviewer
description: 코드 리뷰 전문 에이전트
memory: user
---

코드 리뷰를 수행합니다. 리뷰하면서 발견한 패턴, 컨벤션,
반복되는 이슈를 에이전트 메모리에 기록합니다.

메모리 범위는 세 가지입니다. user는 ~/.claude/agent-memory/에 저장되어 모든 프로젝트에서 공유됩니다. project는 .claude/agent-memory/에 저장되어 프로젝트 전용이고 Git으로 팀과 공유할 수 있어요. local은 .claude/agent-memory-local/에 저장되는데 프로젝트 전용이지만 커밋은 안 합니다. 특별한 이유가 없다면 user를 권장해요.

Hooks와의 연동

서브 에이전트에도 Hooks를 걸 수 있습니다. 서브 에이전트 frontmatter에 직접 정의하거나 프로젝트 settings.json에서 라이프사이클 이벤트에 반응하게 설정하면 됩니다.

다음은 Bash 명령만 허용하되 읽기 전용 SQL 쿼리만 실행할 수 있도록 Hook으로 제한하는 예시입니다.

db-reader.md

---
name: db-reader
description: 읽기 전용 데이터베이스 쿼리를 실행합니다.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

데이터베이스 분석가로서 읽기 전용 접근 권한만 가집니다.
SELECT 쿼리로 데이터를 분석하고 질문에 답합니다.

validate-readonly-query.sh 스크립트에서 INSERT, UPDATE, DELETE 같은 쓰기 작업이 감지되면 종료 코드 2를 반환해서 실행을 차단합니다.

프로젝트 settings.json에서는 SubagentStart와 SubagentStop 이벤트로 특정 서브 에이전트가 시작되거나 종료될 때 스크립트를 실행할 수도 있습니다.

settings.json

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-reader",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ]
  }
}

포그라운드와 백그라운드

서브 에이전트는 포그라운드 또는 백그라운드에서 돌릴 수 있습니다.

포그라운드로 실행하면 작업이 끝날 때까지 메인 대화가 기다립니다. 권한 프롬프트나 질문이 사용자에게 직접 전달되니까 상호작용이 필요한 작업에 쓰기 좋아요.

백그라운드로 실행하면 메인 대화와 동시에 돌아갑니다. 시작 전에 필요한 도구 권한을 미리 확보하고 이후에는 사전 승인된 범위 안에서 자율적으로 동작해요. Ctrl+B를 눌러서 포그라운드 작업을 백그라운드로 보낼 수도 있습니다.

독립적인 조사를 여러 갈래로 진행해야 할 때 백그라운드 서브 에이전트가 빛을 발합니다.

인증 모듈, 데이터베이스 모듈, API 모듈을 각각 서브 에이전트로 병렬 탐색해줘

이렇게 요청하면 세 개의 서브 에이전트가 동시에 각 영역을 조사하고 Claude가 결과를 종합해줍니다.

서브 에이전트 재개

서브 에이전트는 기본적으로 매번 새 컨텍스트에서 시작합니다. 그런데 이전 작업을 이어서 하고 싶을 때가 있죠. 이때 재개(resume) 기능을 쓰면 됩니다. 재개된 서브 에이전트는 이전 대화 내용, 도구 호출 결과, 추론 과정까지 전부 유지한 채 작업을 이어갑니다.

code-reviewer 서브 에이전트로 인증 모듈을 리뷰해줘
[에이전트 완료]

이어서 인가 로직도 분석해줘
[Claude가 이전 컨텍스트를 유지한 채로 서브 에이전트를 재개]

서브 에이전트 대화 기록은 ~/.claude/projects/{프로젝트}/{세션ID}/subagents/에 파일로 저장됩니다. 메인 대화가 압축되더라도 서브 에이전트 기록은 영향을 받지 않습니다.

활용 패턴

서브 에이전트를 잘 활용하는 패턴을 몇 가지 소개합니다.

가장 흔한 건 대량 출력 격리입니다. 테스트 실행이나 로그 분석처럼 출력이 많은 작업을 서브 에이전트에게 맡기면 메인 컨텍스트를 깔끔하게 유지할 수 있어요. “서브 에이전트로 테스트를 돌리고 실패한 것만 에러 메시지와 함께 알려줘”라고 요청하면 되죠.

독립적인 탐색을 동시에 돌리는 병렬 조사도 유용합니다. 서브 에이전트가 각각 다른 영역을 탐색한 뒤 Claude가 결과를 종합하는 방식인데 탐색 경로가 서로 의존하지 않을 때 잘 동작해요.

여러 서브 에이전트를 순서대로 연결하는 순차 체인도 있습니다. “code-reviewer 에이전트로 성능 이슈를 찾고 optimizer 에이전트로 수정해줘”처럼 요청하면 첫 번째 결과를 바탕으로 두 번째가 이어서 작업하죠. 참고로 서브 에이전트가 또 다른 서브 에이전트를 생성할 수는 없습니다. 중첩 위임이 필요하다면 메인 대화에서 순차적으로 체인을 구성해야 해요.

서브 에이전트 vs 메인 대화

모든 작업을 서브 에이전트에게 넘기는 게 항상 좋은 건 아닙니다.

반복적인 피드백이 필요하거나 계획-구현-테스트가 하나의 흐름으로 이어지는 작업은 메인 대화에서 직접 하는 게 낫습니다. 한두 줄 빠르게 고치는 작업도 마찬가지고요. 서브 에이전트는 새로 시작할 때 컨텍스트를 다시 수집해야 해서 오버헤드가 좀 생기거든요.

반면 출력이 많거나 도구 제한이 필요하거나 독립적으로 완결되는 작업은 서브 에이전트에게 위임하는 게 좋습니다. 결과 요약만 돌려주니까 메인 대화 컨텍스트를 아낄 수 있어요.

마치며

서브 에이전트는 Claude Code의 컨텍스트 한계를 넘어서 복잡한 작업을 효과적으로 나누는 방법입니다. 기본 제공되는 Explore, Plan, General-purpose 에이전트만으로도 Claude Code가 알아서 활용하지만 프로젝트에 맞는 커스텀 서브 에이전트를 만들면 워크플로우가 확 달라질 겁니다.

Claude Code에 대해 더 알고 싶다면 소개 포스팅을 참고하세요. AI 에이전트에게 절차적 지식을 전달하는 방법은 Agent Skills에서, 에이전트 동작을 세밀하게 제어하는 방법은 Hooks에서 다루고 있습니다. 코드를 작성하기 전에 설계를 검토하는 Plan 모드도 내부적으로 서브 에이전트를 활용합니다. 서브 에이전트를 넘어 여러 Claude 인스턴스가 팀으로 협업하는 구조가 궁금하다면 에이전트 팀도 살펴보세요. 서브 에이전트에게 작업을 체계적으로 분배하고 의존성을 관리하는 방법은 Tasks 가이드에서 다루고 있습니다. 공식 문서에서 더 자세한 내용을 확인할 수 있습니다.

This work is licensed under CC BY 4.0

서브 에이전트가 필요한 이유

기본 제공 서브 에이전트

커스텀 서브 에이전트 만들기

서브 에이전트의 저장 위치

권한 모드

Skills 주입

영속적 메모리

Hooks와의 연동

포그라운드와 백그라운드

서브 에이전트 재개

활용 패턴

서브 에이전트 vs 메인 대화

마치며

관련 포스트

클로드 코드 자동 메모리: AI가 스스로 배우고 기억하는 법

클로드 코드 Tasks: 세션을 넘나드는 작업 관리

Agent Skill 만들기: SKILL.md 작성 가이드

Agent Skills: AI를 위한 업무 매뉴얼

뉴스레터 구독