Blog

Claude Code Spec Kit: configurare le specifiche

Markdown

Come configurare GitHub Spec Kit in Claude Code: 4 fasi: Specify, Plan, Tasks, Implement. Ecco cosa sostituisce il vibe coding improvvisato.

Leggi l’articolo completo

Punto chiave

Spec Kit è uno strumento di GitHub che ti permette di scrivere una specifica dell’attività in linguaggio naturale, dopodiché Claude Code elabora un piano, lo suddivide in attività e scrive il codice. Non è teoria: 107.000 stelle su GitHub in 8 mesi e AWS ha usato questa metodologia per realizzare un progetto di scoperta di farmaci in 3 settimane invece che in diversi mesi. Questa guida illustra l’installazione, i modelli, le 4 fasi del flusso di lavoro e il controllo finale, oltre a come collegarlo al tuo CLAUDE.md.

Documentazione Ailoot — materiale di riferimento sull’uso del servizio.

Che fine ha fatto il vibe coding nel maggio 2026?

Punto chiave

In 8 mesi GitHub Spec Kit ha raccolto 107.000 stelle. AWS ha pubblicato un caso di studio che riportava un risparmio di oltre 80 ore su una funzionalità. La tendenza della settimana a maggio: la specifica come alternativa all’improvvisazione.

Un anno dopo, il 4 febbraio 2026, ha pubblicato un thread retrospettivo:

Nel suo intervento a Sequoia Ascent 2026, l’ha formulato in modo ancora più preciso: “Il vibe coding alza il livello minimo: ciò che tutti possono fare nel software. L’agentic engineering preserva il livello massimo: lo standard qualitativo dello sviluppo professionale”. Sullo stesso palco, ha pronunciato una frase entrata nel lessico del settore: “Il vibe coding non ti autorizza a introdurre vulnerabilità. Come prima, sei comunque responsabile del tuo software”.

Sono successe due cose in parallelo. Nel settembre 2025, GitHub ha pubblicato lo strumento Spec Kit, che ha raccolto 107.000 stelle in 8 mesi. Nel febbraio 2026, AWS ha pubblicato un caso di studio dettagliato sulla scoperta di farmaci che riportava “il 95% della logica di business generata dalla specifica, con un risparmio di oltre 80 ore”.

Entro la fine di maggio 2026, nel mondo anglofono si era formato un consenso: il vibe coding come metodo di lavoro è il livello per principianti. Il passo successivo è lo Spec-Driven Development. Questa guida spiega come installare e applicare l’approccio.

Che cosa sono Spec Kit e lo Spec-Driven Development?

Punto chiave

Lo Spec-Driven Development (SDD) capovolge l’approccio consueto agli agenti IA. Prima, il codice era la fonte di verità e la specifica era documentazione di supporto. Ora la fonte di verità è la specifica e il codice ne diventa il passaggio finale: l’implementazione. Spec Kit è uno strumento CLI di GitHub che trasforma 4 fasi (Specify, Plan, Tasks, Implement) e un controllo finale Converge in comandi pronti all’uso in Claude Code, Cursor, Copilot e oltre 30 altri agenti.

L’idea centrale della metodologia è riassunta in una frase della documentazione ufficiale di GitHub:

Lo Spec-Driven Development cambia la gerarchia: le specifiche non sono al servizio del codice; è il codice a essere al servizio delle specifiche. La specifica diventa l’artefatto principale e il codice ne è l’espressione in uno specifico linguaggio e framework.

— Documentazione GitHub Spec Kit, https://github.com/github/spec-kit/blob/main/spec-driven.md

In pratica, il processo si articola in 4 fasi (Spec Kit ne aggiunge un’altra, una fase zero — la constitution, descritta più avanti):

  1. Specify - scrivi in linguaggio naturale la specifica di ciò che vuoi. COSA fare e PERCHÉ. Non COME.
  2. Plan - l’agente prende la specifica e prepara un piano tecnico: quali tecnologie usare, quale architettura e quali componenti.
  3. Tasks - l’agente suddivide il piano in attività specifiche e verificabili, con le relative dipendenze.
  4. Implement - l’agente (o i suoi subagenti) svolge le attività e scrive il codice.

Dopo Implement, la versione corrente di Spec Kit prevede una fase di verifica chiamata Converge: l’agente confronta il codice finito con la specifica, il piano e le attività, poi aggiunge a tasks.md ciò che è stato tralasciato. Ripeti Implement e Converge finché Converge non risponde “Converged”.

