TL;DR: "이 프로젝트에서는 테스트에 Vitest를 사용하고, 커버리지(Coverage) 80% 이상을 유지하며..."라는 말을 매번 Claude에게 하고 있지는 않은가? 그것은 설정의 문제가 아니라 설계의 문제다. Claude Code의 서브 에이전트(Sub-agent)는 .claude/agents/ 디렉토리에 Markdown 파일을 하나 두는 것만으로, 전문 특화된 AI 팀원으로서 정의할 수 있다. Git 리포지토리(Repository)에 커밋하면 팀원 모두가 동일한 에이전트를 공유할 수 있다. 본 기사에서는 설계 판단 기준부터 실전적인 에이전트 예시까지, 현장에서 바로 사용할 수 있는 수준으로 해설한다.

왜 커스텀 서브 에이전트가 필요한가

Claude Code는 단독으로도 강력하지만, 팀에서 본격적으로 사용하다 보면 다음과 같은 문제에 부딪힌다.

매번 같은 지시를 반복하는 문제. "이 프로젝트에서는 테스트에 Vitest를 사용하고, 커버리지(Coverage) 80% 이상을 유지하며, src/__tests__/에 배치하고..."라는 말을 매번 전달하는 것은 비효율적이다. CLAUDE.md에 작성하면 일부는 해결되지만, 복잡한 워크플로우(Workflow)를 심어두면 CLAUDE.md가 비대해져 본래의 용도(프로젝트 개요 및 규칙)에서 벗어나게 된다.

품질 체크가 개인의 역량에 의존하는 문제. 코드 리뷰의 관점, 보안 체크 항목, 성능 측정 기준 등은 사람에 따라 차이가 난다. "그 사람이 리뷰했으니까 괜찮아"라는 상태는 확장(Scale)할 수 없다.

컨텍스트 윈도우(Context Window)를 소모하는 문제. 테스트 실행 시 발생하는 방대한 로그 출력, 코드베이스(Codebase) 전체 탐색, 의존성 조사 등을 메인 대화에서 수행하면, AI가 유지할 수 있는 대화 이력의 상한선인 컨텍스트 윈도우를 압박하여 정작 중요한 구현 작업에서 컨텍스트가 부족해진다.

서브 에이전트는 이러한 문제에 대한 Claude Code의 네이티브(Native)한 해결책이다. 전문 특화된 AI 팀원을 정의하고, 필요할 때 독립된 컨텍스트에서 동작시킬 수 있다.

단, 만들지 말아야 할 경우도 있다. 한 달에 1~2번 정도만 실행하는 작업이라면 CLAUDE.md에 절차를 적어두는 것이 관리 비용이 더 낮다. Claude의 기본 동작만으로 충분한 범용적인 리뷰에도 필요하지 않다. 팀에 Claude Code가 아직 보급되지 않은 단계에서는 에이전트의 가치가 이해되지 않아 방치될 리스크가 있다.

서브 에이전트의 기본 구조

에이전트의 실체: Markdown 파일 하나

서브 에이전트의 실체는 YAML 프런트매터(Frontmatter)가 포함된 Markdown 파일이다.

---
name: test-runner
description: 테스트 실행 및 결과 분석을 수행한다. 테스트 실행, 커버리지 확인, 실패한 테스트의 원인 조사에 사용한다.
...

이를 .claude/agents/test-runner.md에 저장하면, Claude Code가 태스크(Task) 내용에 따라 이 에이전트에게 자동으로 위임하게 된다. 단, 위임의 정확도는 description을 어떻게 작성하느냐에 크게 의존한다(후술).

# 디렉토리가 없으면 생성한다
mkdir -p .claude/agents

배치 위치와 스코프(Scope)

서브 에이전트는 배치 위치에 따라 스코프가 달라진다.

배치 위치	스코프	용도
.claude/agents/	프로젝트 고유	팀에서 공유하는 전문 에이전트. Git 커밋 권장
~/.claude/agents/	사용자 글로벌	개인의 모든 프로젝트에서 사용하는 에이전트

