La cosa più costosa del lavorare con un agente è rispiegare il contesto. Ogni mattina rispieghi le decisioni di ieri, incolli l'ultimo messaggio di commit, ristabilisci quale bug blocca il deploy. Moltiplica per ogni sessione e il costo nascosto è di ore a settimana, non minuti.
STATE.md elimina quella tassa. Un file, aggiornato alla fine di ogni sessione, caricato all'inizio della successiva. La disciplina: prima di chiudere una sessione, dedica tre minuti all'aggiornamento del file. Domani, quei tre minuti ne risparmieranno venti.
STATE.md contiene tre cose, niente di più.
Decisioni: ciò su cui ti sei accordato e perché. Senza il perché, il tuo io futuro riapre la decisione. "Trigger Postgres invece di cron per il digest giornaliero: i trigger sono transazionali, cron compete con il percorso di scrittura."
In corso: ciò che è a metà, abbastanza specifico da poter essere consegnato. "Migrazione 014 scritta in /migrations/014_add_subscription_columns.sql ma non applicata. Deve essere eseguita prima che l'handler del webhook vada online."
Blocchi: ciò che impedisce il progresso, incluso ciò che hai provato. "La firma del webhook di Stripe fallisce nell'ambiente di test. Ho provato il parser del corpo raw, ancora 400. Prossimo: controlla la variabile d'ambiente nell'anteprima di Vercel."
Limitalo a 60-80 righe. Quando qualcosa si risolve, rimuovilo. Quando qualcosa viene spedito, archivialo.
La disciplina dell'aggiornamento. Aggiungi un hook Stop per ricordarti:
{
"hooks": {
"Stop": [
{
"command": "echo 'Prima di chiudere: aggiorna STATE.md con decisioni, elementi in corso e blocchi di questa sessione.'"
}
]
}
}Il promemoria da solo non basta; l'abitudine deve essere automatica. Il percorso più veloce: fallo per cinque sessioni consecutive. Alla sesta sessione, ti sentirai a disagio a chiudere senza aggiornare. Il disagio è il segnale che l'abitudine si è formata.
MEMORY.md è l'indice per tutto ciò che è duraturo. Ogni voce è una riga che punta a un file separato. Quattro tipi:
user_*: fatti duraturi su di te: fuso orario, contesto di carriera, preferenze. user_location.md
feedback_*: regole apprese dagli errori, con un campo di confidenza. Inizia a 0.3, aumenta a 0.5 quando il pattern si ripete, promuovi a CLAUDE.md a 0.9+. feedback_public_endpoints_need_rate_limits.md
project_*: stato e decisioni datate per un progetto. Archivia quando viene spedito. project_stripe_integration_2026_05.md
reference_*: tabelle di ricerca per persone, strumenti, API. reference_neon_db_config.md
Mantieni ogni riga dell'indice sotto i 200 caratteri e l'indice sotto le 200 righe. Oltre, le voci vengono troncate e Claude non può vederle.
STATE.md è per ora. MEMORY.md è per sempre. La regola generale: se lo diresti in uno standup, va in STATE.md. Se lo scriveresti in una wiki o in un documento di onboarding, va in un file di memoria. Gli standup sono transitori; le wiki sono durature.
Quando un progetto viene spedito e STATE.md contiene ancora cinque righe al riguardo, sposta quelle righe in un file di memoria project_* datato e cancellale. Il progetto non ha smesso di essere importante; ha smesso di essere attuale. Questa distinzione mantiene STATE.md utile.
Scrivi lo stato, non un diario. Una voce di diario: "Ho lavorato all'integrazione di Stripe. È stato complicato." Una voce di stato: "Endpoint webhook in app/api/webhooks/stripe/route.ts. La verifica della firma funziona localmente, fallisce nell'anteprima di Vercel (formato del corpo raw errato). Prossimo: controlla la configurazione del middleware rawBody." Uno dà alla sessione successiva un punto di partenza; l'altro le dà un memoriale.
Altri due anti-pattern: voci in corso senza un'azione concreta successiva che una nuova sessione potrebbe eseguire, e voci duplicate per lo stesso argomento tra le sessioni. Unisci i duplicati: un argomento, una voce, solo lo stato attuale.
Un buon aggiornamento di sessione è di nove-dodici righe: una decisione con motivazione, un elemento in corso con il passo successivo, un blocco con ciò che hai provato.
Scalare oltre 50 file di memoria: il livello di digest. Ogni riga puntatore di MEMORY.md costa circa 100-150 token. A 200 righe sono 20-30K token di soli puntatori. La soluzione: STRATEGY-DIGEST.md, un riassunto di 2-3 frasi di ogni documento principale più un campo "Usa quando:":
## q2-positioning.md
Il posizionamento del Q2 mira all'abilitazione dell'IA nelle organizzazioni di vendita del mercato medio.
Usa quando: discuti il cliente target, i prezzi o la qualificazione dei lead.Claude legge il digest (circa 3K token) e carica un documento completo solo quando pertinente. Con 25 documenti di strategia, sono 3K token invece di 50K. Il campo "Usa quando:" è il meccanismo di routing: scrivilo come una condizione di trigger specifica, non una descrizione del file.
STATE.md cattura lo stato attuale (decisioni, in corso, blocchi) sotto le 80 righe; aggiornalo alla fine della sessione e archivia rapidamente la cronologia. MEMORY.md indicizza la conoscenza duratura in quattro tipi (utente, feedback, progetto, riferimento), limitata a 200 righe. Inizia stasera con tre righe: una decisione, un elemento in corso, un blocco. Tre righe battono zero mentre l'abitudine si forma.