Claude 답변이 너무 장황한가요? Subagent로 나만의 AI 팀 만들기

Claude에게 코드 보안 검토를 맡겼더니 리팩터링 제안, 성능 분석, 테스트 케이스까지 한꺼번에 3,000줄이나 가져온 적이 있습니다. 문제는 AI가 너무 많은 내용을 준다는 데 있지 않습니다. 한 가지 일에만 집중하라고 지시할 방법이 없다는 데 있습니다.

Subagent는 바로 이 문제를 해결하는 기능입니다. 각 Subagent에는 독립적인 작업 범위, 도구 권한, 모델을 지정할 수 있으며 프로젝트의 .claude/agents/ 디렉터리에 저장됩니다. 코드 검토가 필요하면 코드 검토 Subagent를, 문서 작성이 필요하면 문서 작성 Subagent를 호출하면 됩니다. 작업 경계가 설정 파일에 명확히 적혀 있으므로 범위를 넘거나 주제에서 벗어나지 않습니다.

이 글에서는 Subagent 설정 방법과 호출 방식, Multi-Agent 협업 패턴을 설명하고 블로그 작성 시스템의 실전 사례도 함께 소개합니다.

Subagent란 무엇인가

간단히 말해 Subagent는 Claude를 위해 직접 만드는 맞춤형 전담 도우미입니다. 각 도우미에는 고유한 작업 범위와 도구 권한이 있으며, 사용하는 모델까지 서로 다르게 설정할 수 있습니다.

이들은 프로젝트의 .claude/agents/ 디렉터리에 들어가며, 파일 하나가 곧 도우미 하나입니다. 파일 구조도 간단합니다. 위쪽에는 YAML 설정을, 아래쪽에는 Markdown으로 작성한 상세 프롬프트를 넣습니다.

---

name: code-reviewer
description: 코드 품질과 보안 취약점을 전문적으로 검토하는 도우미
tools: [Read, Grep, Glob]
model: haiku

---

당신은 다음 문제를 집중적으로 찾는 코드 검토 전문가입니다.
- 보안 취약점(SQL 인젝션, XSS 등)
- 성능 병목
- 코드 규칙 문제
문제만 지적하고 코드를 직접 수정하지 마세요.

일반적인 Claude 대화와 비교하면 Subagent에는 세 가지 뚜렷한 차이가 있습니다.

집중도 — 지정한 일만 수행하고 주제에서 벗어나지 않습니다. 코드 검토를 맡기면 검토만 하며, 내친김에 리팩터링까지 하지는 않습니다.

제한성 — 사용할 수 있는 도구 권한을 사용자가 부여합니다. 읽기 전용 검토 도우미는 파일을 수정할 방법 자체가 없습니다.

재사용성 — 설정 파일을 프로젝트에 넣어 두면 모든 팀원이 사용할 수 있습니다. 새 팀원도 입사하자마자 @code-reviewer를 호출해 바로 작업을 시작할 수 있습니다.

Subagent가 필요한 이유

솔직히 처음에는 굳이 이런 기능까지 필요한가 싶었습니다. Claude와 그냥 대화하면 되지 않을까요?

하지만 한동안 사용해 보고 나니 확실히 편리했습니다.

집중도

Claude 자체는 너무 다재다능합니다. 코드에 관해 질문하면 모범 사례를 설명하고, 프레임워크를 추천하고, 문서까지 작성해 줄 수 있습니다. 때로는 유용하지만 대부분은 잡음에 불과합니다.

Subagent를 사용하면 하나의 작업에 집중하게 만들 수 있습니다. 코드 검토 전담 도우미는 리팩터링 방안을 작성하지 않고, 테스트 작성 전담 도우미는 아키텍처 설계에 이의를 제기하지 않습니다.

비용 최적화

많은 사람이 놓치는 부분이 있습니다. 모든 작업에 가장 비싼 모델이 필요한 것은 아닙니다.

검색, 형식 변환, 간단한 분석에는 Haiku만으로 충분하며 비용은 Sonnet의 약 1/3입니다. 팀 단위로 한 달 동안 사용하면 절감되는 비용이 상당합니다.

병렬 처리

제가 가장 만족한 부분은 바로 이것입니다.

여러 작업을 동시에 시작해 병렬로 실행할 수 있습니다. 예를 들어 기능 하나를 완성한 뒤 도우미 하나에는 단위 테스트를, 다른 하나에는 코드 검토를, 또 다른 하나에는 문서 작성을 동시에 맡길 수 있습니다. 실제로 사용해 보니 효율 향상이 매우 뚜렷했습니다.