판단 기준은 단순하다. 해당 에이전트가 프로젝트의 기술 스택이나 규약에 의존하는가? 의존한다면 .claude/agents/ (프로젝트 고유)에 둔다. 범용적이라면 ~/.claude/agents/ (글로벌)에 둔다.

동일한 이름의 에이전트가 여러 위치에 있는 경우, 프로젝트 고유 에이전트가 우선된다. 즉, 글로벌에 범용 버전을 두고 특정 프로젝트에서 오버라이드(Override)하는 방식으로 사용할 수 있다.

프런트매터 완전 레퍼런스

---
name: agent-name # 필수. 소문자와 하이픈으로 구성된 식별자
description: | # 필수. Claude가 언제 위임할지 판단하는 데 사용
...

각 필드의 설계 판단을 심층적으로 살펴본다.

name : 명명 규칙

소문자와 하이픈으로 구성한다. 파일명과 일치시키는 것이 관례다.

# Good
name: api-reviewer
name: migration-checker
...

1 에이전트 1 책임 (1 Agent 1 Responsibility) 이 원칙이다. do-everything 이나 super-helper 와 같은 이름을 붙이고 싶다면, 에이전트를 분할해야 한다는 신호다.

description : 가장 중요한 필드

description 은 Claude가 "이 작업을 어떤 에이전트에게 위임할 것인가"를 판단하는 유일한 단서다. 모호하면 위임되지 않고, 너무 구체적이면 특정 케이스에서만 사용된다.

# Bad: 너무 모호함
description: 코드를 리뷰한다
# Bad: 너무 구체적임
...

description に <example> 블록을 포함하면, Claude의 판단 정밀도가 더욱 높아진다.

description: |
코드 변경 사항을 리뷰한다.
<example>
...

tools : 최소 권한의 원칙

에이전트에게 전달하는 툴은 필요 최소한으로 제한한다. 이는 보안뿐만 아니라, 에이전트 행동의 예측 가능성을 높이기 위함이기도 하다.

# 읽기 전용 에이전트 (리뷰, 분석, 감사)
tools: Read, Grep, Glob
# 리서치 에이전트
...

disallowedTools 를 사용하면, 상속받은 것 중에서 특정 툴만 금지할 수 있다. "기본적으로 모든 툴을 사용할 수 있지만, 파일 쓰기만은 금지"와 같은 제어에 유용하다.

disallowedTools: Write, Edit, Bash

model : 비용과의 트레이드오프 (Trade-off)

값	용도	비용
haiku	경량 작업 (탐색, 포맷 체크)	최저
sonnet	표준적인 개발 작업	중간
opus	복잡한 추론, 아키텍처 설계	최고
inherit	부모 세션과 동일한 모델	부모 설정에 따름

현실적인 선택 방법: 빈번하게 호출되는 에이전트 (lint 체크, 포맷 확인 등)는 haiku 로, 판단이 필요한 에이전트 (코드 리뷰, 설계 판단)는 sonnet 으로 설정한다. opus 는 아키텍처 리뷰 등 정말 깊은 사고가 필요한 상황으로 한정한다.

memory : 세션을 넘나드는 기억

memory 필드를 설정하면, 에이전트가 세션을 넘나들며 학습 내용을 축적할 수 있다.

memory: project # .claude/agent-memory/<name>/ 에 저장. Git 공유 가능
memory: user # ~/.claude/agent-memory/<name>/ 에 저장. 개인용
memory: local # .claude/agent-memory-local/<name>/ 에 저장. Git 비공유

메모리가 활성화된 에이전트는 메모리 디렉토리 내의 MEMORY.md 가 자동으로 시스템 프롬프트(System Prompt)에 주입된다. "지난번 리뷰에서 지적한 문제가 재발하지 않았는가"와 같은 체크가 가능해진다.

메모리 운영 비용. 메모리가 축적될수록 시스템 프롬프트가 길어져 에이전트의 컨텍스트 윈도우 (Context Window) 를 압박한다. 정기적으로 MEMORY.md 를 정리하는 운영이 필요하다.

실전: 프로젝트 전용 에이전트 설계하기

여기서부터는 실제 프로젝트에서 유용한 에이전트를 단계별로 설계해 본다.

