Claude Code 하위 에이전트 실전 가이드

게시 2025/10/19 업데이트 2026/01/20

By BLUEBUG

32 분읽는 시간

빠른 시작: 5분 만에 하위 에이전트 활용하기

기본 명령어

  
# 에이전트 직접 호출

# 백그라운드로 전환
Ctrl + B (작업 진행 중 누르면 백그라운드로 이동)

# 커스텀 에이전트 관리
/agents         # 에이전트 목록 보기
/agents create  # 새 에이전트 만들기

즉시 사용 가능한 프롬프트 템플릿

코드베이스 분석 요청

다음 항목을 중점적으로 봐줘:
1. 사용 중인 라이브러리/프레임워크
2. 토큰 저장 방식
3. 권한 검증 로직
4. 취약점이나 개선 필요 사항

결과는 auth-analysis.md 파일로 저장해줘.

구현 계획 수립

다음 단계로 계획을 세워줘:
1. 필요한 API 엔드포인트 목록
2. 데이터베이스 스키마 변경사항
3. 프론트엔드 컴포넌트 구조
4. 에러 핸들링 시나리오

implementation-plan.md로 저장해줘.

병렬 분석 실행

다음 3개 작업을 백그라운드로 동시에 실행해줘:

@explore 데이터베이스 스키마 분석 → db-schema.md
@explore API 라우트 구조 분석 → api-structure.md  
@explore 프론트엔드 컴포넌트 구조 분석 → ui-components.md

실전 시나리오별 워크플로우

시나리오 1: 기존 프로젝트에 새 기능 추가

상황: Next.js 프로젝트에 댓글 기능 추가

1단계: 현황 분석 (5분)

어떻게 저장되고 표시되는지 분석해줘.

특히 다음을 확인해줘:
- 사용 중인 ORM과 데이터 모델
- 컨텐츠 생성/조회 API 패턴
- UI 컴포넌트 구조와 상태 관리 방식

분석 결과를 content-system-analysis.md로 저장해줘.

[Ctrl + B로 백그라운드 전환]

2단계: 구현 계획 수립 (10분)

댓글 기능의 상세 구현 계획을 세워줘.

포함 사항:
- Comment 데이터 모델 (필드, 관계, 인덱스)
- API 엔드포인트 (POST /api/comments, GET /api/posts/:id/comments 등)
- 프론트엔드 컴포넌트 (CommentList, CommentForm, CommentItem)
- 실시간 업데이트 전략
- 권한 검증 (본인 댓글만 수정/삭제)

comment-implementation.md로 저장해줘.

3단계: 병렬 구현 (20분)

comment-implementation.md 계획을 기반으로 다음 작업을 병렬 실행해줘:

트랙 1: @coder 데이터베이스 마이그레이션 작성
- schema/comment.ts 생성
- 마이그레이션 파일 생성
- 관계 설정 (User, Post와의 relation)

트랙 2: @coder API 라우트 구현
- app/api/comments/route.ts (POST, GET)
- app/api/comments/[id]/route.ts (PATCH, DELETE)
- 권한 검증 미들웨어 적용

트랙 3: @coder React 컴포넌트 구현
- components/comments/CommentList.tsx
- components/comments/CommentForm.tsx
- components/comments/CommentItem.tsx
- 낙관적 업데이트 적용

각 트랙 완료 시 해당 파일들을 생성해줘.

4단계: 통합 검증 (10분)

구현된 코드를 검토해줘.

확인 항목:
✓ 데이터 모델이 계획대로 구현되었는가
✓ API가 RESTful 원칙을 따르는가
✓ 에러 핸들링이 모든 엔드포인트에 있는가
✓ 컴포넌트가 재사용 가능한 구조인가
✓ 타입 안정성이 보장되는가

발견된 문제점을 review-report.md로 저장하고,
심각한 이슈가 있으면 즉시 알려줘.

시나리오 2: 레거시 코드 리팩토링

상황: 오래된 클래스 컴포넌트를 함수형으로 전환

1단계: 대상 파일 식별

각 컴포넌트에 대해:
- 파일 경로
- 사용 중인 라이프사이클 메서드
- 상태 관리 방식
- 의존성 (다른 컴포넌트와의 관계)

