Aggiornare il contesto man mano che il progetto cresce

Un progetto vivo cambia. File di regole, architettura, decisioni, README scritti al giorno 1 sono validi al giorno 1. Al giorno 30, se non aggiornati, sono peggio di niente: dicono cose che non sono più vere e fanno sbagliare l’AI in modi sottili. Mantenere il contesto vivo è disciplina, non talento.

Perché questa lezione conta

Senza ritmo di aggiornamento, ogni progetto che dura più di un mese sviluppa “dark patterns documentali”: file presenti ma stale, regole superate ma mai rimosse, decisioni prese ma non scritte. Il modello AI legge questi documenti e applica regole vecchie a codice nuovo. Risultato: incoerenze, bug strani, refactor inattesi. Aggiornare regolarmente costa molto meno che debuggare le conseguenze.

Obiettivo operativo

Alla fine devi saper:

1. distinguere tre artefatti vivi (decision log, riepilogo, regole) e cosa va in ognuno;
2. impostare un rituale di manutenzione del contesto;
3. riconoscere segnali di “contesto stale” prima che producano danno.

Nucleo della lezione

1. Tre artefatti vivi

Decision log (docs/decisions.md): elenco append-only di decisioni con motivazione. Mai modifichi voci passate; aggiungi nuove. Ogni voce: data, decisione, contesto, alternative scartate, conseguenze attese.

Esempio:

## 2026-04-15: scelto Drizzle ORM al posto di Prisma
- Contesto: backend Bun + Postgres, serverless edge.
- Motivazione: Prisma ha overhead di runtime su edge; Drizzle è più leggero.
- Alternative scartate: Kysely (preferenza per type-safe schema), raw SQL (troppo verboso).
- Conseguenze: refactor 3 query esistenti, type system più stretto, build size -30%.

## 2026-05-02: rimossa colonna `users.timezone`, sostituita con timezone passato a runtime
- Contesto: utenti viaggiano, timezone fissa diventa stale.
- Motivazione: derivata da browser/device.
- Alternative scartate: lasciare e accettare drift.
- Conseguenze: migrazione DB, modificato profilo, codice di display.

Cresce nel tempo. Diventa la “memoria storica” del progetto. Letto da AI in sessioni nuove, dà contesto storico.

Riepiloghi periodici (docs/status.md): stato attuale del progetto. Cosa è fatto, cosa in corso, cosa rimanda. Aggiornato a tappe (settimanale, dopo milestone). Sostituisce versioni precedenti, non append.

Esempio:

## Stato 2026-05-08

### Fatto
- Auth: email/password + magic-link.
- CRUD task con condivisione fra coppia.
- UI principale: lista task, dettaglio, ricerca.

### In corso
- Notifiche push (50%).
- Export CSV (specifica in fase di scrittura).

### Rimanda
- Mobile app (out of scope MVP).
- Internationalizazione (per ora solo italiano).

### Debiti tecnici noti
- Test coverage bassa su modulo `notifications/`.
- Nessun rate limiting su POST /tasks.

### Rischi aperti
- Performance lista con > 1000 task non testata.

Regole (AGENTS.md): convenzioni stabili. Modificate quando emerge nuova convenzione o si supera vecchia. Mai append cieco: rimuovi regole obsolete.

2. Quando aggiornare

Cinque trigger:

• Dopo milestone: feature chiusa → aggiorna status.md, valuta nuove voci in decision log.
• Dopo refactor significativo: se hai cambiato architettura, aggiorna architettura.md e decision log.
• Dopo bug importante: se la causa rivela una convenzione mancante, aggiungi a AGENTS.md.
• Dopo cambio architettura: stack, framework, hosting → aggiorna tutto.
• Periodico: ogni settimana o ogni 2 settimane su progetti attivi, anche solo per “no changes”.

Il “no changes” è importante: una rilettura periodica costringe a notare cose stale.

3. Segnali di contesto stale

Riconosci quando il contesto sta degradando:

• Modello AI propone soluzioni che usano librerie/pattern che hai sostituito mesi fa.
• Tu rispondi al modello “no aspetta, ora facciamo X” su decisione che doveva già essere documentata.
• Il README.md parla di una struttura cartelle diversa da quella reale.
• Decisioni recenti non sono in decisions.md.
• status.md parla di cose già finite o già cambiate.
• Tu eviti di leggere AGENTS.md perché “tanto so cosa c’è dentro” — significa che è stantio.

Quando vedi questi segnali, fermati e fai ciclo di aggiornamento prima del prossimo task.

Caso guidato

Immagina che il progetto parta così:

MVP: app note personali.
Storage: localStorage.
UI: una pagina.
Test: nessuno.

Dopo tre sessioni AI la realtà cambia:

• hai aggiunto cartelle src/lib/notes e src/lib/storage;
• hai introdotto export JSON;
• hai scoperto che localStorage non basta per allegati;
• hai deciso di non aggiungere account nel primo rilascio;
• hai una checklist manuale per creare, cercare, esportare.

Se non aggiorni il contesto, la prossima richiesta partirà da informazioni vecchie. L’AI potrebbe proporre ancora localStorage per allegati, oppure aggiungere login perché non sa che è escluso.

Aggiornamento minimo:

## Stato attuale
- App note personali local-first, senza account.
- Note testuali in localStorage tramite `src/lib/storage`.
- Export JSON già implementato.

## Decisioni
- No auth nella v1: riduce complessità e dati personali.
- Allegati rimandati: localStorage non è adatto.