Ogni fase corrisponde a un file markdown separato nel repository. In Claude Code, ogni fase è un comando slash separato: /speckit-specify, /speckit-plan, /speckit-tasks, /speckit-implement, mentre il controllo è /speckit-converge. La documentazione di Spec Kit riporta gli stessi comandi con un punto (/speckit.specify), ma in Claude Code Spec Kit li installa come skill, che si invocano con un trattino. Se qualcosa va storto in una fase, modifica il file markdown e ripeti la fase successiva.

Spec Kit è un’implementazione specifica di SDD. A maggio 2026 contava già più di 30 integrazioni con diversi agenti IA. All’interno dello stesso repository, Spec Kit funziona allo stesso modo con Claude Code, Cursor, GitHub Copilot, Codex CLI, Windsurf, Qwen, Tabnine, Amazon Q, Gemini, Goose e una dozzina di altri.

Fase di Spec KitComando slashArtefatto nel repository
Constitution/speckit-constitution.specify/memory/constitution.md
Specify/speckit-specifyspecs/###-feature/spec.md
Clarify (facoltativo)/speckit-clarifymodifiche in spec.md
Plan/speckit-planspecs/###-feature/plan.md
Checklist (facoltativo)/speckit-checklistchecklist della qualità dei requisiti
Tasks/speckit-tasksspecs/###-feature/tasks.md
Analyze (facoltativo)/speckit-analyzerapporto su spec, plan e tasks
Implement/speckit-implementcodice nel progetto
Converge/speckit-convergeverdetto “Converged” o nuove attività in tasks.md

Dopo un’esecuzione, il repository contiene quindi non solo il codice, ma anche la sua specifica, il piano e le attività. Un mese dopo puoi tornare al progetto, leggere spec.md e capire che cosa è stato fatto e perché. Non è più “vibe coding: il codice non esiste”: è la memoria di lavoro del progetto.

Perché serve a chi fa vibe coding senza scrivere codice?

Punto chiave

Il problema principale per chi fa vibe coding è l’imprevedibilità. Oggi l’agente ti crea una funzionalità funzionante in 20 minuti; domani, con un’attività simile, produce un groviglio di codice. Spec Kit elimina la causa di questa imprevedibilità: un’attività descritta in modo vago. Quando scrivi una specifica usando un modello, l’agente lavora in modo coerente perché ha una fonte di verità inequivocabile. Inoltre, ottieni un artefatto persistente nel repository a cui potrai tornare un mese dopo.

Spec Kit formalizza la pianificazione in passaggi distinti con 4 comandi slash. La logica: separare “ragionarci sopra” dall’“implementarlo”, in modo che avvengano in finestre di contesto diverse. Ogni fase parte da un contesto pulito, non ingombrato da quella precedente.

Tre vantaggi concreti per chi fa vibe coding:

  • Prevedibilità. Quando dici all’agente “crea un modulo di registrazione con conferma via email”, è lui a indovinare 10 dettagli, e tre non corrispondono a ciò che avevi in mente. Se hai un spec.md con User Stories, Acceptance Scenarios e marcatori [NEEDS CLARIFICATION] per ogni punto incerto, non c’è nulla da indovinare.
  • Memoria del progetto. Un mese dopo non ricorderai che cosa hai discusso con l’agente in chat. Ma spec.md, plan.md e tasks.md sono nel repository, nella cartella specs/###-feature/ accanto al codice. Ti mostrano non solo che cosa è stato fatto, ma anche perché.
  • Scalabilità. Per una funzionalità che coinvolge 1-2 file, la differenza è appena percettibile. Per una che coinvolge 20 file e 5 entità di dati, la differenza è tra “riscrivere tutto dopo 4 ore” e “dopo 4 ore è tutto nel branch principale”. AWS Kiro ha dimostrato il 95% di automazione della logica di business a partire da una specifica nel progetto TargetID.

La grande illusione del vibe coding è che all’inizio sembri più veloce. Mezz’ora e hai un prototipo. Ma dopo una settimana il prototipo si rompe ed è più facile buttarlo via. Lo Spec-Driven Development richiede un po’ più di tempo all’inizio (un’ora invece di mezz’ora), ma dopo una settimana lavori ancora nello stesso repository.

Come installare Spec Kit in Claude Code (4 passaggi)

Punto chiave