스텝 1: 프로젝트의 "반복 작업"을 나열하기

먼저, 일상적인 개발에서 반복하고 있는 지시 사항이나 체크 항목을 리스트업한다.

- PR 전 코드 리뷰 (우리 팀의 규약에 부합하는가)
- 테스트 실행 및 커버리지 확인
- DB 마이그레이션(Migration) 안전성 체크
...

스텝 2: 1 에이전트 1 책임 원칙으로 분할하기

"모든 것을 다 하는 에이전트"는 만들지 않는다. 분할 판단 기준:

• 그 description 을 1~2문장으로 쓸 수 있는가? → No 라면 분할한다.
• 사용하는 타이밍이 다른가 (커밋 전 vs 배포 전)? → Yes 라면 분할한다.
• 필요한 툴 권한이 다른가? → Yes 라면 분할한다.

스텝 3: 에이전트 구현하기

아래에 실용적인 에이전트 예시 4가지를 제시한다.

예시 1: 프로젝트 규약 체커 (Project Convention Checker)

팀의 코딩 규약(Coding Convention)을 따르고 있는지 검증하는 읽기 전용(Read-only) 에이전트.

---
name: convention-checker
description: |
...

설계 의도: haiku 모델을 선택한 이유는 명명 규칙(Naming Convention)의 일치 여부 판정이나 파일 행 수 체크와 같이 정량적인 패턴 매칭(Pattern Matching)이 중심이기 때문이다. 깊은 추론은 필요하지 않으며, 빠르고 저렴한 비용이 우선시된다. 다만, "이 의존성 순환이 아키텍처 위반인가?"와 같이 문맥 판단이 필요한 규약 체크에서는 haiku를 사용할 경우 오판이 발생할 수 있다. 그럴 경우에는 sonnet으로의 전환을 검토한다. tools를 읽기 전용으로 한정하여 임의로 코드를 수정하지 않도록 설정했다.

예시 2: DB 마이그레이션 리뷰어 (DB Migration Reviewer)

데이터베이스 마이그레이션(Database Migration)의 안전성을 검증하는 에이전트.

---
name: migration-reviewer
description: |
...

설계 의도: 마이그레이션의 안전성 판단에는 추론 능력이 필요하므로 sonnet을 사용한다. Bash를 포함시킨 이유는 테이블의 행 수 추정이나 기존 스키마 확인을 위해 psql 명령어가 필요할 수 있기 때문이다. 단, psql로 DB에 접속하려면 DATABASE_URL 등의 환경 변수가 필요하다. CI 환경처럼 접속할 수 없는 환경에서는 Bash를 제외하고 정적인 마이그레이션 파일 분석에만 집중하는 것이 더 안전하다.

예시 3: API 사양 정합성 체커 (API Spec Consistency Checker)

구현체와 OpenAPI 사양서(OpenAPI Specification) 간의 정합성을 검증하는 에이전트. 사양과 구현의 불일치는 버그의 온상이 된다.

---
name: api-spec-checker
description: |
...

설계 의도: 읽기 전용(Read, Grep, Glob)으로 한정했다. 사양서나 구현 코드를 수정할 권한은 필요하지 않으며, 차이점(Diff)을 보고하는 것이 역할이다. sonnet을 선택한 이유는 스키마의 구조적 일치 여부를 판정하는 데 문맥 이해(Context Understanding)가 필요하기 때문이다.

예시 4: 릴리스 노트 생성 에이전트 (Release Note Generation Agent)

Git의 커밋 히스토리(Commit History)로부터 릴리스 노트를 자동으로 생성하는 에이전트.

