Claude Code 멀티 에이전트 (Sub-agents) 사용법

Overview

Claude Code의 멀티 에이전트는 정확히는 Sub-agents (서브에이전트) 기능이다. 서브에이전트는 자체 시스템 프롬프트, 자체 컨텍스트 윈도우, 자체 도구 접근 권한, 자체 권한 모드를 가진 격리된 Claude 인스턴스로, 메인 대화 컨텍스트를 깨끗하게 유지하면서 특정 작업을 위임할 수 있다.

 

DevOps 작업 (Terraform, Kubernetes, ArgoCD 등)에 바로 활용 가능한 구조다.

 

 

 

 

---

 

 

1. 핵심 개념

서브에이전트의 가장 큰 가치는 컨텍스트 보존이다. 테스트 실행, 문서 조회, 로그 파일 처리는 상당한 컨텍스트를 소비하는데, 이를 서브에이전트에 위임하면 verbose한 출력은 서브에이전트 컨텍스트에 머물고 관련 요약만 메인 대화로 돌아온다.

 

또한 여러 서브에이전트가 동시에 실행될 수 있어 복잡한 워크플로우를 극적으로 단축시킨다. 예: 코드 리뷰 중 `style-checker`, `security-scanner`, `test-coverage` 서브에이전트를 동시 실행할 수 있다.

 

 

 

 

 

2. 서브에이전트 생성 방법

 

 

방법 A: /agents 명령 (권장)

Claude Code 터미널에서 실행한다.

/agents

• 대화창이 열리면 새 에이전트 생성, 프로젝트 레벨 또는 개인 레벨 선택, 이름과 설명 부여, 도구와 프롬프트 정의를 할 수 있다.

 

 

 

방법 B: 파일 직접 작성

서브에이전트는 YAML frontmatter를 가진 Markdown 파일이며, 스코프에 따라 다른 위치에 저장한다. 같은 이름의 서브에이전트가 여러 개일 때는 우선순위가 높은 위치가 이긴다.

 

저장 위치는 다음과 같다.

• 프로젝트 전용: `.claude/agents/` — 팀과 Git으로 공유한다.
• 사용자 전역: `~/.claude/agents/` — 모든 프로젝트에서 사용한다.

 

 

 

 

3. 서브에이전트 파일 구조

---
name: terraform-reviewer
description: Terraform 코드 리뷰 및 보안 검토 전문 에이전트. Terraform 파일 변경사항이 있을 때 자동 호출.
tools: Read, Grep, Glob, Bash
model: sonnet
---

당신은 Terraform 인프라 코드 리뷰 전문가입니다.

검토 항목:
1. 보안: IAM 정책, 보안 그룹, 암호화 설정
2. 모범 사례: 모듈화, 변수 사용, tagging
3. 비용 최적화: 인스턴스 타입, 스토리지 클래스
4. State 관리: backend 설정, locking

결과는 다음 형식으로 보고:
- 🔴 Critical: 즉시 수정 필요
- 🟡 Warning: 권장 개선사항
- 🟢 Suggestion: 선택적 개선

 

 

 

 

 

 

4. DevOps 워크플로우용 추천 에이전트 구성

EKS, GKE, Terraform, ArgoCD 같은 인프라 환경에 맞춘 예시 팀이다.

.claude/agents/
├── terraform-reviewer.md      # IaC 리뷰
├── k8s-manifest-validator.md  # Kubernetes manifest 검증
├── argocd-troubleshooter.md   # ArgoCD 동기화 문제 분석
├── helm-chart-builder.md      # Helm chart 작성
└── gitlab-ci-optimizer.md     # GitLab CI/CD 파이프라인 최적화

 

 

 

 

5. 호출 방법

 

자동 위임

description을 잘 작성하면 Claude가 자동으로 적절한 서브에이전트를 선택한다.

 

 

명시적 호출

특정 서브에이전트 사용을 보장하려면 프롬프트에서 이름을 언급한다.

Use the code-reviewer agent to check the authentication module

• 이렇게 하면 자동 매칭을 우회하고 직접 호출된다.

 

 

예시는 다음과 같다.

terraform-reviewer 서브에이전트로 modules/eks 디렉토리 검토해줘

 

 

 

 

 

6. 병렬 실행 (멀티 에이전트의 장점)

독립적인 조사를 위해 여러 서브에이전트를 동시에 spawn할 수 있다.