Spec Kit si installa tramite uv, un gestore di pacchetti Python di Astral. Il comando è lungo una riga. Una volta installato, vai nel tuo repository, esegui specify init con il flag --integration claude (oppure scegli Claude Code dall’elenco degli agenti) e otterrai una struttura già pronta, con modelli per constitution, spec, plan e tasks, oltre a una serie di comandi /speckit-* direttamente in Claude Code. L’installazione richiede 5 minuti se uv è già installato e 10 minuti se devi installarlo da zero.

Passaggio 1. Installa uv. Devi farlo una volta sola; poi rimane sul tuo sistema.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Verifica che uv sia stato installato:

uv --version

Passaggio 2. Installa Spec Kit. Un solo comando:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

Verifica:

specify --version

Passaggio 3. Inizializza il repository. Vai nella cartella del progetto (o creane una nuova) ed esegui:

specify init --here --integration claude

Il flag --integration claude seleziona direttamente Claude Code. Se lo ometti, Spec Kit ti chiede di scegliere un agente da un elenco interattivo e potrebbe anche chiederti il tipo di script (su macOS e Linux, lascia sh). Se la cartella non è vuota, Spec Kit avviserà che unirà i propri file ai tuoi: prima esegui il commit del lavoro, poi ripeti il comando con il flag --force.

Dopodiché, nel repository compariranno:

.specify/
  memory/
    constitution.md        # project rules, filled in by /speckit-constitution
  scripts/
  templates/
    spec-template.md
    plan-template.md
    tasks-template.md
.claude/
  skills/
    speckit-constitution/SKILL.md
    speckit-specify/SKILL.md
    speckit-clarify/SKILL.md
    speckit-plan/SKILL.md
    speckit-checklist/SKILL.md
    speckit-tasks/SKILL.md
    speckit-analyze/SKILL.md
    speckit-implement/SKILL.md
    speckit-converge/SKILL.md
    speckit-taskstoissues/SKILL.md

Passaggio 4. Apri Claude Code e controlla i comandi slash. Esegui questo comando nella stessa cartella:

claude

Nella sessione, digita /speckit: tra i suggerimenti dovrebbero comparire i comandi speckit-*. Se non compaiono, riavvia Claude Code perché rilegga .claude/skills/. Se hai già un CLAUDE.md nella radice del progetto, Spec Kit lo lascia intatto: funziona insieme a esso, in .specify/memory/constitution.md.

Spec Kit funziona anche senza Claude Code (supporta oltre 30 agenti), ma questa guida illustra la configurazione specifica per Claude. Se vuoi installare subito due strumenti, consulta le guide separate su come configurare CLAUDE.md e la Plan Mode in Claude Code.

Spec Kit è il primo elemento di un “contratto di lavoro per l’agente”. La configurazione completa include tutti e tre questi componenti: un clone IA (la tua metodologia sotto forma di Skills e subagent), un Second Brain (la struttura business/ a cui l’agente ritorna ogni volta) e il context engineering (Spec Kit, Plan Mode, /compact). Sono i tre pilastri senza i quali l’IA ha allucinazioni.

Come scrivere la tua prima specifica (Specify)

Punto chiave

Spec Kit ti chiede di descrivere una funzionalità in forma libera, poi amplia la descrizione trasformandola in un file spec.md basato su un modello: User Stories con priorità P1/P2/P3, Acceptance Scenarios nel formato Given/When/Then, Functional Requirements (FR-001, FR-002 e così via) e Success Criteria con risultati misurabili. Nei punti in cui l’agente è incerto, inserisce un marcatore [NEEDS CLARIFICATION: ...] e tu rispondi prima di passare a Plan.

In Claude Code, digita:

/speckit-specify

L’agente ti chiederà di descrivere la funzionalità. In questa fase, usa un linguaggio semplice, senza termini tecnici:

I want a registration form in my app. The user enters an email
and password, receives a confirmation email, and after confirming
lands on the dashboard. Confirmation expires after 48 hours. If the
email is still unconfirmed, delete the account within 5 minutes after
that deadline; never delete a confirmed account.

Nell’esempio la tolleranza di eliminazione è chiarita in 5 minuti dopo la scadenza di 48 ore. Per un prodotto reale confermala prima di Plan; una scadenza esatta a 48 ore richiede progetto e test che la facciano rispettare. L’agente preparerà specs/001-registration/spec.md: aprilo per vedere questa struttura.

# Feature Specification: User Registration

**Feature Branch**: `001-registration`
**Created**: 2026-05-31
**Status**: Draft
**Input**: User Description: "I want a registration form..."

## User Scenarios & Testing *(mandatory)*

### Primary User Story
As a new user, I want to register an account with email confirmation,
so that I can access the dashboard with a verified identity.

