Claude Code 에이전트 시스템 완벽 가이드 - Sub-Agent, Custom Agent, Skill, Agent Team

Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 도구다. 터미널에서 자연어로 코드를 짜고, 파일을 수정하고, 프로젝트 전체를 관리할 수 있다. 그런데 단순히 "AI한테 코드 짜달라고 하는 도구"로만 쓰면 절반도 활용 못 하는 셈이다. Claude Code의 진짜 힘은 에이전트 시스템에 있다.

Sub-Agent, Custom Agent, Skill, 그리고 최근 추가된 Agent Team까지. 이 네 가지를 이해하면 반복 작업 자동화부터 멀티에이전트 협업까지, 혼자서는 엄두도 못 낼 규모의 작업을 Claude Code 하나로 처리할 수 있다. 이 글에서는 각 개념의 차이, 실전 설정법, 그리고 실제 활용 사례까지 정리한다.

Claude Code란

Claude Code는 Anthropic이 만든 CLI(Command Line Interface) 기반 AI 코딩 에이전트다. VS Code나 JetBrains 같은 IDE가 아니라 터미널에서 직접 동작한다. npm으로 설치하고, 터미널에서 claude 명령어를 입력하면 바로 대화가 시작된다.

단순한 코드 자동완성 도구가 아니다. 파일을 읽고, 수정하고, 새로 만들고, 터미널 명령어를 실행하고, Git 커밋까지 한다. 자연어 한 마디로. 2026년 2월 기준 Claude Pro 플랜($20/월)이면 사용할 수 있고, Max 플랜($100/월)을 쓰면 더 많은 사용량이 주어진다.

여기까지는 다른 AI 코딩 도구와 비슷해 보일 수 있다. Claude Code가 진짜 차별화되는 지점은 에이전트 시스템이다. 작업을 분할하고, 전문 에이전트에게 위임하고, 여러 에이전트가 동시에 협업하는 구조를 직접 설계할 수 있다.

Claude Code 에이전트 시스템 전체 구조

Claude Code의 에이전트 시스템은 크게 4가지 레이어로 나뉜다.

구분	Sub-Agent	Custom Agent	Skill	Agent Team
정의	작업을 병렬 처리하는 하위 에이전트	특화 워크플로우를 자동화하는 커스텀 에이전트	반복 작업을 명령어로 실행하는 스킬	여러 세션이 협업하는 팀 모드
실행 방식	Task tool로 자동 위임	.claude/agents/ 마크다운 파일	.claude/skills/ 또는 .claude/commands/	TeammateTool로 세션 간 조율
컨텍스트	독립 컨텍스트 윈도우	독립 컨텍스트 + 커스텀 시스템 프롬프트	메인 컨텍스트에서 실행	각 세션별 독립 컨텍스트
병렬 처리	최대 7개 동시	1개씩 호출	메인 세션에서 순차 실행	여러 세션 동시 실행
적합한 작업	파일 분석, 검색, 코드 리뷰	테스트 생성, 코드 리뷰, 디버깅	커밋 메시지, 문서 생성, 반복 패턴	대규모 리팩토링, PR 리뷰, 멀티모듈
난이도	자동 (별도 설정 불필요)	중간 (마크다운 파일 작성)	쉬움 (마크다운 파일 1개)	고급 (실험 기능, 설정 필요)

쉽게 말하면 이렇다. Skill은 "나한테 이 일 시키면 이렇게 해"라는 매뉴얼이고, Custom Agent는 "이 분야 전문가를 따로 고용한 것"이고, Sub-Agent는 "일을 쪼개서 여러 명한테 동시에 시키는 것"이고, Agent Team은 "아예 팀을 꾸려서 프로젝트를 돌리는 것"이다.

Sub-Agent - Task tool로 작업을 병렬 처리하기

Sub-Agent는 Claude Code의 Task tool이 자동으로 생성하는 하위 에이전트다. 사용자가 직접 만들 필요 없이, 복잡한 작업을 요청하면 Claude Code가 알아서 작업을 쪼개고 여러 Sub-Agent에게 동시에 위임한다.

