Case Study: Errantia
Come un progetto reale è stato costruito con MdExplorer + Claude Code + SDD
Introduzione
Errantia è una piattaforma di geolocalizzazione basata su NFC che permette agli artigiani di creare "oggetti erranti" — oggetti fisici dotati di tag NFC destinati a viaggiare nel mondo. Ogni oggetto ha un codice univoco e una pagina web dove chiunque lo trovi può segnalare la propria posizione, contribuendo al viaggio dell'oggetto.
Il progetto è stato sviluppato da un singolo sviluppatore usando l'approccio SDD (Spec Driven Development) con Claude Code come partner AI. Tutte le specifiche sono state scritte e gestite in MdExplorer, versionate con Git, e usate come contesto per generare codice con Claude Code.
Errantia is an NFC-based geolocation platform that allows artisans to create "wandering objects" — physical objects with NFC tags destined to travel the world. Each object has a unique code and a web page where anyone who finds it can report their location, contributing to the object's journey.
The project was developed by a single developer using the SDD (Spec Driven Development) approach with Claude Code as AI partner. All specifications were written and managed in MdExplorer, versioned with Git, and used as context to generate code with Claude Code.
Fase 1 — Analisi Funzionale con Claude Code
Il progetto è partito con prompt a Claude Code per definire il dominio. Il risultato: 10 documenti funzionali organizzati per attore (Artigiano, Viaggiatore, Scopritore, Admin). Ogni documento include:
- Glossario dei termini di dominio — definizioni condivise per evitare ambiguità
- Requisiti numerati (RF-AUTH-01, RF-LAND-02, ecc.) per tracciabilità completa
- Criteri di accettazione per ogni requisito
- Flussi utente e mockup ASCII per visualizzare le interazioni
Tutti i documenti sono stati aperti come progetto MdExplorer, organizzati in cartelle, e versionati con Git fin dal primo commit.
Vedi un esempio di SRS — Un documento di Software Requirements Specification generato con questo approccio.
The project started with prompts to Claude Code to define the domain. The result: 10 functional documents organized by actor (Artisan, Traveler, Discoverer, Admin). Each document includes:
- Domain glossary — shared definitions to avoid ambiguity
- Numbered requirements (RF-AUTH-01, RF-LAND-02, etc.) for full traceability
- Acceptance criteria for each requirement
- User flows and ASCII mockups to visualize interactions
All documents were opened as an MdExplorer project, organized in folders, and versioned with Git from the very first commit.
See an SRS example — A Software Requirements Specification document generated with this approach.
Fase 2 — Architettura Tecnica
Le specifiche funzionali hanno alimentato Claude Code per generare l'analisi tecnica completa. Stack scelto:
- Node.js + Express (backend)
- Angular 17 (frontend)
- PostgreSQL + PostGIS (database con supporto geospaziale)
Il documento ANALISI_TECNICA.md include:
- Schema database con 15+ tabelle e relazioni documentate
- API spec con tutti gli endpoint documentati, metodi HTTP, payload e codici di risposta
- Diagrammi PlantUML per l'architettura complessiva del sistema
- Sequence diagram per i flussi critici (registrazione, creazione oggetto, segnalazione posizione)
- Decisioni tecniche con motivazioni e alternative considerate
Vedi esempio architettura — Un documento di architettura tecnica con diagrammi PlantUML.
Vedi esempio API — Documentazione API con endpoint, payload e codici di risposta.
The functional specifications fed Claude Code to generate the complete technical analysis. Chosen stack:
- Node.js + Express (backend)
- Angular 17 (frontend)
- PostgreSQL + PostGIS (database with geospatial support)
The ANALISI_TECNICA.md document includes:
- Database schema with 15+ tables and documented relationships
- API spec with all endpoints documented, HTTP methods, payloads and response codes
- PlantUML diagrams for the overall system architecture
- Sequence diagrams for critical flows (registration, object creation, position reporting)
- Technical decisions with reasoning and considered alternatives
See architecture example — A technical architecture document with PlantUML diagrams.
See API example — API documentation with endpoints, payloads and response codes.
Fase 3 — Sprint Planning
Il progetto è stato organizzato in sprint, ognuno con un documento markdown dedicato. Ogni sprint include:
- Obiettivo e scope — cosa include e cosa NON include lo sprint
- User stories in formato Agile ("Come [attore] voglio [azione] per [beneficio]")
- Task checklist con ID univoci (BE-XX per backend, FE-XX per frontend, DO-XX per DevOps)
- Criteri di completamento per verificare la chiusura dello sprint
Il primo sprint (SPRINT-01-POC) ha validato il concept end-to-end con il flusso minimo: login artigiano → creazione oggetto → landing NFC → segnalazione posizione. Questo ha permesso di verificare le scelte architetturali con un prototipo funzionante prima di investire tempo nelle feature avanzate.
Vedi esempio sprint — Un documento di sprint planning con user stories, task e checklist.
The project was organized into sprints, each with a dedicated markdown document. Each sprint includes:
- Goal and scope — what the sprint includes and what it does NOT include
- User stories in Agile format ("As a [role] I want [action] so that [benefit]")
- Task checklist with unique IDs (BE-XX for backend, FE-XX for frontend, DO-XX for DevOps)
- Completion criteria to verify sprint closure
The first sprint (SPRINT-01-POC) validated the concept end-to-end with the minimum flow: artisan login → object creation → NFC landing → position reporting. This allowed validating architectural choices with a working prototype before investing time in advanced features.
See sprint example — A sprint planning document with user stories, tasks and checklist.
Fase 4 — Sviluppo con Claude Code
Il file CLAUDE.md configura il contesto del progetto Errantia per Claude Code. Include:
- Regole di progetto — convenzioni, standard, vincoli architetturali
- Struttura cartelle — dove trovare codice, specifiche, test
- Convenzioni di codice — naming, pattern, formattazione
- Riferimenti alle specifiche correnti — path allo sprint attivo e ai documenti chiave
Claude Code legge CLAUDE.md + le specifiche e genera codice allineato all'architettura documentata. Ogni task completato aggiorna la checklist nel file sprint. Il workflow operativo:
- Apri il file sprint corrente in MdExplorer
- Identifica il prossimo task da implementare
- Dai il prompt a Claude Code referenziando il task e le specifiche
- Claude Code genera il codice allineato all'architettura
- Aggiorna la checklist sprint spuntando il task completato
- Commit sia il codice che l'aggiornamento dello sprint
Importante: Il commit include sempre sia il codice generato che l'aggiornamento della checklist sprint. Questo garantisce che lo storico Git mostri l'avanzamento del progetto in modo coerente: ogni commit racconta cosa è stato implementato e quale task è stato chiuso.
The CLAUDE.md file configures the Errantia project context for Claude Code. It includes:
- Project rules — conventions, standards, architectural constraints
- Folder structure — where to find code, specs, tests
- Code conventions — naming, patterns, formatting
- References to current specs — path to the active sprint and key documents
Claude Code reads CLAUDE.md + the specifications and generates code aligned with the documented architecture. Each completed task updates the checklist in the sprint file. The operational workflow:
- Open the current sprint file in MdExplorer
- Identify the next task to implement
- Give a prompt to Claude Code referencing the task and the specifications
- Claude Code generates code aligned with the architecture
- Update the sprint checklist by checking off the completed task
- Commit both the code and the sprint update
Important: The commit always includes both the generated code and the sprint checklist update. This ensures the Git history shows project progress coherently: every commit tells what was implemented and which task was closed.
Risultati
Dopo 7 sprint completati, il progetto Errantia ha raggiunto i seguenti risultati:
- Versione v0.7.0 con MVP completo e funzionante
- 40+ feature implementate, dalla registrazione utente alla mappa interattiva dei viaggi
- Documentazione sempre aggiornata e allineata al codice, perché evolve nello stesso repository
- Le specifiche sono la "single source of truth" del progetto — ogni decisione tecnica è tracciata e motivata nei documenti
- Lo storico Git mostra l'evoluzione parallela di codice e specifiche, permettendo di ricostruire il percorso decisionale in ogni momento
- Ogni decisione tecnica è tracciata e motivata nei documenti, con alternative considerate e motivazioni della scelta
L'approccio SDD con MdExplorer + Claude Code ha dimostrato che anche un singolo sviluppatore può gestire un progetto complesso mantenendo documentazione di livello enterprise. Le specifiche non sono un peso aggiuntivo ma un acceleratore: fornendo contesto strutturato a Claude Code, la qualità del codice generato aumenta significativamente e il tempo di sviluppo si riduce.
After 7 completed sprints, the Errantia project achieved the following results:
- Version v0.7.0 with a complete and functional MVP
- 40+ features implemented, from user registration to the interactive travel map
- Documentation always up to date and aligned with the code, because it evolves in the same repository
- Specifications are the "single source of truth" of the project — every technical decision is tracked and motivated in the documents
- The Git history shows the parallel evolution of code and specifications, allowing to reconstruct the decision path at any time
- Every technical decision is tracked and motivated in the documents, with considered alternatives and reasoning behind the choice
The SDD approach with MdExplorer + Claude Code has demonstrated that even a single developer can manage a complex project while maintaining enterprise-level documentation. Specifications are not an additional burden but an accelerator: by providing structured context to Claude Code, the quality of generated code increases significantly and development time decreases.