Windsurf: memorie e regole (Memories & Rules)

In questa lezione esploriamo come in Windsurf, e attraverso il suo agente Cascade, possiamo andare oltre la semplice generazione di codice. Possiamo infatticostruire una memoria condivisa e duratura del progetto, definire regole di comportamento coerenti e far sì che il nostro ambiente di sviluppo “ricordi” decisioni, standard e contesto. Così da rendere più coerente, stabile e scalabile il lavoro del nostro team di sviluppo.

Quando iniziamo a usare Cascade su un nuovo progetto spesso ci accorgiamo che dopo poche sessioni la quantità di contesto che definiamo (architettura, decisioni, stack tecnologico, convenzioni) diventa già significativa. Funzionalità, dipendenze, convenzioni di naming, pattern architetturali, tutte informazioni che, se non annotate, rischiano di perdersi con il tempo o con il cambio di membri del team. È qui che le “memorie” entrano in gioco e consentono di “depositare” queste informazioni in un archivio persistente in modo che ogni volta che torniamo a lavorare sul progetto, Cascade le ricordi e le possa usare come riferimento. Il sistema di “Memories & Rules” rappresenta pertanto una delle funzionalità capace di garantire continuità e coerenza nel tempo.

Cos’è una Memory (e come si crea in Windsurf)

Nel contesto di Windsurf, una “Memory” è un frammento di conoscenza contestuale che Cascade decide o che noi decidiamo di conservare per il futuro. Le memories possono essere generate in due modi: automaticamente, quando Cascade identifica un contesto utile da conservare, come una decisione architetturale, una tecnologia adottata, un pattern ricorrente, oppure manualmente, quando noi esplicitamente chiediamo di “memorizzare” un certo fatto, convenzione o requisito.

Per esempio: supponiamo che in una riunione di design decidiamo che tutte le API REST del progetto devono restituire errori in un formato JSON standardizzato con un campo "errorCode" e un campo "errorMessage". Possiamo chiedere a Cascade:

Memorizza che lo standard di error handling è questo formato JSON per tutte le API.

Da quel momento, ogni volta che genereremo o modificheremo endpoint API, Cascade terrà conto di quella regola standard e uniformerà la produzione di errori secondo quel formato. In questo modo mettiamo nero su bianco una decisione che altrimenti rischierebbe di rimanere solo una semplice intenzione.

Le memories vengono salvate in un’area dedicata, tipicamente in un percorso come ~/.windsurf/memories/. Questo consente che, sessione dopo sessione, anche se chiudiamo l’IDE o torniamo sul progetto dopo settimane, Cascade ricordi il contesto e lo utilizzi per guidarci nelle prossime interazioni. Per poter vedere le Memorie salvate basta cliccare sull'icona in alto a destra dell'IDE, come mostrato nella figura in basso.

Le regole: definire standard e comportamenti coerenti nel progetto

Le “Regole” (Rules) servono a formalizzare convenzioni, standard di codice, pratiche, decisioni progettuali, preferenze di stack, pattern architetturali e tutto ciò che vogliamo garantire come costante nel tempo. In Windsurf possiamo definire regole globali, valide per tutti i progetti, oppure regole specifiche per un singolo progetto.

Le regole globali (di solito in un file come global_rules.md) stabiliscono le basi condivise. Ad esempio standard di formattazione, stile di codice, principi architetturali generali, convenzioni di nomenclatura, linee guida sulla complessità del codice, sull’organizzazione dei moduli, sulle dipendenze consentite, ecc.

Le regole di progetto (spesso in .windsurf/rules, o un file equivalente nella root del repo) servono per adattare le regole globali alle esigenze specifiche di quel particolare progetto. Possiamo fissare tecnologie supportate, vincoli sull’uso di librerie, strutture di cartelle, processi di deploy, regole di sicurezza, naming convention particolari, e così via.

In questo modo, ogni volta che chiediamo a Cascade di scrivere codice, di aggiungere una feature o di modificare qualcosa, l’agente lo fa “nel rispetto delle regole”. Questo riduce drasticamente il rischio di incoerenze, incoordinazione di team e assicura che il codice resti conforme agli standard decisi fin dall’inizio.

In che modo Memorie e Regole collaborano in Windsurf

Quando uniamo Memorie e Regole in Windsurf, otteniamo un contesto persistente e condiviso. Le regole fungono da “costituzione” del progetto. Le memorie come “storia e conoscenza accumulata”. Ogni volta che prendiamo una decisione importante (scelta di librerie, patterns architetturali, convenzioni di risposta API, struttura directory, politiche di sicurezza, workflow di deploy), possiamo memorizzarla e Cascade la userà come guida in ogni attività futura.

Così, se un nuovo membro entra nel team di sviluppo, non deve scorrere decine di documenti o chiedere a qualcuno. La memoria è lì, e gli aiuterà a capire le scelte fatte e il motivo dietro di esse. Questo meccanismo migliora enormemente la collaborazione, la coerenza e la manutenzione.

Per rimanere nel concreto, quando iniziamo un nuovo progetto, il primo passaggio che dovremmo fare è definire le regole. Quindi, creiamo il file global_rules.md (o utilizziamo uno già esistente se facciamo parte di un’organizzazione), cliccando sul pulsante "Global" dopo aver cliccato sul pulsante "Rules, Memories & Workflow", in alto a destra.

In questo file possiamo andare a inserire delle regole, come per esempio:

Non generare mai funzioni superiori a 100–150 righe se non strettamente necessario: proponi refactoring automatici.

Così da definire un comportamento coerente di Cascade in tutti i progetti, indipendentemente dal linguaggio o dal repository. Una cosa importante da sottolineare è che le global rules definiscono il comportamento base e universale di Cascade. Ciò che deve valere sempre e ovunque, indipendentemente dal repository, dal codice o dal contesto operativo.

Regole e Activation Modes

Quando andiamo a definire una regola di progetto (cliccando sul pulsante "+Project", visibile nella figura in alto), oltre a definire il contenuto della suddetta regola dobbiamo definire anche quando questa debba attivarsi, scegliendo uno fra quattro diversi Activation Modes, ognuno pensato per un livello distinto di controllo.

Una rule impostata su Manual resta passiva finché non la richiamiamo esplicitamente tramite @mention, rendendola perfetta per linee guida occasionali o da usare solo in contesti specifici.

Se invece selezioniamo Always On, la regola diventa attiva permanentemente e viene applicata a qualsiasi richiesta, assumendo un ruolo globale e continuo nel comportamento del modello.

Con Model Decision, forniamo una descrizione naturale della regola e lasciamo che sia Cascade a decidere autonomamente, caso per caso, quando applicarla in base alla pertinenza del contesto: un approccio più intelligente e adattivo.

Infine, Glob ci permette di agganciare l’attivazione a pattern di file. Come estensioni o directory, così che la rule si applichi automaticamente solo quando Cascade lavora su quei file specifici, offrendo granularità operativa e controllo mirato all’interno del workspace.

Conclusioni

In questa lezione abbiamo abbiamo visto come le memorie ci permettano di non ripetere informazioni e mantenere continuità, mentre le regole definiscono il modo in cui il modello opera, pensa e modifica il codice. Abbiamo distinto tra regole globali, che rappresentano principi permanenti, e regole di progetto, più dinamiche e attivabili in base a pattern o decisione del modello.

Con memorie e rules costruiamo un ecosistema intelligente che apprende, si adatta e lavora con noi in modo sempre più fluido e coerente.