### Acceptance Scenarios
1. **Given** I am on the registration page,
   **When** I submit valid email and password,
   **Then** I receive a confirmation email within 1 minute.
2. **Given** I clicked the confirmation link within 48 hours,
   **When** I land on the dashboard,
   **Then** I see my email confirmed in profile.
3. **Given** I have not confirmed at the 48-hour deadline,
   **When** cleanup runs within the next 5 minutes,
   **Then** my account is deleted and email is freed for re-registration.
4. **Given** my account is just under 48 hours old or already confirmed,
   **When** cleanup runs,
   **Then** the account is not deleted.

## Requirements *(mandatory)*

### Functional Requirements
- **FR-001**: System MUST accept registration via [NEEDS CLARIFICATION:
  email/password only, or also SSO/OAuth?]
- **FR-002**: System MUST send confirmation email within 60 seconds
- **FR-003**: Confirmation MUST expire at 48 hours; the system MUST
  delete still-unconfirmed accounts no later than 5 minutes after that
  deadline and MUST NOT delete confirmed accounts
- **FR-004**: System MUST log all registration attempts for [NEEDS
  CLARIFICATION: how long do we retain logs - 30 days, 90 days, forever?]

### Key Entities
- User: email, password_hash, email_verified_at, created_at, deleted_at
- ConfirmationToken: token, user_id, expires_at, used_at

## Success Criteria *(mandatory)*
- **SC-001**: 95% of confirmation emails delivered within 60 seconds (p95)
- **SC-002**: 0 accidental deletions of confirmed accounts
- **SC-004**: No deletion before 48 hours; every eligible unconfirmed
  account is deleted by age 48 hours 5 minutes under the tested workload
- **SC-003**: Registration completion rate > 60% (from form open to dashboard)

Fai attenzione ai marcatori [NEEDS CLARIFICATION: ...]. Spec Kit li inserisce intenzionalmente dove l’agente non ha ricevuto dal tuo testo una risposta inequivocabile. Prima di passare alla fase Plan, devi rispondere manualmente nel spec.md oppure eseguire /speckit-clarify: l’agente esaminerà i punti poco chiari e ti farà domande durante il dialogo.

In Spec Kit, il comando integrato /speckit-clarify sostituisce il “fammi domande” detto a voce. L’effetto è lo stesso: non si passa a Plan finché in spec.md non rimangono marcatori [NEEDS CLARIFICATION].

In spec.md non devono esserci tecnologie. Nessun riferimento a React, Postgres, Prisma o Redis. La specifica descrive ciò che fa il sistema dal punto di vista dell’utente e del business. Lo stack tecnologico arriva nella fase successiva.

Che cosa fa Claude nella fase Plan?

Punto chiave

Il comando /speckit-plan prende la specifica completa e prepara un piano tecnico: quali tecnologie usare, quale architettura, quali moduli, entità di dati e contratti API. Il piano viene salvato in specs/###-feature/plan.md, i contratti vengono esportati in una cartella contracts/ separata e il modello dei dati va in data-model.md. In questa fase Claude conosce già il tuo stack grazie a CLAUDE.md e alla constitution, così il piano si adatta al progetto esistente invece di suggerire “riscriviamo tutto in Rust”.

Quando spec.md è pronto, esegui:

/speckit-plan

Facoltativamente, puoi passare suggerimenti sulle tecnologie direttamente nel comando:

/speckit-plan Next.js App Router, Prisma, PostgreSQL, Resend for email

Claude legge tre fonti: il tuo spec.md, il tuo CLAUDE.md (o memory/constitution.md) e il codice esistente nel repository. L’output è un plan.md con una struttura più o meno simile a questa:

# Implementation Plan: User Registration

## Technical Context
- Framework: Next.js 14 App Router
- Database: PostgreSQL via Prisma
- Email: Resend (single transport)
- Validation: Zod schema in shared lib
- Auth: NextAuth.js with credentials provider

## Architecture Decisions

### 1. Token storage
Tokens stored in DB (table ConfirmationToken), not in JWT.
Reason: need server-side revoke on email re-register.

### 2. Email delivery
Async via cron `/api/cron/send-confirmation` triggered immediately
after registration. Retries handled by Resend.

### 3. Auto-delete cron
Run `/api/cron/cleanup-unconfirmed` every minute. Delete rows only where
created_at <= NOW() - INTERVAL '48 hours' AND email_verified_at IS NULL.
The clarified example allows at most 5 minutes of deletion delay.
Verify scheduler lag and completion time against that bound; report
a missed bound as a failure, not a successful daily cleanup.