## Rischi aperti
- Migrazione futura da localStorage a IndexedDB.
- Nessun test automatico: esiste checklist manuale.

## Prossimo task
- Migliorare ricerca senza cambiare storage.

Questo aggiornamento richiede 10 minuti e risparmia ore di correzioni. Il contesto non deve raccontare tutto: deve raccontare ciò che cambia le decisioni future.

Procedura pratica

Rituale di manutenzione fine-sessione (10 minuti):

1. Decision log: ho preso decisioni rilevanti? Scrivile (data, motivazione, alternative).
2. Status: aggiorna sezioni “Fatto / In corso / Rimanda”. Rimuovi voci obsolete.
3. Regole AI: ho notato comportamento sbagliato del modello prevenibile da regola? Aggiungi.
4. Architettura: ho cambiato qualcosa di strutturale? Aggiorna diagramma.
5. Commit: tutti gli aggiornamenti in un commit “docs:” separato dai cambiamenti di codice.

Settimanale (30 min):

1. Rilettura status.md: tutto ancora valido?
2. Rilettura AGENTS.md: ogni regola ancora pertinente? Ce ne sono di superate?
3. Rilettura decisions.md: voci recenti coerenti con stato attuale?
4. Pulizia: rimuovi note temporanee superate, TODO chiusi non rimossi, commenti FIXME di un mese fa.

Laboratorio guidato

Sul tuo progetto attivo, fai audit di contesto:

Step 1: apri AGENTS.md. Per ogni regola, verifica: è ancora seguita? è ancora applicabile? Se no, candidata alla rimozione.

Step 2: apri README.md. Le istruzioni di setup funzionano davvero su una macchina pulita? Esistono ancora i comandi che cita?

Step 3: architettura.md (se esiste). Riflette il sistema reale o una versione di mesi fa?

Step 4: trova cose decise di recente che NON sono in decisions.md. Aggiungile retrospettivamente con la data corretta.

Step 5: scrivi status.md da zero (5 minuti). Confronta con il vecchio: cosa è cambiato che non avevi documentato?

Il delta fra “cosa è scritto” e “cosa è vero” è la misura della tua disciplina di aggiornamento.

Output atteso

Tre file aggiornati:

• decisions.md: append-only, decisioni con data e motivazione.
• status.md: stato corrente sostituito ad ogni revisione.
• AGENTS.md: regole vivenți, niente stale.

E un calendario personale (anche solo mentale) per rivisitarli.

Studio passo passo

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

1. Prima lettura: chiarisci l’obiettivo: mantenere allineati documentazione, prompt e codice mentre il progetto cambia. Se non riesci a riscriverlo in una frase tua, rileggi il nucleo della lezione.
2. Seconda lettura: trasforma i contenuti in domande operative:

• Decision log: cosa è stato scelto, perché, quali alternative sono state scartate.
• Riepiloghi periodici: stato attuale, file importanti, debiti noti, test disponibili, rischi aperti.
• Quando aggiornare: dopo milestone, refactor, cambio architettura, bug importante o nuova integrazione.

3. Applicazione: svolgi il laboratorio: dopo una serie di modifiche simulate, aggiornare README, regole agente e decision log senza duplicare tutto. L’output da ottenere è: un rituale di manutenzione del contesto da eseguire a fine sessione di lavoro.

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

• ho i tre artefatti per il progetto principale;
• li aggiorno al termine di ogni sessione significativa;
• ho fatto rilettura settimanale almeno una volta nelle ultime 2 settimane;
• non ho note temporanee in regole AI vecchie più di un mese;
• il README riflette lo stato reale del progetto.

Errori comuni

Doc fatta una volta, mai aggiornata. Diventa fonte di errori invece che fonte di verità.

Decision log mancante. Tre mesi dopo non sai più perché hai scelto X. Riapri il dibattito ogni volta.

Status come blog. “Oggi ho fatto…” è journaling, non status. Status descrive lo stato attuale, sostituisce versione precedente.

Note temporanee accumulate. “Per ora non aggiungere…” mai rimosso. Modello segue regola obsoleta.

Aggiornamento solo quando “ci si ricorda”. Senza rituale, salta. Dopo milestone è ottimo trigger.

Niente commit “docs:” separati. Aggiornamenti documentazione mescolati a feature. PR illeggibili. Commit separato per docs.

Prompt di lavoro

Aiutami con la manutenzione del contesto del progetto.

Ho questi tre file:
- AGENTS.md: [incolla o link]
- decisions.md: [incolla o link]
- status.md: [incolla o link]

Recenti cambiamenti al codice/architettura (ultime 2 settimane):
[descrivi in 5-10 punti]

Per ognuno dei tre file, dimmi:

1. Cosa va aggiornato (rimosso o modificato).
2. Cosa va aggiunto.
3. Eventuali contraddizioni con il codice attuale.
4. Note temporanee che andrebbero rimosse o consolidate.

Output: patch testuale per ogni file, pronta da copiare. Niente prosa lunga.

Concludi indicando se ci sono decisioni recenti che NON sono ancora in `decisions.md`.

Esercizio finale

Apri il progetto a cui stai lavorando. Senza guardare la documentazione, scrivi su un foglio: cosa è fatto, cosa stai facendo ora, cosa hai deciso di rimandare, ultime 3 decisioni importanti. Ora apri status.md e decisions.md. Quanto coincidono con quello che hai scritto? Quasi mai 100%. La differenza è il tuo debito documentale.