Subagenti Specializzati in Claude Code
I subagenti sono uno dei meccanismi più avanzati di Claude Code. A differenza delle skill (moduli di conoscenza passivi), i subagenti sono assistenti autonomi specializzati che operano con prompt personalizzati, restrizioni sugli strumenti e ruoli ben definiti. Ogni subagente è progettato per eccellere in un dominio specifico: code review, refactoring, debugging, testing, DevOps, sicurezza e molto altro.
In questo quattordicesimo articolo della serie, esploreremo l'architettura dei subagenti, le sei categorie principali con oltre cento esempi dalla community, i pattern di creazione e orchestrazione, e le best practice per costruire un ecosistema di agenti specializzati che lavorano in sinergia all'interno del terminale.
Cosa Imparerai
- Comprendere la differenza tra skill e subagenti
- Esplorare le 6 categorie principali di subagenti
- Creare subagenti personalizzati con prompt strutturati
- Configurare restrizioni sugli strumenti per ogni subagente
- Applicare pattern di delega tra agente principale e subagenti
- Scoprire oltre 100 subagenti dalla community
- Orchestrare più subagenti per task complessi
- Applicare best practice per la specializzazione degli agenti
Panoramica della Serie Completa
| # | Articolo | Focus |
|---|---|---|
| 1 | Claude come Partner Tecnico | Setup e primi passi |
| 2 | Contesto e Setup del Progetto | CLAUDE.md e configurazione |
| 3 | Ideazione e Requisiti | MVP e user personas |
| 4 | Architettura Backend e Frontend | Spring Boot e Angular |
| 5 | Struttura del Codice | Organizzazione e convenzioni |
| 6 | Prompt Engineering Avanzato | Tecniche avanzate |
| 7 | Testing e qualità | Strategie e generazione test |
| 8 | Documentazione Professionale | README, API, ADR |
| 9 | Deploy e DevOps | Docker, CI/CD, monitoring |
| 10 | Evoluzione e Manutenzione | Refactoring e scalabilità |
| 11 | Integrazione Progetto Reale | Claude Code in produzione |
| 12 | Claude Code CLI | Comandi e configurazione |
| 13 | Agent Skills | capacità modulari |
| 14 | Subagenti Specializzati (sei qui) | Agenti con ruoli specifici |
| 15 | Hooks e Automazione | Event-driven workflows |
| 16 | Ralph Wiggum Method | Sviluppo guidato da test |
| 17 | BMAD Method | Gestione progetti strutturata |
| 18 | Orchestrazione Multi-Agente | Pipeline di agenti |
| 19 | Collaborative Work | Team e pair programming AI |
| 20 | Sicurezza e Best Practice | Hardening e compliance |
| 21 | Monitoring e Observability | Metriche e debugging |
1. Architettura dei Subagenti
Un subagente è un file Markdown posizionato nella directory
.claude/agents/ del progetto. Ogni file definisce un assistente specializzato
con la propria identità, competenze, strumenti permessi e formato di output.
L'agente principale di Claude Code può delegare task specifici ai subagenti
quando il contesto della richiesta corrisponde al loro dominio di competenza.
Skill vs Subagenti: Le Differenze Fondamentali
Confronto tra Skill e Subagenti
| Caratteristica | Skill | Subagente |
|---|---|---|
| Directory | .claude/skills/ |
.claude/agents/ |
| Natura | Modulo di conoscenza passivo | Assistente autonomo attivo |
| Identita | Nessuna - è un'estensione dell'agente principale | Ruolo definito con personalità e competenze proprie |
| Tool Access | Usa gli stessi tool dell'agente principale | Può avere tool permessi/negati specifici |
| Autonomia | Zero - segue le istruzioni dell'agente | Alta - prende decisioni nel suo dominio |
| Invocazione | Automatica o con /skill |
Con /agents o delega automatica |
| Contesto | Condivide il contesto dell'agente principale | Riceve un contesto filtrato e specifico |
| Uso ideale | Conoscenze e template | Task complessi che richiedono giudizio |
Struttura della Directory
Organizzazione dei subagenti in un progetto
.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 sprintAnatomia di un Subagente
Ogni file subagente segue una struttura predefinita che include quattro sezioni fondamentali: definizione del ruolo, strumenti permessi, istruzioni operative e formato di output.
.claude/agents/template-agent.md - Struttura base
# 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. Le 6 Categorie di Subagenti
La community ha sviluppato una tassonomia di subagenti organizzata in sei categorie principali. Il repository awesome-claude-code-subagents raccoglie oltre 100 agenti specializzati pronti all'uso e personalizzabili. Vediamo ogni categoria in dettaglio con esempi concreti.
Categoria 1: Essential Development
I subagenti di sviluppo essenziale coprono le attivita quotidiane di ogni sviluppatore: revisione del codice, refactoring e debugging. Sono i più utilizzati e spesso il punto di partenza per chi adotta i subagenti.
Subagenti di Sviluppo Essenziale
| Subagente | Ruolo | Output Tipico |
|---|---|---|
| code-reviewer | Revisore di codice senior | Report con issue classificate per severity, suggerimenti di fix |
| refactoring-expert | Specialista in refactoring | Piano di refactoring con step ordinati, codice refactorizzato |
| debugger | Investigatore di bug | Analisi root cause, stack trace commentato, fix proposto |
| architect | Architetto software | ADR, diagrammi C4, trade-off analysis |
| pair-programmer | Compagno di pair programming | Suggerimenti in tempo reale, alternative di implementazione |
.claude/agents/code-reviewer.md - Subagente Code Review
# 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 - Subagente Debugger
# 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]
```Categoria 2: Language-Specific Experts
I subagenti esperti di linguaggio portano conoscenze approfondite su ecosistemi specifici: idiomi del linguaggio, framework principali, tool di build, pattern di design e best practice della community. Sono particolarmente utili in team multi-stack dove non tutti sono esperti di ogni tecnologia.
Subagenti Esperti di Linguaggio
| Subagente | Stack | Specializzazioni |
|---|---|---|
| python-expert | Python 3.12+ | Django, FastAPI, asyncio, type hints, pytest, Poetry |
| typescript-expert | TypeScript 5.x | Angular, React, Node.js, strict mode, generics avanzati |
| rust-expert | Rust (stable) | Ownership, lifetime, async/await, unsafe, no_std, Tokio |
| go-expert | Go 1.22+ | Goroutine, channel, generics, context, net/http, gRPC |
| java-expert | Java 21+ | Spring Boot, virtual threads, records, sealed classes, 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 esportataCategoria 3: DevOps & Cloud Specialists
I subagenti DevOps portano competenze specializzate su infrastruttura cloud, containerizzazione, orchestrazione e pipeline di deployment. Sono essenziali per team che gestiscono infrastrutture complesse e necessitano di automazione affidabile.
Subagenti DevOps e Cloud
| Subagente | Dominio | Specializzazioni |
|---|---|---|
| docker-specialist | Containerizzazione | Multi-stage build, layer optimization, compose, security scanning |
| k8s-engineer | Kubernetes | Deployment, Service, Ingress, HPA, RBAC, Helm charts |
| ci-cd-architect | Pipeline CI/CD | GitHub Actions, GitLab CI, Jenkins, ArgoCD, deployment strategies |
| aws-consultant | Amazon Web Services | EC2, ECS, Lambda, RDS, S3, CloudFront, IAM, CDK/Terraform |
| terraform-expert | Infrastructure as Code | Moduli, state management, workspace, provider, drift detection |
.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"]
```Categoria 4: Testing & Security
I subagenti di testing e sicurezza automatizzano la scrittura di test e l'identificazione di vulnerabilità. Sono progettati per lavorare in modo sistematico, coprendo edge case che spesso vengono trascurati nello sviluppo quotidiano.
Subagenti Testing e Sicurezza
| Subagente | Focus | Output |
|---|---|---|
| unit-test-writer | Test unitari | Test con 80%+ coverage, mock/stub, edge case |
| integration-test-writer | Test di integrazione | Test con database reale, API call, workflow completi |
| e2e-test-writer | Test end-to-end | Test Playwright/Cypress con page objects e scenari utente |
| security-auditor | Audit di sicurezza | Report OWASP, CVE check, analisi dipendenze |
| performance-tester | Test di performance | Load test, profiling, bottleneck identification |
| accessibility-auditor | Audit accessibilità | Report WCAG 2.1 AA con violazioni e fix proposti |
.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]
```Categoria 5: Data, ML & AI
I subagenti specializzati in dati, machine learning e intelligenza artificiale assistono nella costruzione di pipeline di dati, training di modelli, valutazione delle performance e deployment di soluzioni ML.
Subagenti Data e ML
| Subagente | Focus | capacità |
|---|---|---|
| data-pipeline-builder | ETL e pipeline dati | Costruisce pipeline ETL con Apache Airflow, dbt, o script Python |
| ml-trainer | Training modelli | Configura esperimenti ML con tracking, iperparametri e cross-validation |
| model-evaluator | Valutazione modelli | Analizza metriche, genera confusion matrix, ROC curve e report |
| data-quality-checker | qualità dei dati | Verifica completezza, coerenza, freshness e accuracy dei dataset |
| prompt-engineer | Prompt engineering | Ottimizza prompt per LLM con A/B testing e evaluation framework |
.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 esponenzialeCategoria 6: PM & Business Analysis
I subagenti di project management e business analysis assistono nella gestione del ciclo di vita del progetto: dalla raccolta dei requisiti alla pianificazione degli sprint, dalla scrittura delle user stories alla gestione del backlog.
Subagenti PM e Business
| Subagente | Focus | Output |
|---|---|---|
| requirements-analyst | Analisi requisiti | Documenti di requisiti, diagrammi use case, acceptance criteria |
| story-writer | User stories | User stories con acceptance criteria, story points, dependency map |
| sprint-master | Sprint planning | Sprint backlog, velocity chart, burndown, retrospective report |
| stakeholder-reporter | Report per stakeholder | Status report, risk register, milestone tracking, KPI dashboard |
| technical-writer | Documentazione tecnica | API docs, user guides, architecture docs, runbook operativi |
.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. Creare Subagenti Personalizzati
Creare un subagente efficace richiede una comprensione chiara del dominio di competenza e dei confini operativi. Un subagente ben progettato è come un membro del team: ha un ruolo chiaro, sa cosa può e non può fare, e comunica in modo strutturato.
Framework di Design per Subagenti
Le 5 Domande Fondamentali
- CHI e? Definire il ruolo, l'esperienza e la personalità dell'agente
- COSA sa fare? Elencare le competenze con il livello di expertise
- COME opera? Descrivere il processo decisionale e le metodologie
- DOVE opera? Definire i confini: tool permessi, file accessibili
- COSA produce? Specificare il formato e la struttura dell'output
Esempio Pratico: Subagente per Migrazione Database
.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. Pattern di Delega tra Agente Principale e Subagenti
L'orchestrazione tra l'agente principale di Claude Code e i subagenti segue pattern di delega ben definiti. Comprendere questi pattern è fondamentale per sfruttare al massimo il potenziale dei subagenti.
Pattern 1: Direct Delegation
L'utente invoca esplicitamente un subagente con il comando /agents
e gli assegna un task specifico. Il subagente opera autonomamente nel suo
dominio e riporta il risultato.
Esempio di delega diretta
# 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 riportaPattern 2: Automatic Routing
L'agente principale analizza il prompt dell'utente e delega automaticamente al subagente più appropriato. Questo pattern funziona quando i subagenti hanno domini chiaramente distinti.
Esempio di routing automatico
# 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 checklistPattern 3: Pipeline Delegation
Più subagenti vengono invocati in sequenza, dove l'output di uno diventa l'input del successivo. Questo pattern è ideale per workflow complessi che attraversano più domini.
Pipeline di subagenti per una nuova feature
# 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 reviewPattern 4: Parallel Delegation
Quando i task sono indipendenti tra loro, più subagenti possono lavorare in parallelo. Questo pattern riduce significativamente il tempo totale per task complessi.
Pattern di Delega a Confronto
| Pattern | Quando Usarlo | Vantaggi | Limitazioni |
|---|---|---|---|
| Direct | Task singolo in un dominio specifico | Controllo totale, prevedibile | Richiede conoscenza dei subagenti |
| Automatic | Task chiari che rientrano in un dominio | Trasparente per l'utente | Possibile routing errato |
| Pipeline | Workflow multi-fase con dipendenze | qualità elevata, ogni fase specializzata | Tempo di esecuzione sequenziale |
| Parallel | Task indipendenti da eseguire simultaneamente | Velocita, efficienza | Possibili conflitti su file condivisi |
5. L'Ecosistema Community: 100+ Subagenti
Il repository awesome-claude-code-subagents raccoglie una collezione curata di oltre 100 subagenti sviluppati dalla community. Ecco una panoramica organizzata per dominio delle risorse più utilizzate.
Catalogo Subagenti Community - Top 50
| # | Subagente | Categoria | Descrizione |
|---|---|---|---|
| 1 | senior-reviewer | Development | Code review con 20+ check automatici |
| 2 | bug-hunter | Development | Debugging sistematico con git bisect |
| 3 | arch-advisor | Development | Consulenza architetturale con ADR |
| 4 | clean-coder | Development | Refactoring basato su Clean Code |
| 5 | api-designer | Development | Design API RESTful con OpenAPI |
| 6 | python-guru | Language | Python idiomatico con type hints |
| 7 | ts-wizard | Language | TypeScript avanzato e type gymnastics |
| 8 | rust-sentinel | Language | Rust con focus su safety e performance |
| 9 | go-builder | Language | Go idiomatico con concurrency patterns |
| 10 | java-architect | Language | Java 21+ con virtual threads e records |
| 11 | swift-expert | Language | Swift/SwiftUI per iOS development |
| 12 | kotlin-expert | Language | Kotlin con coroutines e Compose |
| 13 | docker-master | DevOps | Dockerfile ottimizzati multi-stage |
| 14 | k8s-navigator | DevOps | Kubernetes manifest e Helm charts |
| 15 | terraform-planner | DevOps | IaC con moduli e state management |
| 16 | gh-actions-builder | DevOps | GitHub Actions workflow ottimizzati |
| 17 | aws-architect | DevOps | AWS Well-Architected con CDK |
| 18 | gcp-consultant | DevOps | Google Cloud con Terraform |
| 19 | test-craftsman | Testing | Test unitari con pattern avanzati |
| 20 | e2e-automator | Testing | Playwright e2e con page objects |
| 21 | load-tester | Testing | Test di carico con k6 e Artillery |
| 22 | pen-tester | Security | Penetration testing automatizzato |
| 23 | vuln-scanner | Security | Scan vulnerabilità con trivy e snyk |
| 24 | compliance-checker | Security | GDPR, SOC2, HIPAA compliance |
| 25 | data-engineer | Data/ML | Pipeline ETL con Airflow e dbt |
Catalogo Subagenti Community - 26-50
| # | Subagente | Categoria | Descrizione |
|---|---|---|---|
| 26 | ml-engineer | Data/ML | Training modelli con MLflow tracking |
| 27 | data-quality | Data/ML | Great Expectations per validazione dati |
| 28 | prompt-optimizer | Data/ML | Ottimizzazione prompt LLM |
| 29 | sql-expert | Data/ML | Query SQL ottimizzate con explain plan |
| 30 | product-owner | PM | Backlog management e prioritizzazione |
| 31 | scrum-master | PM | Sprint planning e retrospective |
| 32 | tech-writer | PM | Documentazione tecnica professionale |
| 33 | ux-reviewer | PM | Heuristic evaluation interfacce |
| 34 | onboarding-guide | PM | Guide onboarding per nuovi sviluppatori |
| 35 | react-expert | Language | React 19 con server components |
| 36 | angular-expert | Language | Angular 18+ standalone e signals |
| 37 | vue-expert | Language | Vue 3 Composition API |
| 38 | nextjs-expert | Language | Next.js App Router e RSC |
| 39 | graphql-architect | Development | Schema GraphQL e resolver design |
| 40 | microservices-designer | Development | Architettura microservizi con DDD |
| 41 | event-sourcing-expert | Development | Event sourcing e CQRS |
| 42 | regex-master | Development | Pattern regex complessi con test |
| 43 | git-historian | Development | Analisi storia Git e archeologia codice |
| 44 | monitoring-engineer | DevOps | Prometheus, Grafana, alerting |
| 45 | nginx-configurator | DevOps | Configurazione Nginx ottimizzata |
| 46 | ssl-manager | Security | Certificati SSL, Let's Encrypt, TLS |
| 47 | a11y-auditor | Testing | Audit accessibilità WCAG 2.1 AA |
| 48 | seo-optimizer | Development | Ottimizzazione SEO tecnica |
| 49 | i18n-specialist | Development | Internazionalizzazione e localizzazione |
| 50 | migration-planner | Development | Migrazione framework e versioni |
Oltre a questi 50, il repository contiene decine di subagenti più specializzati per domini di nicchia: blockchain, IoT, game development, real-time systems, mobile development e altro. Ogni subagente può essere scaricato e personalizzato per le esigenze specifiche del proprio progetto.
6. Orchestrazione tra Subagenti Multipli
L'orchestrazione di più subagenti è il livello più avanzato di utilizzo di Claude Code. Permette di creare team virtuali dove ogni membro ha un ruolo specifico e contribuisce a un obiettivo comune.
Pattern Team: Code Review Completa
Orchestrazione per code review multi-aspetto
# 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 azionePattern Team: Sprint Planning
Orchestrazione per sprint planning
# 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. Best Practice per la Specializzazione degli Agenti
Dopo aver lavorato con decine di subagenti, emergono pattern chiari su cosa rende un subagente efficace e come evitare le trappole comuni.
Principi Fondamentali
| Principio | Descrizione | Esempio |
|---|---|---|
| Least Privilege | Dare a ogni agente solo i tool strettamente necessari | Il code-reviewer non può scrivere file, solo leggere |
| Clear Boundaries | Definire confini chiari tra i domini degli agenti | Il debugger non scrive test, il test-writer non debugga |
| Explicit Role | Il ruolo deve essere specifico, non generico | "Senior Python Developer" non "Sviluppatore" |
| Structured Output | Ogni agente produce output in formato predefinito | Template Markdown con sezioni standard |
| Idempotent Actions | Le azioni di un agente devono essere ripetibili | Rieseguire un audit deve produrre lo stesso risultato |
| Progressive Detail | Sommario prima, dettagli su richiesta | Executive summary + detailed findings |
Anti-Pattern da Evitare
Errori Comuni con i Subagenti
- God Agent: Un agente che fa tutto. Se il file supera le 200 righe, è troppo generico
- Tool Overload: Dare troppi tool a un agente riduce la prevedibilità del suo comportamento
- Ambiguous Role: "Esperto generico" non funziona. La specializzazione è la chiave
- No Output Format: Senza un formato standard, ogni esecuzione produce risultati diversi
- Conflicting Agents: Due agenti con tool Write sugli stessi file creano conflitti
- Missing Constraints: Senza vincoli espliciti, l'agente può prendere decisioni inaspettate
- Copy-Paste Agents: Clonare un agente cambiando solo il nome non funziona - personalizzare tutto
Metriche di qualità per Subagenti
Come Valutare un Subagente
| Metrica | Descrizione | Target |
|---|---|---|
| Accuracy | Percentuale di output corretti e utili | > 90% |
| Consistency | Output coerente tra esecuzioni diverse | > 95% |
| Boundary Respect | Rispetto dei tool e confini definiti | 100% |
| Format Compliance | Aderenza al formato di output definito | > 95% |
| Usefulness | Valore pratico dell'output per l'utente | > 85% |
Conclusione
I subagenti specializzati trasformano Claude Code da un singolo assistente a un team di esperti virtuali a disposizione nel terminale. Le sei categorie - sviluppo essenziale, esperti di linguaggio, DevOps, testing e sicurezza, data e ML, project management - coprono l'intero spettro delle competenze necessarie nello sviluppo software moderno.
Punti Chiave
- Subagenti vs Skill: I subagenti sono assistenti autonomi con ruolo e tool propri, le skill sono moduli di conoscenza passivi
- File Markdown in
.claude/agents/: Semplici da creare, versionare e condividere - 6 categorie coprono ogni esigenza: Development, Language, DevOps, Testing, Data/ML, PM
- Least Privilege: Dare a ogni agente solo i tool strettamente necessari
- 4 pattern di delega: Direct, Automatic, Pipeline e Parallel per ogni scenario
- 100+ subagenti dalla community: Il repository awesome-claude-code-subagents come punto di partenza
- Orchestrazione multi-agente: Team virtuali per task complessi come review, sprint planning, audit
- Output strutturato: Ogni agente deve produrre report nel formato predefinito
Nel prossimo articolo esploreremo gli Hooks e l'Automazione: meccanismi event-driven che permettono di eseguire azioni automatiche in risposta a eventi specifici nel workflow di Claude Code. Vedremo come creare hook per pre-commit, post-build, pre-deploy e molto altro, costruendo pipeline di automazione sofisticate senza intervento manuale.