Sub-Agent의 동작 원리

예를 들어 "이 프로젝트의 모든 TypeScript 파일에서 사용되지 않는 import를 찾아줘"라고 요청하면, Claude Code는 이렇게 처리한다.

1. 프로젝트 구조를 파악한다
2. 파일 수가 많으면 여러 Sub-Agent를 생성한다
3. 각 Sub-Agent가 담당 파일을 병렬로 분석한다
4. 결과를 모아서 메인 에이전트가 종합한다

최대 7개의 Sub-Agent가 동시에 돌아간다. 혼자 하면 하루 종일 걸릴 분석 작업이 몇 분 만에 끝나는 이유다.

Sub-Agent가 자동 활성화되는 조건

• 분석할 파일이 50개 이상일 때
• 분석할 디렉토리가 7개 이상일 때
• 작업 복잡도가 높다고 판단될 때

별도로 설정할 건 없다. Claude Code가 "이건 쪼개서 하는 게 빠르겠다"고 판단하면 알아서 Sub-Agent를 띄운다. 다만 명시적으로 "병렬로 처리해줘"라고 요청하면 더 적극적으로 활용한다.

Sub-Agent 활용 팁

Sub-Agent 각각은 독립된 컨텍스트 윈도우에서 돌아간다. 메인 대화 내용을 그대로 가져가지 않는다는 뜻이다. 그래서 Sub-Agent에게 위임할 작업은 자기 완결적이어야 한다. "아까 말한 그 파일"처럼 맥락에 의존하는 지시는 잘 안 통한다.

Custom Agent - 전문가 에이전트 직접 만들기

Custom Agent는 특정 업무에 특화된 AI 전문가를 직접 설계하는 기능이다. .claude/agents/ 폴더에 마크다운 파일 하나를 만들면 된다.

Custom Agent 파일 구조

프로젝트 루트에 .claude/agents/ 폴더를 만들고, 마크다운 파일을 넣는다. 파일 형식은 YAML 프론트매터 + 시스템 프롬프트로 구성된다.

예를 들어 코드 리뷰 전문 에이전트를 만든다면 이렇게 작성한다.

---
name: code-reviewer
description: 코드 품질과 보안을 검토하는 리뷰 에이전트
model: sonnet
tools: [Read, Grep, Glob]
---

당신은 시니어 개발자 수준의 코드 리뷰어입니다.

## 리뷰 기준
- 보안 취약점 (SQL injection, XSS 등)
- 성능 이슈 (불필요한 렌더링, N+1 쿼리)
- 코드 컨벤션 준수 여부
- 에러 핸들링 누락

## 출력 형식
파일별로 이슈를 정리하되, 심각도를 높음/중간/낮음으로 표시합니다.

YAML 프론트매터 주요 필드

필드	설명	예시
name	에이전트 이름 (필수)	code-reviewer
description	언제 이 에이전트를 쓸지 설명 (필수)	코드 품질 검토용
model	사용할 모델	opus, sonnet, haiku
tools	허용할 도구 목록	[Read, Grep, Glob, Bash]
disallowedTools	금지할 도구 목록	[Write, Edit]
permissionMode	권한 모드	default, strict, permissive
skills	로드할 스킬 목록	[my-skill]
maxTurns	최대 실행 턴 수	10

Custom Agent 저장 위치

두 가지 옵션이 있다.

• 프로젝트 레벨 - .claude/agents/ 폴더에 저장하면 해당 프로젝트에서만 사용할 수 있다. Git으로 팀과 공유 가능
• 사용자 레벨 - ~/.claude/agents/ 폴더에 저장하면 모든 프로젝트에서 사용할 수 있다. 개인 전용

프로젝트에 종속된 에이전트(테스트 생성기, 코드 리뷰어 등)는 프로젝트 레벨에, 범용 에이전트(블로그 작성, 번역 등)는 사용자 레벨에 두는 게 좋다.

Custom Agent 호출 방법

Claude Code 세션에서 /agents 명령어를 입력하면 등록된 에이전트 목록이 나온다. 거기서 선택하거나, 자연어로 "코드 리뷰해줘"처럼 요청하면 description이 매칭되는 에이전트가 자동으로 활성화된다.

