Guida Spec Driven Development

Guida Spec Driven Development

Indice Guida Spec Driven Development

1. Introduzione ai paradigmi Development Driven
2. Cos’è lo Spec Driven Development
3. Il GitHub Spec Kit: panoramica e funzionamento
4. Come implementare lo Spec Driven Development
5. Vantaggi dello Spec Driven Development
6. Svantaggi e limitazioni
7. Best practice per l’utilizzo
8. Esempi pratici di implementazione
9. Conclusioni e formazione continua

1. Introduzione ai paradigmi Development Driven

Nel panorama dello sviluppo software moderno, diversi paradigmi “driven” hanno rivoluzionato l’approccio alla creazione di applicazioni. Il Test-Driven Development (TDD) ha insegnato a scrivere i test prima del codice, garantendo maggiore qualità e copertura. Il Behavior-Driven Development (BDD) ha spostato il focus sul comportamento atteso del software, facilitando la comunicazione tra team tecnici e business.

Questi approcci condividono un principio fondamentale: definire chiaramente l’intento prima dell’implementazione. Lo Spec Driven Development rappresenta l’evoluzione naturale di questa filosofia nell’era dell’AI, dove le specifiche non sono più semplici guide, ma artefatti eseguibili che generano direttamente codice funzionante.

2. Cos’è lo Spec Driven Development

Lo Spec Driven Development ribalta il paradigma tradizionale dello sviluppo software, trasformando le specifiche da semplici scaffold in artefatti eseguibili che generano implementazioni funzionanti. Anziché considerare il codice come fonte di verità, questo approccio eleva le specifiche a elemento centrale del processo di sviluppo.

Le specifiche diventano l’unità fondamentale della programmazione, agendo come guida per gli agenti AI che possono riferirsi ad esse, validare il proprio lavoro e mantenere l’orientamento durante l’esecuzione di task complessi.

In pratica, lo sviluppatore non scrive più codice direttamente, ma descrive cosa vuole costruire e perché, lasciando che gli agenti AI basati su LLM gestiscano l’implementazione tecnica. Questo passaggio dall’implementazione all’intento rappresenta un cambio di paradigma significativo: la comunicazione efficace diventa la competenza più scarsa e preziosa per i programmatori del futuro.

3. Il GitHub Spec Kit: panoramica e funzionamento

GitHub Spec Kit è un toolkit open source che implementa il paradigma Spec Driven Development, fornendo una struttura standardizzata per creare, gestire ed eseguire specifiche attraverso agenti AI. Il progetto, disponibile su https://github.com/github/spec-kit, è compatibile con diversi coding agent come Claude Code, GitHub Copilot, Cursor, Gemini CLI, Windsurf e altri.

Architettura del toolkit

Il Spec Kit organizza il progetto in una struttura ben definita con cartelle dedicate a memoria (constitution.md per i principi guida), script di automazione, specifiche delle feature e template riutilizzabili.

I componenti principali includono:

• Constitution: documento che definisce principi di governance, standard di qualità, pattern architetturali e pratiche di sviluppo
• Specifications: descrizioni dettagliate delle funzionalità con user stories e requisiti funzionali
• Implementation Plan: piani tecnici con scelte di tech stack, data model e contratti API
• Tasks: breakdown eseguibili delle attività con dipendenze e path specifici dei file

Il flusso di lavoro

Il processo si articola in quattro fasi con checkpoint specifici: Specify (descrizione high-level e generazione spec), Plan (dettagli tecnici e architettura), Tasks (breakdown in chunk revisabili) e Implement (esecuzione task con validazione).

L’installazione avviene tramite il CLI:

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

# Inizializzazione progetto
specify init my-project --ai claude

# Verifica prerequisiti
specify check

Comandi principali

Il toolkit espone una serie di comandi slash utilizzabili direttamente nell’agente AI:

• /speckit.constitution: crea i principi guida del progetto
• /speckit.specify: definisce cosa costruire senza dettagli implementativi
• /speckit.clarify: chiarisce aree sotto-specificate prima della pianificazione
• /speckit.plan: crea piani tecnici con scelte di stack e architettura
• /speckit.tasks: genera task list eseguibili dal piano di implementazione
• /speckit.implement: esegue tutti i task secondo l’ordine corretto