재사용성

작성한 설정 파일을 Git 저장소에 바로 커밋하면 모든 팀원이 사용할 수 있습니다. 프로젝트에서 쌓인 경험이 실행 가능한 설정으로 바뀌는 셈입니다.

"Subagent의 핵심 가치는 집중도와 재사용성입니다. 한 명의 제너럴리스트가 전문가 팀으로 바뀌고, 각 전문가는 자신이 잘하는 일만 담당합니다."

YAML 설정 자세히 알아보기

이제 실제 설정 파일은 어떻게 작성하는지 살펴보겠습니다.

완전한 Subagent 설정에는 몇 가지 필드가 있지만, 필수 필드는 두 개뿐입니다.

---

name: blog-writer             # 필수: 도우미의 고유 식별자
description: 블로그 초안 작성 전문가  # 필수: 자동 실행에 영향을 주는 짧은 설명
tools: [Read, Write, Grep]     # 선택: 도구 권한, 기본값은 전체 도구
model: sonnet                 # 선택: 모델 선택, 기본값은 주 대화에서 상속

---

# 프롬프트는 YAML 아래에 작성합니다.
당신은 전문 블로그 작가입니다...

name — 호출할 때 도우미를 식별하는 ID입니다. code-reviewer, test-writer처럼 역할을 한눈에 알 수 있는 이름이 좋습니다.

description — 매우 중요한 필드입니다. Claude는 이 설명을 보고 해당 도우미를 언제 자동으로 실행할지 판단합니다. 여기에 ‘여러 작업을 처리하는 범용 도우미’라고 쓰면 사실상 자동으로 실행되지 않습니다.

나쁜 예:

description: 도우미

좋은 예:

description: 블로그 주제를 심층 조사하고 구조화된 콘텐츠 기획 문서 작성

tools — 도구 권한 목록입니다. 설정하지 않으면 기본적으로 모든 도구를 사용할 수 있지만, 실제로는 그다지 좋은 선택이 아닙니다. 이 문제는 뒤에서 자세히 설명하겠습니다.

model — 사용할 모델을 선택합니다. haiku는 저렴하고 빠르며, sonnet은 균형 잡힌 기본 선택이고, opus는 품질이 가장 높지만 가장 비쌉니다.

도구 권한 제어

이 부분에서는 저도 시행착오를 겪었기 때문에 따로 짚어 볼 가치가 있습니다.

처음에는 편하게 하려고 모든 Subagent에 기본 전체 권한을 부여했습니다. 그러다 어느 날 코드 분석만 해야 하는 도우미가 파일 몇 개를 알아서 수정했고, 그 수정도 잘못된 적이 있었습니다.

그 이후로 도구 권한을 진지하게 다루기 시작했습니다. 원칙은 간단합니다. 꼭 필요한 권한만 부여하고 그 이상은 주지 않습니다.

자주 쓰는 도구 권한 조합은 다음과 같습니다.

작업 유형	권장 도구 조합
읽기 전용 분석	Read, Grep, Glob
검색 조사	Read, WebSearch, WebFetch
콘텐츠 편집	Read, Edit
콘텐츠 생성	Read, Write, Edit
전체 권한	All tools(신중하게 사용)

실제 설정을 비교해 보겠습니다.

나쁜 설정: 코드 검토 도우미에 너무 많은 권한 부여

---

name: code-reviewer
tools: []  # 빈 배열 = 전체 권한, 안전하지 않습니다.

---

좋은 설정: 읽기 전용 권한만 부여

---

name: code-reviewer
tools: [Read, Grep, Glob]

---

읽기 전용 검토 도우미는 코드를 실수로 수정할 방법 자체가 없습니다. 이런 제약이 오히려 보호 장치가 됩니다.

세 가지 호출 방법

설정을 작성했다면 어떻게 호출할까요? 세 가지 방법이 있습니다.

자동 실행

description을 충분히 명확하게 작성하면 Claude가 언제 실행해야 할지 자동으로 판단합니다. 예를 들어 ‘코드 검토와 관련된 모든 요청 처리’라고 설명해 두었다면 사용자가 ‘이 PR을 검토해 줘’라고 했을 때 자동으로 실행됩니다.

@-mention

가장 직접적인 방법은 @agent-name을 입력하는 것입니다.

