[Claude Code 에이전트] 서브에이전트부터 병렬 실행까지 — 실전 활용법 완벽 가이드

 

안녕하세요!

재아군의 관찰인생입니다.

 

Claude Code를 쓰다 보면 한 가지 한계를 느끼게 됩니다.

한 번에 하나의 작업만 처리할 수 있고, 복잡한 작업을 시키면 컨텍스트가 금방 차버리는 것.

이 문제를 해결하는 것이 바로 에이전트(Agent) 시스템입니다.

 

서브에이전트를 생성해서 독립적인 작업을 위임하고, 여러 에이전트를 병렬로 실행하고, 나아가 커스텀 에이전트를 직접 정의하는 것까지.

오늘은 Claude Code의 에이전트 활용법을 기본 개념부터 고급 패턴까지 완벽하게 정리해 보겠습니다.

 

 

---

 

1. Claude Code 에이전트 시스템이란?

 

Claude Code의 에이전트 시스템은 메인 대화에서 독립적인 서브프로세스를 생성하여 작업을 위임하는 메커니즘입니다.

일반적인 Claude Code 사용에서는 하나의 대화 컨텍스트 안에서 모든 작업이 순차적으로 진행됩니다. 에이전트 시스템을 활용하면 이 제약을 벗어날 수 있습니다.

 

구분	일반 사용	에이전트 활용
실행 방식	순차 실행 (한 번에 하나)	병렬 실행 (여러 작업 동시)
컨텍스트	단일 컨텍스트에 모든 정보	작업별 독립 컨텍스트 (오염 방지)
복잡한 작업	컨텍스트 윈도우 한계로 품질 저하	분할 정복으로 품질 유지
전문성	범용 지시	역할별 전문화된 에이전트 정의 가능
격리	파일 충돌 위험	worktree 격리로 안전한 병렬 수정

 

 

---

 

2. 에이전트의 3가지 유형

 

유형 1: 내장 서브에이전트 (Agent Tool)

 

Claude Code가 내부적으로 사용하는 Agent 도구를 통해 서브에이전트를 생성합니다.

코드 탐색, 리서치, 복잡한 분석 작업을 메인 컨텍스트를 오염시키지 않고 수행할 때 사용됩니다.

 

# Claude Code에게 이렇게 지시하면 서브에이전트가 생성됩니다
"src/ 디렉토리의 전체 아키텍처를 분석해줘"

# Claude Code의 내부 동작:
# → Agent 도구 호출 (subagent_type: "Explore")
# → 독립 컨텍스트에서 파일 탐색 수행
# → 결과만 메인 컨텍스트로 반환

 

서브에이전트는 포그라운드(결과를 기다림)와 백그라운드(결과를 나중에 받음) 두 가지 모드로 실행할 수 있습니다.

 

유형 2: 커스텀 에이전트 (.claude/agents/)

 

프로젝트 디렉토리의 .claude/agents/에 마크다운 파일로 역할이 특화된 에이전트를 정의할 수 있습니다.

 

# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: "보안 취약점을 분석하는 전문 에이전트"
---

# Security Reviewer

당신은 보안 전문가입니다. 코드를 분석할 때 다음을 중점적으로 확인합니다:

## 검사 항목
- SQL 인젝션 가능성
- XSS 취약점
- 인증/인가 누락
- 하드코딩된 시크릿
- OWASP Top 10 위반 사항

## 출력 형식
심각도(Critical/High/Medium/Low)로 분류하여 보고합니다.

 

이렇게 정의한 에이전트는 Claude Code가 자동으로 인식하여, 관련 작업 시 해당 에이전트를 서브에이전트로 호출합니다.

 

유형 3: Agent SDK (프로그래밍 방식)

 

Anthropic의 Claude Agent SDK를 사용하면 코드로 에이전트를 프로그래밍할 수 있습니다.

CI/CD 파이프라인, 자동화 스크립트, 커스텀 도구에서 Claude를 에이전트로 활용하는 방식입니다.

 

// Agent SDK를 사용한 코드 리뷰 자동화
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 16384,
  system: "당신은 코드 리뷰 전문가입니다. PR의 변경사항을 분석하고 개선 제안을 합니다.",
  tools: [
    {
      name: "read_file",
      description: "파일 내용을 읽습니다",
      input_schema: {
        type: "object",
        properties: {
          path: { type: "string", description: "파일 경로" }
        },
        required: ["path"]
      }
    }
  ],
  messages: [
    { role: "user", content: "이 PR의 변경사항을 리뷰해주세요: ..." }
  ]
});

 

 

---

 

3. 실전 활용 패턴 5가지

 

패턴 1: 병렬 리서치 (Fan-out)

 

여러 독립적인 조사를 동시에 수행하는 패턴입니다.

 

# 프롬프트
"다음 3가지를 병렬로 조사해줘:
1. src/api/ 디렉토리의 모든 엔드포인트 목록
2. package.json의 의존성 중 deprecated된 패키지
3. src/db/의 마이그레이션 히스토리 분석

각각 서브에이전트로 실행해서 결과를 종합해줘."

 

