👥 AI 에이전트 팀 — 여러 Claude가 동시에 일하기 — 클로드 코드 무료 학습

서브에이전트란? — 부하직원에게 일 시키기

회사에서 팀장이 모든 일을 혼자 하진 않잖아요? 간단한 일은 팀원한테 “이거 해놓고 결과만 줘” 하고 넘기죠. 그 사이에 팀장은 다른 일을 해요.

Claude Code에서도 똑같아요. 메인 Claude(팀장)가 서브에이전트(팀원)를 만들어서 일을 시키고, 결과만 받아요. 이게 바로 Agent 도구예요.

회사	Claude Code
팀장	메인 Claude (대화 중인 Claude)
팀원	서브에이전트 (Agent 도구로 생성)
"이 보고서 정리해놔"	"이 파일 분석해서 요약해줘"
팀원이 결과물 전달	서브에이전트가 결과 반환
팀장은 그 사이 다른 일	메인 Claude는 다른 작업 계속

서브에이전트는 메인 Claude가 알아서 만들어요. 여러분이 직접 만들 필요 없어요. “이 폴더 분석해줘”라고 말하면, Claude가 복잡하다고 판단되면 자동으로 서브에이전트를 띄워서 처리해요.

서브에이전트가 생기는 과정

여러분이 Claude에게 작업 지시

"이 프로젝트의 README를 분석해서 요약해줘"

메인 Claude가 판단

"이건 별도로 처리하는 게 효율적이겠다"

서브에이전트 생성 (Agent 도구)

새로운 Claude가 생겨서 해당 작업만 집중 처리

결과 반환

서브에이전트가 완료되면 메인 Claude에게 결과 전달

서브에이전트의 핵심 특징

🕵

독립 실행

서브에이전트는 자기만의 컨텍스트에서 작업해요. 메인 대화에 영향을 주지 않아요.

🚀

병렬 처리

여러 서브에이전트를 동시에 띄울 수 있어요. 파일 5개를 동시에 분석하는 것도 가능해요.

📦

결과만 전달

서브에이전트가 중간에 뭘 했는지는 중요하지 않아요. 최종 결과만 메인 Claude에게 돌아와요.

💡

자동 생성

여러분이 직접 만들 필요 없어요. Claude가 필요하다고 판단하면 알아서 만들어요.

서브에이전트가 자동으로 생기는 프롬프트 예시

src 폴더에 있는 모든 TypeScript 파일을 분석해서
각 파일의 역할을 한 줄로 요약해줘.

# Claude가 파일이 많으면 자동으로 서브에이전트를 띄워서
# 각 파일을 병렬로 분석해요.

한 줄 요약

서브에이전트 = 메인 Claude의 부하직원. 복잡한 작업을 나눠서 처리하고, 결과만 보고해요. 여러분은 그냥 시키면 돼요.

에이전트 팀이란? — 프로젝트 팀 구성하기

서브에이전트가 “부하직원 한 명한테 일 시키기”라면, 에이전트 팀은 “프로젝트 팀 전체를 구성하기”예요. 팀장이 작업을 나누고, 여러 팀원이 각자 맡은 부분을 동시에 처리하는 거예요.

회사에서 신제품 런칭할 때를 생각해보세요. 디자이너는 디자인, 개발자는 코드, 마케터는 홍보를 동시에 하잖아요? 에이전트 팀도 이와 똑같아요.

프로젝트 팀	에이전트 팀
팀 구성 회의	리드가 팀원(독립 세션) 생성
업무 분배	공유 태스크 리스트에서 작업 배분
팀원 간 소통	팀원끼리 직접 메시지 교환
각자 담당 파트 작업	에이전트가 병렬로 동시 작업
결과물 취합	리드가 결과를 종합

에이전트 팀의 작동 방식

팀 생성 요청

"3명으로 팀 만들어줘" 같이 자연어로 요청하면 리드가 팀원(독립 세션)을 생성해요.

공유 태스크 리스트로 작업 배분

리드가 태스크를 만들면, 팀원들이 각자 가져가서 작업해요.

팀원 간 직접 소통

팀원끼리 메시지를 주고받으며 정보를 공유하고 조율해요.

병렬 실행 + 결과 종합

모든 팀원이 각자의 독립 세션에서 동시에 작업하고, 리드가 결과를 모아요.