class-components-inventory.md로 저장해줘.

2단계: 우선순위 결정

리팩토링 우선순위를 정해줘.

기준:
- 의존성이 적은 것부터 (리프 컴포넌트 우선)
- 복잡도가 낮은 것부터
- 비즈니스 영향도 고려

refactoring-priority.md로 저장해줘.

3단계: 단계적 리팩토링

refactoring-priority.md의 순서대로 리팩토링을 진행해줘.

각 컴포넌트에 대해:
1. 클래스 → 함수형 전환
2. componentDidMount → useEffect 변환
3. setState → useState 변환
4. 타입스크립트 적용 (Props, State 인터페이스)
5. 테스트 코드 업데이트

한 번에 하나씩 진행하고, 각 완료 후 테스트가 통과하는지 확인해줘.

시나리오 3: 새 프로젝트 부트스트래핑

상황: SaaS 대시보드 프로젝트 시작

전체 워크플로우 (60분)

# 1단계: 프로젝트 계획 (15분)
프로젝트 구조를 계획해줘:

요구사항:
- 사용자 인증 (이메일/비밀번호, Google OAuth)
- 조직/팀 관리 (멀티 테넌시)
- 역할 기반 권한 (Admin, Member, Viewer)
- 실시간 데이터 업데이트
- 반응형 UI

기술 선택 기준:
- 빠른 개발 속도
- 확장 가능성
- 타입 안정성

project-plan.md로 저장해줘.

---

# 2단계: 프로젝트 초기화 (10분)

실행할 명령:
1. Next.js 프로젝트 생성 (TypeScript, Tailwind, ESLint)
2. 필요한 패키지 설치 (next-auth, prisma, zod 등)
3. 기본 폴더 구조 생성
4. 환경변수 템플릿 (.env.example) 생성
5. Git 초기화 및 첫 커밋

---

# 3단계: 데이터베이스 설계 (15분)

모델:
- User (id, email, name, password, role)
- Organization (id, name, slug)
- OrganizationMember (userId, organizationId, role)
- Invitation (email, organizationId, role, token)

관계와 인덱스를 포함해서 prisma/schema.prisma를 생성해줘.

---

# 4단계: 인증 시스템 구현 (20분)
3개 트랙으로 병렬 실행:

트랙 1: @coder NextAuth.js 설정
- app/api/auth/[...nextauth]/route.ts
- lib/auth.ts (설정 파일)
- Credentials Provider (이메일/비밀번호)
- Google Provider
- 세션 전략 설정

트랙 2: @coder 회원가입/로그인 UI
- app/(auth)/login/page.tsx
- app/(auth)/signup/page.tsx  
- components/auth/LoginForm.tsx
- components/auth/SignupForm.tsx

트랙 3: @coder 미들웨어 및 유틸
- middleware.ts (인증 체크)
- lib/session.ts (서버에서 세션 가져오기)
- lib/auth-utils.ts (권한 체크 헬퍼)

---

# 5단계: 검증 및 테스트

체크리스트:
✓ 회원가입 시 비밀번호 해싱
✓ 로그인 실패 시 적절한 에러 메시지
✓ 보호된 라우트에 미들웨어 적용
✓ 세션 만료 처리
✓ CSRF 보호

auth-review.md로 리포트 작성해줘.

복사 붙여넣기 가능한 템플릿

템플릿 1: 철저한 코드 분석

## 분석 항목

### 1. 아키텍처
- 디렉토리 구조
- 주요 모듈과 역할
- 의존성 그래프

### 2. 데이터 흐름
- 데이터 소스 (DB, API, 파일 등)
- 상태 관리 패턴
- 데이터 변환 지점

### 3. 코딩 패턴
- 사용 중인 디자인 패턴
- 네이밍 컨벤션
- 에러 핸들링 방식

### 4. 개선 포인트
- 중복 코드
- 성능 병목
- 보안 취약점
- 기술 부채

결과를 [이름]-analysis.md로 저장해줘.

템플릿 2: 상세 구현 명세

## 구현 명세 구조

### 1. 개요
- 기능 설명
- 비즈니스 가치
- 성공 기준

