[Claude Code] 서브에이전트(Subagents) 시스템

1. 도입부 (Introduction)

대규모 언어 모델(LLM)을 활용한 개발에서 가장 큰 적은 '노이즈'다.
복잡한 버그를 잡기 위해 수십 개의 파일을 읽고 방대한 로그를 분석하다 보면, 정작 중요한 지침들이 컨텍스트 윈도우 뒤편으로 밀려나 성능이 저하되곤 한다.

Claude Code의 서브에이전트(Subagents) 시스템은 바로 이 문제를 해결하기 위해 등장했다. 주 대화(Main Conversation)를 방해하는 무거운 작업들을 별도의 격리된 컨텍스트에서 수행하고 '요약본'만 받아오는 이 방식은, 마치 팀장이 실무자에게 조사를 맡기고 보고서만 받는 효율적인 협업 구조와 닮아 있다.
오늘은 이 서브에이전트를 직접 설계하고 프로젝트의 '실무 지휘관'으로 만드는 고도화된 전략을 정리해 본다.

 

2. 주요 특징 및 핵심 로직 (Main Features & Logic)

서브에이전트는 특정 유형의 작업을 처리하기 위해 특화된 '독립 AI 어시스턴트'다.

📌 2.1 서브에이전트의 작동 매커니즘

1. 위임(Delegate): Claude가 작업을 분석하다가 특정 서브에이전트의 역할과 일치한다고 판단하면 해당 에이전트를 생성한다.
2. 격리 실행(Isolated Execution): 서브에이전트는 주 대화와 분리된 자체 컨텍스트 윈도우에서 실행된다. 이 공간에는 주 대화의 지저분한 기록이 들어오지 않는다.
3. 결과 종합(Summarize): 서브에이전트가 작업을 마치면, 주 대화로는 방대한 중간 과정 대신 핵심 요약 결과만 반환된다.

 

📌 2.2 왜 서브에이전트인가?

• 컨텍스트 보존: 수천 줄의 파일 읽기나 로그 분석 결과가 주 대화를 오염시키지 않는다.
• 제약 조건 적용: 특정 에이전트에게는 '읽기 전용' 권한만 주거나, 특정 도구만 쓰도록 강제할 수 있다.
• 비용 제어: 단순 탐색은 Haiku 같은 저렴한 모델로, 정밀 분석은 Sonnet/Opus로 라우팅하여 효율을 극대화한다.

 

 

3. 상세 가이드 1: 내장 서브에이전트 이해하기

Claude Code에는 우리가 정의하지 않아도 이미 열일하고 있는 '기본 워커'들이 있다.

에이전트	모델 (기본값)	주요 도구 및 목적
Explore	Haiku (속도 중점)	코드베이스 검색 및 탐색. 쓰기(Write/Edit) 권한이 거부된 안전한 탐색기다.
Plan	상속 (주 대화 모델)	plan mode 진입 시 연구를 수행한다. 무한 중첩 방지를 위해 다른 에이전트를 생성할 수 없다.
General-purpose	상속 (주 대화 모델)	탐색과 코드 수정이 모두 필요한 복합적인 다단계 작업에 투입된다.

 

 

4. 상세 가이드 2: 사용자 정의 서브에이전트 제작법

나만의 전문가 에이전트를 만드는 가장 정석적인 방법은 YAML Frontmatter가 포함된 Markdown 파일을 작성하는 것이다.

📌 4.1 서브에이전트 파일 구성 요소

서브에이전트 파일은 설정부(Frontmatter)와 지침부(Markdown)로 나뉜다.

• 저장 위치: - 전역 적용(Personal): ~/.claude/agents/<name>.md
  • 프로젝트 전용(Project): .claude/agents/<name>.md

 

 

📌 4.2 핵심 설정 필드 (Frontmatter)

필드	설명
tools	사용할 수 있는 도구 목록. Skill을 포함하면 다른 스킬 호출도 가능해진다.
model	sonnet, opus, haiku 중 선택. 명시하지 않으면 주 대화의 모델을 따른다.
memory	user, project, local 범위 중 선택하여 대화 간 학습 내용을 저장하게 한다. (강력 추천!)
isolation	worktree로 설정 시, 임시 git worktree에서 독립적으로 파일을 수정한다.

 

5. 심화 기술: 에이전트의 능력을 극대화하는 패턴

📌 5.1 지속적 메모리(Persistent Memory) 연동

서브에이전트가 단순 일회용 소모품이 되지 않게 하려면 memory: project 설정을 사용하라. 에이전트가 발견한 패턴이나 아키텍처 결정을 MEMORY.md에 기록하고, 다음 대화에서 이를 먼저 읽고 시작하게 된다.

 