Claude Code는 3개의 서브에이전트를 병렬로 생성하여 각각의 조사를 동시에 수행합니다. 순차 실행 대비 시간을 1/3로 단축할 수 있습니다.

 

패턴 2: 생성-검증 루프 (Generator-Evaluator)

 

하나의 에이전트가 코드를 생성하고, 다른 에이전트가 검증하는 패턴입니다.

 

# 프롬프트
"src/utils/validator.ts에 이메일 검증 함수를 작성해줘.
작성 후 별도의 에이전트로 다음을 검증해줘:
- 엣지 케이스 테스트 (빈 문자열, 특수문자, 유니코드)
- 보안 취약점 분석
- 기존 코드 패턴과의 일관성

검증에서 문제가 발견되면 수정해줘."

 

이 패턴은 자가 검증의 한계를 극복합니다. 같은 컨텍스트에서 생성과 검증을 하면 자기 코드의 문제를 놓치기 쉽지만, 독립된 에이전트가 검증하면 객관성이 높아집니다.

 

패턴 3: Worktree 격리 작업

 

Git worktree를 활용하여 메인 코드에 영향을 주지 않고 실험하는 패턴입니다.

 

# 프롬프트
"새로운 인증 방식을 실험해볼 건데, worktree로 격리해서 작업해줘.
현재 JWT 기반 인증을 세션 기반으로 변경하는 프로토타입을 만들어줘.
메인 브랜치는 건드리지 마."

 

에이전트가 isolation: "worktree" 모드로 실행되면, Git worktree에서 독립적으로 파일을 수정합니다. 실험이 성공하면 병합하고, 실패하면 worktree를 삭제하면 됩니다.

 

패턴 4: 전문가 풀 (Expert Pool)

 

커스텀 에이전트를 역할별로 정의하고, 작업에 따라 적절한 전문가를 호출하는 패턴입니다.

 

# .claude/agents/ 디렉토리 구조
.claude/agents/
├── frontend-architect.md    # React/UI 전문가
├── backend-expert.md        # API/DB 전문가
├── security-reviewer.md     # 보안 전문가
├── performance-analyst.md   # 성능 분석가
└── test-engineer.md         # 테스트 전문가

 

# 프롬프트
"새 결제 기능을 추가하려고 해.
1. backend-expert로 API 설계를 먼저 해줘
2. frontend-architect로 결제 UI 컴포넌트를 만들어줘
3. security-reviewer로 전체 코드를 보안 검증해줘
4. test-engineer로 테스트를 작성해줘"

 

각 에이전트 파일에 해당 분야의 전문 지식, 검사 항목, 출력 형식을 미리 정의해두면 일관된 품질을 유지할 수 있습니다.

 

패턴 5: 파이프라인 (Sequential Chain)

 

여러 에이전트가 순서대로 작업하며, 이전 에이전트의 출력이 다음 에이전트의 입력이 되는 패턴입니다.

 

# 블로그 자동화 파이프라인 예시
1. keyword-hunter 에이전트 → 트렌드 키워드 발굴
2. market-analyst 에이전트 → 경쟁 콘텐츠 분석
3. topic-orchestrator 에이전트 → 글 생성
4. seo-optimizer 에이전트 → SEO 최적화
5. fact-checker 에이전트 → 팩트 검증

 

이 패턴은 하네스(Harness)라는 상위 구조로 관리됩니다. 에이전트 팀의 구성, 실행 순서, 데이터 흐름을 정의하는 오케스트레이터 역할을 합니다.

 

 

---

 

4. 커스텀 에이전트 작성법

 

커스텀 에이전트를 효과적으로 작성하는 구조를 살펴보겠습니다.

 

에이전트 파일 구조

 

# .claude/agents/code-reviewer.md

---
name: code-reviewer
description: "PR 코드 리뷰 전문 에이전트. 코드 품질, 보안, 성능을 종합 분석."
---

# Code Reviewer Agent

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

## 핵심 역할
- 코드 품질 분석 (가독성, 유지보수성, DRY 원칙)
- 보안 취약점 탐지 (OWASP Top 10)
- 성능 이슈 식별 (N+1 쿼리, 불필요한 렌더링)
- 테스트 커버리지 확인

## 분석 원칙
- 사소한 스타일 이슈보다 로직 오류에 집중
- "이렇게 하면 더 좋습니다" 형태의 건설적 피드백
- 변경의 의도를 먼저 파악한 후 리뷰

## 출력 형식
### Critical (즉시 수정 필요)
### Suggestion (개선 제안)
### Positive (잘한 점)

 

효과적인 에이전트 작성 팁

 

항목	좋은 예	나쁜 예
역할 정의	"보안 전문가로서 OWASP Top 10 기준으로 분석"	"코드를 잘 분석해주세요"
출력 형식	심각도 분류 + 구체적 예시 포함	자유 형식 텍스트
범위 제한	"src/api/ 디렉토리만 분석"	"프로젝트 전체를 분석"
description	트리거 키워드 포함: "보안, security, 취약점"	모호한 설명

 

description 필드에 트리거 키워드를 포함하는 것이 중요합니다. Claude Code는 사용자의 프롬프트와 에이전트의 description을 매칭하여 자동으로 적절한 에이전트를 선택합니다.

 