Research the authentication, database, and API modules in parallel using separate subagents

• 각 서브에이전트가 독립적으로 자기 영역을 탐색하고 Claude가 결과를 종합한다. 연구 경로가 서로 의존하지 않을 때 가장 잘 작동한다.

 

 

 

DevOps 예시는 다음과 같다.

EKS 클러스터 업그레이드 준비를 위해 병렬로 조사해줘:
- k8s-compatibility-checker 로 API deprecation 확인
- helm-chart-builder 로 차트 호환성 검토
- terraform-reviewer 로 EKS 모듈 변경사항 점검

 

 

 

 

7. YAML Frontmatter 주요 필드

필드	설명
name	에이전트 식별자 (kebab-case 권장)
description	언제 호출되는지 명확히 기술 (자동 위임에 핵심)
tools	허용 도구 목록 (생략 시 모든 도구 상속)
model	sonnet, opus, haiku 중 선택

 

 

 

에이전트별로 도구 범위를 제한해야 한다.

• PM과 Architect는 읽기 위주 (search, docs) 도구를 사용한다.
• Implementer는 Edit / Write / Bash + UI 테스팅 도구를 사용한다.
• Release는 필요한 것만 사용한다.

tools를 생략하면 암묵적으로 모든 도구 접근을 허용하는 것이니 의도적으로 설정해야 한다.

 

 

 

 

 

8. 운영 팁

• 재시작 필요: `.claude/agents/` 에 정의된 에이전트는 시작 시에만 로드된다. 실행 중 새 에이전트 파일을 만들면 세션을 재시작해야 로드된다.
• 확인: `/agents` 명령으로 현재 로드된 에이전트 목록을 확인한다.
• Git 관리: 프로젝트 레벨 에이전트는 `.claude/agents/` 를 커밋해 팀과 공유한다.

 

 

 

 

9. 빌트인 서브에이전트 활용

직접 만들지 않아도 빌트인 에이전트들이 자동으로 작동한다.

이름	용도
Explore	코드베이스 검색과 이해를 위한 빠른 read-only 에이전트. Haiku로 실행되어 빠르고 저렴하다.
Plan	Plan 모드 (/plan)에서 코드베이스 조사를 수행한다.
general-purpose	탐색 + 수정이 모두 필요한 작업을 처리한다.
claude-code-guide	Claude Code 자체 사용법 질문에 답변한다.
statusline-setup	터미널 상태 표시줄 설정을 담당한다.

 

 

 

 

 

---

 

 

마치며

서브에이전트는 Claude Code를 단순한 코딩 어시스턴트에서 팀 단위의 AI 워크플로우로 확장시켜주는 핵심 기능이다. 특히 DevOps 환경처럼 Terraform, Kubernetes, ArgoCD, CI/CD 파이프라인 등 서로 다른 도메인이 얽혀있는 작업에서는 각 영역에 특화된 에이전트를 구성해두면 컨텍스트 오염 없이 깊이 있는 분석이 가능하다.

 

처음부터 완벽한 에이전트 팀을 만들 필요는 없다. 자주 반복하는 작업 하나부터 시작해 서브에이전트로 분리해보고, 점진적으로 팀을 확장해 나가는 것이 좋다. 예를 들어 매번 같은 패턴으로 검토하는 Terraform PR 리뷰, 반복적인 ArgoCD 동기화 이슈 디버깅, Helm 차트 업그레이드 호환성 점검 같은 작업이 1순위 후보가 된다.

 

또한 `.claude/agents/` 디렉토리를 Git으로 관리하면 팀원 전체가 동일한 품질의 검토와 작업 프로세스를 공유할 수 있어, 단순한 개인 생산성 도구를 넘어 팀 표준화 도구로도 활용할 수 있다.

 

작은 에이전트 하나부터 시작해서, 자신만의 DevOps 워크플로우를 자동화해보길 추천한다.

 

 

 

 

 

 

 

 

 

 

---

Reference

 

• 공식 문서: https://code.claude.com/docs/en/sub-agents
• 100+ 사전 제작 에이전트 모음 (DevOps, K8s 카테고리 풍부): https://github.com/VoltAgent/awesome-claude-code-subagents
• 185개 에이전트 + 16개 오케스트레이터: https://github.com/wshobson/agents

 

 

 

 

 

 

Somaz | DevOps Engineer | Kubernetes & Cloud Infrastructure Specialist