에이전트 팀을 요청하는 프롬프트 예시

에이전트 팀을 만들어서 이 프로젝트를 리팩토링해줘.
- TypeScript 변환 담당 1명
- Tailwind 마이그레이션 담당 1명
- 테스트 코드 담당 1명

각자 동시에 진행해줘.

# "에이전트 팀을 만들어서"라고 직접 요청해야 해요.
# Claude가 팀을 제안할 수도 있지만, 승인은 여러분이 해요.

에이전트 팀은 언제 활성화되나요?

에이전트 팀은 현재 실험적 기능이에요. 기본적으로 비활성화되어 있고, 설정에서 직접 켜야 사용할 수 있어요. 팀이 필요한 규모의 작업을 요청하면 Claude가 팀 구성을 제안하고, 여러분이 승인하면 팀이 만들어져요. 자동으로 생기지는 않아요.

에이전트 팀 = 나만의 프로젝트 팀

팀장(여러분)이 지시하면, 팀원(에이전트)들이 동시에 일해요

언제 팀이 필요할까?

모든 작업에 에이전트 팀이 필요한 건 아니에요. 간단한 작업은 서브에이전트 하나로 충분하고, 규모가 큰 작업만 팀이 필요해요. 구분하는 기준은 간단해요.

서브에이전트면 충분한 경우

결과만 필요한 집중 작업

“이 함수의 버그 고쳐줘”

독립적인 작업

“이 파일 분석해서 요약해줘”

에이전트 팀이 필요한 경우

토론/협업이 필요한 작업

“보안, 성능, 테스트 관점에서 동시에 리뷰해줘”

여러 가설을 동시에 탐색

“버그 원인을 여러 각도에서 동시에 조사해줘”

에이전트 팀이 빛나는 실전 시나리오

🔍

다각도 리서치 & 리뷰

보안, 성능, 테스트 커버리지를 각각 다른 팀원이 동시에 검토하고 발견 결과를 공유해요.

🛠

새 모듈/기능 개발

프론트엔드, 백엔드, 테스트를 각각 다른 팀원이 독립적으로 동시에 작업해요.

🐛

경쟁 가설 디버깅

버그 원인에 대해 여러 가설을 동시에 테스트하고, 팀원끼리 서로의 가설을 검증해요.

🌐

크로스 레이어 작업

프론트, 백엔드, 테스트 등 여러 계층에 걸친 변경을 각 담당자가 동시에 조율하며 작업해요.

서브에이전트는 자동, 에이전트 팀은 요청

서브에이전트는 Claude가 알아서 만들어요. 하지만 에이전트 팀은 여러분이 “팀을 만들어서 처리해줘”라고 요청해야 해요. Claude가 팀이 필요하다고 판단하면 제안할 수도 있지만, 여러분의 승인 없이 팀이 만들어지지는 않아요.

커스텀 에이전트 만들기 — 나만의 전문가 팀

지금까지는 Claude가 알아서 서브에이전트를 만들었어요. 그런데 여기서 한 단계 더 나아갈 수 있어요.내가 원하는 전문가를 미리 정의해둘 수 있거든요.

회사에 “코드 리뷰 전담” 팀원이 있으면 편하잖아요? Claude Code에서도 커스텀 에이전트를 만들어서 특정 역할을 전담하게 할 수 있어요.

만드는 법 — 파일 하나면 끝

프로젝트 폴더에 .claude/agents/ 폴더를 만들고, 그 안에 마크다운 파일(.md)을 하나 만들면 돼요. 파일 이름이 곧 에이전트 이름이에요.

폴더 구조

내 프로젝트/
├── .claude/
│   └── agents/
│       ├── code-reviewer.md    ← 코드 리뷰 전문가
│       ├── doc-writer.md       ← 문서 작성 전문가
│       └── deploy-expert.md    ← 배포 전문가
├── src/
└── package.json

에이전트 파일 작성법

.md 파일 안에 YAML 머리말(frontmatter)로 설정을 적고, 본문에 에이전트의 역할과 규칙을 적어주면 돼요. 필수 항목은 name과 description이에요. description이 Claude가 “이 에이전트를 언제 호출할지” 판단하는 기준이거든요. 추가로 tools(사용 도구), model(사용 모델) 등을 지정할 수 있어요.

code-reviewer.md 예시

