Il Workflow SDD con Claude Code
Scrivi le specifiche in MdExplorer, versionale con Git, usale come contesto per Claude Code
Cos'è lo Spec Driven Development?
Lo Spec Driven Development (SDD) è un approccio dove le specifiche tecniche guidano lo sviluppo software. Invece di scrivere codice e poi documentare, si parte dalle specifiche. Con l'avvento degli strumenti AI come Claude Code, le specifiche diventano non solo documentazione per gli umani, ma anche contesto strutturato per l'AI che genera il codice.
La narrativa centrale: Scrivi le specifiche in MdExplorer, versionale con Git, usale come contesto per Claude Code, genera il codice allineato all'architettura documentata.
In un workflow tradizionale, la documentazione è spesso un prodotto secondario: viene scritta dopo lo sviluppo, si disallinea rapidamente e nessuno la aggiorna. Con lo SDD, le specifiche sono il punto di partenza. Sono il contratto tra chi definisce i requisiti e chi implementa il codice — sia esso un umano o un'intelligenza artificiale.
Spec Driven Development (SDD) is an approach where technical specifications drive software development. Instead of writing code and then documenting, you start from specs. With the advent of AI tools like Claude Code, specifications become not just documentation for humans, but structured context for the AI that generates the code.
The central narrative: Write specs in MdExplorer, version with Git, use as context for Claude Code, generate code aligned with the documented architecture.
In a traditional workflow, documentation is often an afterthought: written after development, quickly becomes outdated, and nobody updates it. With SDD, specifications are the starting point. They are the contract between those who define requirements and those who implement the code — whether that's a human or an artificial intelligence.
Il Ciclo SDD + Claude Code
Il workflow SDD con Claude Code si articola in 5 fasi che formano un ciclo iterativo. Ogni fase produce artefatti in Markdown, versionati con Git, che alimentano la fase successiva.
The SDD workflow with Claude Code consists of 5 phases that form an iterative cycle. Each phase produces Markdown artifacts, versioned with Git, that feed the next phase.
Dai prompt a Claude Code per generare documenti di analisi funzionale: requisiti, user stories, flussi, mockup ASCII. L'AI produce documenti strutturati e completi partendo dalla tua descrizione del dominio.
Suggerimento: Descrivi il dominio di business in modo dettagliato. Più contesto fornisci nel prompt, più precise saranno le specifiche generate.
Give prompts to Claude Code to generate functional analysis documents: requirements, user stories, flows, ASCII mockups. The AI produces structured and complete documents starting from your domain description.
Tip: Describe the business domain in detail. The more context you provide in the prompt, the more precise the generated specs will be.
Apri i documenti generati come progetto MdExplorer. Organizza in cartelle logiche (es. analisi/, architettura/, sprints/). Versiona con Git per tracciare ogni evoluzione delle specifiche.
MdExplorer ti permette di navigare tra i documenti con link interni, visualizzare diagrammi PlantUML e avere una visione d'insieme della struttura del progetto attraverso il tree view.
Open the generated documents as an MdExplorer project. Organize in logical folders (e.g. analisi/, architettura/, sprints/). Version with Git to track every spec evolution.
MdExplorer allows you to navigate between documents with internal links, visualize PlantUML diagrams, and have an overview of the project structure through the tree view.
Usa Claude Code per generare l'analisi tecnica partendo dalle specifiche funzionali: stack tecnologico, schema database, API spec, diagrammi PlantUML. Le specifiche funzionali diventano l'input per le decisioni architetturali.
In questa fase nascono i documenti più importanti: ANALISI_TECNICA.md, API_SPEC.md, DATABASE_SCHEMA.md. Ogni decisione architetturale è documentata con motivazione e alternative considerate.
Use Claude Code to generate the technical analysis from functional specs: tech stack, database schema, API spec, PlantUML diagrams. Functional specifications become the input for architectural decisions.
In this phase the most important documents are created: ANALISI_TECNICA.md, API_SPEC.md, DATABASE_SCHEMA.md. Every architectural decision is documented with reasoning and considered alternatives.
Definisci sprint con scope chiaro, user stories, task checklist, acceptance criteria. Ogni sprint ha un documento markdown dedicato, ad esempio sprints/SPRINT-01-POC.md.
Le user stories seguono il formato Agile: "Come [attore] voglio [azione] per [beneficio]". Ogni task ha un ID univoco (BE-01, FE-01, DO-01) che verrà usato nei commit Git per garantire tracciabilità completa.
Define sprints with clear scope, user stories, task checklist, acceptance criteria. Each sprint has a dedicated markdown document, e.g. sprints/SPRINT-01-POC.md.
User stories follow the Agile format: "As a [role] I want [action] so that [benefit]". Each task has a unique ID (BE-01, FE-01, DO-01) that will be used in Git commits to ensure full traceability.
Alimenta Claude Code con CLAUDE.md + specifiche → genera codice allineato all'architettura documentata. Ogni task completato aggiorna la checklist sprint. Il file CLAUDE.md fa da ponte: Claude Code lo legge automaticamente e conosce struttura, convenzioni e riferimenti alle specifiche.
Importante: Il codice generato è allineato alle specifiche perché Claude Code ha accesso diretto ai documenti di architettura, alle convenzioni di codice e ai requisiti funzionali tramite CLAUDE.md.
Feed Claude Code with CLAUDE.md + specs → generate code aligned with the documented architecture. Each completed task updates the sprint checklist. The CLAUDE.md file acts as a bridge: Claude Code reads it automatically and knows the structure, conventions, and references to specs.
Important: Generated code is aligned with specifications because Claude Code has direct access to architecture documents, code conventions, and functional requirements through CLAUDE.md.
Il Loop Continuo
Il ciclo non è lineare ma iterativo: codice generato → aggiorna specifiche → prossimo sprint. Le specifiche evolvono con il progetto. Ogni modifica alle spec genera un commit Git, mantenendo lo storico completo delle decisioni.
Questo approccio garantisce che la documentazione non diventi mai obsoleta. Quando il codice cambia, le specifiche vengono aggiornate nello stesso commit o nella stessa pull request. Il team può sempre risalire al "perché" di ogni decisione tecnica navigando la history Git delle specifiche.
Il ciclo in sintesi:
- Scrivi o aggiorna le specifiche in MdExplorer
- Fai commit e push con Git integrato
- Claude Code legge le specifiche aggiornate via CLAUDE.md
- Genera o modifica il codice in linea con le specifiche
- Aggiorna le checklist sprint e le specifiche se necessario
- Ripeti per il prossimo task o sprint
The cycle is not linear but iterative: generated code → update specs → next sprint. Specs evolve with the project. Every spec change generates a Git commit, maintaining a complete history of decisions.
This approach ensures documentation never becomes outdated. When code changes, specs are updated in the same commit or pull request. The team can always trace back to the "why" of every technical decision by navigating the Git history of the specs.
The cycle in brief:
- Write or update specs in MdExplorer
- Commit and push with integrated Git
- Claude Code reads updated specs via CLAUDE.md
- Generate or modify code aligned with specs
- Update sprint checklists and specs if needed
- Repeat for the next task or sprint
Il Ruolo di CLAUDE.md
Il file CLAUDE.md è il "ponte" tra le specifiche del progetto e l'AI. Viene posizionato nella root del repository e Claude Code lo legge automaticamente come contesto di progetto ogni volta che viene invocato.
Contiene:
- Regole del progetto — convenzioni, standard, vincoli
- Struttura delle cartelle — dove trovare specifiche, codice, test
- Convenzioni di codice — naming, pattern, architettura
- Riferimenti alle specifiche — path ai documenti chiave
Grazie a CLAUDE.md, Claude Code non genera codice "generico": genera codice che rispetta le convenzioni del progetto, usa lo stack tecnologico documentato e implementa i requisiti descritti nelle specifiche.
The CLAUDE.md file is the "bridge" between project specs and the AI. It is placed in the repository root and Claude Code reads it automatically as project context every time it is invoked.
It contains:
- Project rules — conventions, standards, constraints
- Folder structure — where to find specs, code, tests
- Code conventions — naming, patterns, architecture
- References to specifications — paths to key documents
Thanks to CLAUDE.md, Claude Code doesn't generate "generic" code: it generates code that respects project conventions, uses the documented tech stack, and implements the requirements described in the specs.
Suggerimento: Mantieni CLAUDE.md aggiornato con il progetto. Quando cambi sprint, aggiorna il riferimento allo sprint corrente. Quando aggiungi nuovi moduli, aggiorna la struttura delle cartelle. Questo file è il "manuale operativo" che l'AI consulta per ogni operazione.
Tip: Keep CLAUDE.md updated with the project. When you change sprints, update the reference to the current sprint. When you add new modules, update the folder structure. This file is the "operating manual" that the AI consults for every operation.