---
name: release-note-writer
description: |
...
```markdown
## v{버전} 릴리스 노트 ({날짜})
### 신규 기능
- {사용자 대상 설명} (#{PR 번호})
### 버그 수정
- {수정 내용} (#{PR 번호})
### 성능 개선
- {개선 내용 및 효과}

주의

...

**설계 의도:** `memory: project`를 설정했다. 과거 릴리스 노트의 톤(Tone)이나 작성 방식을 학습하여, 회차를 거듭할수록 프로젝트의 스타일에 익숙해지도록 한다.

---
## 에이전트 호출 방법
### 자동 위임 (권장)
Claude는 대화의 문맥과 에이전트의 `description`을 대조하여 적절한 에이전트에게 자동으로 위임한다.

사용자 입력

...

자동 위임의 정확도는 `description`의 품질과 직결된다. 의도대로 위임되지 않는다면 `description`을 재검토하는 것이 가장 먼저 해야 할 일이다.
**자동 위임의 한계에 대해 솔직하게 말하자면,** 자동 위임은 편리하지만 과신은 금물이다. `description`을 정성스럽게 작성하더라도 의도대로 위임되지 않을 때가 있다. 특히 여러 에이전트가 유사한 역할을 수행할 경우 Claude의 판단이 흔들리기 쉽다. 마이그레이션 안전 확인과 같이 업무에 치명적인(Mission-critical) 체크는 자동 위임에 의존하지 않고 명시적으로 호출하는 운영 방식을 취하는 것이 확실하다.

### 명시적 지시
자동 위임에 의존하지 않고 직접 지정할 수도 있다.

migration-reviewer 에이전트로 db/migrations/ 파일을 리뷰해줘

### `/agents` 명령어로 확인

/agents

사용 가능한 에이전트 목록을 확인할 수 있다. 새로운 에이전트를 생성하는 UI도 제공된다.
---
## 서브 에이전트 vs 스킬 vs 명령어: 용도 구분
Claude Code에는 여러 확장 포인트가 있어 혼동하기 쉽다. 먼저 세 가지 개념을 간결하게 정리한다.
- **서브 에이전트 (Sub-agent)** (`.claude/agents/*.md`): 독립된 컨텍스트 (Context)에서 동작하는 전문 AI. 도구 제한이나 메모리 (Memory)를 가질 수 있다.
- **스킬 (Skill)** (`.claude/skills/*/SKILL.md`): Claude의 메인 대화에 주입되는 행동 정의. 실행 컨텍스트는 공유된다.
- **슬래시 명령어 (Slash Command)** (`.claude/commands/*.md`): `/command`로 수동 실행하는 정형화된 작업의 템플릿.
판단 기준을 표로 정리한다.

| 특성 | 서브 에이전트 | 스킬 | 슬래시 명령어 |
|------|--------------|--------|----------------|
| 실행 컨텍스트 | **독립** (메인과 별개) | 메인과 **동일** | 메인과 **동일** |

**판단 흐름:**
1. 대량의 출력이 발생하는 작업인가? → **서브 에이전트** (메인 컨텍스트를 보호)
2. 전문 지식이 필요하며, 도구를 제한하고 싶은가? → **서브 에이전트**
3. Claude의 행동이나 판단 기준을 정의하고 싶은가? → **스킬**
4. 매번 동일한 절차를 실행하기만 하면 되는가? → **슬래시 명령어**
---
## 설계 안티 패턴 (Anti-patterns)
### 1. 「만능 에이전트」를 만들어 버리는 경우
```yaml
# Bad
name: super-agent
description: 무엇이든 함

책임이 모호한 에이전트는 Claude가 "언제 사용할지"를 판단할 수 없다. 결과적으로 사용되지 않거나, 부적절한 타이밍에 사용된다.

2. 도구를 모두 개방하는 경우

# Bad: 읽기 전용 작업인데 모든 도구 허용
name: code-analyzer
description: 코드를 분석함
...

읽기 전용 분석 에이전트가 왠지 모르게 파일을 수정해 버리는 리스크가 있다. 최소 권한의 원칙 (Principle of Least Privilege)을 준수하라.

3. description을 대충 작성하는 경우

# Bad
description: 리뷰
# Good
...

description에 "use proactively"라고 영어로 기술하면, Claude가 태스크 완료 후 자발적으로 해당 에이전트를 호출하게 된다. 이는 Claude Code의 내부 프롬프트가 이 키워드를 인식하기 때문이다. 리뷰 계열의 에이전트에 특히 유효하다.

4. 시스템 프롬프트에 모호한 지시를 적는 경우

# Bad
적당히 잘 리뷰해 주세요.
# Good
...

체크 항목을 구체적으로 나열할수록 에이전트의 출력은 안정된다.

제한 사항과 마주하기

서브 에이전트는 만능이 아니다. 현시점(2026년 2월)의 제한 사항을 솔직하게 적는다.

서브 에이전트 중첩(Nesting)은 불가능하다

서브 에이전트가 다시 서브 에이전트를 생성할 수는 없다. 워크플로우에 중첩이 필요한 경우에는 메인 대화에서 서브 에이전트를 순차적으로 호출하거나, 스킬로 제어한다.

형제 에이전트 간의 직접 통신은 불가능하다

병렬로 동작하는 여러 서브 에이전트가 서로 정보를 공유할 수 있는 수단은 없다. 공유가 필요한 경우에는 메인 대화를 경유한다.

매번 클린 스타트 (Clean Start)

서브 에이전트는 새로운 호출마다 새로운 컨텍스트로 시작한다. 이전 결과를 이어받으려면 memory 필드를 사용하는 것이 기본적인 수단이다.

세션 시작 시 로드됨

.claude/agents/에 파일을 수동으로 추가한 경우, 현재 세션에서는 인식되지 않는다. 세션을 재시작하거나 /agents 명령어로 다시 로드해야 한다.

확장 사고 (Extended Thinking)의 제한

2026년 2월 시점에서는 서브 에이전트에서의 확장 사고 이용이 보장되지 않는다. 깊은 추론이 필요한 태스크(아키텍처 설계 판단 등)는 서브 에이전트에 위임하지 않고 메인 세션에서 직접 실행하는 것이 확실하다. 이 제한은 향후 변경될 가능성이 있으므로 공식 문서에서 최신 상황을 확인하라.

팀 운영: Git에 커밋하기

.claude/agents/

를 리포지토리(Repository)에 커밋하면, 팀원 모두가 동일한 서브 에이전트(Sub-agent)를 사용할 수 있다.

.claude/
├── agents/
│ ├── convention-checker.md # 규약 체크
...

리뷰 포인트: 에이전트 파일도 코드와 마찬가지로 리뷰 대상에 포함한다. 특히 tools의 권한과 description의 상세도는 팀 내에서 합의를 거쳐야 한다.

버전 관리 (Versioning): 프로젝트의 기술 스택(Tech Stack)이 변경되면 에이전트도 업데이트해야 한다. TypeORM에서 Prisma로 전환했는데, 에이전트가 여전히 TypeORM을 전제로 체크를 계속한다면 의미가 없다.

요약: 내일부터 시작할 액션 플랜

• 하나를 직접 만들어 보기. 우선 팀에서 가장 반복적으로 내리는 지시 사항을 하나 골라 서브 에이전트로 만든다. 처음부터 완벽함을 목표로 하지 않는다.
• 읽기 전용(Read-only)부터 시작하기. tools: Read, Grep, Glob를 사용하는 읽기 전용 에이전트는 리스크가 낮다. 리뷰 계열이나 분석 계열부터 시작하는 것이 안전하다.
• 의도대로 위임되지 않을 때는 description을 다듬기. description 작성 방식을 재검토한다. <example> 블록을 추가하는 것이 효과적이다.
• Git에 커밋하기. 팀에서 사용한다면 .claude/agents/에 커밋한다. 개인용이라면 ~/.claude/agents/에 배치한다.
• 정기적으로 유지보수하기. 에이전트는 만들고 끝나는 것이 아니다. 분기마다 사용되지 않는 에이전트를 정리하고, 기술 스택의 변경 사항을 반영하도록 관리한다. 아무도 유지보수하지 않는 에이전트는 잘못된 체크를 통과시켜 버리는 '안도감의 함정'이 될 수 있다.

서브 에이전트의 본질은 '반복되는 지시를 재사용 가능한 형태로 정의하는 것'이다. CLAUDE.md가 '프로젝트의 규칙서'라면, 서브 에이전트는 '팀의 전문가'다. 적절하게 설계한다면 품질 향상과 작업 효율화를 동시에 실현할 수 있다.

참고 링크

Discussion