모듈 3: Subagents - 전문 AI 에이전트
학습 목표
- Subagent의 개념과 일반 AI 응답의 차이를 이해한다
- 프로젝트에 정의된 에이전트들의 역할을 설명할 수 있다
- 언제 어떤 에이전트를 사용해야 하는지 판단할 수 있다
Subagent란?
.claude/agents/ 폴더의 마크다운 파일로 정의된 전문 역할을 가진 AI 서브프로세스입니다.
메인 Claude가 복잡한 작업을 처리할 때, 전문 에이전트에게 특정 작업을 위임합니다.
[메인 Claude]
|
|-- "이 코드 검증해줘" --> [validation-gates 에이전트]
| - 테스트 실행
| - 빌드 확인
| - 결과 보고
|
|-- "아키텍처 다이어그램" --> [architecture-manager 에이전트]
| - PlantUML 코드 생성
|
|-- "코드 패턴 분석해줘" --> [code-analyst 에이전트]
- 기존 패턴 분석
- 리포트 생성
일반 Claude vs Subagent
| 구분 | 일반 Claude 응답 | Subagent |
|---|---|---|
| 역할 | 범용 | 특화된 역할 |
| 컨텍스트 | 주 대화 전체 | 위임받은 작업만 |
| 도구 접근 | 전체 | 지정된 도구만 |
| 독립성 | 없음 | 자율 실행 후 보고 |
| 병렬 실행 | 불가 | 가능 |
프로젝트의 Subagent 목록
.claude/agents/
├── validation-gates.md # 테스트/검증 전문
├── architecture-manager.md # 아키텍처 다이어그램 전문
├── code-analyst.md # 코드 패턴 분석 전문
├── documentation-manager.md # 문서화 전문
└── web-researcher.md # 웹 리서치 전문
validation-gates 에이전트 (가장 중요)
역할
코드 품질 게이트키퍼. 구현 후 자동으로 검증을 수행합니다.
정의된 책임
1. 자동화 테스트 실행
- 모든 관련 테스트 실행
- 린팅/포맷 검사
- 타입 체크
- 빌드 검증
2. 검증 게이트 체크리스트
- [ ] 단위 테스트 통과
- [ ] 린팅 오류 없음
- [ ] 빌드 성공 (Warning 0)
- [ ] 보안 취약점 없음
3. 반복 수정 프로세스
실패 시: 분석 -> 수정 -> 재실행 (최대 3회)사용 시점
/execute-prp 실행 후 자동으로 호출됨
또는 수동으로: "validation-gates 에이전트로 현재 코드 검증해줘"
실제 동작 예시
[메인 Claude]
"CrossSectionViewModel 구현 완료. validation-gates에 검증 요청"
|
v
[validation-gates 에이전트]
$ dotnet build
Warning 0개 확인... OK
$ dotnet test
CrossSectionTests.cs - 3개 테스트 통과 OK
$ 리소스 cleanup 패턴 확인...
using 블록 3개 감지 OK
보고: "모든 검증 게이트 통과. 구현 완료."
architecture-manager 에이전트
역할
PlantUML 전문가. 자연어 설명을 아키텍처 다이어그램 코드로 변환합니다.
사용 예시
사용자: "HmEG 기반 WPF 앱의 레이어 아키텍처를 다이어그램으로 그려줘"
[architecture-manager 에이전트]
@startuml
package "UI Layer" {
[MainWindow.xaml]
[EGViewportControl]
}
package "ViewModel Layer" {
[MainViewModel]
[ViewportViewModel]
}
package "HmEG Engine" {
[EGViewport]
[RootSpace]
}
[MainWindow.xaml] --> [MainViewModel]
[MainViewModel] --> [EGViewport]
@endumlcode-analyst 에이전트
역할
기존 코드베이스 분석 전문가. 새 기능 구현 전 기존 패턴 파악에 사용합니다.
출력 형식
### Codebase Analysis Report
#### 1. Relevant Files
- examples/EGViewportSample/ViewModels/CrossSectionViewModel.cs
이유: 단면 뷰 패턴의 참조 구현체
#### 2. Code Patterns to Follow
- **ViewModel 구조:**
ObservableObject 상속, EGViewport 생성자 주입 패턴
#### 3. Conventions
- 네이밍: [기능명]ViewModel 패턴
- using 블록으로 HmEG 객체 관리Subagent 정의 파일 구조
---
name: validation-gates
description: "에이전트 설명 - 메인 Claude가 언제 이 에이전트를 호출할지 결정하는 데 사용"
tools: Bash, Read, Edit, MultiEdit, Grep, Glob, TodoWrite
---
[에이전트의 역할, 책임, 작업 방식 설명]중요 필드:
name: 에이전트 식별자description: 메인 Claude가 읽는 호출 판단 기준tools: 이 에이전트가 사용할 수 있는 도구 목록
Subagent의 도구 제한
보안 및 역할 명확화를 위해 각 에이전트는 필요한 도구만 가집니다:
# validation-gates: 코드 실행 및 읽기/수정만
tools: Bash, Read, Edit, MultiEdit, Grep, Glob, TodoWrite
# architecture-manager: 읽기와 그리기만
tools: Read, Glob, Grep, WebFetch
# documentation-manager: 읽기/쓰기만
tools: Read, Write, Edit, MultiEdit, Grep, Glob병렬 실행 활용
여러 독립적인 작업은 병렬로 실행됩니다:
[메인 Claude]
|
|-- (동시에) --> [validation-gates] 테스트 실행
|-- (동시에) --> [documentation-manager] 문서 업데이트
|
v (둘 다 완료 후)
결과 통합 보고
커스텀 Subagent 작성 실습
HmEG 프로젝트 전용 에이전트를 작성해보세요:
# .claude/agents/hmeg-reviewer.md
---
name: hmeg-reviewer
description: "HmEG C# 코드의 리소스 관리, 예외 처리, 성능을 검토하는 전문 리뷰어"
tools: Read, Grep, Glob
---
# HmEG Code Reviewer
당신은 HmEG 엔진 기반 C# 코드 전문 리뷰어입니다.
## 검토 항목
1. 리소스 관리
- HmEG 객체의 using 블록 또는 Dispose() 호출 확인
- IDisposable 인터페이스 올바른 구현 확인
2. 예외 처리
- try/catch 블록 적절성 확인
- 사용자 친화적 에러 메시지 확인
3. 성능
- 불필요한 Redraw() 호출 확인
- 대량 객체 생성 패턴 확인
## 출력 형식
- 통과: [항목 목록]
- 개선 필요: [항목 + 수정 방안]
- 심각한 문제: [즉시 수정 필요 항목]핵심 정리
- Subagent는 전문 역할을 가진 자율 AI 서브프로세스
.claude/agents/폴더에 마크다운 파일로 정의description필드가 메인 Claude의 에이전트 선택 기준- 도구 제한으로 역할 명확화 및 보안 강화
- validation-gates가 가장 핵심: 코드 품질 자동 검증
- 병렬 실행으로 여러 검증 작업을 동시 수행 가능