Capstone — architettura su carta e file di contesto del progetto

Brief scelto. Ora serve la mappa tecnica: come è fatto il sistema, quali contratti tra parti, dove vivono dati e logica. Disegno + file di contesto = il modello AI ha tutto per generare in modo coerente. Senza, ogni sessione reinventa.

Perché questa lezione conta

Il salto da brief a codice è dove si introducono molti errori. Ogni “il modello capirà” si paga in scelte arbitrarie: stato nel posto sbagliato, naming incoerente, struttura cartelle improvvisata. Investire 90 minuti in architettura su carta + file di contesto trasforma le successive 20 ore di generazione in implementazione invece che in negoziazione continua con il modello.

Obiettivo operativo

Alla fine devi avere:

1. diagramma architettura testuale dell’app capstone;
2. AGENTS.md/CLAUDE.md completo;
3. decisions.md iniziale con 3-5 decisioni motivate;
4. setup repo con primo commit pulito.

Nucleo della lezione

1. Mappa dell’app

Combina le lezioni 23 (4 strati) e 28 (diagramma):

Strati:

• Frontend: cosa l’utente vede. Componenti principali, route.
• Backend: API/server-side, regole.
• Dati: persistenza.
• Servizi esterni: auth provider, email, pagamenti, modelli AI.

Diagramma testuale: caselle + frecce + confini fiducia. Esempio per tracker abitudini local-first:

[Browser PWA]
   ↑↓ Service Worker (cache, offline)
   ↕  IndexedDB (abitudini, log giornalieri)
   
[Vercel Edge — solo statico]
   ↑ HTTPS
   
Niente backend persistente, niente account, niente dati lasciano dispositivo.
Confine: Browser è il sistema completo.

Contratti:

• Componenti: <HabitList>, <HabitForm>, <TodayView>, <CalendarView>.
• Schema IndexedDB:
  • store habits: id, name, color, createdAt
  • store entries: id, habitId, date (YYYY-MM-DD), done (boolean)
• API: nessuna (no server).
• Eventi: habit.added, entry.toggled (interni, per reattività UI).

Decisioni rischiose da prototipare:

• service worker offline-first (rischio principale: caching strategy).
• IndexedDB con uso facile (tante librerie, scelgo idb o dexie).
• export CSV (formato + meccanismo download lato client).

Identifica almeno 2-3 punti rischiosi da prototipare per primi.

2. AGENTS.md

File di regole per il progetto, basato su lezione 30. Per capstone:

# AGENTS.md — Tracker Abitudini

## Comandi essenziali
- Dev: `bun dev` (porta 4321)
- Build: `bun run build`
- Type check: `bun run astro check`
- Lint: `bun run lint`
- Test: `bun test`

## Stack
- Astro 5 (statico, niente SSR per privacy)
- Tailwind CSS 4
- TypeScript strict
- IndexedDB tramite libreria `idb` v8
- Service Worker + Workbox per offline

## Struttura
- src/components/ : componenti UI
- src/lib/db.ts : wrapper IndexedDB
- src/lib/sw.ts : service worker
- src/pages/ : route Astro
- src/styles/ : tailwind config
- public/manifest.webmanifest : PWA

## Convenzioni
- TS strict, no `any`
- Componenti: PascalCase (`HabitList.tsx`)
- File util: kebab-case (`format-date.ts`)
- Async/await, no .then()
- Errori: Result<T, AppError> per funzioni che falliscono
- Date in formato ISO YYYY-MM-DD per chiavi e display
- Niente librerie UI pesanti (solo Tailwind utilities)

## Vincoli rigidi
- NO chiamate a server esterni runtime (privacy)
- NO PII in nessun log
- NO nuove dipendenze senza approvazione
- NO modifiche a astro.config, tailwind.config senza approvazione
- IndexedDB solo per storage. localStorage solo per preferenze.
- Service Worker registrato solo in produzione (DEV non).

## Riferimenti
- Architettura: docs/architettura.md
- Decisioni: docs/decisions.md
- Brief: docs/capstone-brief.md

3. decisions.md iniziale

3-5 decisioni con motivazione + alternative, basato su lezione 27/37:

# Decision Log

## 2026-05-08: Astro statico + PWA, no backend
- Contesto: tracker abitudini personale, vincolo rigido "dati restano sul dispositivo".
- Motivazione: zero infrastruttura, privacy massima, no costi runtime, semplice da deployare.
- Alternative scartate:
  - Next.js + Postgres: backend non necessario, costi, complicato.
  - Tauri/Electron: overhead per app web semplice.