Skill - 반복 작업을 슬래시 커맨드로 만들기

Skill은 Claude Code에서 가장 쉽게 시작할 수 있는 자동화 방법이다. 마크다운 파일 하나만 만들면 슬래시 커맨드(/)로 호출할 수 있는 커스텀 명령어가 된다.

Skill과 Slash Command의 관계

엄밀히 말하면 두 가지 형태가 있다.

• Slash Command (.claude/commands/) - 슬래시 커맨드로 직접 호출하는 단순 프롬프트. 메인 컨텍스트에서 실행된다
• Skill (.claude/skills/) - 더 구조화된 형태. SKILL.md 파일 + 스크립트 + 리소스로 구성된다. Claude가 필요할 때 동적으로 로드한다

Slash Command 만들기

.claude/commands/ 폴더에 마크다운 파일을 만들면 끝이다. 파일명이 곧 명령어 이름이 된다.

예를 들어 커밋 메시지를 자동 생성하는 명령어를 만든다면, .claude/commands/commit.md 파일을 만들고 이렇게 작성한다.

---
description: 변경사항을 분석해서 커밋 메시지를 생성합니다
allowed-tools: [Bash, Read, Grep]
---

현재 staging된 변경사항을 분석하고, Conventional Commits 형식으로 커밋 메시지를 작성해주세요.

## 규칙
- feat, fix, refactor, docs, test 중 적절한 타입 선택
- 제목은 50자 이내
- 본문에 "왜" 변경했는지 설명

이제 Claude Code에서 /commit이라고 입력하면 이 프롬프트가 실행된다.

Skill 만들기 (구조화된 방법)

좀 더 복잡한 자동화가 필요하면 Skill을 쓴다. .claude/skills/ 폴더 아래에 스킬 폴더를 만들고, SKILL.md 파일을 작성한다.

.claude/skills/
  api-test-generator/
    SKILL.md           # 메인 지침서
    scripts/
      generate.py      # 실행 스크립트
    references/
      api-spec.yaml    # 참고 문서
    templates/
      test-template.md # 출력 템플릿

Skill은 3단계로 로드된다. 1단계는 YAML 메타데이터로 항상 로드된다. 2단계는 SKILL.md 본문으로 필요할 때 로드된다. 3단계는 스크립트와 참고 문서로 요청 시에만 로드된다. 이 구조 덕분에 무거운 리소스가 있어도 평소에는 컨텍스트를 잡아먹지 않는다.

Skill vs Slash Command, 뭘 쓸까

기준	Slash Command	Skill
파일 구조	마크다운 파일 1개	폴더 + SKILL.md + 리소스
실행 방식	/명령어로 직접 호출	Claude가 필요 시 자동 로드
적합한 용도	커밋 메시지, 코드 생성 패턴	API 테스트, 문서 생성, 복잡한 워크플로우
리소스 포함	프롬프트만	스크립트, 템플릿, 참고문서 포함 가능
난이도	5분이면 만든다	설계가 필요하다

간단한 건 Slash Command, 복잡한 건 Skill. 처음 시작한다면 Slash Command부터 만들어 보는 걸 추천한다.

Agent Team - 여러 에이전트가 팀으로 협업하기

Agent Team은 2026년 2월 Opus 4.6과 함께 공개된 실험 기능이다. 여러 Claude Code 세션이 각자 독립적으로 돌아가면서, 서로 메시지를 주고받으며 하나의 프로젝트를 함께 작업한다.

Agent Team 활성화 방법

실험 기능이라 기본으로는 꺼져 있다. 활성화하려면 설정에 다음을 추가한다.

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

환경 변수로 설정하거나, settings.json에 직접 추가해도 된다.

Agent Team의 구조

한 세션이 팀 리더가 되고, 나머지 세션은 팀원(Teammate)이 된다. 리더가 작업을 분배하고, 각 팀원은 자기 컨텍스트 윈도우에서 독립적으로 작업한다. Sub-Agent와 다른 점이 두 가지 있다. 팀원끼리도 직접 소통할 수 있고, 사용자가 개별 팀원과 직접 대화할 수도 있다.