---
name: code-reviewer
description: 코드 변경사항을 검토하고 버그, 보안 취약점, 개선점을 찾아줍니다.
tools: Read, Grep, Glob, Bash
model: sonnet
---

# 코드 리뷰어

## 역할
- 코드 변경사항을 꼼꼼히 검토
- 버그 가능성이 있는 코드 찾기
- 보안 취약점 체크
- 성능 개선점 제안

## 규칙
- 항상 구체적인 파일명과 라인 번호를 명시
- 심각도를 3단계로 분류 (높음/중간/낮음)
- 수정 제안은 코드 예시와 함께 제공
- 칭찬할 점도 반드시 언급

doc-writer.md 예시

---
name: doc-writer
description: 코드를 분석해서 README, API 문서, 사용 가이드를 작성합니다.
tools: Read, Grep, Glob
model: haiku
---

# 문서 작성자

## 역할
- 코드를 읽고 이해하기 쉬운 문서 작성
- README.md 자동 생성 및 업데이트
- API 엔드포인트 문서화
- 설치/사용 가이드 작성

## 규칙
- 한국어로 작성 (코드 용어는 영어 유지)
- 비개발자도 이해할 수 있는 수준으로
- 실행 가능한 예시 코드 반드시 포함
- 마크다운 형식, 목차 포함

deploy-expert.md 예시

---
name: deploy-expert
description: 프로젝트를 Vercel, GitHub Pages 등에 배포하고 CI/CD를 설정합니다.
---

# 배포 전문가

## 역할
- 프로젝트 빌드 및 배포
- CI/CD 파이프라인 설정
- 환경 변수 관리
- 배포 후 검증

## 규칙
- 배포 전 반드시 빌드 테스트 실행
- 환경 변수는 .env에서만 관리
- 배포 후 실제 URL에서 동작 확인
- 롤백 방법도 함께 안내

description이 호출의 핵심이에요

description 한 줄이 가장 중요해요. Claude는 이 설명을 보고 “이 에이전트를 호출할까 말까”를 결정하거든요. 마치 회사에서 팀원의 직무 기술서(JD)를 보고 적합한 사람한테 일을 배분하는 것과 같아요.

좋은 description

코드 변경사항을 검토하고 버그, 보안 취약점, 개선점을 찾아줍니다.— 언제 호출해야 하는지 명확해요.

나쁜 description

유용한 도우미입니다.— 너무 모호해서 Claude가 언제 호출할지 판단할 수 없어요.

커스텀 에이전트를 사용하는 2가지 방법

1. 자동 호출

description에 맞는 작업을 요청하면 Claude가 알아서 해당 에이전트를 호출해요.

이 PR을 리뷰해줘.

# Claude가 code-reviewer 에이전트를
# 자동으로 호출해서 처리해요.

2. 이름 지정 호출

대화에서 에이전트 이름을 직접 언급하면 Claude가 해당 에이전트를 호출해요.

code-reviewer 서브에이전트로 이 커밋을 검토해줘.

# code-reviewer 에이전트가
# 직접 호출돼서 처리해요.

실용적인 커스텀 에이전트 아이디어

보고서 작성자 — 데이터를 분석해서 HTML 보고서를 만들어요.
번역가 — 코드 주석과 문서를 한영 번역해요.
테스트 전문가 — 코드에 맞는 테스트를 자동 생성해요.
리팩토링 전문가 — 코드를 깔끔하게 정리해요.

서브에이전트 vs 에이전트 팀 — 뭘 써야 하나?

서브에이전트와 에이전트 팀, 비슷해 보이지만 용도가 달라요. 핵심 차이를 한눈에 비교해볼게요.

항목	서브에이전트 (Agent)	에이전트 팀 (Agent Teams)
비유	부하직원 1명에게 일 시키기	프로젝트 팀 전체를 구성하기
구조	메인 세션 안에서 실행	각자 독립된 세션으로 실행
소통	결과만 메인 Claude에게 보고	팀원끼리 직접 메시지 교환
조율	메인 Claude가 관리	공유 태스크 리스트로 자기 조율
활성화	Claude가 자동으로 생성	사용자가 요청해야 생성 (실험 기능)
토큰 사용량	적음 (요약만 반환)	많음 (각 팀원이 독립 인스턴스)
적합한 상황	결과만 필요한 집중 작업	토론/협업이 필요한 복잡한 작업

한눈에 보는 판단 기준