- Conseguenze: niente sync multi-device per MVP, niente auth.
- Reversibile: sì, posso aggiungere backend dopo.

## 2026-05-08: IndexedDB con `idb` (Mozilla)
- Contesto: persistence locale, dati strutturati.
- Motivazione: IndexedDB è standard browser, `idb` è wrapper minimal e tipato.
- Alternative scartate:
  - Dexie.js: più feature ma più peso (50KB vs 5KB).
  - localStorage: limite 5MB e API sincrone non adatte.
  - SQLite WASM: overkill per scope.
- Reversibile: medio. Cambio richiede migrazione dati.

## 2026-05-08: Service Worker via Workbox
- Contesto: PWA offline-first.
- Motivazione: Workbox gestisce cache strategy, manifest, update senza scrivere SW a mano.
- Alternative scartate: SW a mano (più controllo ma più rischio errori).
- Reversibile: sì.
- Rischio: cache stale se non gestita bene. Strategy iniziale: stale-while-revalidate per app shell.

4. Setup repo

Sequenza di lezione 11:

1. git init, gh repo create (privata, così iteri sicuro).
2. .gitignore: node_modules/, .env*, dist/, .DS_Store.
3. package.json: bun init o equivalente.
4. Setup Astro: bun create astro@latest.
5. Setup Tailwind: bunx astro add tailwind.
6. Crea docs/ con i file: capstone-brief.md, architettura.md, decisions.md.
7. Crea AGENTS.md (sopra).
8. README.md minimo.
9. Primo commit: “chore: initial project setup”.
10. Push.

Repo pronto. Da qui prossimo deploy: capstone-generation.

Esempio completo di pacchetto iniziale

Capstone: “registro spese personali local-first”.

docs/architettura.md minimo:

# Architettura

## Obiettivo
Registrare spese personali, categorizzarle e vedere riepilogo mensile. Nessun account nella v1.

## Blocchi
- UI: form spesa, lista spese, filtro mese, riepilogo categoria.
- Logica: validazione importo/data/categoria, calcolo totali, ordinamento.
- Storage: IndexedDB tramite wrapper `expenseRepository`.
- Esterni: nessuno.

## Confini
- UI non parla direttamente con IndexedDB.
- Calcoli in `src/lib/expenses`, non nei componenti.
- Date salvate ISO `YYYY-MM-DD`.

docs/decisions.md:

## No account nella v1
Motivo: riduce dati personali, backend e auth.
Conseguenza: niente sync multi-dispositivo.

## IndexedDB invece di localStorage
Motivo: dataset potenzialmente grande e query future.
Conseguenza: serve wrapper testabile.

AGENTS.md:

- Non aggiungere backend o auth.
- Non usare librerie chart finché non esiste riepilogo dati testato.
- Ogni modifica deve indicare test manuale eseguito.
- Prima implementare dominio e storage, poi UI.

Questo pacchetto basta per il primo prompt agentico. Non è documentazione decorativa: è il recinto operativo.

Checklist di accettazione dei file

Prima di passare alla generazione, controlla i tre file come se fossero codice.

architettura.md è accettabile se:

• nomina blocchi concreti, non solo categorie generiche;
• indica dove vive ogni regola importante;
• separa UI, logica e storage;
• contiene almeno due domande aperte;
• elenca cosa è fuori scope nella v1.

AGENTS.md è accettabile se:

• contiene comandi reali del progetto;
• vieta esplicitamente modifiche rischiose non richieste;
• dice come verificare un task;
• resta sotto 100 righe;
• non contiene preferenze vaghe come “scrivi bene”.

decisions.md è accettabile se ogni decisione ha contesto, motivazione, alternativa scartata e conseguenza. Una decisione senza conseguenza è spesso solo una preferenza.

Se uno di questi file non passa, non chiedere ancora codice. Chiedi all’AI di criticare il pacchetto:

Leggi questi tre file come revisore tecnico. Trova ambiguità, contraddizioni, decisioni mancanti e punti dove un agente potrebbe fraintendere. Non proporre codice.

Questa revisione preventiva è piccola, ma evita che il capstone parta storto.

Nota importante: non cercare di prevedere tutto. Il pacchetto iniziale deve rendere chiaro il prossimo passo, non l’intera vita del prodotto. Una domanda aperta scritta bene è meglio di una decisione inventata per chiudere il documento.

Quando sei incerto, marca esplicitamente la scelta come provvisoria e indica quale esperimento la renderà definitiva durante la prossima sessione operativa del progetto.