### 2. 기술 설계
#### 2.1 데이터 모델
- 테이블/컬렉션 스키마
- 관계 및 제약조건
- 인덱스 전략

#### 2.2 API 설계
- 엔드포인트 목록
- 요청/응답 스키마
- 에러 코드 정의

#### 2.3 UI/UX
- 화면 구성
- 컴포넌트 계층
- 사용자 플로우

### 3. 구현 계획
#### 3.1 작업 분해
- [ ] Task 1: [설명]
- [ ] Task 2: [설명]
- [ ] Task 3: [설명]

#### 3.2 의존성
- Task X는 Task Y 이후 진행

#### 3.3 예상 소요 시간
- 총 [X]시간 예상

### 4. 위험 요소
- 잠재적 문제점
- 완화 전략

### 5. 테스트 계획
- 단위 테스트 대상
- 통합 테스트 시나리오
- E2E 테스트 케이스

[기능명]-spec.md로 저장해줘.

템플릿 3: 코드 리뷰 체크리스트

## 코드 품질

### 기능성
- [ ] 모든 요구사항이 구현되었는가
- [ ] 엣지 케이스가 처리되는가
- [ ] 에러 핸들링이 적절한가

### 코드 구조
- [ ] 단일 책임 원칙을 따르는가
- [ ] 함수/메서드 길이가 적절한가 (50줄 이하)
- [ ] 중복 코드가 없는가

### 타입 안정성
- [ ] 모든 변수/함수에 타입이 명시되었는가
- [ ] any 사용이 최소화되었는가
- [ ] 타입 가드가 필요한 곳에 사용되었는가

### 성능
- [ ] 불필요한 리렌더링이 없는가
- [ ] 무한 루프 가능성이 없는가
- [ ] 메모리 누수 위험이 없는가

### 보안
- [ ] 사용자 입력 검증이 있는가
- [ ] SQL Injection 방어가 되는가
- [ ] XSS 방어가 되는가
- [ ] 민감 정보 노출이 없는가

### 테스트
- [ ] 핵심 로직에 테스트가 있는가
- [ ] 테스트 커버리지가 80% 이상인가
- [ ] 테스트가 통과하는가

## 심각도별 분류
- Critical (즉시 수정): 
- High (우선 수정):
- Medium (개선 권장):
- Low (참고):

review-[기능명].md로 저장해줘.

성능 최적화 가이드

컨텍스트 사용량 모니터링

현재 사용량 확인

현재 메인 대화의 컨텍스트 사용량을 알려줘.
- 사용 중인 토큰
- 남은 토큰
- 사용률(%)

토큰 절약 전략