---

 

5. 경쟁 도구 비교

 

비교 항목	Claude Code Agent	OpenAI Codex	Cursor Agent
서브에이전트	병렬 생성, 백그라운드 실행 지원	클라우드 샌드박스 기반 병렬	IDE 내 단일 에이전트
커스텀 에이전트	.claude/agents/ 마크다운 정의	API 기반 프로그래밍	제한적
격리	Git worktree 기반	클라우드 샌드박스	없음
실행 환경	로컬 터미널 (전체 시스템 접근)	클라우드 (제한된 환경)	IDE (에디터 기능 중심)
SDK	Claude Agent SDK (TypeScript/Python)	OpenAI Agents SDK	없음

 

Claude Code의 핵심 강점은 로컬 환경에서의 자율성과 마크다운 기반의 간편한 에이전트 정의입니다. 코드 한 줄 없이 마크다운 파일만으로 전문 에이전트를 구축할 수 있다는 점이 진입 장벽을 크게 낮춥니다.

 

---

 

6. 도입 시 베스트 프랙티스

 

5가지 원칙

 

1. 단순하게 시작하세요: 처음부터 5개의 에이전트 팀을 구성하지 마세요. 가장 자주 반복하는 작업 1개에 대한 에이전트를 만들고, 효과를 확인한 후 점진적으로 확장하세요.
2. 에이전트의 역할을 좁게 정의하세요: "만능 에이전트"보다 "보안 전문 에이전트", "테스트 전문 에이전트"처럼 단일 책임으로 정의하면 결과 품질이 높아집니다.
3. 출력 형식을 표준화하세요: 에이전트의 출력 형식을 미리 정의하면 결과를 파싱하거나 다음 에이전트에 전달하기 쉽습니다.
4. 병렬 실행 시 파일 충돌에 주의하세요: 여러 에이전트가 같은 파일을 동시에 수정하면 충돌이 발생합니다. 독립적인 파일을 수정하거나 worktree 격리를 사용하세요.
5. 에이전트 파일을 Git으로 관리하세요: .claude/agents/ 디렉토리를 Git에 커밋하면 팀 전체가 동일한 에이전트 팀을 활용할 수 있습니다.

 

흔한 실수와 해결 방법

 

실수	결과	해결 방법
에이전트를 너무 많이 호출	API 비용 급증, 응답 시간 느려짐	단순한 작업은 메인 컨텍스트에서 직접 처리, 복잡한 작업만 에이전트 위임
에이전트 간 의존성 무시	의존적인 작업을 병렬로 실행하여 에러	독립적인 작업만 병렬, 의존적인 작업은 순차 실행
description 미작성	Claude Code가 에이전트를 자동 선택하지 못함	description에 트리거 키워드와 용도를 명확히 기술

 

---

 

7. 향후 전망

 

Claude Code의 에이전트 시스템은 빠르게 진화하고 있습니다.

 

• 멀티 모델 에이전트: 현재는 같은 Claude 모델만 사용하지만, 향후 작업 특성에 따라 Opus(복잡한 추론), Sonnet(일반 코딩), Haiku(빠른 분류)를 자동 선택하는 멀티 모델 에이전트가 보편화될 전망입니다.
• 에이전트 마켓플레이스: 현재는 팀 내부에서 에이전트를 공유하지만, 오픈소스 에이전트 저장소가 활성화되면서 검증된 에이전트를 npm 패키지처럼 설치하는 생태계가 형성되고 있습니다.
• 자율 에이전트 체인: GitHub Issue가 등록되면 자동으로 분석 에이전트 → 구현 에이전트 → 테스트 에이전트 → PR 생성 에이전트가 순차적으로 실행되는 완전 자동화 파이프라인이 이미 실험 단계에 있습니다.
• 크로스 플랫폼 에이전트 표준: MCP가 도구 연결의 표준이 되었듯, 에이전트 정의의 표준화도 진행 중입니다. 하나의 에이전트 정의가 Claude Code, Cursor, Copilot 등 여러 플랫폼에서 동작하는 미래가 가까워지고 있습니다.

 

 

---

 

마무리

 

지금까지 Claude Code 에이전트 활용법을 기본 개념부터 고급 패턴까지 살펴보았습니다.

 

• 서브에이전트로 복잡한 작업을 분할하고 병렬 실행하여 시간을 단축할 수 있습니다.
• 커스텀 에이전트를 마크다운으로 간편하게 정의하여 팀의 전문 지식을 코드화할 수 있습니다.
• 생성-검증 패턴으로 자가 검증의 한계를 극복하고 코드 품질을 높일 수 있습니다.
• Worktree 격리로 실험적 작업을 안전하게 수행할 수 있습니다.

 

에이전트 시스템은 Claude Code를 단순한 코딩 도구에서 개발 팀의 AI 동료로 격상시키는 핵심 기능입니다.

오늘 소개한 패턴들을 직접 시도해 보시길 권합니다.

 

궁금한 점이나 에이전트 활용 사례가 있다면 댓글로 공유해 주세요!

감사합니다!