📌 5.2 동적 컨텍스트 포크(Fork) 모드

실험적인 기능인 CLAUDE_CODE_FORK_SUBAGENT=1을 활성화하면, 서브에이전트가 아예 지금까지의 주 대화 기록을 통째로 복사(Fork)해서 시작한다. 배경 설명이 길게 필요한 부차적 작업을 시킬 때 토큰 캐싱 효율이 매우 좋다.

 

 

6. 실전 예제 코드로 배우는 서브에이전트 설계

💻 예제 1: 시니어 코드 리뷰어 (읽기 전용 전문가)

코드 수정 권한을 박탈하고 오직 분석에만 집중하는 정밀 리뷰어다.

파일 경로: ~/.claude/agents/code-reviewer.md

---
name: code-reviewer
description: 코드 품질, 보안, 유지보수성을 시니어의 시각에서 정밀 검토합니다.
tools: Read, Grep, Glob, Bash  # Edit/Write 도구가 없어 코드를 멋대로 고치지 못함
model: sonnet
memory: project # 프로젝트별 리뷰 패턴을 기억함
---
당신은 15년 차 시니어 백엔드 엔지니어입니다.
요청을 받으면 먼저 `git diff`를 통해 변경 사항을 파악하고, 다음 체크리스트를 기준으로 리뷰하세요.

- 네이밍 컨벤션 및 가독성
- 에러 핸들링의 적절성
- 보안 취약점 (SQL Injection 등)
- 불필요한 코드 중복

결과는 우선순위(Critical/Suggestion)별로 나누어 주 대화로 보고하세요.

 

💻 예제 2: 데이터베이스 쿼리 검증자 (Hook 활용)

Bash 명령을 허용하되, 특정 SQL 쓰기 작업을 차단하는 안전한 DB 에이전트다.

파일 경로: ~/.claude/agents/db-reader.md

---
name: db-reader
description: 읽기 전용 DB 쿼리를 실행하여 데이터를 분석합니다.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly.sh" # 실행 전 스크립트로 검증
---
당신은 데이터 분석가입니다. `SELECT` 쿼리만을 사용하여 사용자의 질문에 답하세요.
절대로 데이터를 수정하거나 스키마를 변경해서는 안 됩니다.

 

7. 실무 팁 및 주의사항 (Practical Tips)

1. 명확한 설명(Description) 작성: Claude가 언제 위임할지 결정하는 기준은 오직 description 필드다. "이런 상황에 적극적으로 사용하라(Use proactively when...)"는 문구를 넣어라.
2. 서브에이전트 재개(Resume): 서브에이전트가 작업을 마친 뒤 "방금 그 에이전트 이어서 이 부분도 봐줘"라고 하면, 새로 생성하지 않고 이전 컨텍스트를 그대로 유지한 채 작업을 이어간다.
3. @-mention의 활용: 자동 위임이 답답하다면 @를 입력해 직접 에이전트를 지목하라. @"code-reviewer (agent)"와 같이 지목하면 모델은 군말 없이 해당 워커를 깨운다.
4. 간결한 지침 유지: 서브에이전트 본문도 결국 토큰이다. "어떻게" 보다는 "무엇을" 위주로, 그리고 꼭 필요한 제약 사항만 명시하는 것이 비용 절감의 핵심이다.
5. EPIC 사이클 준수: 서브에이전트에게도 탐색(Explore) → 계획(Plan) → 구현(Implement) → 커밋(Commit)의 흐름을 지시하여 결과의 안정성을 높여라.
6. 가시성 확보: 터미널에서 Ctrl+B를 누르면 현재 실행 중인 백그라운드 에이전트 목록을 볼 수 있다.
7. 검증 가이드: 에이전트의 작업이 끝난 후에는 반드시 npm test 등 자동화된 테스트를 통해 결과물을 검증하는 습관을 들여라.

 

8. 결론 (Conclusion)

Claude Code의 서브에이전트 시스템은 AI를 단순한 도구에서 '관리 가능한 인적 자원'으로 격상시킨다.

전문화된 시스템 프롬프트로 에이전트의 성격을 규정하고, 도구 제한으로 안전성을 확보하며, 지속적 메모리로 경험을 축적하는 것. 이 과정을 거치면 터미널은 단순한 셸이 아닌, 세계 최고의 엔지니어들이 상주하는 '가상 오피스'가 될 것이다.
오늘 정리한 예시들을 바탕으로 당신만의 전문가 팀을 꾸려보길 바란다.

참고 자료:

• Claude Code 서브에이전트 공식 문서
• Agent Teams 실험적 기능 가이드
• Anthropic 공식 프롬프트 엔지니어링 마스터 가이드