Slash Commands avanzati: subagenti e orchestrazione di strumenti

I primi due articoli hanno coperto cos'è un slash command (un file Markdown) e come usare il prefisso ! per iniettare output della shell nel contesto. Questo va oltre: come far sì che un singolo command orchestri le capacità più potenti di Claude Code — riferimenti a file, subagenti, strumenti MCP — tenendo i permessi sotto controllo.

A questo livello un command non è più una semplice "scorciatoia di prompt", ma un piccolo workflow riutilizzabile.

Riferimenti `@file`: l'iniezione statica fatta meglio di `!cat`

!cat file.md riesce a spingere il contenuto di un file nel contesto, ma passa dalla shell e porta con sé diversi svantaggi: ogni volta si avvia un sottoprocesso; spazi o caratteri speciali nel percorso vanno escapati; e Claude Code non lo vede come "un file", solo come un blocco di testo.

Il riferimento @ è nativo:

---
description: Rivedere le modifiche secondo le convenzioni del progetto
---

Fai riferimento alle seguenti convenzioni:

@.claude/context/coding-standards.md
@.claude/context/security-checklist.md

Ora rivedi le modifiche del git diff e segnala tutto ciò che viola le regole.

!`git diff HEAD`

@percorso dice a Claude Code: "allega questo file alla conversazione". La differenza:

Caso	Con `!cat`	Con `@`
Percorso da argomento (`$ARGUMENTS`)	✅ solo `!cat` funziona	❌ `@` non espande le variabili
Convenzioni e template fissi del progetto	⚠️ si può, ma è pesante	✅ nativo, risparmia una chiamata shell
Contenuto dinamico (diff, log, risultati dei test)	✅ `!` obbligatorio	❌ impossibile

Regola: @ per i file statici, ! per output dinamici, !cat $ARGUMENTS per percorsi parametrici.

`allowed-tools`: mettere limiti di permesso a un command

Per default, durante l'esecuzione di un command il modello può usare tutti gli strumenti della sessione. Non è sempre quello che vuoi — per esempio /review è una revisione in sola lettura, e non vuoi che "per strada" modifichi anche una sola riga di codice.

Aggiungendo allowed-tools nel frontmatter, mentre il command è attivo sono permessi solo gli strumenti elencati:

---
description: Code review in sola lettura
allowed-tools: Read, Grep, Glob, Bash(git diff:*), Bash(git log:*)
---

Rivedi le differenze tra il branch corrente e master, solo lettura, niente modifiche.

!`git diff master...HEAD`

Alcuni punti chiave:

Bash(git diff:*) è un'autorizzazione fine — sono permesse solo chiamate bash che iniziano con git diff, git push viene bloccato
Read / Grep / Glob apre esplicitamente solo gli strumenti di lettura
Edit / Write non compaiono: anche se il modello volesse modificare codice, non ha i mezzi per farlo

Allo stesso modo, un command ad alti privilegi come /deploy può essere autorizzato esplicitamente:

---
description: Deploy del branch corrente
allowed-tools: Bash(kamal deploy:*), Bash(git push:*), Read
---

Scolpire nel marmo "cosa può fare questo command" è molto più affidabile che affidarsi a un'approvazione manuale di un prompt bash ad ogni esecuzione.

Invocare un subagente: isolare ciò che consuma contesto

Alcuni task fanno esplodere il contesto della conversazione principale — setacciare decine di file alla ricerca di tutte le chiamate di una funzione, fare statistiche sul codebase, analizzare un grosso blocco di log. Farlo direttamente lascia migliaia di righe di output nel contesto, e la conversazione successiva diventa lenta e meno acuta.

L'approccio giusto è passare quel lavoro a un subagent: il subagente gira in un contesto separato e riporta solo la conclusione. Nel command basta indicarlo esplicitamente:

---
description: Indagine approfondita su tutti gli usi di un simbolo
allowed-tools: Task
---

Usa il subagente Explore per indagare in profondità tutti gli usi del seguente simbolo: $ARGUMENTS

Chiedi al subagente di coprire:
- Tutti i punti di chiamata (inclusi i file di test)
- Gli scenari di business coinvolti
- L'eventuale presenza di implementazioni alternative equivalenti

Quando il subagente torna, dammi solo un riassunto da ≤300 parole, senza incollare frammenti di codice grezzi.

Con /trace SomeClass#some_method Claude Code avvia un subagente Explore che scandisce il codebase in parallelo; la conversazione principale riceve solo la conclusione distillata. Niente output di grep, niente frammenti di file, contesto pulito.

Livello successivo:

---
description: Indagine parallela su tre soluzioni candidate
allowed-tools: Task
---

Avvia 3 subagenti in parallelo, ognuno indaghi una delle seguenti vie di implementazione:

1. Usare l'esistente ActiveJob + Sidekiq
2. Usare Solid Queue
3. Costruire una piccola queue custom

Ogni agente risponde su: impegno, rischi, invasività sul codice esistente. Quando tornano tutte e tre le conclusioni, il confronto lo faccio io.