## Data Model
See data-model.md

## API Contracts
See contracts/
- POST /api/auth/register
- POST /api/auth/confirm
- GET /api/auth/resend-confirmation

## Implementation Phases
1. Database migration (Prisma schema + migration file)
2. API routes (3 endpoints)
3. UI: registration form + confirmation success page
4. Cron jobs (send + cleanup)
5. Email template
6. Integration tests

data-model.md descriverà le entità e le relative relazioni. contracts/ conterrà modelli di contratti API, sotto forma di YAML OpenAPI oppure di tipi di richiesta e risposta TypeScript. Non è codice: è ciò che Claude trasformerà in route reali più avanti.

Il vantaggio principale della fase Plan è il contesto pulito. Claude non cerca di tenere a mente contemporaneamente la specifica e l’implementazione. Prima ragiona, registra le decisioni in un file e poi passa alla fase successiva.

C’è poi il comando facoltativo /speckit-analyze. Si esegue dopo la fase Tasks e prima di Implement: esamina l’insieme spec.md + plan.md + tasks.md per individuare contraddizioni e verifica che il piano e le attività coprano tutti i requisiti della specifica. Non modifica i file, produce solo un rapporto. In sostanza, è un controllo formale prima dell’implementazione.

Come suddividere il lavoro in attività (Tasks)

Punto chiave

Il comando /speckit-tasks suddivide il piano in attività concrete. Ogni attività include le dipendenze, una stima e un’indicazione che specifica se “si può eseguire in parallelo” oppure se deve essere “strettamente sequenziale”. Il risultato è tasks.md, in cui le attività seguono il formato checklist [ ] T-001: .... Puoi poi affidarle all’implementazione con /speckit-implement oppure convertirle in GitHub Issue con /speckit-taskstoissues e distribuirle tra un team o più sessioni di Claude Code in parallelo.

Quando hai spec.md e plan.md, esegui:

/speckit-tasks

Claude amplia il piano e crea tasks.md:

# Tasks: User Registration

## Phase 1: Database (no dependencies)
- [ ] T-001: Add User model to prisma/schema.prisma (parallel-safe)
- [ ] T-002: Add ConfirmationToken model to prisma/schema.prisma (after T-001)
- [ ] T-003: Generate migration `add-user-registration` (after T-002)

## Phase 2: API contracts (no dependencies)
- [ ] T-004: Create Zod schemas in shared/validation/auth.ts
- [ ] T-005: Define TypeScript types in shared/types/auth.ts (after T-004)

## Phase 3: Routes (depends on Phase 1+2)
- [ ] T-006: Implement POST /api/auth/register
- [ ] T-007: Implement POST /api/auth/confirm
- [ ] T-008: Implement GET /api/auth/resend-confirmation

## Phase 4: UI (parallel with Phase 3)
- [ ] T-009: Build /register page with form
- [ ] T-010: Build /register/confirm/[token] page
- [ ] T-011: Build /register/success page

## Phase 5: Cron + integration (depends on Phase 3+4)
- [ ] T-012: Cron /api/cron/send-confirmation
- [ ] T-013: Cron /api/cron/cleanup-unconfirmed
- [ ] T-014: Email template registration-confirmation.tsx
- [ ] T-015: Integration tests (Playwright), including cleanup just
  before 48h, exactly at 48h, deletion by 48h 5m, delayed-job failure,
  and protection of confirmed accounts

## Notes
- T-001, T-004, T-009-T-011 are parallel-safe (different files)
- T-002 conflicts with T-001 (same file: schema.prisma) - run sequentially
- T-006 needs T-003 (migration applied) and T-005 (types)

Nota i marcatori parallel-safe e after T-NNN. Sono il grafo delle dipendenze che permette di eseguire più fasi in parallelo in seguito. Tutta l’accelerazione di Spec Kit si basa su questo meccanismo: alcune attività possono essere affidate contemporaneamente a cinque sessioni diverse di Claude Code, mentre altre devono essere necessariamente sequenziali.

Spec Kit lo fa automaticamente, con un solo comando, già pronto all’uso.

Il comando facoltativo /speckit-taskstoissues prende tasks.md e crea GitHub Issue dall’elenco, ciascuna con un link a spec.md. È utile se lavori in team o vuoi seguire i progressi con GitHub Projects.

Come implementare con i subagenti (Implement)

Punto chiave