@code-reviewer 이 함수에 문제가 있는지 확인해 줘

Task 도구

프로그래밍 방식의 호출로, 더 복잡한 상황에 적합합니다.

Task(subagent_type="code-reviewer", prompt="src/ 디렉터리의 모든 파일 검토")

방법	문법	적합한 상황	특징
자동 실행	명시적으로 호출할 필요 없음	명확한 키워드	편리하지만 잘못 실행될 수 있음
Task 도구	Task(subagent_type="name")	프로그래밍 방식 호출	정밀한 제어
@-mention	@agent-name	대화형 사용	직관적이지만 이름을 기억해야 함

개인적으로는 간단하고 직접적인 @-mention을 가장 자주 사용합니다. 자동 실행은 가끔 잘못 판단할 수 있고, Task 도구는 복잡한 워크플로에서 주로 사용합니다.

Multi-Agent 협업

지금까지는 단일 도우미의 사용법만 살펴봤습니다. Subagent의 진정한 강점은 여러 도우미의 협업에 있습니다.

순차 패턴

제가 가장 자주 사용하는 방식은 순차 패턴이며, 특히 콘텐츠 제작 워크플로에 적합합니다.

사용자가 주제 입력
    |
@blog-planner 조사 및 개요 작성
    | 기획 문서 출력
@blog-writer 개요를 읽고 초안 작성
    | 초안 출력
@blog-editor 초안을 읽고 게시용으로 다듬기
    | 최종 원고 출력

각 도우미는 하나의 단계만 담당하고 앞 단계의 출력이 다음 단계의 입력이 됩니다. 명확하고 제어하기 쉬우며 디버깅도 간단합니다.

병렬 패턴

병렬 패턴은 더욱 편리합니다. 기능 하나를 완성한 뒤 다음 작업을 동시에 시작할 수 있습니다.

• @test-writer: 단위 테스트 작성
• @code-reviewer: 코드 검토
• @doc-writer: 문서 작성

세 작업이 서로 간섭하지 않고 병렬로 실행됩니다. 순차로 처리하면 30분 걸리던 일을 이제 10분 만에 끝낼 수 있습니다.

HITL 패턴(Human In The Loop)

사람의 확인이 필요한 상황에 적합한 패턴도 있습니다.

@planner 계획 생성
    |
사용자가 확인 또는 수정
    |
@executor 계획 실행

이 패턴의 장점은 중요한 의사 결정 지점을 사람이 통제하므로 완전히 제어를 잃는 상황을 막을 수 있다는 것입니다.

설정 작성 팁 7가지

몇 달 동안 Subagent를 사용하며 설정을 더 유용하게 만드는 팁 7가지를 정리했습니다.

팁 1: 설명을 정확하게 작성하기

description은 자동 실행의 정확도에 직접적인 영향을 줍니다.

너무 모호함 — 거의 자동으로 실행되지 않음:

description: 범용 도우미

정확한 설명 — 역할 범위가 명확함:

description: Python 코드의 보안 취약점과 성능 문제를 전문적으로 검토

팁 2: 프롬프트를 구체적으로 작성하기

‘당신은 코드 검토 전문가입니다’라고만 하지 말고 무엇을 어떻게 검토할지 구체적으로 알려 주세요.

너무 포괄적인 예:

당신은 코드 검토 전문가입니다. 사용자의 코드를 검토해 주세요.

구체적인 지침:

당신은 Python 코드 보안 검토 전문가입니다.
## 검토 중점
1. SQL 인젝션 위험 - 모든 데이터베이스 작업 확인
2. XSS 취약점 - 사용자 입력 처리 확인
3. 민감한 정보 노출 - 로그와 오류 처리 확인
## 출력 형식
각 문제를 다음 형식으로 보고하세요.
- 파일: xxx
- 줄 번호: xxx
- 위험 수준: 높음/중간/낮음
- 문제 설명: xxx
- 수정 제안: xxx

팁 3: 도구 최소화하기

앞서 설명했듯이 꼭 필요한 권한만 부여하세요. 권한을 적게 준다고 도우미가 덜 똑똑해지는 것은 아닙니다. 할 수 있는 작업의 범위만 제한될 뿐입니다.

팁 4: 알맞은 모델 선택하기

간단한 작업에는 Haiku, 복잡한 작업에는 Sonnet을 사용하세요. 구체적으로는 다음과 같습니다.