Tre subagenti in parallelo, la conversazione principale attende una volta sola. È una delle leve più forti che un command può offrire: trasformare un task di ricerca che costerebbe un sacco di token in un workflow scatenabile con un solo tasto.

Invocare strumenti MCP: far toccare ai command sistemi esterni

Se alla sessione sono collegati server MCP (Linear, GitHub, Sentry, un proxy di database custom…), un command può istruire direttamente il modello a usare quegli strumenti:

---
description: Genera una todo di implementazione a partire da una issue Linear
allowed-tools: mcp__linear__*, Read, Grep
---

Leggi la descrizione completa e i commenti della issue Linear $ARGUMENTS.

Incrociali con lo stato attuale del codebase (trova da solo i file rilevanti con Grep/Read) e produci una todo di implementazione:
- Quali file vanno toccati
- Ogni passo è un commit separato o si fa insieme
- Ci sono ambiguità da chiarire prima con il PM

Non iniziare a scrivere codice, solo il piano.

mcp__linear__* autorizza tutti gli strumenti Linear MCP — il modello può tirare giù dettagli della issue, commenti, stato. L'intero command diventa il punto di partenza di un workflow "dal ticket al piano di implementazione".

Punto cruciale: quando scrivi un nome di strumento MCP in allowed-tools devi usare il prefisso completo (mcp__<server>__<tool>), altrimenti l'autorizzazione non ha effetto.

La trappola della composizione: i slash command non si espandono ricorsivamente

Un fraintendimento molto comune: scrivere /test nel file di /review pensando di innescare il command test. Non funziona. Un slash command viene espanso una volta sola, al livello superiore dell'input utente. Dentro un command, /xxx è solo testo normale: il modello lo legge, ma Claude Code non lo esegue.

Per comporre più command ci sono alcune vie corrette:

Via A: estrarre la logica condivisa in un file di contesto, richiamato da vari command con @ o !cat

@.claude/context/review-checklist.md
@.claude/context/security-checklist.md

Via B: scrivere nel command "fai come /review" + ripetere le istruzioni chiave

Poco elegante ma efficace. Se il prompt è abbastanza chiaro, il modello segue lo stesso cammino.

Via C: un command avvia un subagente con il tool Task, e il prompt del subagente riusa gli stessi file di contesto

La vera orchestrazione di workflow passa da qui. Il command padre coordina e aggrega, il subagente esegue i passi concreti.

Anti-pattern da evitare: scrivere un command di centinaia di righe che prova a fare tutto in un'unica istruzione. La granularità esplode, la manutenzione va a picco, e il budget token di una singola esecuzione viene divorato da un solo command.

Quando usare cosa

A questo punto abbiamo in mano più o meno tutti i meccanismi che Claude Code offre per iniettare "capacità esterne" in un command. Come scegliere:

Necessità	Meccanismo preferito
Convenzioni, template, documenti di contesto fissi	riferimento `@file`
Stato in tempo reale (diff, log, test, query DB)	iniezione `!shell`
Contenuto di file con parametro	`!cat $ARGUMENTS`
Ricerca costosa in contesto, scansioni multi-file	subagent via Task
Sistemi esterni (issue tracker, monitoraggio, produzione)	strumenti MCP + `allowed-tools`
Workflow multi-step seriali/paralleli	command padre che orchestra subagenti

I limiti di permesso dichiarali esplicitamente con allowed-tools, specialmente per i command condivisi dal team: scolpire cosa può fare il command è più affidabile che contare su un'approvazione umana ad ogni chiamata.

Un esempio vicino alla produzione

Mettendo tutto insieme, ecco un command "indaga il percorso implementativo a partire da un ticket Linear":

---
description: Produci un piano di implementazione a partire da un ticket Linear
allowed-tools: mcp__linear__*, Task, Read, Grep, Glob, Bash(git log:*)
---

## Contesto

@.claude/context/architecture.md
@.claude/context/coding-standards.md

## Stato attuale del codebase

!`git log --oneline -10`

## Compito

Tira giù descrizione, commenti e ticket collegati del ticket Linear $ARGUMENTS.

Poi avvia due subagenti in parallelo:
1. Il primo: trova nel codebase tutte le implementazioni esistenti correlate e i moduli riutilizzabili
2. Il secondo: valuta i rischi — quali percorsi di codice ad alto traffico tocca questa modifica, ci sono buchi nella copertura dei test

Quando sono tornati entrambi, produci:
- Passi di implementazione (ordinati per dipendenze)
- Elenco rischi
- Granularità di commit suggerita

Non iniziare a scrivere codice.

Con /plan ENG-4213, una sola istruzione fa girare l'intera catena: prende il ticket → indaga il codebase in parallelo → valuta i rischi → sintetizza il piano. All'utente resta solo leggere la conclusione e decidere se partire.

Questo è l'arco completo dei primi tre articoli della serie sui slash command: definire prompt riutilizzabili (intro) → iniettare contesto dinamico (context) → orchestrare strumenti e subagenti (questo articolo). A questo livello .claude/commands/ non è più una cartella di scorciatoie: è la piccola libreria di workflow del team.