4. Come implementare lo Spec Driven Development

Fase 1: Definire la Constitution

La constitution è il fondamento del progetto. Si crea con:

// Comando nell'agente AI
/speckit.constitution Create principles focused on:
- Code quality and testing standards (TDD, unit test coverage >80%)
- Architecture patterns (hexagonal, microservices)
- Performance requirements (API response <200ms)
- Security compliance (OWASP Top 10)

Fase 2: Creare la specifica

La specifica descrive il “cosa” e il “perché”, non il “come”:

/speckit.specify Build a task management system where users can:
- Create projects with multiple task boards
- Drag and drop tasks between columns (To Do, In Progress, Review, Done)
- Assign tasks to team members with visual indicators
- Add unlimited comments per task with edit/delete permissions
- Filter tasks by assignee and status

Fase 3: Piano di implementazione

Il piano introduce i dettagli tecnici:

/speckit.plan Use ASP.NET Core 8 with Entity Framework Core.
Database: PostgreSQL for persistence
Frontend: Blazor Server with SignalR for real-time updates
Architecture: Clean Architecture with CQRS pattern
APIs: RESTful endpoints with OpenAPI documentation
Testing: xUnit for unit tests, Playwright for E2E

Esempio di struttura dati generata:

public class TaskItem
{
    public Guid Id { get; set; }
    public string Title { get; set; }
    public string Description { get; set; }
    public TaskStatus Status { get; set; }
    public Guid AssigneeId { get; set; }
    public DateTime CreatedAt { get; set; }
    public List<Comment> Comments { get; set; }
}

public enum TaskStatus
{
    ToDo,
    InProgress,
    InReview,
    Done
}

Fase 4: Breakdown dei task

/speckit.tasks

Il comando genera task organizzati per user story con gestione dipendenze, marcatori di esecuzione parallela, path specifici dei file e struttura TDD.

Fase 5: Implementazione

/speckit.implement

L’agente esegue i task in ordine, gestendo dipendenze e validando progressivamente l’output.

5. Vantaggi dello Spec Driven Development

Qualità e manutenibilità

Lo sviluppo guidato da specifiche mantiene design, sviluppo, documentazione e testing sempre sincronizzati, risultando in risparmi di tempo, informazioni sempre aggiornate e riduzione del lavoro di manutenzione.

Collaborazione migliorata

Le specifiche tecniche sono cruciali per allineare i team software, fornendo un linguaggio comune tra sviluppatori, QA, product manager e stakeholder.

Iterazione rapida

La natura iterativa dell’approccio consente di modificare facilmente la direzione: basta aggiornare la spec, rigenerare il piano e lasciare che l’agente gestisca il resto. Questo permette di sperimentare con diverse implementazioni senza costose riscritture.

Context engineering ottimizzato

Le specifiche forniscono il contesto di alta qualità necessario agli agenti AI per avere successo, comunicando in modo chiaro formati input/output, regole di business, casi edge, vincoli di integrazione e requisiti di performance.

6. Svantaggi e limitazioni

Overhead iniziale

Il principale problema non è l’AI, ma il fattore umano: SDD richiede agli sviluppatori di specificare le proprie intenzioni con precisione, ma raramente i requisiti sono completamente formulati prima dell’implementazione.

Limitazioni tecniche attuali

Spec Kit è ancora sperimentale con limiti noti: impossibilità di cambiare tool AI dopo l’inizializzazione, focus su progetti greenfield più che su codebase esistenti, dipendenza da Python 3.11+ e sviluppo rapido con documentazione che può non essere aggiornata.

Problemi di rigenerazione

La rigenerazione stabile è difficile: questo è il motivo per cui lo spec-driven development è un approccio iterativo, non una soluzione magica “genera una volta”. Ogni rigenerazione può produrre implementazioni leggermente diverse.

Complessità per task piccoli

Quando si chiede di correggere un piccolo bug, il workflow diventa come usare una mazza per schiacciare una noce: il documento dei requisiti trasforma il bug in multiple user story con numerosi criteri di accettazione.

7. Best practice per l’utilizzo – Guida Spec Driven Development

1. Definire una constitution dettagliata