• Haiku에 적합한 작업: 검색 요약, 형식 변환, 간단한 분석, 데이터 정리
• Sonnet에 적합한 작업: 복잡한 로직, 창의적인 콘텐츠, 코드 생성, 추론 분석

팁 5: 충분히 테스트하기

설정을 작성한 뒤 여러 호출 방법을 시도해 보세요. 자동 실행이 제대로 작동하는지, @-mention에 문제가 없는지, 경계 상황은 어떻게 처리하는지 확인해야 합니다.

팁 6: 문서를 명확하게 작성하기

프롬프트 자체가 곧 문서입니다. 명확하게 작성하면 팀원도 이 도우미가 무엇을 하고 어떻게 사용하는지 한눈에 이해할 수 있습니다.

팁 7: 자주 개선하기

한 번에 완벽하게 작성하려 하지 마세요. 우선 사용할 수 있는 버전을 만든 다음 일정 기간 실제로 사용하면서 피드백에 따라 조금씩 조정하세요.

자주 발생하는 실수와 예방법

팁을 살펴봤으니 이제 제가 직접 겪었던 실수를 소개하겠습니다.

실수 1: 설명이 너무 모호함

‘범용 도우미’ 같은 설명을 적으면 Claude는 언제 호출해야 할지 알 수 없습니다. 무엇을 담당하는지 구체적으로 작성해야 합니다.

나쁜 예:

description: 사용자를 돕는 도우미

개선된 예:

description: 사용자가 ‘테스트’ 또는 ‘단위 테스트’를 언급하면 테스트 케이스 자동 생성

실수 2: 도구 권한이 너무 많음

편의를 위해 모든 권한을 부여하면 도우미가 원치 않는 작업까지 할 수 있습니다. 특히 Write 권한은 부여하기 전에 신중하게 생각해야 합니다.

나쁜 예:

name: format-converter
tools: []  # 빈 배열 = 전체 권한

개선된 예:

name: format-converter
tools: [Read, Write]

실수 3: 프롬프트가 너무 김

Subagent 프롬프트도 token을 소비합니다. 수천 자짜리 프롬프트를 작성하면 호출할 때마다 그만큼의 token이 소모됩니다. 간결하게 유지하고 필요한 정보만 작성하세요.

실수 4: model 설정을 잊음

model을 설정하지 않으면 기본적으로 주 대화의 모델, 보통 Sonnet을 상속합니다. 간단한 작업에 불필요한 비용을 쓰게 됩니다.

설정을 잊은 예:

name: text-extractor
tools: [Read]

설정한 예:

name: text-extractor
tools: [Read]
model: haiku

실수 5: 순환 호출

Agent A가 Agent B를 호출하고 Agent B가 다시 Agent A를 호출하는 경우입니다. 이런 무한 루프는 시간 초과가 발생하거나 사용자가 강제로 중지할 때까지 계속 실행됩니다.

올바름: A -> B -> C

잘못됨: A -> B -> A

실수 6: 오류 처리가 없음

Subagent도 실패할 수 있습니다. 워크플로에 오류 처리 로직을 추가하여 실패를 제때 발견할 수 있게 하세요.

실수 7: 설정을 버전 관리하지 않음

설정 파일은 Git에 커밋해야 합니다. 설정을 변경한 뒤 문제가 생기더라도 이전 버전으로 되돌릴 수 있습니다.

실전 사례: 블로그 작성 시스템

이론을 충분히 살펴봤으니 실제 사례를 보겠습니다.

제가 사용하는 블로그 작성 시스템은 세 개의 Subagent로 구성되어 있습니다.

시스템 아키텍처

사용자가 주제 제공
    |
blog-planner: 조사 + 기획(20분)
    | 출력: docs/[주제]-콘텐츠-기획-문서.md
blog-writer: 초안 작성(40분)
    | 출력: docs/[주제]-초안.md
blog-editor: 교정 및 최적화(20분)
    | 출력: docs/[주제]-최종-원고.md

blog-planner(기획자)

---

name: blog-planner
description: 주제를 심층 조사하고 콘텐츠 기획 문서 작성
tools: [Read, Write, Grep, WebSearch, WebFetch]
model: sonnet

---

당신은 다음 작업을 담당하는 콘텐츠 기획자입니다.
1. WebSearch로 주제의 최신 동향 조사
2. 대상 독자와 문제점 분석
3. 글의 구조와 SEO 전략 설계
4. 기획 문서를 docs/ 디렉터리에 출력