“결과만 필요한 집중 작업” → 서브에이전트

✓ 이 폴더 분석해서 요약해줘
✓ 테스트 돌리고 실패한 것만 알려줘
✓ 이 코드 TypeScript로 변환해줘
✓ 여러 파일을 병렬로 리서치해줘

“토론/협업이 필요한 작업” → 에이전트 팀

✓ 보안/성능/테스트 관점에서 동시에 PR 리뷰
✓ 버그 원인을 여러 가설로 동시에 조사
✓ 프론트 + 백엔드 + 테스트를 각자 담당
✓ 서로 발견한 내용을 공유하고 검증

커스텀 에이전트는 어디에 해당하나요?

커스텀 에이전트는 서브에이전트의 한 종류예요. 기본 서브에이전트(Explore, Plan 등)는 Claude가 자동으로 만들지만, 커스텀 에이전트는 여러분이 미리 정의해둔 전문가를 Claude가 호출하는 거예요. 에이전트 팀과는 별개의 기능이에요.

구분	기본 서브에이전트	커스텀 서브에이전트
정의 방법	Claude에 내장 (Explore, Plan 등)	내가 .md 파일로 미리 정의
전문성	범용 (탐색, 계획 등 일반 용도)	특화 (역할/규칙/도구를 내가 지정)
모델 선택	자동 (Explore=Haiku 등)	내가 지정 가능 (Haiku, Sonnet, Opus)
재사용	항상 사용 가능	프로젝트 또는 사용자 수준에서 계속 사용
설정 시간	0초 (내장)	5분 (파일 한 개 작성, 또는 /agents 명령어)

결론은 간단해요

집중 작업은 서브에이전트 (자동), 토론/협업이 필요한 작업은 에이전트 팀 (요청 필요), 자주 반복되는 전문 작업은 커스텀 서브에이전트. 서브에이전트는 Claude가 알아서 쓰고, 커스텀 서브에이전트만 미리 만들어두면 돼요. 에이전트 팀은 정말 큰 작업에서 직접 요청해보세요.

집중 작업 = 서브에이전트 • 협업 = 팀 • 반복 작업 = 커스텀

서브에이전트는 자동, 에이전트 팀은 요청, 커스텀은 미리 만들어두기

직접 해보기

읽기만 하면 감이 안 잡혀요. 아래 실습을 따라해보세요.

실습 1: 서브에이전트 체험 (가장 쉬움)

아무 프로젝트 폴더에서 Claude Code를 실행하고 아래 프롬프트를 입력해보세요. Claude가 서브에이전트를 만들어서 병렬로 분석하는 걸 볼 수 있어요.

프롬프트 입력

이 프로젝트의 모든 파일을 분석해서
각 파일이 뭐 하는 파일인지 한 줄로 요약해줘.
표로 정리해줘.

파일이 5개 이상이면 Claude가 서브에이전트를 자동 생성해요. 터미널에서 “Agent”라는 표시가 보이면 성공이에요!

실습 2: 커스텀 에이전트 만들기

나만의 전문가 에이전트를 만들어봐요. Claude Code에 이렇게 말하면 돼요.

커스텀 서브에이전트 생성 (방법 1: /agents 명령어)

/agents
# → "Create new agent" 선택
# → User-level 또는 Project-level 선택
# → Claude에게 역할 설명하면 자동 생성

커스텀 서브에이전트 생성 (방법 2: 직접 파일 생성)

.claude/agents/ 폴더에 report-writer.md 파일을 만들어줘.

역할: 데이터를 분석해서 예쁜 HTML 보고서를 만드는 전문가
규칙:
- 항상 차트와 표를 포함
- 한국어로 작성
- 핵심 인사이트를 3줄로 요약
- 깔끔한 디자인 (그라데이션 + 카드 레이아웃)

/agents 명령어가 가장 쉬운 방법이에요. 파일이 생기면, “이 CSV를 분석해서 보고서 만들어줘”라고 하면 자동으로 이 에이전트가 호출돼요.

실습 3: 에이전트 팀 체험 (도전, 실험 기능)

에이전트 팀은 실험적 기능이라 먼저 설정에서 활성화해야 해요. 그 후 팀 구성을 직접 요청해보세요.

에이전트 팀 요청