Riempire il file constitution in dettaglio prima di eseguire qualsiasi prompt, utilizzando MCP server di documentazione per recuperare le guide di stile più recenti del framework scelto.

2. Iterare sulla specifica

Sviluppare iterativamente il file di specifica, trattandolo come artefatto che vive più a lungo del codice e che abilita la rigenerazione futura della codebase.

3. Commit frequenti

Fare commit presto e spesso: se le cose vanno male, questa è la rete di sicurezza. È buona pratica comunque.

4. Code review regolari

Richiedere code review ogni 3-4 task completati. Utilizzare prompt specifici:

// Prompt per code review
"You are a deeply experienced, highly critical software engineer. 
Please conduct a deep code review focusing on:
- Architecture adherence to Clean Code principles
- Security vulnerabilities (OWASP compliance)
- Performance bottlenecks
- Test coverage and quality
Tasks 1-5 have been completed, focus on those."

5. Integration test first

Gli integration test sono fondamentali per verificare se il codice funziona davvero, quindi assicurarsi che il modello li scriva il prima possibile e iterare fino al loro passaggio.

6. Aggiornare le specifiche

Aggiornare architecture.md e tasks.md quando si scoprono nuove esigenze architetturali, feature o task da completare.

7. Scalare l’uso secondo la complessità

Spec Kit è più adatto per codice production-ready e feature complesse con più step e test, mentre potrebbe essere eccessivo per aggiunte semplici come una sezione testimonial.

8. Esempi pratici di implementazione

Esempio JavaScript: API REST con Express

Constitution per un’API Node.js:

// .specify/memory/constitution.md

## Technical Principles
- Use Express.js with TypeScript for type safety
- Follow RESTful API design principles
- Implement JWT authentication with refresh tokens
- Use Prisma ORM with PostgreSQL
- Error handling via custom middleware
- API versioning in URL path (/api/v1/)
- OpenAPI 3.0 documentation with Swagger UI
- Jest for unit tests, Supertest for integration tests
- Minimum 80% code coverage required

Specifica di una feature:

/speckit.specify Create a user authentication system that:
- Registers new users with email validation
- Authenticates users with JWT tokens (access + refresh)
- Implements rate limiting (5 attempts per 15 minutes)
- Provides password reset via email token
- Logs all authentication events for audit
- Returns standardized error responses

Piano tecnico risultante:

/speckit.plan Stack:
- Express 4.18+
- TypeScript 5.0+
- Prisma 5.0 with PostgreSQL
- bcrypt for password hashing
- jsonwebtoken for JWT
- nodemailer for email
- express-rate-limit for throttling

Architecture:
- Controllers handle HTTP requests
- Services contain business logic
- Repositories manage data access
- Middleware for auth, validation, error handling

Task breakdown generato:

## Phase 1: Setup & Configuration
[T001] Create Prisma schema for User model
[T002] Generate and run migrations
[T003] Set up JWT utility functions
[T004] [P] Create email service
[T005] [P] Implement rate limiter middleware

## Phase 2: TDD
[T006] Write tests for user registration
[T007] Write tests for login flow
[T008] Write tests for token refresh

## Phase 3: Implementation
[T009] Implement UserRepository
[T010] Implement AuthService
[T011] Implement AuthController
[T012] Set up routes and middleware chain

Esempio .NET: Microservizio con Clean Architecture

Constitution per microservizio .NET:

// .specify/memory/constitution.md

## Technical Principles
- ASP.NET Core 8.0 with C# 12
- Clean Architecture (Domain, Application, Infrastructure, API)
- CQRS with MediatR for command/query separation
- Entity Framework Core with SQL Server
- FluentValidation for input validation
- Serilog for structured logging
- AutoMapper for DTO mapping
- xUnit + FluentAssertions + Moq for testing
- Docker containerization required

Specifica Order Management:

/speckit.specify Create order management feature:
- Create orders with multiple line items
- Calculate totals with tax and discounts
- Validate inventory availability before order creation
- Emit OrderCreated event for downstream processing
- Support order status transitions (Pending→Confirmed→Shipped→Delivered)
- Query orders by customer with pagination
- Generate order confirmation PDF

Esempio di Domain Entity generato:

// Domain/Entities/Order.cs
public class Order : AggregateRoot
{
    public OrderId Id { get; private set; }
    public CustomerId CustomerId { get; private set; }
    public OrderStatus Status { get; private set; }
    public Money Total { get; private set; }
    private readonly List<OrderLine> _lines = new();
    public IReadOnlyCollection<OrderLine> Lines => _lines.AsReadOnly();
    
    public static Order Create(CustomerId customerId, 
        List<OrderLine> lines, 
        IDiscountPolicy discountPolicy)
    {
        var order = new Order
        {
            Id = OrderId.New(),
            CustomerId = customerId,
            Status = OrderStatus.Pending
        };
        
        foreach (var line in lines)
        {
            order.AddLine(line);
        }
        
        order.CalculateTotal(discountPolicy);
        order.AddDomainEvent(new OrderCreatedEvent(order.Id));
        
        return order;
    }
    
    public void Confirm()
    {
        if (Status != OrderStatus.Pending)
            throw new InvalidOrderStateException();
            
        Status = OrderStatus.Confirmed;
        AddDomainEvent(new OrderConfirmedEvent(Id));
    }
}

Command Handler generato:

// Application/Orders/Commands/CreateOrderCommandHandler.cs
public class CreateOrderCommandHandler 
    : IRequestHandler<CreateOrderCommand, Result<OrderDto>>
{
    private readonly IOrderRepository _repository;
    private readonly IInventoryService _inventoryService;
    private readonly IUnitOfWork _unitOfWork;
    
    public async Task<Result<OrderDto>> Handle(
        CreateOrderCommand request, 
        CancellationToken ct)
    {
        // Validate inventory
        var available = await _inventoryService
            .CheckAvailability(request.Lines, ct);
        if (!available.IsSuccess)
            return Result<OrderDto>.Failure(available.Error);
        
        // Create order
        var order = Order.Create(
            request.CustomerId, 
            request.Lines,
            new StandardDiscountPolicy());
        
        await _repository.AddAsync(order, ct);
        await _unitOfWork.SaveChangesAsync(ct);
        
        return Result<OrderDto>.Success(
            OrderDto.FromDomain(order));
    }
}

9. Conclusioni e formazione continua

Lo Spec Driven Development rappresenta un’evoluzione significativa nel modo in cui concepiamo lo sviluppo software nell’era dell’AI. Stiamo passando da “il codice è la fonte di verità” a “l’intento è la fonte di verità”, dove la specifica determina cosa viene costruito.

Nonostante le limitazioni attuali e la curva di apprendimento iniziale, questo approccio offre vantaggi concreti in termini di qualità, manutenibilità e velocità di iterazione, specialmente per progetti complessi o team distribuiti.

L’importanza della formazione continua

In un settore in continua evoluzione come l’informatica, la formazione continua del personale non è più un’opzione, ma una necessità strategica. Le tecnologie emergenti come lo Spec Driven Development, gli agenti AI e i nuovi paradigmi di sviluppo richiedono un aggiornamento costante delle competenze.

Innovaformazione può supportare la tua azienda in questo percorso di crescita, offrendo corsi personalizzati su richiesta, tra cui:

• Corso Spec Driven Development: approfondimento teorico e pratico del paradigma SDD
• Corso GitHub Spec Kit: implementazione hands-on del toolkit con casi d’uso reali
• Corsi AI-Assisted Development: integrazione di agenti AI nel workflow di sviluppo

Modalità di erogazione

I corsi vengono erogati in modalità online in classe virtuale, con calendario completamente da concordare in base alle esigenze della vostra azienda. Questa flessibilità permette di organizzare la formazione senza impattare negativamente sulla produttività del team.

Finanziamento con Fondimpresa

Per le aziende che hanno necessità di gestire il piano formativo attraverso Fondimpresa, Innovaformazione offre supporto completo nella pratica amministrativa, rendendo accessibile la formazione attraverso i fondi interprofessionali.

Contatti

Per ricevere una proposta personalizzata di corso Spec Driven Development o GitHub Spec Kit, o per valutare altre esigenze formative del vostro team:

Email: info@innovaformazione.net
Telefono: 3471012275 (Dario Carrassi)

Consulta il catalogo completo dei corsi disponibili QUI

(fonte) (fonte) (fonte) (fonte)