blog-writer(작성자)

---

name: blog-writer
description: 기획 문서를 바탕으로 블로그 초안 작성
tools: [Read, Write, Grep]
model: sonnet

---

당신은 다음 작업을 담당하는 콘텐츠 작성자입니다.
1. 기획 문서 읽기
2. 개요에 따라 전체 초안 작성
3. 자연스럽고 AI 느낌이 나지 않는 콘텐츠 작성
4. 초안을 docs/ 디렉터리에 출력

blog-editor(편집자)

---

name: blog-editor
description: 초안을 편집하고 자연스러운 표현으로 개선
tools: [Read, Edit]
model: haiku

---

당신은 다음 작업을 담당하는 콘텐츠 편집자입니다.
1. 초안 읽기
2. AI 느낌이 나는 표현 확인 및 제거
3. 자연스러움과 가독성 향상
4. 최종 원고를 docs/ 디렉터리에 출력

작업 흐름은 간단합니다.

# 1단계: 기획
@blog-planner Claude Code Subagent 사용 팁
# 2단계: 작성
@blog-writer
# 3단계: 편집
@blog-editor

각 단계의 입력과 출력이 명확하므로 문제가 생겨도 쉽게 위치를 찾을 수 있습니다.

비용 최적화 제안

마지막으로 비용을 살펴보겠습니다.

Haiku와 Sonnet의 가격은 약 3배 차이가 납니다. 구체적인 가격은 Anthropic 공식 웹사이트를 참고하세요. 일반적인 블로그 작성 작업에서도 모델을 합리적으로 배정하면 상당한 비용을 절감할 수 있습니다.

모델 선택 전략

제가 권하는 기준은 다음과 같습니다.

Haiku를 사용할 상황

• 검색과 정보 요약
• 간단한 형식 변환
• 데이터 정리와 분류
• 코드 검토(읽기 전용 분석)

Sonnet을 사용할 상황

• 콘텐츠 제작(블로그, 문서)
• 복잡한 코드 생성
• 추론이 필요한 분석 작업
• 높은 품질이 필요한 상황

모델 비교 참고

모델	특징	적합한 상황
Haiku	빠르고 저렴함	간단한 작업
Sonnet	균형 잡힌 기본 선택	복잡한 작업
Opus	가장 높은 품질, 가장 비쌈	최고 수준의 품질

저는 Opus를 거의 사용하지 않습니다. 매우 중요하고 최고 수준의 품질이 필요한 작업이 아니라면 일상 업무에는 Sonnet으로 충분합니다.

비용 절감 원칙

다음 원칙을 기억하세요.

• Haiku로 할 수 있다면 Sonnet을 쓰지 않기
• 도구를 제한할 수 있다면 All tools를 부여하지 않기
• 프롬프트를 간결하게 쓸 수 있다면 길게 쓰지 않기
• 출력을 제한할 수 있다면 마음대로 늘어놓게 하지 않기

마치며

결국 Subagent는 특별한 마법이 아니라 Claude의 능력을 필요에 따라 분리하는 기능입니다. 한 명의 제너럴리스트가 전문가 팀으로 바뀌고, 각 전문가는 자신이 잘하는 일만 담당합니다.

아직도 ‘Claude 하나로 모든 일을 처리하는’ 방식을 사용하고 있다면 Subagent를 꼭 시도해 보시기를 권합니다. 30분 정도 들여 설정 몇 개를 작성하면 ‘Claude가 또 주제에서 벗어났네’라고 느끼는 수많은 순간을 줄일 수 있습니다.

핵심 원칙은 다음과 같습니다.

1. Agent 하나는 한 가지 일만 수행합니다.
2. 꼭 필요한 도구 권한만 부여합니다.
3. 간단한 작업에는 Haiku를 사용합니다.
4. 프롬프트는 구체적이고 명확하게 작성합니다.
5. 여러 Agent가 협업할 때는 문서로 결과를 전달합니다.

문제가 생겨도 당황하지 마세요. 대부분은 설정이 잘못 작성된 경우입니다. 이 글의 팁 7가지와 실수 7가지를 하나씩 확인하면 대부분 해결할 수 있습니다.

마지막으로 한마디 덧붙이겠습니다. 완벽한 설정을 추구하지 말고 먼저 사용한 뒤 천천히 개선하세요.

여러분만의 AI 팀을 성공적으로 만들기를 바랍니다!

---