L’ultima fase, /speckit-implement, avvia l’implementazione. Claude procede dall’inizio alla fine di tasks.md, spuntando le attività con [x] man mano che le completa. Puoi eseguire più sessioni di Claude Code in parallelo, una per fase. All’interno di ogni sessione, Claude avvia subagenti per diversi tipi di lavoro: un revisore del codice, un tester per i controlli e un redattore della documentazione per il README. Questo è il concetto dei “1000 subagenti paralleli” di cui Anthropic ha scritto al rilascio di Opus 4.8: in Spec Kit è semplicemente una modalità di lavoro, non un prodotto a sé.

/speckit-implement

Claude inizia dalla prima attività di tasks.md. Ogni attività segue un breve ciclo: legge i file pertinenti, scrive una diff, esegue i test e spunta [x]. I subagenti vengono chiamati automaticamente quando serve: uno separato per la revisione del codice, uno per eseguire il linter e uno per verificare eventuali regressioni.

E, a parte, sulle regole:

In Spec Kit, questo ciclo è formalizzato. Hai spec.md come fonte di verità, plan.md per le decisioni tecniche e tasks.md come checklist. Se Claude devia dal percorso in una fase qualsiasi, torni alla specifica e dici: “Questo non corrisponde a FR-003; rifallo”. Niente prompt lunghi del tipo “ricordati di quello che abbiamo discusso...”: tutta la cronologia è nei file.

Se hai collegato i Dynamic Workflows in Opus 4.8, puoi portare Spec Kit in modalità completamente automatizzata: basta un comando /speckit-implement e Claude parallelizza il lavoro, consolida i risultati e li controlla. Il limite è 1000 subagenti contemporaneamente. Per la maggior parte delle funzionalità ne bastano 10-30.

Quando tutte le caselle [x] sono spuntate e il controllo della sezione successiva restituisce “Converged”, rivedi la PR (o una serie di PR, se le attività sono molte) e uniscila. Gli artefatti — spec.md, plan.md, tasks.md — restano nel repository come documentazione della funzionalità. Un anno dopo non dovrai ricostruire a ritroso la logica partendo dal codice.

Come verificare che all’agente non sia sfuggito nulla (Converge)

Punto chiave

Dopo Implement, la versione corrente di Spec Kit offre una fase di controllo chiamata /speckit-converge. L’agente confronta il codice finito con spec.md, plan.md e tasks.md. Se tutto corrisponde, risponde “Converged” e lascia invariati i file. Se trova omissioni, le aggiunge come nuove attività in fondo a tasks.md. Poi esegui di nuovo /speckit-implement, seguito ancora da /speckit-converge, finché non ottieni “Converged”.

/speckit-converge

Prima l’agente fornisce un riepilogo di ciò che ha trovato, con i livelli di gravità, poi presenta uno di due esiti. “Converged” significa che non ci sono omissioni, tasks.md è rimasto identico byte per byte e puoi passare alla revisione. “Tasks appended” significa che sono state trovate omissioni, aggiunte alla sezione Convergence di tasks.md; l’agente ti dice quante sono.

Converge non modifica né elimina codice: l’unica scrittura consiste nell’aggiunta di nuove attività a tasks.md. Puoi quindi eseguirlo senza preoccupazioni, ma solo dopo che /speckit-implement ha già elaborato le attività presenti in tasks.md. Ogni passaggio successivo rileva meno omissioni.

In cosa Spec Kit differisce da CLAUDE.md e Plan Mode?

Punto chiave

È una domanda comune quando si confrontano questi strumenti. La risposta breve: CLAUDE.md è il “contratto di lavoro” dell’agente, un’unica fonte di verità per tutto il progetto. Plan Mode è una pianificazione una tantum prima di una richiesta specifica. Spec Kit copre l’intero ciclo di vita di una funzionalità: dalla descrizione all’implementazione, con gli artefatti nel repository. Non si sostituiscono a vicenda: insieme formano un sistema a tre livelli: contesto globale (CLAUDE.md) → contesto del progetto (constitution di Spec Kit) → contesto della funzionalità (spec.md + plan.md + tasks.md).

Confrontiamoli su 5 caratteristiche:

CaratteristicaCLAUDE.mdPlan ModeSpec Kit
Quando viene eseguitoOgni sessioneSu richiesta (Shift+Tab o /plan)Con il comando slash /speckit-*
DurataIntero progettoUna sessioneUna funzionalità
Dove si trovaRadice del repositoryNel contesto di Claudespecs/###-feature/*
Che cosa contieneStack, regole, glossarioPiano e osservazioni correntispec + plan + tasks + contracts
ModelloLibero (regole del repository)NessunoMarkdown strutturato
Ruolo idealeRegole e stack del progettoControllo prima di una modifica importanteIntero ciclo della funzionalità: dal COSA al CODICE