Agent Team이 효과적인 상황

• PR 리뷰 - 보안 담당, 성능 담당, 테스트 담당 에이전트가 동시에 리뷰하고 리더가 종합한다
• 대규모 리팩토링 - 프론트엔드, 백엔드, 테스트 담당이 각각 변경사항을 처리하고 통합한다
• 디버깅 - 여러 가설을 동시에 검증하는 "경쟁적 디버깅"이 가능하다
• 리서치 - 각 팀원이 다른 측면을 조사하고 결과를 합친다

Agent Team 사용 시 주의사항

아직 실험 기능이라 몇 가지 제약이 있다. /resume이나 /rewind로 진행 중인 팀원을 복원할 수 없고, 리더는 한 번에 하나의 팀만 관리할 수 있으며, 팀원이 또 다른 팀을 만들 수는 없다. 안정성이 완벽하지 않으므로, 중요한 프로덕션 작업보다는 리뷰나 분석 같은 "읽기 중심" 작업부터 시작하는 게 안전하다.

실전 활용 사례 3가지

사례 1. 블로그 글 자동 작성 파이프라인

Custom Agent 3개를 조합하면 블로그 글 작성 전체를 자동화할 수 있다.

• 리서치 에이전트 (Sonnet 모델) - 웹 검색으로 최신 정보 수집, 팩트체크
• 이미지 에이전트 (Sonnet 모델) - 공식 스크린샷, 인터페이스 이미지 소싱
• 작성 에이전트 (Opus 모델) - 수집된 자료로 SEO 최적화된 글 작성

하나의 메인 에이전트가 이 3개를 순차적으로 호출하면, 주제 입력 한 번으로 리서치부터 발행까지 끝난다. 실제로 이 글도 비슷한 파이프라인으로 작성되었다.

사례 2. 테스트 코드 자동 생성

Custom Agent로 테스트 전문 에이전트를 만들면, 기존 코드를 분석해서 유닛 테스트와 E2E 테스트를 자동 생성할 수 있다. tools에 [Read, Grep, Glob, Write, Bash]를 넣고, Playwright MCP 서버와 연동하면 브라우저 테스트까지 자동화된다.

사례 3. 멀티에이전트 코드 리뷰

Agent Team을 활용한 사례다. 리더 에이전트가 PR의 변경 파일을 분석하고, 보안/성능/테스트 3명의 팀원에게 리뷰를 분배한다. 각 팀원이 독립적으로 리뷰한 뒤, 리더가 종합해서 이슈 목록을 만든다. 한 명이 순차적으로 3번 리뷰하는 것보다 빠르고, 전문 영역별로 더 깊은 분석이 가능하다.

Claude Code 에이전트 시스템 시작하는 법

Step 1. Claude Code 설치

Node.js 18 이상이 필요하다. 터미널에서 다음 명령어를 실행한다.

npm install -g @anthropic-ai/claude-code

설치 후 claude를 입력하면 브라우저가 열리면서 로그인 화면이 나온다. Claude Pro($20/월) 또는 Max($100/월) 플랜이 필요하다. 2026년 2월 기준.

Step 2. 첫 번째 Slash Command 만들기

프로젝트 루트에서 다음을 실행한다.

mkdir -p .claude/commands

그리고 .claude/commands/review.md 파일을 만든다.

---
description: 현재 변경사항을 코드 리뷰합니다
---

git diff로 현재 변경사항을 확인하고, 다음 기준으로 리뷰해주세요.

1. 버그 가능성
2. 성능 이슈
3. 보안 취약점
4. 개선 제안

이제 Claude Code에서 /review를 입력하면 자동으로 코드 리뷰가 시작된다.

Step 3. 첫 번째 Custom Agent 만들기

mkdir -p .claude/agents

.claude/agents/debugger.md 파일을 만든다.

---
name: debugger
description: 에러를 체계적으로 분석하고 해결하는 디버깅 전문가
model: sonnet
tools: [Read, Grep, Glob, Bash]
---

