Claude Code 서브에이전트 튜토리얼: 나만의 AI 팀 만들기
Developers Digest 데모를 프레임별로 따라 해 보세요. /agents 마법사로 서브에이전트를 만들고, 각자에게 전용 도구와 시스템 프롬프트를 부여한 뒤, 조사 에이전트와 프론트엔드 에이전트가 랜딩 페이지를 함께 완성하는 과정을 확인합니다.
요약
- Claude Code에서 /agents를 입력해 에이전트 패널을 열고 1분 안에 첫 서브에이전트를 만들 수 있습니다.
- 각 서브에이전트는 .claude/agents/의 단일 markdown 파일이며 name, description, 도구 목록, system prompt를 담습니다.
- Claude로 에이전트를 생성한 뒤 Firecrawl, Context7 같은 MCP 서버를 포함한 도구 권한을 좁히고 터미널 색상을 고릅니다.
- 데모에서는 웹 조사 서브에이전트와 Next.js 프론트엔드 서브에이전트가 AI 뉴스를 조사하고 SaaS 랜딩 페이지를 엔드투엔드로 완성합니다.
Claude Code NEW Sub Agents in 7 Minutes
영상 출처:Developers Digest7:10
Create subagents — Claude Code official docs
공식 문서 ·:Anthropic
스크린샷은 Developers Digest 워크스루에서 가져왔으며, 용어와 파일 규칙은 Anthropic 공식 sub-agents 문서와 대조했습니다.
모든 스크린샷의 저작권은 Developers Digest에 있으며 튜토리얼 설명을 위해서만 사용합니다. 타임스탬프로 원본 영상으로 이동할 수 있습니다.
Claude Code 서브에이전트 단계별 만들기
파트 1 · /agents로 첫 서브에이전트 만들기
- 1
/agents로 에이전트 패널 열기
Claude Code 세션에서 /agents를 입력하고 Create new agent를 선택합니다. 패널에는 기존 서브에이전트 목록과 항상 사용 가능한 내장 general-purpose 에이전트가 표시됩니다.
슬래시 명령 하나로 에이전트 관리자에 진입합니다.영상 0:30 보기 - 2
프로젝트 또는 개인 범위 선택
1단계에서는 에이전트의 위치를 정합니다. Project(.claude/agents/)는 저장소 안에, Personal(~/.claude/agents/)은 머신의 모든 프로젝트에서 사용할 수 있게 합니다.
프로젝트 에이전트는 저장소에 커밋할 수 있고, 개인 에이전트는 어디서든 따라옵니다.영상 0:46 보기 - 3
Claude에게 에이전트 생성 맡기기
2단계에서는 Generate with Claude(권장) 또는 Manual configuration을 고릅니다. 영상에서는 Next.js, Tailwind, ShadCN/UI 전문가인 프론트엔드 담당자를 요청했고 Claude가 전체 구성을 작성합니다.
역할을 한 줄로 설명하면 Claude가 파일을 작성해 줍니다.영상 1:05 보기 - 4
도구 권한 범위 정하기
4단계에서는 에이전트가 다룰 도구를 묶음으로 선택합니다. All tools, Read-only tools, Edit tools, Execution tools, MCP & Other tools. 개별 해제도 가능하고, 데모처럼 전부 허용할 수도 있습니다.
프론트엔드는 전체 권한, 백엔드는 DB와 로그만 주는 식의 설계도 가능합니다.영상 1:36 보기 - 5
터미널 색상 지정하기
팔레트에서 배경색을 고릅니다. Red, Blue, Green, Orange, Yellow, Purple, Pink, Cyan, Automatic이 있으며 미리보기로 대화 속 에이전트 이름 칩의 모습을 확인할 수 있습니다.
색상 덕분에 어떤 전문가가 실행 중인지 한눈에 보입니다.영상 1:48 보기 - 6
생성된 프롬프트 검토 후 저장
확인 화면에는 위임 판단에 쓰이는 description, 전체 system prompt, 경고가 표시됩니다. 데모에서는 description가 400자를 넘는다는 경고가 떴습니다. Enter로 저장합니다.
나중에 얼마든지 수정할 수 있는 평범한 markdown 파일입니다.영상 2:15 보기
파트 2 · 에이전트 파일과 두 번째 전문가
- 7
.claude/agents에서 markdown 파일 찾기
모든 서브에이전트는 하나의 markdown 파일로 존재합니다. 데모는 Finder에서 프로젝트를 열어 숨김 폴더 .claude/agents와 그 안의 nextjs-tailwind-shadcn-engineer.md를 보여 줍니다. 저장소에 커밋할 수 있습니다.
첫 에이전트를 저장하면 이 폴더가 나타납니다.영상 3:10 보기 - 8
웹 조사 전문가 추가하기
같은 흐름으로 두 번째 에이전트를 만듭니다. 이번에는 필요한 MCP 도구만 선택합니다. Firecrawl 서버의 scrape, map, search 세 가지이며 카운터는 25개 중 3개 선택을 표시합니다.
좁은 도구 목록은 각 에이전트를 집중적이고 예측 가능하게 만듭니다.영상 3:36 보기 - 9
저장 전에 프론트매터 확인하기
확인 화면에는 Name: web-research-specialist, Location: .claude/agents/web-research-specialist.md, 세 개의 mcp__mcp-server-firecrawl__ 도구, description, system prompt가 나열됩니다.
프론트매터와 본문은 Claude가 초안을 쓰며 언제든 조정할 수 있습니다.영상 3:42 보기
파트 3 · 실제 조사·빌드 작업 위임하기
- 10
실제 빌드 위임하기
가격표와 FAQ를 갖춘 SaaS 랜딩 페이지를 요청하되, 메인 영역에는 2025년 7월 top 5 AI 뉴스를 조사해 보여 달라고 하고, 코드 작성 전에 웹 조사를 먼저 하라고 지시합니다.
프롬프트 하나가 방금 만든 팀 전체로 분배됩니다.영상 4:26 보기 - 11
Claude의 오케스트레이션 지켜보기
Claude는 요청을 다단계 계획으로 나누고, web-research-specialist 에이전트를 먼저 실행한 뒤 nextjs-tailwind-shadcn-engineer 에이전트에게 빌드를 넘기며, todo 리스트로 전 과정을 추적합니다.
각 프론트매터의 description가 위임 시점을 결정합니다.영상 4:28 보기 - 12
조사 결과 수집하기
web-research-specialist는 도구 10회 사용, 22.5k 토큰, 약 2분 만에 조사를 마치고, Claude Code는 todo 리스트의 조사 항목에 취소선을 긋고 다음 단계로 넘어갑니다.
새로운 사실이 컨텍스트로 메인 대화에 흘러 들어갑니다.영상 4:38 보기
파트 4 · 빌드 단계와 결과물
- 13
프론트엔드 에이전트에게 빌드 맡기기
nextjs-tailwind-shadcn-engineer 에이전트가 인수하여 앱·컴포넌트 파일과 설정을 작성하고 npm run dev를 실행합니다. 메인 대화는 marinating 상태를 유지합니다.
무거운 파일 편집은 서브에이전트 자신의 컨텍스트에서 일어납니다.영상 4:45 보기 - 14
완성된 사이트 검토하기
결과물은 Developer's Digest 랜딩 페이지입니다. 조사한 5개 AI 뉴스로 구성된 히어로, 3단계 가격표, 작동하는 FAQ 아코디언, 다크 모드까지 요청 그대로 완성됩니다.
전문가들이 빌드하는 동안 메인 대화는 큰 그림에 집중했습니다.영상 6:12 보기
거대 프롬프트 하나 vs 서브에이전트 팀
| 역량 | 거대한 시스템 프롬프트 하나 | 서브에이전트 팀 |
|---|---|---|
| 컨텍스트 | 하나의 대화에 모든 것이 쌓여 화제가 흐려집니다. | 각 서브에이전트는 자신만의 깨끗한 컨텍스트 창에서 작업합니다. |
| 지시 | 모든 규칙을 단일 프롬프트에 욱여넣어야 합니다. | 에이전트마다 전용 시스템 프롬프트를 주고 점진적으로 키울 수 있습니다. |
| 도구 | 모든 도구가 항상 활성화됩니다. | 에이전트별 허용 목록. Firecrawl, Context7 같은 MCP 서버도 포함할 수 있습니다. |
| 재사용 | 프로젝트 간 지시를 손으로 복사·붙여넣기 합니다. | 저장소에 커밋하거나 전역으로 설치할 수 있는 markdown 파일. |