In termini di Spec Kit, è .specify/memory/constitution.md. Durante l’inizializzazione, Spec Kit può usare il tuo CLAUDE.md esistente come base per la constitution oppure creare un file separato accanto a esso. Di solito tengo CLAUDE.md come “contratto” globale (stack, glossario, protocollo di deployment) e uso la constitution di Spec Kit per regole specifiche di questo flusso di lavoro, per esempio: “tutti i moduli usano la validazione Zod; niente controlli manuali”.

Il collegamento con Plan Mode è più semplice. Plan Mode è una modalità rapida di “pianificazione prima di scrivere codice” all’interno di una singola sessione. Funziona bene per modifiche piccole (correggere un bug, rifattorizzare una funzione). Per una funzionalità grande, Plan Mode non è adatto perché la finestra di contesto di una sessione è troppo piccola per un piano di 3000 righe, come spiego direttamente durante la sessione dal vivo:

Spec Kit è uno strumento concreto di context engineering. Sposta la “tovaglia architetturale” dalla chat ai file. Spec.md rimane nel repository e ogni nuova sessione Claude lo legge di nuovo: non devi ripeterti.

Una configurazione per un progetto grande:

  1. CLAUDE.md - stack, glossario e cose da non fare. Si trova nella radice.
  2. .specify/memory/constitution.md per Spec Kit: regole specifiche di questo flusso di lavoro.
  3. specs/001-feature-A/spec.md, plan.md, tasks.md - prima funzionalità.
  4. specs/002-feature-B/spec.md, plan.md, tasks.md - seconda funzionalità.
  5. Per il lavoro quotidiano, usa /speckit-implement (per le attività già pronte) oppure /plan (un rapido controllo prima di una modifica).

Quali casi reali stanno funzionando?

Punto chiave

L’approccio Spec Kit e SDD ha già prodotto risultati misurabili nelle grandi aziende. AWS, in un progetto di scoperta di farmaci: il 95% della logica di business generata da una specifica, con un risparmio di oltre 80 ore su una funzionalità. Rackspace Technology: 52 settimane di lavoro ridotte a 3 settimane, +90% di efficienza. Spec Kit ha raccolto 107.000 stelle su GitHub in 8 mesi.

Casi specifici:

  • AWS Kiro - agente per la scoperta di farmaci. In un post sul blog AWS Industries del 18 febbraio 2026, il team descrive il progetto TargetID. Tre sviluppatori, tre settimane, un agente per la scoperta di farmaci. I dati riportati nell’articolo: Kiro ha generato oltre il 95% del codice della logica di business, risparmiando più di 80 ore di sviluppo. Inoltre: “La documentazione README scritta da Kiro ci ha fatto risparmiare circa 8 ore” e “il 40% in meno di cicli iterativi di prompt e correzione”.
  • Rackspace Technology. Nello stesso blog AWS, Rackspace afferma di aver “completato 52 settimane di lavoro stimato in sole 3 settimane” e di aver ottenuto un “aumento del 90% dell’efficienza”. Non si tratta più di una piccola funzionalità: è un intero progetto aziendale.

Per chi legge, significa che l’approccio non è teorico: team di rilievo lo stanno già usando in produzione.

Quando NON è adatto Spec Kit?

Punto chiave

Spec Kit non è adatto a ogni situazione. Ha tre ambiti chiaramente sfavorevoli: modifiche piccole (correggere un bug, rinominare una variabile), esperimenti e prototipi (dove non sapere che cosa vuoi è proprio il senso del vibe coding) e codice legacy con stato complesso (dove la specifica diventa obsoleta più in fretta di quanto tu riesca a finire di scriverla). Ci sono critiche autorevoli a questi casi. Vale la pena conoscerne gli argomenti, per non perdere tempo a scrivere specifiche quando non servono.

Non adatto n. 1 - modifiche piccole. Se l’attività è “rinominare una variabile”, “correggere un refuso nel testo” o “aggiungere un log”, passare da Specify → Plan → Tasks richiederà più tempo della modifica stessa. Per le modifiche piccole, Plan Mode o anche solo un prompt diretto in Claude Code sono più rapidi.