에이전트 팀을 만들어서 이 프로젝트를 개선해줘.
- 한 명은 TypeScript 변환 담당
- 한 명은 문서(README, CHANGELOG) 담당
- 한 명은 테스트 코드 담당

각자 동시에 진행해줘.

에이전트 팀을 쓰려면 설정에서 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS를 활성화해야 해요. Claude가 팀 구성을 제안하면 승인하고, 각 팀원이 어떻게 작업하는지 관찰해보세요.

확인 체크리스트

서브에이전트가 자동 생성되는 걸 확인했다.claude/agents/ 폴더에 커스텀 에이전트를 만들었다커스텀 에이전트가 실제로 호출되는 걸 봤다서브에이전트가 병렬로 작업하는 걸 확인했다

에이전트가 생기는 걸 못 봤다면, 파일이 너무 적은 걸 수도 있어요. 파일이 5개 이상인 프로젝트에서 해보세요. 없으면 mkdir test-project으로 폴더를 만들고 파일 10개를 먼저 생성해달라고 한 뒤 분석을 시키면 돼요.

활용 팁 + 출처

에이전트 팀을 효과적으로 쓰기 위한 실용 팁들이에요.

1. 작업 범위를 명확하게

“이 프로젝트 좀 고쳐줘”보다 “src 폴더의 모든 .js 파일을 .ts로 변환하고 타입을 추가해줘”가 훨씬 좋은 결과를 만들어요. 에이전트에게 일을 시킬 때도 구체적일수록 좋아요.

2. 커스텀 에이전트는 점진적으로

처음부터 에이전트 10개를 만들 필요 없어요. 자주 반복하는 작업이 생기면 그때 하나씩 만드세요. 코드 리뷰를 자주 한다? code-reviewer.md 하나 만들면 돼요.

3. description을 자주 다듬으세요

커스텀 에이전트가 호출이 안 되거나, 엉뚱한 상황에서 호출되면 description을 수정해보세요. Claude가 이 한 줄로 판단하기 때문에, 명확하고 구체적으로 쓰는 게 중요해요.

4. 토큰 사용량을 체크하세요

에이전트 팀은 여러 Claude가 동시에 작동하기 때문에 토큰을 많이 사용해요. 토큰 한도가 부족하면 작업을 작게 나눠서 시키세요./cost 명령어로 사용량을 확인할 수 있어요.

5. 에이전트 간 파일 충돌 주의

서브에이전트든 에이전트 팀이든, 여러 에이전트가 같은 파일을 동시에 수정하면 충돌이 날 수 있어요. “A는 프론트만, B는 백엔드만” 처럼 작업 영역을 명확하게 나눠주면 충돌을 예방할 수 있어요.

6. 커스텀 에이전트를 팀과 공유하기

.claude/agents/ 폴더를 Git에 커밋하면 팀원 모두가 같은 커스텀 에이전트를 쓸 수 있어요. 팀 전체의 작업 품질이 올라가요. 코드 리뷰 기준, 문서 작성 규칙 등을 에이전트로 통일할 수 있죠.

실수	결과	해결법
모호한 description	에이전트가 호출 안 됨	구체적인 역할 + 상황 서술
너무 많은 에이전트	Claude가 헷갈림	핵심 5개 이하로 유지
같은 파일 동시 수정	코드 충돌	작업 영역을 명확히 분리
컨텍스트 한도 초과	서브에이전트 결과가 잘림	에이전트 팀으로 전환 고려
커스텀 에이전트 Git 미포함	팀원이 못 씀	.claude/agents/ 폴더를 커밋

AI 에이전트 팀 = 나만의 자동화 부서

서브에이전트로 간단한 일을 위임하고, 에이전트 팀으로 대규모 작업을 동시에 처리하고, 커스텀 에이전트로 전문가를 미리 배치하세요.

하나만 기억하세요

여러분은 “팀장”이에요. 작업을 지시하면 Claude가 팀을 구성하고, 에이전트들이 동시에 일하고, 결과만 여러분에게 보고해요. 팀장은 일을 시키는 것이지, 직접 하는 게 아니에요. 시키는 연습을 하세요.

참고 자료

서브에이전트 (Custom Subagents) — code.claude.com/docs/en/sub-agents
에이전트 팀 (Agent Teams, 실험 기능) — code.claude.com/docs/en/agent-teams
기능 비교 (Subagent vs Agent Team) — code.claude.com/docs/en/features-overview