Procedura pratica

90 minuti per costruire tutto:

1. Brief letto (5 min): rinfresca.
2. Mappa dell’app (15 min): 4 strati con contenuti.
3. Diagramma (15 min): testuale.
4. Contratti (15 min): componenti, schema dati, eventi.
5. AGENTS.md (15 min): comandi, convenzioni, vincoli.
6. decisions.md (15 min): 3-5 decisioni con motivo.
7. Setup repo (10 min): comandi sequenziali, primo commit.

A 90 minuti hai tutto pronto per iniziare la generazione.

Laboratorio guidato

Per il tuo capstone, segui la procedura. Risultati attesi:

• docs/architettura.md: diagramma + contratti + 2-3 decisioni rischiose.
• AGENTS.md: ~50-80 righe di regole specifiche.
• decisions.md: 3-5 decisioni con motivo + alternative.
• Repo Git inizializzato con primo commit.
• Push su remote (anche privato).

Output atteso

Pacchetto di contesto sufficiente per far lavorare un agente AI senza dover spiegare tutto in chat ogni volta. Architettura + regole + decisioni vivono in repo, non nella tua testa.

Studio passo passo

Studia questa lezione in tre passaggi, senza correre subito al prompt o al codice.

1. Prima lettura: chiarisci l’obiettivo: preparare il terreno tecnico prima della generazione, collegando architettura, regole e setup. Se non riesci a riscriverlo in una frase tua, rileggi il nucleo della lezione.
2. Seconda lettura: trasforma i contenuti in domande operative:

• Mappa dell’app: UI, dati, logica, API, persistenza, autenticazione eventuale, servizi esterni.
• File di contesto: regole agente, decisioni iniziali, comandi, vincoli, stile, criteri di test.
• Individuazione dei punti rischiosi da implementare per primi o prototipare separatamente.

3. Applicazione: svolgi il laboratorio: produrre diagramma e file AGENTS.md/README iniziale per il capstone. L’output da ottenere è: un pacchetto di contesto sufficiente a far lavorare un agente senza ripetere tutto in chat.

Prima di passare alla lezione successiva, controlla di avere un artefatto concreto: una tabella, un prompt, una checklist, un mini report, un diff commentato o una decisione scritta. Nel vibe coding la comprensione resta astratta finché non produce una traccia verificabile.

Checklist di verifica

• mappa 4 strati per capstone scritta;
• diagramma testuale presente;
• contratti principali definiti;
• AGENTS.md sotto 100 righe;
• decisions.md con 3+ voci motivate;
• repo inizializzata con primo commit;
• 2-3 punti rischiosi identificati per prototipare per primi.

Errori comuni

Saltare l’architettura, andare al codice. Il modello inventa scelte coerenti tra loro ma non con la tua intenzione.

Architettura troppo dettagliata. Diagramma di 5 pagine, file di regole gigante. Procrastinazione travestita.

Niente AGENTS.md. Ogni sessione il modello inventa convenzioni. Naming, struttura, pattern: incoerenti.

Decision log vuoto. Tre mesi dopo non ricordi perché. Riapri il dibattito.

Niente prima commit. Stato pulito = prerequisito. Senza commit, modifiche AI mescolate a setup iniziale.

Architettura senza domande aperte. Pretendi di sapere tutto. Domande aperte rendono il file onesto.

Prompt di lavoro

Sto costruendo architettura per il mio capstone.

Brief:
[incolla docs/capstone-brief.md]

Aiutami in 4 fasi (rispondi una alla volta):

Fase 1 — Mappa 4 strati: per ognuno (frontend/backend/dati/esterni) cosa contiene specificamente per il mio progetto.

Fase 2 — Diagramma testuale: caselle + frecce + confini fiducia. Compatto, leggibile.

Fase 3 — Contratti: componenti chiave, schema dati, API/eventi, errori. Tabella con nome + responsabilità.

Fase 4 — Decisioni rischiose: 2-3 punti dove la scelta tecnica non è ovvia. Per ognuno: 2-3 alternative + raccomandazione + come prototiparla.

Concludi con:
- bozza AGENTS.md (max 80 righe)
- bozza decisions.md con 3 voci

Output: file pronti da copiare nel repo. Niente codice ancora.

Esercizio finale

Mostra architettura.md + AGENTS.md + decisions.md a una persona tecnica esterna. In 5 minuti capisce il progetto? Identifica scelte non ovvie? Segnala buchi? Quasi sempre 1-2 cose mancano. Rifinisci prima del prossimo passo (generazione).