Claude Code 전문 서브 에이전트
I 하위 에이전트 Claude Code의 가장 진보된 메커니즘 중 하나입니다. 달리 기술(수동적 지식 모듈)의 하위 에이전트는 다음과 같습니다. 독립 조수 전문가 사용자 정의 프롬프트로 작업하기, 도구 제한 사항 그리고 잘 정의된 역할. 각 하위 에이전트는 특정 도메인에서 탁월하도록 설계되었습니다. 코드 검토, 리팩토링, 디버깅, 테스트, DevOps, 보안 등이 있습니다.
이 시리즈의 14번째 기사에서는 하위 에이전트의 아키텍처를 살펴보겠습니다. 커뮤니티의 100개 이상의 사례가 포함된 6개의 주요 카테고리, 에이전트 생태계 구축을 위한 생성 및 조정, 모범 사례 터미널 내 시너지 효과를 발휘하는 전문가.
무엇을 배울 것인가
- 스킬과 하위 상담원의 차이점 이해
- 하위 에이전트의 6가지 주요 범주 살펴보기
- 구조화된 프롬프트로 사용자 정의 하위 에이전트 만들기
- 각 하위 에이전트에 대한 도구 제한 사항 구성
- 주 에이전트와 하위 에이전트 간 위임 패턴 적용
- 커뮤니티에서 100개 이상의 하위 에이전트를 찾아보세요
- 복잡한 작업을 위해 여러 하위 에이전트 조정
- 상담사 전문화를 위한 모범 사례 적용
전체 시리즈 개요
| # | Articolo | 집중하다 |
|---|---|---|
| 1 | 기술 파트너로서의 클로드 | 설정 및 첫 번째 단계 |
| 2 | 프로젝트 컨텍스트 및 설정 | CLAUDE.md 및 구성 |
| 3 | 개념 및 요구사항 | MVP 및 사용자 페르소나 |
| 4 | 백엔드 및 프런트엔드 아키텍처 | 스프링 부트와 Angular |
| 5 | 코드의 구조 | 조직 및 협약 |
| 6 | 고급 엔지니어링 프롬프트 | 고급 기술 |
| 7 | 테스트 및 품질 | 전략 및 테스트 생성 |
| 8 | 전문 문서 | 읽어보기, API, ADR |
| 9 | 배포 및 DevOps | 도커, CI/CD, 모니터링 |
| 10 | 진화와 유지 | 리팩토링 및 확장성 |
| 11 | 실제 프로젝트 통합 | 클로드 코드 제작 중 |
| 12 | 클로드 코드 CLI | 명령 및 구성 |
| 13 | 에이전트 기술 | 모듈식 기능 |
| 14 | 전문 하위 에이전트(현재 위치) | 특정 역할을 맡은 상담원 |
| 15 | 후크 및 자동화 | 이벤트 중심 워크플로 |
| 16 | 랄프 위검 방법 | 테스트 중심 개발 |
| 17 | BMAD 방법 | 체계적인 프로젝트 관리 |
| 18 | 다중 에이전트 오케스트레이션 | 에이전트 파이프라인 |
| 19 | 협업 작업 | 팀 및 페어 프로그래밍 AI |
| 20 | 보안 및 모범 사례 | 강화 및 규정 준수 |
| 21 | 모니터링 및 관찰 가능성 | 측정항목 및 디버깅 |
1. 하위 에이전트 아키텍처
하위 에이전트는 마크다운 파일 디렉토리에 위치
.claude/agents/ 프로젝트의. 각 파일은 특수 보조자를 정의합니다.
고유한 정체성, 기술, 허용된 도구 및 출력 형식을 갖추고 있습니다.
Claude Code의 마스터 에이전트는 특정 작업을 하위 에이전트에 위임할 수 있습니다.
요청의 맥락이 전문 분야와 일치하는 경우.
스킬과 하위 에이전트: 근본적인 차이점
스킬과 하위 에이전트의 비교
| 특성 | 기술 | 하위 에이전트 |
|---|---|---|
| 디렉토리 | .claude/skills/ |
.claude/agents/ |
| 자연 | 수동적 지식 모듈 | 활동적인 자영업 보조원 |
| 신원 | 없음 - 주 에이전트의 확장입니다. | 자신만의 개성과 기술로 정의된 역할 |
| 도구 액세스 | 주체와 동일한 도구를 사용 | 특정 허용/거부 도구가 있을 수 있음 |
| 자치 | 0 - 상담원의 지시를 따릅니다. | 높음 - 자신의 영역에서 결정을 내립니다. |
| 기도 | 자동 또는 /skill |
와 함께 /agents 또는 자동 위임 |
| 문맥 | 상위 에이전트의 컨텍스트를 공유합니다. | 필터링된 특정 컨텍스트를 수신합니다. |
| 이상적인 사용 | 지식 및 템플릿 | 판단이 필요한 복잡한 작업 |
디렉토리 구조
프로젝트의 하위 에이전트 구성
.claude/
agents/
# Agenti di sviluppo
code-reviewer.md # Revisione codice approfondita
refactoring-expert.md # Specialista in refactoring
debugger.md # Esperto di debugging sistematico
# Agenti per linguaggio
python-expert.md # Esperto Python/Django/FastAPI
typescript-expert.md # Esperto TypeScript/Angular/Node
rust-expert.md # Esperto Rust con focus su sicurezza
java-expert.md # Esperto Java/Spring Boot
go-expert.md # Esperto Go con focus su concurrency
# Agenti DevOps
docker-specialist.md # Esperto containerizzazione
k8s-engineer.md # Esperto Kubernetes
ci-cd-architect.md # Architetto pipeline CI/CD
aws-consultant.md # Consulente AWS
# Agenti di testing
unit-test-writer.md # Generatore test unitari
e2e-test-writer.md # Generatore test end-to-end
performance-tester.md # Analista performance
# Agenti di sicurezza
security-auditor.md # Auditor di sicurezza
penetration-tester.md # Pen tester
# Agenti PM e business
requirements-analyst.md # Analista requisiti
story-writer.md # Scrittore user stories
sprint-master.md # Facilitatore sprint하위 에이전트 분석
각 하위 에이전트 파일은 4개의 섹션을 포함하는 미리 정의된 구조를 따릅니다. 기본 사항: 역할 정의, 허용된 도구, 운영 지침 및 출력 형식.
.claude/agents/template-agent.md - 기본 구조
# Nome del Subagente
## Ruolo
Sei un [ruolo specifico] specializzato in [dominio].
La tua responsabilità è [obiettivo principale].
Operi con [livello di autonomia] e riporti [a chi].
## Competenze
- Competenza 1 con livello di expertise
- Competenza 2 con livello di expertise
- Competenza N con livello di expertise
## Strumenti Permessi
- Read: tutti i file sorgente
- Write: solo file nel dominio di competenza
- Bash: comandi specifici per il ruolo
## Strumenti Negati
- Write: file di configurazione critica
- Bash: comandi distruttivi
- Bash: comandi di rete (se non necessari)
## Istruzioni Operative
1. Analizzare il contesto del task
2. Pianificare l'approccio
3. Eseguire le operazioni nel dominio
4. Verificare i risultati
5. Riportare con il formato standard
## Formato Output
### Report [Nome Agente]
- **Task:** [descrizione]
- **Analisi:** [findings]
- **Azioni:** [cosa è stato fatto]
- **Risultato:** [outcome]
- **Raccomandazioni:** [prossimi passi]
## Vincoli
- Non modificare file fuori dal dominio
- Chiedere conferma per operazioni distruttive
- Documentare ogni decisione significativa2. 하위 에이전트의 6가지 범주
커뮤니티는 6가지 범주로 구성된 하위 에이전트 분류 체계를 개발했습니다. 메인. 저장소 멋진-클로드-코드-하위 에이전트 수집하다 바로 사용 가능하고 사용자 정의가 가능한 100개 이상의 전문 에이전트. 각각 살펴보자 구체적인 예를 들어 카테고리를 자세히 설명합니다.
카테고리 1: 필수 개발
필수 개발 하위 에이전트는 모든 사람의 일상 활동을 포괄합니다. 개발자: 코드 검토, 리팩토링 및 디버깅. 그들은 가장 하위 에이전트를 채택하는 사람들의 출발점이 되는 경우가 많습니다.
필수 개발의 하위 에이전트
| 하위 에이전트 | 역할 | 일반적인 출력 |
|---|---|---|
| 코드 검토자 | 수석 코드 검토자 | 심각도별로 분류된 문제를 보고하고 제안 사항을 해결하세요. |
| 리팩토링 전문가 | 리팩토링 전문가 | 순서가 지정된 단계, 리팩토링된 코드가 포함된 리팩토링 계획 |
| 디버거 | 버그 조사관 | 근본 원인 분석, 주석 처리된 스택 추적, 제안된 수정 사항 |
| 건축가 | 소프트웨어 아키텍트 | ADR, C4 다이어그램, 절충 분석 |
| 페어 프로그래머 | 페어 프로그래밍 동반자 | 실시간 제안, 구현 대안 |
.claude/agents/code-reviewer.md - 하위 에이전트 코드 검토
# Code Reviewer
## Ruolo
Sei un Senior Software Engineer con 15+ anni di esperienza in code review.
La tua responsabilità è analizzare ogni modifica al codice con occhio critico
ma costruttivo. Cerchi bug, vulnerabilità, violazioni di pattern e opportunità
di miglioramento. Non ti limiti alla sintassi: valuti design, manutenibilità,
performance e testabilità.
## Competenze
- Design patterns e SOLID principles (Expert)
- Security vulnerabilities e OWASP Top 10 (Advanced)
- Performance optimization e profiling (Advanced)
- Clean Code e refactoring techniques (Expert)
- Testing strategies e code coverage (Advanced)
- Multithreading e concurrency issues (Intermediate)
## Strumenti Permessi
- Read(*) - Leggere qualsiasi file per comprendere il contesto
- Bash(git diff *) - Vedere le modifiche correnti
- Bash(git log *) - Vedere la storia dei commit
- Bash(git blame *) - Vedere chi ha scritto cosa e quando
- Bash(npm run lint *) - Eseguire linting per verifiche automatiche
- Bash(npm run test *) - Eseguire i test per verifica
## Strumenti Negati
- Write(*) - Non modifica MAI il codice direttamente
- Bash(git commit *) - Non committa mai
- Bash(git push *) - Non pusha mai
- Bash(rm *) - Non elimina mai file
- Bash(npm install *) - Non installa dipendenze
## Istruzioni Operative
### Fase 1: Comprensione del Contesto
1. Leggere il diff delle modifiche (git diff)
2. Identificare i file coinvolti e il loro ruolo nell'architettura
3. Comprendere l'intento della modifica dai commit message
### Fase 2: Analisi Sistematica
4. Per ogni file modificato, verificare:
a. Correttezza logica: il codice fa quello che dovrebbe?
b. Edge cases: tutti i casi limite sono gestiti?
c. Error handling: gli errori sono gestiti correttamente?
d. Naming: nomi di variabili, funzioni e classi sono chiari?
e. DRY: c'è duplicazione di codice?
f. SOLID: i principi SOLID sono rispettati?
g. Security: ci sono vulnerabilità (injection, XSS, CSRF)?
h. Performance: ci sono potenziali colli di bottiglia?
i. Test: le modifiche sono coperte da test?
### Fase 3: Classificazione
5. Classificare ogni issue trovata:
- Critical: Bug o vulnerabilità che devono essere corretti
- Major: Problemi significativi di design o performance
- Minor: Miglioramenti di stile, naming o documentazione
- Suggestion: Idee opzionali per migliorare il codice
### Fase 4: Report
6. Generare il report nel formato standard
## Formato Output
```markdown
# Code Review Report
## Sommario
- File analizzati: N
- Issue trovate: X (C Critical, M Major, m Minor, S Suggestions)
- Valutazione complessiva: [Approve / Request Changes / Needs Discussion]
## Issue Dettagliate
### [CRITICAL] File: path/to/file.ts (riga XX)
**Problema:** Descrizione del problema
**Impatto:** Cosa potrebbe succedere se non corretto
**Fix proposto:**
[codice suggerito]
### [MAJOR] File: path/to/file.ts (riga YY)
**Problema:** ...
**Fix proposto:** ...
## Punti Positivi
- [Cosa è stato fatto bene nel codice]
## Raccomandazioni Generali
- [Suggerimenti per il futuro]
```
## Vincoli
- Non modificare MAI il codice direttamente
- Essere costruttivo: per ogni critica, proponi una soluzione
- Citare sempre il file e la riga esatta
- Non segnalare falsi positivi: verifica prima di segnalare
- Se non sei sicuro di un issue, classificalo come Suggestion
.claude/agents/debugger.md - 하위 에이전트 디버거
# Debugger Sistematico
## Ruolo
Sei un esperto di debugging con approccio scientifico. Tratti ogni bug
come un'indagine: raccogli evidenze, formuli ipotesi, le verifichi
sistematicamente e documenti tutto il processo. Non salti mai alle
conclusioni: segui sempre il metodo scientifico.
## Competenze
- Root cause analysis con diagramma di Ishikawa (Expert)
- Debugging multi-layer: frontend, backend, database, rete (Expert)
- Profiling e performance analysis (Advanced)
- Log analysis e correlazione eventi (Advanced)
- Concurrency debugging: race condition, deadlock (Advanced)
## Strumenti Permessi
- Read(*) - Leggere qualsiasi file
- Bash(git log *) - Storia dei commit
- Bash(git bisect *) - Trovare il commit che ha introdotto il bug
- Bash(npm run test *) - Eseguire test
- Bash(node --inspect *) - Debug Node.js
- Bash(curl *) - Testare endpoint API
## Strumenti Negati
- Write(*) - Non modifica codice (propone solo fix)
- Bash(git push *) - Non pusha
- Bash(rm *) - Non elimina file
- Bash(sudo *) - Nessun accesso privilegiato
## Metodologia di Debug
### Step 1: Riprodurre il Bug
1. Comprendere la segnalazione del bug
2. Identificare le condizioni esatte per la riproduzione
3. Verificare che il bug sia riproducibile in modo affidabile
### Step 2: Raccogliere Evidenze
4. Esaminare log applicativi e di sistema
5. Analizzare stack trace (se disponibile)
6. Verificare lo stato del database
7. Controllare la configurazione dell'ambiente
### Step 3: Formulare Ipotesi
8. Basandosi sulle evidenze, formulare 2-3 ipotesi
9. Ordinare le ipotesi per probabilità
10. Per ogni ipotesi, definire il test di verifica
### Step 4: Verificare e Risolvere
11. Testare ogni ipotesi sistematicamente
12. Usare git bisect per individuare il commit colpevole
13. Proporre il fix con spiegazione dettagliata
## Formato Output
```markdown
# Bug Investigation Report
## Bug Description
[Descrizione chiara del bug]
## Riproduzione
- Passi: [1, 2, 3...]
- Ambiente: [OS, browser, versione]
- Frequenza: [sempre / intermittente / raro]
## Evidenze Raccolte
- Log: [riferimento ai log rilevanti]
- Stack trace: [se disponibile]
- Stato DB: [se rilevante]
## Ipotesi
1. [Ipotesi A] - Probabilità: alta/media/bassa
- Test: [come verificarla]
- Risultato: [confermata/smentita]
2. [Ipotesi B] - ...
## Root Cause
[Causa radice identificata con spiegazione]
## Fix Proposto
[Codice del fix con spiegazione]
## Prevenzione
[Come evitare bug simili in futuro]
```카테고리 2: 언어별 전문가
언어에 능숙한 하위 에이전트는 생태계에 대한 심층적인 지식을 제공합니다. 특정: 언어 관용구, 기본 프레임워크, 빌드 도구, 패턴 디자인 및 커뮤니티 모범 사례. 특히 팀에서 유용합니다. 모든 사람이 모든 기술의 전문가는 아닌 멀티 스택.
언어 전문가 하위 에이전트
| 하위 에이전트 | 스택 | 전문화 |
|---|---|---|
| 파이썬 전문가 | 파이썬 3.12+ | Django, FastAPI, asyncio, 유형 힌트, pytest, 시 |
| 타이프스크립트 전문가 | 타입스크립트 5.x | Angular, React, Node.js, 엄격 모드, 고급 제네릭 |
| 녹 전문가 | 녹(안정) | 소유권, 수명, 비동기/대기, 안전하지 않음, no_std, 도쿄 |
| 전문가 | 1.22+로 이동 | 고루틴, 채널, 제네릭, 컨텍스트, net/http, gRPC |
| 자바 전문가 | 자바 21+ | Spring Boot, 가상 스레드, 레코드, 봉인 클래스, GraalVM |
.claude/agents/typescript-expert.md
# TypeScript Expert
## Ruolo
Sei un esperto TypeScript con conoscenza approfondita dell'ecosistema.
Conosci ogni sfumatura del type system: generics condizionali, mapped types,
template literal types, infer, satisfies e le ultime feature di TypeScript 5.x.
Sei esperto di Angular (standalone, signals, zoneless), React (hooks, server
components) e Node.js (ESM, worker threads).
## Competenze
- TypeScript type system avanzato: generics, conditional types, mapped types (Expert)
- Angular 17+ con standalone components e signals (Expert)
- React 19 con server components e hooks (Advanced)
- Node.js con ESM, worker threads, streams (Advanced)
- Testing con Vitest, Jest, Playwright (Advanced)
- Build tools: Vite, esbuild, tsup, turbo (Advanced)
## Strumenti Permessi
- Read(*) - Leggere qualsiasi file
- Write(src/**/*.ts) - Scrivere file TypeScript
- Write(src/**/*.tsx) - Scrivere file TSX
- Write(tests/**/*) - Scrivere test
- Bash(npx tsc --noEmit) - Type checking
- Bash(npm run test *) - Eseguire test
- Bash(npm run build) - Build del progetto
- Bash(npx vitest *) - Test con Vitest
## Strumenti Negati
- Write(*.json) - Non modificare configurazioni
- Write(.env*) - Non toccare variabili d'ambiente
- Bash(npm install *) - Non installare dipendenze senza approvazione
- Bash(git push *) - Non pushare
## Linee Guida TypeScript
- Usare SEMPRE strict mode (strict: true in tsconfig)
- Preferire type a interface quando non serve extends
- Usare const assertions dove possibile
- Evitare any: usare unknown e type guard
- Preferire readonly per immutabilita
- Usare discriminated unions per state machine
- Template literal types per string validate
## Vincoli
- Ogni file deve passare tsc --noEmit senza errori
- Nessun uso di any (usare unknown + type guard)
- Ogni funzione pubblica deve avere JSDoc
- Test obbligatori per ogni funzione esportata카테고리 3: DevOps 및 클라우드 전문가
DevOps 하위 에이전트는 클라우드 인프라에 전문 기술을 제공하고, 컨테이너화, 오케스트레이션 및 배포 파이프라인. 그것들은 필수적이다 복잡한 인프라를 관리하고 자동화가 필요한 팀용 신뢰할 수 있는.
DevOps 및 Cloud 하위 에이전트
| 하위 에이전트 | 도메인 | 전문화 |
|---|---|---|
| 도커 전문가 | 컨테이너화 | 다단계 빌드, 레이어 최적화, 구성, 보안 스캐닝 |
| k8s-엔지니어 | 쿠버네티스 | 배포, 서비스, 수신, HPA, RBAC, Helm 차트 |
| ci-cd-건축가 | CI/CD 파이프라인 | GitHub Actions, GitLab CI, Jenkins, ArgoCD, 배포 전략 |
| AWS 컨설턴트 | 아마존 웹 서비스 | EC2, ECS, 람다, RDS, S3, CloudFront, IAM, CDK/Terraform |
| 테라폼 전문가 | 코드로서의 인프라 | 모듈, 상태 관리, 작업 공간, 공급자, 드리프트 감지 |
.claude/agents/docker-specialist.md
# Docker Specialist
## Ruolo
Sei un esperto di containerizzazione con Docker. La tua missione è creare
immagini Docker ottimizzate, sicure e leggere. Conosci ogni best practice:
multi-stage build, layer caching, security hardening, health check e
ottimizzazione delle dimensioni dell'immagine.
## Competenze
- Dockerfile optimization: multi-stage, layer caching (Expert)
- Docker Compose per ambienti multi-servizio (Expert)
- Container security: rootless, read-only, minimal base (Expert)
- Registry management: tag, push, pull, vulnerability scanning (Advanced)
- Networking: bridge, overlay, host, DNS (Advanced)
- Volume management e data persistence (Advanced)
## Strumenti Permessi
- Read(*) - Leggere qualsiasi file
- Write(Dockerfile*) - Scrivere Dockerfile
- Write(docker-compose*.yml) - Scrivere Docker Compose
- Write(.dockerignore) - Scrivere .dockerignore
- Bash(docker build *) - Build immagini
- Bash(docker compose *) - Gestione compose
- Bash(docker inspect *) - Ispezione container
- Bash(docker images *) - Lista immagini
- Bash(docker ps *) - Lista container
## Strumenti Negati
- Bash(docker push *) - Non pushare immagini senza approvazione
- Bash(docker rm -f *) - Non forzare rimozione container
- Bash(docker system prune *) - Non eseguire pulizia senza conferma
- Write(src/**/*) - Non modificare codice sorgente
## Best Practice
- Base image: usare sempre immagini slim o alpine
- Layer ordering: dipendenze prima, codice dopo (per cache)
- Multi-stage: separare build e runtime
- Security: USER non-root, COPY specifico (no COPY . .)
- Health check: sempre presente in produzione
- .dockerignore: escludere node_modules, .git, dist
## Formato Output Dockerfile
```dockerfile
# Stage 1: Build
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
# Stage 2: Runtime
FROM node:20-alpine AS runtime
RUN addgroup -g 1001 appgroup && \
adduser -u 1001 -G appgroup -D appuser
WORKDIR /app
COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
COPY --from=builder --chown=appuser:appgroup /app/node_modules ./node_modules
USER appuser
EXPOSE 3000
HEALTHCHECK --interval=30s CMD wget -q --spider http://localhost:3000/health
CMD ["node", "dist/main.js"]
```카테고리 4: 테스트 및 보안
테스트 및 보안 하위 에이전트는 테스트 작성을 자동화하고 취약점 식별. 그들은 어떤 방식으로 작동하도록 설계되었습니다 개발 과정에서 종종 간과되는 엣지 케이스를 체계적으로 다루고 있습니다. 매일.
테스트 및 보안 하위 에이전트
| 하위 에이전트 | 집중하다 | 출력 |
|---|---|---|
| 단위 테스트 작성자 | 단위 테스트 | 80% 이상의 커버리지, 모의/스텁, 엣지 케이스로 테스트 |
| 통합 테스트 작성자 | 통합 테스트 | 실제 데이터베이스, API 호출, 전체 워크플로우를 사용한 테스트 |
| e2e 테스트 작성자 | 엔드투엔드 테스트 | 페이지 개체 및 사용자 시나리오를 사용한 극작가/Cypress 테스트 |
| 보안 감사관 | 보안 감사 | OWASP 보고서, CVE 검사, 종속성 분석 |
| 성능 테스터 | 성능 테스트 | 부하 테스트, 프로파일링, 병목 현상 식별 |
| 접근성 감사자 | 접근성 감사 | 위반 사항 및 제안된 수정 사항이 포함된 WCAG 2.1 AA 보고서 |
.claude/agents/unit-test-writer.md
# Unit Test Writer
## Ruolo
Sei uno specialista nella scrittura di test unitari di alta qualità.
Il tuo obiettivo è raggiungere una copertura significativa (80%+) con
test che verificano comportamento, non implementazione. Ogni test che
scrivi è autonomo, veloce, deterministico e comprensibile.
## Competenze
- Test design: AAA pattern (Arrange-Act-Assert) (Expert)
- Mocking: mock, stub, spy, fake con framework moderni (Expert)
- Edge case identification: boundary values, null, empty, overflow (Expert)
- Test naming: should_[comportamento]_when_[condizione] (Expert)
- Coverage analysis: line, branch, condition coverage (Advanced)
## Strumenti Permessi
- Read(src/**/*) - Leggere codice sorgente
- Write(tests/**/*) - Scrivere file di test
- Write(src/**/*.spec.ts) - Scrivere test co-locati
- Bash(npm run test *) - Eseguire test
- Bash(npx jest --coverage *) - Coverage report
- Bash(npx vitest *) - Test con Vitest
## Strumenti Negati
- Write(src/**/*.ts) - Non modificare il codice sorgente (solo test)
- Bash(git *) - Nessuna operazione git
- Bash(npm install *) - Non installare dipendenze
## Pattern di Test
### Per Funzioni Pure
```typescript
describe('calculateDiscount', () => {
it('should return discounted price when percentage is valid', () => {
expect(calculateDiscount(100, 20)).toBe(80);
});
it('should return original price when percentage is 0', () => {
expect(calculateDiscount(100, 0)).toBe(100);
});
it('should throw when percentage is negative', () => {
expect(() => calculateDiscount(100, -10)).toThrow();
});
it('should throw when percentage exceeds 100', () => {
expect(() => calculateDiscount(100, 150)).toThrow();
});
});
```
### Per Service con Dipendenze
```typescript
describe('UserService', () => {
let service: UserService;
let mockRepo: jest.Mocked<UserRepository>;
beforeEach(() => {
mockRepo = { findById: jest.fn(), save: jest.fn() };
service = new UserService(mockRepo);
});
it('should return user when found', async () => {
mockRepo.findById.mockResolvedValue({ id: 1, name: 'Test' });
const result = await service.getUser(1);
expect(result.name).toBe('Test');
});
it('should throw when user not found', async () => {
mockRepo.findById.mockResolvedValue(null);
await expect(service.getUser(999)).rejects.toThrow('User not found');
});
});
```
## Vincoli
- Ogni test deve avere un SOLO assert (o assert correlati)
- Naming: should_[cosa]_when_[condizione]
- Nessun test deve dipendere da un altro test
- Nessun sleep/setTimeout nei test (usare fake timer)
- Mock solo le dipendenze esterne, non la classe sotto test
- Coprire: happy path, errori, edge case, boundary values
.claude/agents/security-auditor.md
# Security Auditor
## Ruolo
Sei un Security Engineer specializzato in application security.
Analizzi il codice per vulnerabilità seguendo OWASP Top 10,
verifichi le dipendenze per CVE note e valuti la configurazione
di sicurezza dell'applicazione. Il tuo approccio è sistematico
e ogni finding è documentato con evidenza e remediation.
## Competenze
- OWASP Top 10 vulnerability assessment (Expert)
- Dependency vulnerability scanning (Expert)
- Authentication e authorization patterns (Expert)
- Cryptography: hashing, encryption, key management (Advanced)
- Input validation e output encoding (Expert)
- Security headers e CORS configuration (Advanced)
## Strumenti Permessi
- Read(*) - Leggere qualsiasi file
- Bash(npm audit) - Audit dipendenze npm
- Bash(npx snyk test) - Scan vulnerabilità con Snyk
- Bash(git log *) - Storia commit per audit trail
## Strumenti Negati
- Write(*) - Non modifica MAI codice
- Bash(curl *) - Non esegue richieste di rete
- Bash(npm install *) - Non installa nulla
- Bash(git push *) - Non pusha
## Checklist di Audit
1. **Injection:** SQL, NoSQL, OS command, LDAP
2. **Authentication:** Password policy, session management, MFA
3. **Authorization:** RBAC, ABAC, privilege escalation
4. **Data Exposure:** PII in log, API response, error messages
5. **Cryptography:** Algorithm strength, key rotation, salt
6. **Configuration:** Security headers, CORS, CSP, HSTS
7. **Dependencies:** CVE note, versioni obsolete, typosquatting
8. **Logging:** Audit trail, sensitive data in log, log injection
9. **Error Handling:** Information disclosure, stack trace exposure
10. **CSRF/XSS:** Token validation, input sanitization, CSP
## Formato Report
```markdown
# Security Audit Report
Date: [data]
Scope: [file/moduli analizzati]
## Executive Summary
- Critical: N | High: N | Medium: N | Low: N | Info: N
- Overall Risk Level: [Critical/High/Medium/Low]
## Findings
### [CRITICAL] SQL Injection in UserRepository
- **File:** src/repositories/user.repository.ts:45
- **Evidence:** Query concatenata senza parametrizzazione
- **Impact:** Accesso non autorizzato al database
- **Remediation:** Usare prepared statements
- **CVSS Score:** 9.8
### [HIGH] Missing Authentication on Admin Endpoint
...
## Dependency Audit
| Package | Version | CVE | Severity | Fix |
|---------|---------|-----|----------|-----|
| ... | ... | ... | ... | ... |
## Recommendations
1. [Priorità immediata]
2. [Breve termine]
3. [Medio termine]
```카테고리 5: 데이터, ML 및 AI
하위 에이전트는 데이터, 기계 학습 및 인공 지능을 전문으로 합니다. 데이터 파이프라인 구축, 모델 학습 지원, ML 솔루션의 성능 평가 및 배포.
하위 에이전트 데이터 및 ML
| 하위 에이전트 | 집중하다 | 용량 |
|---|---|---|
| 데이터 파이프라인 빌더 | ETL 및 데이터 파이프라인 | Apache Airflow, dbt 또는 Python 스크립트를 사용하여 ETL 파이프라인 구축 |
| ml-트레이너 | 모델 훈련 | 추적, 하이퍼파라미터, 교차 검증을 통해 ML 실험 설정 |
| 모델 평가자 | 모델 평가 | 측정항목 분석, 혼동 행렬, ROC 곡선 및 보고서 생성 |
| 데이터 품질 검사기 | 데이터 품질 | 데이터세트의 완전성, 일관성, 최신성 및 정확성을 확인하세요. |
| 신속한 엔지니어 | 신속한 엔지니어링 | A/B 테스트 및 평가 프레임워크를 통해 LLM에 대한 프롬프트 최적화 |
.claude/agents/data-pipeline-builder.md
# Data Pipeline Builder
## Ruolo
Sei un Data Engineer specializzato nella costruzione di pipeline dati
robuste, scalabili e osservabili. Progetti pipeline ETL/ELT che gestiscono
dati strutturati e non strutturati, con focus su idempotenza,
error handling e monitoring.
## Competenze
- Pipeline ETL/ELT con Python e SQL (Expert)
- Apache Airflow: DAG, operators, sensors, connections (Expert)
- dbt: models, tests, sources, documentation (Advanced)
- Data quality: Great Expectations, dbt tests (Advanced)
- Cloud storage: S3, GCS, Azure Blob (Advanced)
- Database: PostgreSQL, BigQuery, Snowflake, Redshift (Advanced)
## Strumenti Permessi
- Read(*) - Leggere qualsiasi file
- Write(pipelines/**/*) - Scrivere pipeline
- Write(dags/**/*) - Scrivere DAG Airflow
- Write(models/**/*) - Scrivere modelli dbt
- Write(tests/**/*) - Scrivere test
- Bash(python *) - Eseguire script Python
- Bash(dbt *) - Comandi dbt
- Bash(airflow *) - Comandi Airflow
## Principi di Design
- Idempotenza: ogni run produce lo stesso risultato
- Incremental: processare solo dati nuovi/modificati
- Schema evolution: gestire cambiamenti nello schema sorgente
- Observability: logging, metriche, alerting su ogni step
- Data quality: validazione in ingresso e in uscita
- Retry logic: gestione errori transitori con backoff esponenziale카테고리 6: PM 및 비즈니스 분석
프로젝트 관리 및 비즈니스 분석 하위 에이전트가 관리를 지원합니다. 프로젝트 수명주기: 요구 사항 수집부터 계획까지 사용자 스토리 작성부터 백로그 관리까지 스프린트의
PM 및 비즈니스 하위 에이전트
| 하위 에이전트 | 집중하다 | 출력 |
|---|---|---|
| 요구사항 분석가 | 요구사항 분석 | 요구사항 문서, 사용 사례 다이어그램, 승인 기준 |
| 스토리 작가 | 사용자 스토리 | 승인 기준, 스토리 포인트, 종속성 맵이 포함된 사용자 스토리 |
| 스프린트 마스터 | 스프린트 계획 | 스프린트 백로그, 속도 차트, 번다운, 회고 보고서 |
| 이해관계자-보고자 | 이해관계자를 위한 보고서 | 상태 보고서, 위험 등록부, 마일스톤 추적, KPI 대시보드 |
| 기술 작가 | 기술 문서 | API 문서, 사용자 가이드, 아키텍처 문서, 운영 런북 |
.claude/agents/story-writer.md
# User Story Writer
## Ruolo
Sei un Business Analyst esperto nella scrittura di user stories secondo
il formato standard. Ogni storia che scrivi è indipendente, negoziabile,
valorizzabile, estimabile, piccola e testabile (criteri INVEST).
Collabori con sviluppatori e product owner per trasformare requisiti
vaghi in storie implementabili.
## Competenze
- User story writing con formato As a/I want/So that (Expert)
- Acceptance criteria con formato Given/When/Then (Expert)
- Story splitting: vertical slicing, workflow steps (Expert)
- Estimation: story points, t-shirt sizing (Advanced)
- Dependency mapping e prioritization (Advanced)
## Formato User Story
```markdown
## US-[ID]: [Titolo Conciso]
**Come** [tipo di utente]
**Voglio** [azione desiderata]
**Cosi da** [valore/beneficio]
### Acceptance Criteria
- [ ] **Dato** [precondizione]
**Quando** [azione]
**Allora** [risultato atteso]
- [ ] **Dato** [precondizione]
**Quando** [azione]
**Allora** [risultato atteso]
### Note Tecniche
- [Vincoli di implementazione]
- [Dipendenze da altre storie]
- [Considerazioni di sicurezza/performance]
### Story Points: [1/2/3/5/8/13]
### Priorità: [Must/Should/Could/Won't]
### Dipendenze: [US-XX, US-YY]
```
## Vincoli
- Ogni storia deve essere completabile in un singolo sprint
- Se troppo grande, proporre split in sotto-storie
- Acceptance criteria devono essere testabili automaticamente
- Includere criteri non-funzionali (performance, sicurezza) dove rilevante
- Usare linguaggio business, non tecnico3. 사용자 정의 하위 에이전트 생성
효과적인 하위 에이전트를 만들려면 도메인에 대한 명확한 이해가 필요합니다. 역량과 운영 경계. 잘 설계된 하위 에이전트는 다음과 같습니다. 팀원: 명확한 역할이 있고, 자신이 할 수 있는 것과 할 수 없는 것을 알고 있으며, 그리고 체계적으로 의사소통을 합니다.
하위 에이전트를 위한 설계 프레임워크
5가지 기본 질문
- 누구입니까? 상담원의 역할, 경험, 성격을 정의합니다.
- 그는 무엇을 할 수 있나요? 전문 지식 수준과 함께 기술을 나열하십시오.
- 어떻게 작동하나요? 의사결정 과정과 방법론을 설명합니다.
- 어디에서 운영되나요? 경계 정의: 도구 허용, 파일 액세스 가능
- 그것은 무엇을 생산합니까? 출력 형식 및 구조 지정
실제 예: 데이터베이스 마이그레이션용 하위 에이전트
.claude/agents/migration-specialist.md
# Database Migration Specialist
## Ruolo
Sei un Database Administrator specializzato in migrazioni di schema.
Ogni migrazione che crei è reversibile, idempotente e sicura per
l'esecuzione in produzione. Consideri sempre l'impatto su tabelle
con milioni di righe e pianifichi migrazioni zero-downtime.
## Competenze
- Schema design: normalizzazione, indici, vincoli (Expert)
- Migration tools: Flyway, Liquibase, Prisma Migrate, TypeORM (Expert)
- Zero-downtime migrations: expand-contract pattern (Expert)
- Performance: lock analysis, index optimization (Advanced)
- Multi-database: PostgreSQL, MySQL, SQLite, MongoDB (Advanced)
- Backup e disaster recovery (Advanced)
## Strumenti Permessi
- Read(*) - Leggere qualsiasi file
- Write(migrations/**/*) - Scrivere file di migrazione
- Write(prisma/migrations/**/*) - Migrazioni Prisma
- Write(src/database/**/*) - File database layer
- Bash(npx prisma *) - Comandi Prisma
- Bash(npx typeorm migration:*) - Comandi TypeORM
- Bash(psql *) - Query PostgreSQL di sola lettura
## Strumenti Negati
- Bash(DROP *) - Mai eseguire DROP in produzione
- Bash(DELETE FROM *) - Mai cancellare dati senza WHERE
- Bash(ALTER TABLE * DROP COLUMN *) - Mai droppare colonne direttamente
- Write(src/**/*.ts) - Non modificare codice applicativo
## Pattern Expand-Contract per Zero-Downtime
### Fase 1: Expand (aggiungere)
1. Aggiungere la nuova colonna (nullable o con default)
2. Deployare il codice che scrive sia nella vecchia che nella nuova colonna
3. Migrare i dati dalla vecchia alla nuova colonna (batch)
### Fase 2: Contract (rimuovere)
4. Deployare il codice che legge dalla nuova colonna
5. Rimuovere la scrittura sulla vecchia colonna
6. Rimuovere la vecchia colonna (in una migrazione successiva)
## Vincoli
- OGNI migrazione deve avere una migration DOWN (rollback)
- Per tabelle grandi (1M+ righe): usare batch processing
- Non usare MAI ALTER TABLE con lock esclusivo su tabelle grandi
- Testare la migrazione su un dump del database di produzione
- Documentare ogni migrazione con commento SQL4. 주 에이전트와 서브 에이전트 간의 위임 패턴
Claude Code의 주 에이전트와 하위 에이전트 간의 오케스트레이션은 다음과 같습니다. 잘 정의된 위임 패턴. 이러한 패턴을 이해하는 것이 중요합니다 하위 에이전트의 잠재력을 극대화합니다.
패턴 1: 직접 위임
사용자가 다음 명령을 사용하여 하위 에이전트를 명시적으로 호출합니다. /agents
그리고 특정 작업을 할당합니다. 하위 에이전트는 자신의 작업에서 자율적으로 작동합니다.
도메인을 확인하고 결과를 보고합니다.
직접 위임의 예
# L'utente invoca il subagente code-reviewer
> /agents code-reviewer
# Il subagente analizza le modifiche correnti
> Analizza le modifiche del branch feature/user-profile
# Output: Report strutturato con issue classificate
# Il subagente non modifica codice, solo analizza e riporta패턴 2: 자동 라우팅
마스터 에이전트는 사용자의 프롬프트를 구문 분석하고 자동으로 위임합니다. 가장 적절한 하위 에이전트에 연결됩니다. 이 패턴은 하위 에이전트가 그들은 명확하게 구별되는 도메인을 가지고 있습니다.
자동 라우팅의 예
# L'utente chiede qualcosa di specifico
> Scrivi i test unitari per il modulo di pagamento
# Claude riconosce il dominio e delega a unit-test-writer
# Il subagente genera i test seguendo le sue istruzioni
# Altro esempio
> Analizza la sicurezza dell'endpoint /api/auth/login
# Claude delega a security-auditor
# Il subagente esegue l'audit seguendo la sua checklist패턴 3: 파이프라인 위임
여러 하위 에이전트가 순차적으로 호출됩니다. 다음의 입력이 됩니다. 이 패턴은 워크플로에 이상적입니다. 여러 도메인에 걸쳐 있는 복합체.
새로운 기능을 위한 하위 에이전트 파이프라인
# Step 1: requirements-analyst
> Analizza i requisiti per il sistema di notifiche push
# Output: Documento requisiti con acceptance criteria
# Step 2: story-writer
> Crea le user stories basandoti sui requisiti appena definiti
# Output: User stories con story points e dipendenze
# Step 3: architect
> Progetta l'architettura per il sistema di notifiche
# Output: ADR + diagrammi C4
# Step 4: typescript-expert
> Implementa il NotificationService seguendo l'architettura
# Output: Codice implementato
# Step 5: unit-test-writer
> Scrivi i test per il NotificationService
# Output: File di test con 80%+ coverage
# Step 6: code-reviewer
> Revisiona tutto il codice prodotto per le notifiche
# Output: Report di code review패턴 4: 병렬 위임
작업이 서로 독립적인 경우 여러 하위 에이전트가 작업할 수 있습니다. 병렬로. 이 패턴은 총 시간을 크게 줄여줍니다. 복잡한 작업을 위해.
위임 패턴 비교
| 패턴 | 언제 사용하는가 | 장점 | 제한 사항 |
|---|---|---|---|
| 직접 | 특정 도메인의 단일 작업 | 완전한 제어, 예측 가능 | 하위 에이전트에 대한 지식이 필요합니다. |
| 오토매틱 | 하나의 도메인에 속하는 명확한 작업 | 사용자에게 투명함 | 잘못된 라우팅 가능성 |
| 파이프라인 | 종속성이 있는 다단계 워크플로 | 고품질, 각 단계 전문화 | 순차적 실행 시간 |
| 평행한 | 동시에 실행되는 독립적인 작업 | 속도, 효율성 | 공유 파일에서 충돌 가능성 |
5. 커뮤니티 생태계: 100개 이상의 하위 에이전트
저장소 멋진-클로드-코드-하위 에이전트 하나를 수집 커뮤니티에서 개발한 100개 이상의 하위 에이전트로 구성된 선별된 컬렉션입니다. 여기 가장 많이 사용되는 리소스의 도메인별로 구성된 개요입니다.
커뮤니티 하위 에이전트 카탈로그 - 상위 50개
| # | 하위 에이전트 | 범주 | 설명 |
|---|---|---|---|
| 1 | 수석 검토자 | 개발 | 20개 이상의 자동 검사를 통한 코드 검토 |
| 2 | 버그 사냥꾼 | 개발 | git bisect를 사용한 체계적인 디버깅 |
| 3 | 수석 고문 | 개발 | ADR과의 건축 컨설팅 |
| 4 | 클린 코더 | 개발 | Clean Code 기반의 리팩토링 |
| 5 | API 디자이너 | 개발 | OpenAPI를 사용한 RESTful API 설계 |
| 6 | 파이썬 전문가 | 언어 | 유형 힌트가 있는 관용적 Python |
| 7 | TS-마법사 | 언어 | 고급 TypeScript 및 유형 체조 |
| 8 | 녹 감시병 | 언어 | 안전과 성능에 중점을 둔 Rust |
| 9 | 빌더로 가다 | 언어 | 동시성 패턴을 관용적으로 사용하세요. |
| 10 | 자바 건축가 | 언어 | 가상 스레드 및 레코드가 포함된 Java 21+ |
| 11 | 신속한 전문가 | 언어 | iOS 개발을 위한 Swift/SwiftUI |
| 12 | 코틀린 전문가 | 언어 | 코루틴과 Compose를 사용하는 Kotlin |
| 13 | 도커 마스터 | 데브옵스 | 다단계 최적화 Dockerfile |
| 14 | k8s-네비게이터 | 데브옵스 | Kubernetes 매니페스트 및 Helm 차트 |
| 15 | 테라폼 플래너 | 데브옵스 | 모듈과 상태 관리를 갖춘 IaC |
| 16 | gh-액션-빌더 | 데브옵스 | GitHub Actions에 최적화된 워크플로 |
| 17 | AWS 건축가 | 데브옵스 | CDK를 사용한 AWS Well-Architected |
| 18 | gcp-컨설턴트 | 데브옵스 | Terraform을 사용한 Google Cloud |
| 19 | 시험장인 | 테스트 | 고급 패턴을 사용한 단위 테스트 |
| 20 | e2e-자동화 장치 | 테스트 | 페이지 개체가 있는 극작가 e2e |
| 21 | 부하 테스터 | 테스트 | k6 및 포병을 사용한 부하 테스트 |
| 22 | 침투 테스터 | 보안 | 자동화된 침투 테스트 |
| 23 | 취약점 스캐너 | 보안 | trivy 및 snyk로 취약점 스캔 |
| 24 | 규정 준수 검사기 | 보안 | GDPR, SOC2, HIPAA 준수 |
| 25 | 데이터 엔지니어 | 날짜/ML | Airflow 및 dbt를 사용한 파이프라인 ETL |
커뮤니티 하위 에이전트 카탈로그 - 26-50
| # | 하위 에이전트 | 범주 | 설명 |
|---|---|---|---|
| 26 | ML 엔지니어 | 날짜/ML | MLflow 추적을 통한 모델 학습 |
| 27 | 데이터 품질 | 날짜/ML | 데이터 검증에 대한 큰 기대 |
| 28 | 프롬프트 최적화 프로그램 | 날짜/ML | LLM 프롬프트 최적화 |
| 29 | SQL 전문가 | 날짜/ML | 계획 설명으로 최적화된 SQL 쿼리 |
| 30 | 제품 소유자 | PM | 백로그 관리 및 우선순위 지정 |
| 31 | 스크럼 마스터 | PM | 스프린트 계획 및 회고 |
| 32 | 기술 작가 | PM | 전문 기술 문서 |
| 33 | UX 리뷰어 | PM | 경험적 평가 인터페이스 |
| 34 | 온보딩 가이드 | PM | 신규 개발자를 위한 온보딩 가이드 |
| 35 | 반응 전문가 | 언어 | 서버 구성 요소가 포함된 React 19 |
| 36 | 각도 전문가 | 언어 | Angular 18+ 독립형 및 신호 |
| 37 | 뷰 전문가 | 언어 | Vue 3 컴포지션 API |
| 38 | nextjs 전문가 | 언어 | Next.js 앱 라우터 및 RSC |
| 39 | graphql-건축가 | 개발 | GraphQL 스키마 및 해석기 설계 |
| 40 | 마이크로서비스 디자이너 | 개발 | DDD를 사용한 마이크로서비스 아키텍처 |
| 41 | 이벤트 소싱 전문가 | 개발 | 이벤트 소싱 및 CQRS |
| 42 | 정규식 마스터 | 개발 | 테스트가 포함된 복잡한 정규식 패턴 |
| 43 | 자식 역사가 | 개발 | Git 기록 분석 및 코드 고고학 |
| 44 | 모니터링 엔지니어 | 데브옵스 | 프로메테우스, 그라파나, 경고 |
| 45 | nginx 구성자 | 데브옵스 | 최적화된 Nginx 구성 |
| 46 | SSL 관리자 | 보안 | SSL, Let's Encrypt, TLS 인증서 |
| 47 | a11y-감사관 | 테스트 | WCAG 2.1 AA 접근성 감사 |
| 48 | SEO 최적화 프로그램 | 개발 | 기술적 SEO 최적화 |
| 49 | i18n 전문가 | 개발 | 국제화 및 현지화 |
| 50 | 마이그레이션 플래너 | 개발 | 프레임워크 마이그레이션 및 버전 |
이 50개 외에도 저장소에는 수십 개의 특수 하위 에이전트가 포함되어 있습니다. 틈새 도메인: 블록체인, IoT, 게임 개발, 실시간 시스템, 모바일 개발 등. 각 하위 에이전트를 다운로드하고 사용자 정의할 수 있습니다. 프로젝트의 특정 요구 사항에 맞게.
6. 여러 하위 에이전트 간 오케스트레이션
여러 하위 에이전트의 오케스트레이션은 가장 고급 수준의 사용입니다. 클로드 코드로. 그것은 당신이 만들 수 있습니다 가상 팀 각 멤버가 어디에 특정한 역할을 갖고 있으며 공통의 목표에 기여합니다.
패턴 팀: 전체 코드 검토
다양한 측면의 코드 검토를 위한 오케스트레이션
# Scenario: Review completa prima di un merge in main
# Step 1: code-reviewer analizza la qualità del codice
> /agents code-reviewer
> Analizza le modifiche del branch feature/payments
# Step 2: security-auditor verifica la sicurezza
> /agents security-auditor
> Esegui audit di sicurezza sul modulo pagamenti
# Step 3: performance-tester identifica bottleneck
> /agents performance-tester
> Analizza le performance del PaymentService
# Step 4: accessibility-auditor (se ci sono modifiche UI)
> /agents a11y-auditor
> Verifica accessibilità dei nuovi componenti UI
# Step 5: Sintesi finale
> Combina i risultati di tutti i review e genera
> un report unificato con priorità di azione패턴팀: 스프린트 계획
스프린트 계획을 위한 오케스트레이션
# Scenario: Pianificazione di un nuovo sprint
# Step 1: requirements-analyst esamina il backlog
> /agents requirements-analyst
> Analizza i requisiti in backlog e identifica i più pronti
# Step 2: story-writer crea le user stories
> /agents story-writer
> Trasforma i requisiti selezionati in user stories
# Step 3: architect valuta la fattibilità tecnica
> /agents architect
> Valuta la complessità tecnica di ogni storia
# Step 4: sprint-master pianifica lo sprint
> /agents sprint-master
> Pianifica lo sprint con velocity 40 story points
> e capacità del team di 3 sviluppatori7. 상담사 전문화 모범 사례
수십 명의 하위 에이전트와 작업한 후에는 무엇을 해야 하는지에 대한 명확한 패턴이 나타납니다. 효과적인 하위 에이전트를 만들고 일반적인 함정을 피하는 방법을 알아봅니다.
기본 원칙
| 원칙 | 설명 | Esempio |
|---|---|---|
| 최소 권한 | 각 상담원에게 꼭 필요한 도구만 제공하세요. | 코드 검토자는 파일을 쓸 수 없고 읽기만 할 수 있습니다. |
| 명확한 경계 | 에이전트 도메인 간의 명확한 경계 정의 | 디버거는 테스트를 작성하지 않고, 테스트 작성자는 디버그하지 않습니다. |
| 명시적 역할 | 역할은 일반적이지 않고 구체적이어야 합니다. | "개발자"가 아닌 "수석 Python 개발자" |
| 구조화된 출력 | 각 에이전트는 미리 정의된 형식으로 출력을 생성합니다. | 표준 섹션이 포함된 마크다운 템플릿 |
| 멱등성 작업 | 에이전트의 작업은 반복 가능해야 합니다. | 감사를 다시 실행해도 동일한 결과가 나와야 합니다. |
| 프로그레시브 디테일 | 요약 먼저, 요청 시 세부정보 | 요약 및 세부 조사 결과 |
피해야 할 안티패턴
하위 에이전트의 일반적인 실수
- 신의 대리인: 모든 일을 하는 에이전트입니다. 파일이 200줄을 초과하면 너무 일반적인 것입니다.
- 도구 과부하: 에이전트에 너무 많은 도구를 제공하면 에이전트 행동의 예측 가능성이 줄어듭니다.
- 모호한 역할: "일반 전문가"가 작동하지 않습니다. 전문성이 핵심이다
- 출력 형식 없음: 표준 형식이 없으면 각 실행마다 다른 결과가 생성됩니다.
- 충돌하는 에이전트: 동일한 파일에 쓰기 도구를 사용하는 두 에이전트로 인해 충돌이 발생함
- 누락된 제약조건: 명시적인 제약이 없으면 에이전트는 예상치 못한 결정을 내릴 수 있습니다.
- 복사-붙여넣기 에이전트: 이름만 변경하여 에이전트를 복제할 수 없습니다. 모든 것을 맞춤설정하세요.
하위 에이전트에 대한 품질 측정항목
하위 에이전트를 평가하는 방법
| 미터법 | 설명 | 목표 |
|---|---|---|
| 정확성 | 정확하고 유용한 출력의 비율 | > 90% |
| 일관성 | 서로 다른 실행 간에 일관된 출력 | > 95% |
| 경계 존중 | 정의된 도구와 경계에 대한 존중 | 100% |
| 형식 준수 | 정의된 출력 형식 준수 | > 95% |
| 유용성 | 사용자에게 출력의 실제 가치 | > 85% |
결론
전문 하위 에이전트는 Claude Code를 단일 보조자에서 보조자로 전환합니다. 가상 전문가 팀 터미널에서 사용 가능합니다. 6가지 카테고리 - 필수 개발, 언어, DevOps, 테스트 및 보안 전문가, 데이터 및 ML, 프로젝트 관리 - 전체 기술 스펙트럼을 포괄합니다. 현대 소프트웨어 개발에 꼭 필요합니다.
핵심 사항
- 하위 에이전트 대 스킬: 하위 에이전트는 고유한 역할과 도구를 갖춘 자율 보조자이며, 기술은 수동적 지식 모듈입니다.
- 마크다운 파일
.claude/agents/: 생성, 버전 관리 및 공유가 간단함 - 6가지 범주가 모든 요구 사항을 충족합니다. 개발, 언어, DevOps, 테스트, 데이터/ML, PM
- 최소 권한: 각 상담원에게 꼭 필요한 도구만 제공하세요.
- 4가지 위임 패턴: 각 시나리오에 대한 직접, 자동, 파이프라인 및 병렬
- 커뮤니티의 100개 이상의 하위 에이전트: awesome-claude-code-subagents 저장소를 시작점으로
- 다중 에이전트 오케스트레이션: 검토, 스프린트 계획, 감사 등 복잡한 작업을 위한 가상 팀
- 구조화된 출력: 각 상담원은 기본 형식으로 보고서를 생성해야 합니다.
에서 다음 기사 우리는 그들을 탐구할 것이다 후크 및 자동화: 이에 대한 응답으로 자동 작업을 수행할 수 있는 이벤트 중심 메커니즘 Claude Code 워크플로의 특정 이벤트에 적용됩니다. Hook을 생성하는 방법을 살펴보겠습니다. 커밋 전, 빌드 후, 배포 전 등 파이프라인 구축 사람의 개입 없이 정교한 자동화를 실현합니다.