Non adatto n. 3 - codice legacy con stato complesso. Una forte obiezione: la realtà cambia più in fretta delle specifiche. Prendiamo la fatturazione degli abbonamenti: il team ha descritto i cicli di fatturazione e le regole fiscali, poi una settimana dopo l’ufficio finanziario ha chiesto l’IVA europea. La specifica era già obsoleta prima del rilascio. Quando la logica di business evolve rapidamente, mantenere le specifiche diventa un peso.

Un rischio aggiuntivo è l’illusione di avere il controllo: le strutture sono eleganti, ma spesso gli agenti ignorano le istruzioni oppure, al contrario, seguono i modelli alla lettera. Il risultato è codice strutturalmente corretto ma inadatto al tuo repository specifico: la specifica non garantisce che l’agente l’abbia interpretata come intendevi tu.

Nell’aprile 2026, il Radar di Thoughtworks ha messo in guardia dall’approccio waterfall: scrivere una specifica estesa prima del codice è una strada che ha già portato il settore al fallimento una volta, all’epoca dei requisiti di 200 pagine. Da allora gli ingegneri hanno guardato questo approccio con cautela, e a ragione.

Cosa fare. Suggerisco una regola semplice: rapporta la dimensione della funzionalità al tempo necessario per scrivere una specifica. Se l’implementazione richiederà meno di 2 ore, non scrivere una specifica: Plan Mode è più rapido. Se la funzionalità richiederà una settimana, usa sicuramente Spec Kit: il tempo risparmiato ripagherà l’ora necessaria a scrivere la specifica per cinque volte. Tra 2 ore e una settimana, decidi tu; personalmente scrivo una specifica anche per funzionalità da mezza giornata, perché l’artefatto nel repository vale più dei 30 minuti risparmiati.

E adesso: come integrare Spec Kit nel tuo progetto?

Punto chiave

Il primo passo più semplice è provare Spec Kit su una nuova funzionalità piccola, non su un intero progetto esistente. Installalo, inizializzalo in un repository, esegui /speckit-specify per una funzionalità e guarda gli artefatti. Nel giro di una o due settimane, capirai quando usarlo e quando continuare con prompt rapidi. La metodologia completa combina CLAUDE.md + Spec Kit + Skills + subagent.

Un piano concreto per i prossimi 7 giorni:

  • Giorno 1. Installa uv e Spec Kit (5-10 minuti). Verifica che in Claude Code siano comparsi i comandi /speckit-*. Non provare ad applicarli a un progetto esistente: inizia da uno nuovo.
  • Giorno 2. Scegli una funzionalità reale che vuoi realizzare. Esegui /speckit-specify con una descrizione libera. Apri spec.md, leggilo e rispondi a ogni [NEEDS CLARIFICATION]. Non affrettarti a passare a Plan.
  • Giorno 3. Esegui /speckit-plan con indicazioni sul tuo stack. Leggi plan.md, soprattutto la sezione Architecture Decisions. Se qualcosa non ti convince, modificalo manualmente.
  • Giorni 4-5. Esegui /speckit-tasks, poi /speckit-analyze per ricontrollare l’insieme di specifica, piano e attività, quindi /speckit-implement. Osserva Claude mentre spunta [x] in tasks.md. Potrebbe bloccarsi da qualche parte: è normale. Torna a spec.md, chiarisci il requisito e riavvia /speckit-implement indicando un’attività precisa. Quando le attività sono completate, esegui /speckit-converge e ripeti la sequenza Implement e Converge finché non risponde “Converged”.
  • Giorni 6-7. Rivedi la PR (o la serie di PR), poi uniscila. Leggi spec.md e plan.md: saranno la documentazione della funzionalità per l’anno successivo.

Ecco cosa ti suggerisco di leggere in parallelo:

Il flusso completo di lavoro con il contesto: clone IA + Second Brain + Context Engineering.

Altri materiali sono disponibili su Ailoot.

Maggiori dettagli

Domande frequenti

Perché un’eliminazione quotidiana non basta al requisito delle 48 ore?

Un account che raggiunge la scadenza subito dopo il passaggio quotidiano può attendere quasi un altro giorno. Chiarisci la tolleranza nella specifica, scegli una frequenza compatibile e prova soglia delle 48 ore e ritardo massimo.

Cosa faccio quando plan.md contraddice spec.md?

Torna al requisito e risolvi la discrepanza prima dell’implementazione. Aggiorna insieme specifica, piano, attività e controlli di accettazione, poi usa Analyze e le verifiche per confermare lo stesso comportamento concordato.

Tutti gli articoli