파일 기반 커뮤니케이션 ``` ❌ 나쁜 예: “코드베이스를 분석한 결과 [5000줄의 분석 내용]…”

✅ 좋은 예: → 메인 대화에는 요약만, 상세 내용은 파일에

2. **선택적 정보 로딩**

❌ 나쁜 예: “전체 프로젝트를 한 번에 분석해줘”

✅ 좋은 예: “먼저 @explore로 디렉토리 구조만 파악해줘. 그 다음에 중요한 폴더만 상세 분석할게.”

3. **백그라운드 적극 활용**

긴 작업은 무조건 백그라운드

[작업 시작하면 즉시 Ctrl + B]

여러 작업 병렬 실행

작업 1, 2, 3을 백그라운드로 동시 실행 → 각각 독립 컨텍스트 사용, 메인은 깨끗

### 실제 측정 데이터

┌─────────────────────────────────────────────────────────┐ │ 시나리오: Next.js 풀스택 앱 구축 (인증 + CRUD + UI) │ ├─────────────────────────────────────────────────────────┤ │ 방식 1: 하위 에이전트 미사용 │ │ - 예상 토큰: 350,000+ │ │ - 결과: 컨텍스트 초과로 완료 불가 │ ├─────────────────────────────────────────────────────────┤ │ 방식 2: 하위 에이전트 활용 │ │ - 실제 토큰: 136,000 (68%) │ │ - 절약률: 85%+ │ │ - 결과: 완전 작동하는 앱 완성 │ └─────────────────────────────────────────────────────────┘

---

## 문제 해결 FAQ

### Q1: 에이전트가 명세서를 무시하고 다른 구현을 했어요

**해결책:**

명시된 대로 정확히 구현해줘.

다음 사항을 반드시 지켜줘:

API 엔드포인트: [정확한 경로]
함수 시그니처: [정확한 타입]
에러 처리: [명세서의 에러 코드 사용]

완료 후 명세서와 대조해서 차이점을 보고해줘.

### Q2: 여러 에이전트가 같은 파일을 수정하려고 충돌해요

**해결책:**

작업을 파일 단위로 명확히 분리해서 할당해줘:

트랙 1 @coder: src/auth/* 폴더만 담당 트랙 2 @coder: src/api/* 폴더만 담당 트랙 3 @coder: src/components/* 폴더만 담당

각 에이전트는 자기 영역의 파일만 생성/수정해.

### Q3: 백그라운드 작업 결과를 어떻게 확인하나요?

**해결책:**

작업 상태 확인

백그라운드 작업들의 진행 상황을 알려줘.

완료된 작업 결과 보기

[에이전트명]의 작업 결과를 요약해줘. 생성된 파일 목록과 주요 변경사항을 알려줘.

### Q4: 에이전트가 이전 에이전트의 결과를 모르는 것 같아요

**해결책:**

❌ 나쁜 방법: “아까 A 에이전트가 분석한 결과를 바탕으로…”

✅ 좋은 방법: 그 내용을 기반으로 구현해줘.

명세서를 단일 진실 공급원으로 활용

모든 에이전트가 implementation-plan.md를 참조하게 설정

### Q5: 컨텍스트가 여전히 빨리 차요

**체크리스트:**

□ 파일 기반 커뮤니케이션을 사용하고 있나요? □ 백그라운드 실행을 활용하고 있나요? □ 에이전트에게 “결과를 파일로 저장해줘”라고 명시하나요? □ 불필요한 로그나 중간 과정을 메인 대화에 포함시키지 않나요? □ 명세서를 먼저 만들고 참조하게 하나요?

하나라도 아니라면 그것부터 개선하세요.

---

## 실전 프로젝트 예시 코드

### 예시 1: E2E 기능 구현 (결제 시스템)

1단계: 현황 분석 (백그라운드)

Order 모델과 관련 테이블
주문 생성 API 플로우
프론트엔드 장바구니 로직

order-system-analysis.md로 저장해줘.

[Ctrl + B로 백그라운드 전환]

2단계: 외부 결제 게이트웨이 조사

수수료 구조
API 복잡도
한국 시장 지원
보안 인증 (PCI DSS)

payment-gateway-comparison.md로 저장해줘.

[Ctrl + B]

3단계: 구현 계획 수립

payment-gateway-comparison.md를 참고해서 Stripe 결제 시스템 통합 계획을 세워줘.

포함 사항:

데이터 모델 (Payment, PaymentIntent, Refund)
API 엔드포인트 (webhook 포함)
프론트엔드 플로우 (Stripe Elements 사용)
에러 처리 및 재시도 로직
환불 프로세스

payment-integration-plan.md로 저장해줘.

4단계: 병렬 구현

payment-integration-plan.md를 기반으로 병렬 실행:

트랙 1 @coder: 데이터베이스 레이어

prisma/schema.prisma에 Payment 모델 추가
마이그레이션 생성
lib/db/payment.ts (CRUD 함수)

트랙 2 @coder: Stripe 통합 레이어

lib/stripe/client.ts (Stripe SDK 설정)
lib/stripe/payment-intent.ts (결제 의도 생성/확인)
lib/stripe/webhook.ts (웹훅 검증 및 처리)

트랙 3 @coder: API 라우트

app/api/payments/create-intent/route.ts
app/api/payments/confirm/route.ts
app/api/payments/webhook/route.ts
app/api/payments/refund/route.ts

트랙 4 @coder: 프론트엔드

components/checkout/PaymentForm.tsx (Stripe Elements)
components/checkout/OrderSummary.tsx
hooks/usePayment.ts (결제 로직)
app/checkout/page.tsx

트랙 5 @coder: 테스트

tests/payment.test.ts (단위 테스트)
tests/e2e/checkout.test.ts (E2E 테스트)

5단계: 통합 검증

전체 구현을 검토해줘.

특히 확인: ✓ Webhook 시그니처 검증 ✓ 멱등성 키 사용 ✓ 금액 불일치 방지 ✓ 환불 가능 조건 체크 ✓ PCI DSS 준수 (카드 번호 미저장)

payment-review.md로 리포트 작성해줘.

### 예시 2: 레거시 마이그레이션 (REST → GraphQL)

1단계: 현재 REST API 문서화

각 엔드포인트에 대해:

HTTP 메서드와 경로
요청/응답 스키마
사용 중인 컨트롤러와 서비스
의존하는 데이터 모델

rest-api-inventory.md로 저장해줘.

2단계: GraphQL 스키마 설계

GraphQL 스키마를 설계해줘.

변환 규칙:

GET /users/:id → Query: user(id: ID!)
GET /users → Query: users(filter: UserFilter)
POST /users → Mutation: createUser(input: CreateUserInput!)
중첩된 리소스는 필드로 (User.posts, Post.comments)

graphql-schema.graphql로 스키마 생성해줘.

3단계: 리졸버 구현

graphql-schema.graphql의 각 타입에 대해 리졸버를 작성해줘.

트랙 1: User 리졸버

src/graphql/resolvers/user.ts
Query, Mutation, Field 리졸버
기존 서비스 재사용

트랙 2: Post 리졸버

src/graphql/resolvers/post.ts
DataLoader로 N+1 해결

트랙 3: Comment 리졸버

src/graphql/resolvers/comment.ts
중첩 쿼리 최적화

4단계: 마이그레이션 전략

단계:

GraphQL 서버 별도 포트로 실행
프론트엔드 일부 화면만 GraphQL로 전환
REST와 GraphQL 병행 운영
모니터링 및 성능 비교
전체 전환 후 REST 제거

migration-strategy.md로 저장해줘.

---

## 커스텀 에이전트 예시

### 보안 전문가 에이전트

/agents create

이름: security-reviewer 설명: OWASP Top 10 기반 보안 검토 전문가

시스템 프롬프트: 당신은 보안 전문가입니다. 코드를 검토할 때 다음을 중점적으로 확인하세요:

인증/인가
- 비밀번호 해싱 (bcrypt, scrypt 사용)
- 세션 관리 (안전한 쿠키 설정)
- JWT 검증 (signature, expiration)
입력 검증
- SQL Injection (파라미터화된 쿼리)
- XSS (입력 이스케이핑, CSP 헤더)
- CSRF (토큰 검증)
데이터 보호
- 민감 정보 암호화
- HTTPS 강제
- 환경변수 사용 (하드코딩 금지)
API 보안
- Rate limiting
- 인증 헤더 검증
- 에러 메시지 정보 노출 방지

발견된 취약점을 심각도별로 분류하세요:

Critical: 즉시 수정 필요
High: 릴리즈 전 수정
Medium: 다음 스프린트에서 수정
Low: 개선 권장 ```

사용 예:

보안 관점에서 검토해줘.

security-audit-report.md로 리포트 작성해줘.

성능 최적화 에이전트

/agents create

이름: performance-optimizer
설명: 프론트엔드 성능 최적화 전문가

시스템 프롬프트:
React 애플리케이션의 성능을 최적화하는 전문가입니다.

검토 항목:

1. 렌더링 최적화
   - 불필요한 리렌더링 (React.memo, useMemo, useCallback)
   - 가상화 (대량 리스트는 react-window 사용)
   - 코드 스플리팅 (dynamic import)

2. 번들 크기
   - Tree shaking 기회
   - 중복 의존성
   - 이미지 최적화 (WebP, lazy loading)

3. 네트워크
   - API 호출 중복 제거
   - 캐싱 전략
   - Prefetching/Preloading

4. Web Vitals
   - LCP (Largest Contentful Paint)
   - FID (First Input Delay)
   - CLS (Cumulative Layout Shift)

구체적인 코드 개선안을 제시하세요.