당신은 시니어 개발자 수준의 디버깅 전문가입니다.

## 디버깅 프로세스
1. 에러 메시지와 스택 트레이스를 분석합니다
2. 관련 코드를 탐색하고 원인을 파악합니다
3. 가설을 세우고 검증합니다
4. 수정 방안을 제시합니다 (코드 변경은 하지 않습니다)

## 출력 형식
- 원인 분석 (1-2문장)
- 관련 파일과 라인
- 수정 방안 (구체적인 코드 포함)

/agents를 입력하면 방금 만든 debugger 에이전트가 목록에 보인다.

Step 4. Agent Team 활성화 (선택)

Claude Code 설정에 다음을 추가한다.

claude config set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 1

이제 "팀을 만들어서 이 PR을 리뷰해줘"처럼 요청하면 자동으로 팀이 구성된다.

---

자주 묻는 질문

Claude Code는 무료로 쓸 수 있나?

Claude Code 자체는 무료로 설치할 수 있지만, 실행하려면 Claude Pro($20/월) 이상의 구독이 필요하다. 2026년 2월 기준, Pro 플랜이면 기본적인 사용이 가능하고, 대용량 작업이 많다면 Max($100/월) 플랜이 더 적합하다.

코딩을 몰라도 Custom Agent를 만들 수 있나?

만들 수 있다. Custom Agent 파일은 마크다운 형식이고, 프로그래밍 코드가 아니다. YAML로 이름과 설명을 쓰고, 아래에 "이런 식으로 일해줘"라는 지침을 자연어로 적는 것이다. 마크다운 문법만 알면 된다.

Sub-Agent와 Agent Team의 차이가 뭔가?

Sub-Agent는 하나의 세션 안에서 작업을 쪼개는 것이고, Agent Team은 여러 개의 독립 세션이 협업하는 것이다. Sub-Agent는 결과를 메인 에이전트에게만 보고하지만, Agent Team의 팀원은 서로 메시지를 주고받을 수 있다. 규모로 보면 Sub-Agent는 "팀원에게 심부름 시키기", Agent Team은 "프로젝트 팀 꾸리기"에 가깝다.

Skill은 다른 프로젝트에서도 재사용할 수 있나?

가능하다. ~/.claude/skills/ (사용자 레벨)에 저장하면 모든 프로젝트에서 쓸 수 있고, .claude/skills/ (프로젝트 레벨)에 저장하면 해당 프로젝트에서만 쓸 수 있다. Anthropic의 공식 문서에서 Skill 작성법과 예제를 참고할 수 있다.

Agent Team은 안정적인가?

아직 실험(experimental) 기능이다. 세션 복원이 안 되거나, 팀원 간 조율이 꼬이는 경우가 간혹 있다. Anthropic이 지속적으로 개선하고 있지만, 프로덕션 코드 수정보다는 리뷰, 분석, 리서치 같은 "읽기 중심" 작업에 먼저 적용해보는 걸 권한다.

VS Code에서도 Claude Code 에이전트를 쓸 수 있나?

쓸 수 있다. Claude Code는 VS Code와 JetBrains IDE에 네이티브 통합을 지원한다. 터미널에서 쓰는 것과 동일한 에이전트 시스템을 IDE 안에서 바로 활용할 수 있다. .claude/agents/, .claude/commands/, .claude/skills/ 폴더 구조도 그대로 인식된다.

---

정리

Claude Code의 에이전트 시스템은 단순한 AI 코딩 도구를 넘어, 자동화 파이프라인을 직접 설계할 수 있는 플랫폼이다. Slash Command로 반복 작업을 자동화하고, Custom Agent로 전문가를 만들고, Sub-Agent로 작업을 병렬 처리하고, Agent Team으로 대규모 협업을 돌린다.

처음이라면 Slash Command 하나 만드는 것부터 시작하면 된다. 5분이면 만들고, 한 번 만들면 매일 쓰게 된다. 더 다양한 AI 자동화 사례가 궁금하다면 자동화 사례를 참고하고, AI 도구 활용법을 영상으로 보고 싶다면 영상 레시피를 확인해 보자.