🎓 유데미 강의 추천
Claude Code 실전 강의 — AI 코딩을 지금 시작하세요
설치부터 자동화·에이전트 활용까지, 실무에서 바로 쓰는 Claude Code 활용법을 단계별로 배울 수 있습니다.
강의 보러가기 →
Claude Code 가이드 #5 — 에이전트 & 서브에이전트
Claude Code의 에이전트 시스템은 2026년 들어 대폭 강화되었습니다. 기존 서브에이전트에 더해 Agent Teams (2026.02 출시)가 추가되어, 여러 에이전트가 협업하는 멀티에이전트 워크플로우가 가능해졌습니다. 🎓 유데미 강의 추천 Claude Code 실전 강의 — AI 코딩을 지금 시작하세요 설치부터 자동화·에이전트 활용까지, 실무에서 바로 쓰는 Claude Code 활용법을 단계별로 배울 수 있습니다.
by Lee
Claude Code의 에이전트 시스템은 2026년 들어 대폭 강화되었습니다. 기존 서브에이전트에 더해 Agent Teams(2026.02 출시)가 추가되어, 여러 에이전트가 협업하는 멀티에이전트 워크플로우가 가능해졌습니다. 이 편에서는 서브에이전트부터 Agent Teams까지 전체 에이전트 시스템을 정리합니다.
강의 보러가기 →
에이전트 시스템 개요
Claude Code의 에이전트는 세 가지 레벨로 구분됩니다.
- 메인 에이전트: 사용자와 직접 대화하는 기본 Claude Code 인스턴스
- 서브에이전트: 메인 에이전트가 특정 작업을 위임하는 하위 에이전트. 독립 컨텍스트에서 실행
- Agent Teams: 여러 에이전트가 역할을 나누어 협업하는 팀 단위 시스템 (2026.02~)
💡 핵심 차이: 서브에이전트는 메인 에이전트의 "도구"로 동작하고, Agent Teams는 독립적인 에이전트들이 서로 통신하며 협업합니다. 서브에이전트는 서브에이전트를 생성할 수 없지만, Agent Teams의 멤버는 각자 서브에이전트를 가질 수 있습니다.
서브에이전트 — 작업 위임
서브에이전트는 마크다운 프론트매터로 정의됩니다. .claude/agents/ 디렉토리에 파일을 생성하고, /agents 명령어로 목록을 확인합니다.
에이전트 파일 예시 (.claude/agents/security-reviewer.md)--- name: Security Reviewer model: claude-sonnet-4-6 tools: - Read - Grep - Glob --- # 역할 코드의 보안 취약점을 검토합니다. # 체크리스트 - SQL 인젝션 - XSS - 인증/인가 이슈 - 하드코딩된 시크릿 - OWASP Top 10
서브에이전트의 핵심 특성:
- 메인 에이전트와 별도 컨텍스트에서 실행 (메인 컨텍스트 오염 방지)
- 지정된 도구만 사용 가능 (보안 격리)
- 서브에이전트는 서브에이전트를 생성할 수 없음 (무한 재귀 방지)
- 결과를 메인 에이전트에 반환하여 취합
병렬 리뷰 실행claude --agent security-reviewer.md review src/ claude --agent performance-reviewer.md review src/ claude --agent style-reviewer.md review src/
⚠️ 막히는 케이스: 서브에이전트가 무한 루프처럼 보이면, 에이전트 파일의 역할 정의가 모호하기 때문입니다. "XX를 찾아서 YY 형식으로 보고하라"처럼 종료 조건을 명확히 하세요.
Agent Teams — 멀티에이전트 협업
Agent Teams는 2026년 2월에 출시된 실험적 기능입니다. 여러 에이전트가 각자 역할을 맡아 동시에 작업하고, 서로 메시지를 주고받으며 협업합니다.
Agent Teams 활성화# 환경 변수로 실험 기능 활성화 export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Agent Teams의 핵심 구성요소:
- 팀 리더: 작업을 분배하고 결과를 취합하는 코디네이터 역할
- 팀 멤버: 각자 전문 영역(프론트엔드, 백엔드, 테스트 등)을 담당
- 메시지 버스: 에이전트 간 통신 채널. 진행 상황 공유, 질문, 결과 전달
- 태스크 보드: 전체 작업의 진행 상태를 추적
⚠️ 막히는 케이스: Agent Teams가 활성화되지 않는다면 환경 변수 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1을 확인하세요. 아직 실험 단계이므로 기본 비활성화 상태입니다.
Agent SDK — 커스텀 에이전트 빌드
더 복잡한 에이전트 시스템이 필요하면 Claude Agent SDK(TypeScript/Python)를 사용합니다. 커스텀 도구, 외부 API 연동, 복잡한 워크플로우를 프로그래밍 방식으로 구축할 수 있습니다.
Agent SDK 기본 구조 (TypeScript)import { Agent } from '@anthropic-ai/claude-agent-sdk'; const reviewer = new Agent({ name: 'Code Reviewer', model: 'claude-sonnet-4-6', tools: ['read_file', 'search'], instructions: 'Review code for bugs and suggest fixes.' }); const result = await reviewer.run('Review the auth module');
Agent SDK는 Claude Code의 에이전트 파일(.md)보다 유연하지만, 설정이 복잡합니다. 단순 작업은 에이전트 파일, 프로덕션 파이프라인은 Agent SDK를 권장합니다.
에이전트 방식 비교
| 항목 | 서브에이전트 | Agent Teams | Agent SDK |
|---|---|---|---|
| 설정 난이도 | 낮음 (.md 파일) | 중간 (환경 변수 + 팀 구성) | 높음 (코드 작성) |
| 에이전트 간 통신 | 불가 (결과만 반환) | 메시지 버스 | 완전 커스텀 |
| 재귀 생성 | 불가 | 멤버별 서브에이전트 가능 | 제한 없음 |
| 적합한 상황 | 단일 작업 위임 | 팀 단위 협업 | 프로덕션 파이프라인 |
| 상태 | 정식 | 실험적 (2026.02~) | 정식 |
⚠️ 막히는 케이스: AGENTS.md를 자동 생성하면 오히려 비용이 약 20% 증가한다는 보고가 있습니다. 에이전트 파일은 실제 필요한 역할만 수동으로 정의하세요.
다음 편에서는 GitHub Actions 연동을 다룹니다. PR 자동 리뷰와 CI/CD 통합을 설정하는 방법을 알아봅니다.
🎓 관련 강의
Claude Code 완전 정복 — 유데미 강의
이 글에서 다룬 내용을 더 체계적으로 배우고 싶다면 강의를 확인해보세요. 실전 예제 중심으로 구성되어 있습니다.
강의 살펴보기 →
자주 묻는 질문
Claude Code 가이드 #5, 한 줄로 정리하면 어떻게 되나요?
Claude Code 의 에이전트는 메인·서브에이전트·Agent Teams 세 레벨로 나뉩니다. 단일 작업 위임은 .claude/agents/ 에 .md 파일 하나로 끝나는 서브에이전트, 여러 에이전트가 메시지 버스로 협업하는 건 실험 단계의 Agent Teams, 프로덕션 파이프라인은 코드로 짜는 Agent SDK 가 맞습니다. 정리하면 작업의 복잡도가 올라갈수록 .md 파일에서 환경변수, 다시 코드 순으로 한 단계씩 올라가 선택하면 됩니다.
실무에서 처음 도입할 때 가장 먼저 확인할 것은 무엇인가요?
먼저 자신에게 필요한 게 어느 레벨인지부터 정하시는 게 좋습니다. 단일 작업 위임이면 .claude/agents/ 에 .md 파일 하나 두고 도구(Read·Grep 등)만 지정하면 끝이고, 팀 단위 협업은 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 환경변수가 켜져 있어야 동작합니다. Agent Teams는 아직 실험 단계라 기본 비활성이라는 점, 그리고 AGENTS.md를 자동 생성하면 비용이 약 20% 늘 수 있다는 점을 처음부터 염두에 두시면 헛도는 시간을 줄입니다.
가장 자주 발생하는 실수나 함정은 무엇인가요?
서브에이전트가 끝나지 않고 무한 루프처럼 도는 경우가 가장 흔합니다. 원인은 역할 정의가 모호해서 종료 조건이 없기 때문이라, 에이전트 .md 파일에 'XX를 찾아서 YY 형식으로 보고하라'처럼 끝나는 지점을 명시해야 합니다. 두 번째는 서브에이전트가 또 서브에이전트를 부를 거라 기대하는 실수인데, 재귀 생성은 막혀 있으니 다단계 위임이 필요하면 Agent Teams나 Agent SDK로 올라가야 합니다.
다른 대안과 비교했을 때 어떤 상황에 적합한가요?
세 방식은 적합한 상황이 분명히 갈립니다. 서브에이전트는 보안 리뷰나 특정 검사처럼 메인 컨텍스트를 더럽히지 않고 한 가지 작업을 위임할 때 적합하고, 도구를 Read·Grep 등으로 제한해 격리할 수 있어 안전합니다. 다만 에이전트끼리 대화가 필요하거나 서브에이전트가 또 다른 에이전트를 부르는 다단계 구조에는 맞지 않습니다. 그런 경우엔 Agent Teams 가 답이지만 아직 실험 기능이라 안정성이 필요한 운영 환경에는 부적합하고, 재현성과 외부 API 연동이 중요한 프로덕션 파이프라인이라면 설정이 복잡해도 Agent SDK 로 가야 합니다. 반대로 일회성 단순 작업에 Agent Teams 나 SDK 를 꺼내면 과한 설정 비용만 치르게 되니, 가장 가벼운 .md 서브에이전트부터 시작하시길 권합니다.
더 깊게 공부하려면 어떤 자료를 보면 좋을까요?
두 곳을 추천합니다. 가벼운 서브에이전트 정의는 Claude Code 공식 문서의 subagents 페이지(code.claude.com/docs)에서 .md 프론트매터의 name·model·tools 필드 규칙과 /agents 명령 사용법을 정확히 익히는 것이 빠릅니다. 그 위 단계로 코드 기반 에이전트를 직접 만들고 싶다면 Claude Agent SDK 문서를 보세요. 깃허브의 anthropics/claude-agent-sdk-typescript 저장소 예제를 따라 Agent 클래스에 커스텀 tools 와 instructions 를 붙여보면 .md 파일로는 안 되는 외부 API 연동과 복잡한 워크플로우 제어가 어떻게 가능한지 감이 잡힙니다.
claude-code클로드 코드에이전트서브에이전트코드리뷰
