ousterhout-quality-program

SKILL.md

---
name: ousterhout-quality-program
description: Usa ogni volta che il codice scritto o revisionato crea o modifica un confine: un nuovo modulo, classe, componente, helper, hook, servizio o wrapper; qualsiasi estrazione o centralizzazione di codice condiviso; ogni momento "facciamo che questo sia riutilizzabile"; e quando si revisiona, rifattorizza o progetta esplicitamente un modulo. Valuta se un'astrazione giustifica la sua esistenza: profondità del modulo, se nascondere una decisione di design, se il codice duplicato protegge un invariante condiviso o è solo una rima, se un'interfaccia è stabile. Previene l'applicazione meccanica di SOLID/Clean Code che produce molte classi superficiali. Definisce inoltre il test del costo per il lettore (codice facile da leggere e modificare per umani e agenti) e la procedura per rifattorizzare una codebase esistente secondo questo standard.
---

# Programma di Qualità Ousterhout

## Panoramica

Il compito di un modulo è nascondere la complessità dietro una piccola interfaccia. La misura principale è la **profondità**: un modulo profondo offre un'interfaccia semplice su una funzionalità sostanziale; l'interfaccia di un modulo superficiale è quasi complessa quanto la sua implementazione, quindi non si ripaga in nulla. La complessità è ciò che si percepisce quando una modifica ti costringe a capire o toccare codice che non ti aspettavi — Ousterhout indica due fonti: **dipendenze** (non puoi cambiare A senza cambiare B) e **oscurità** (l'informazione importante non è ovvia).

Ousterhout da solo ti dice come *si sente* un buon modulo. È più efficace se combinato con altre lenti che indicano dove dovrebbero stare i confini e come muoversi verso di essi in sicurezza. Questa skill è quella lente combinata.

## Dove le Revisioni Sbagliano Davvero

I due errori che questa skill esiste per correggere — osservati ripetutamente nel codice scritto da agenti — sono nel **rimedio**, non nel verdetto split/non-split in sé:

1. **La correzione superficiale.** Date sei conversioni `as unknown as`, il revisore senza aiuti le centralizza in un unico helper generico `castRows<T>()` — più ordinato, ma l'oscurità sopravvive. La correzione profonda sono mapper tipizzati da riga→dominio con test fissati prima (applicando Parnas: una conversione è il segnale di un confine mancante; Beck: dimostra la mappatura prima di spostarla). Sistemare un segnale non significa rimuoverlo.
2. **L'estrazione riflessiva.** Data la stessa logica di aggiornamento ripetuta in tre componenti fratelli, ogni revisore senza aiuti ha detto "estrai un helper condiviso" — il riflesso DRY. La regola di questo programma, che estende Metz: aspetta l'invariante, non la terza somiglianza — centralizza quando il codice protegge una regola condivisa, non quando fa rima.

Quando ti trovi a raccomandare una correzione, passala attraverso entrambi: rimuove l'oscurità o la sposta solo, e l'estrazione protegge un invariante o solo deduplica una forma?

## Porta di Proporzionalità

Salta la lente quando una modifica non aggiunge nessun nuovo nome esportato/importabile, non crea un nuovo modulo/classe/componente/helper/hook/servizio/wrapper, e non centralizza nulla. Sono esenti rinominazioni pure, codemod meccanici, modifiche di configurazione/dati e correzioni di una singola riga. In caso di dubbio, esegui solo i due test principali (profondità, invariante) e fermati lì.

## La Regola Completa

Ogni pezzo di codice generato o revisionato passa attraverso la lente Ousterhout prima che il compito sia considerato concluso — non solo le revisioni di design esplicite — tranne le modifiche sotto la porta di proporzionalità (nessun nuovo confine, nessuna centralizzazione: rinominazioni, codemod, modifiche di configurazione). Due test: (1) **Profondità** — una nuova interfaccia deve nascondere sostanzialmente più di quanto espone; un'interfaccia complessa quanto ciò che incapsula non vale nulla. (2) **Invariante** — estrai codice condiviso solo quando protegge una regola condivisa, mai perché tre siti fanno rima; e una correzione deve rimuovere l'oscurità, non spostarla (centralizzare sei conversioni in un helper è ancora sei conversioni). Quando una modifica crea o rimodella un confine, prima trova come un prodotto consolidato risolve un problema di questa forma e scala e adotta le sue convenzioni a meno che non ci sia una ragione dichiarata per non farlo (un pattern ricordato dall'addestramento è una rivendicazione, non una fonte), poi esegui i controlli sotto.

## Quando Usare

- Decidere se una nuova classe/funzione/hook vale la sua interfaccia, o è solo un passaggio superficiale.
- Un file supera una soglia di dimensione e stai decidendo *come* dividerlo, non solo se farlo.
- Codice ripetuto ti tenta a estrarre un helper condiviso.
- Progettare o revisionare un confine attorno a una regola di business (un controllo di ambito di autorizzazione, una regola di denaro/arrotondamento, una guardia di transizione di macchina a stati, una regola di conservazione dati).
- Un'interfaccia sta per crescere con un parametro o un caso speciale.
- Portare un codice esistente a questo standard — vedi "Refactoring di un Codice Esistente a Questo Standard" sotto.

**Non per:** modifiche meccaniche banali, o quando una convenzione di progetto già detta la struttura — vedi la Porta di Proporzionalità sopra. Affidati a `karpathy-guidelines` per la disciplina dei cambi chirurgici e a una skill di sviluppo guidato dai test per la rete di sicurezza del refactoring, quando disponibili.

## Le Lenti

Ogni lente aggiunge esattamente una domanda. Ousterhout è la spina dorsale; le altre correggono i suoi punti ciechi.

| Lente | La domanda che aggiunge | Quando prevale |
|---|---|---|
| **Ousterhout** — moduli profondi | Questa interfaccia nasconde più di quanto espone? | Spina dorsale predefinita. |
| **Parnas** — nascondere l'informazione | Quale decisione di design (probabilmente soggetta a cambiamento) questo modulo nasconde? | Il *motivo* per cui un modulo dovrebbe essere profondo. Se non nasconde nulla che cambia, la profondità è solo estetica. |
| **Brooks** — essenziale vs accidentale | Questo elimina la complessità accidentale, o sposta solo la complessità essenziale del dominio? | Elimina i "refactor" che spostano il disordine senza ridurlo. |
| **Evans** — Domain-Driven Design | Questo confine è nominato nel linguaggio del dominio, non in un linguaggio generico di utilità? | Rinomina `utils`/`helpers` — dai al confine il nome dell'invariante che questo repository ha effettivamente. |
| **Fowler** — refactoring / odori | Qual è la mossa più piccola e sicura verso un design più profondo? | Trasforma il "dovrebbe essere più profondo" in passi concreti dietro test superati. |
| **Beck** — design semplice, test-first | Ho dimostrato il comportamento attuale prima di approfondire la giuntura? | Un freno all'architettura prematura. Fallo funzionare e testalo prima, poi approfondisci la giuntura giusta. |
| **Hickey** — semplice vs facile | Questo intreccia concetti non correlati, o è genuinamente un solo concetto? | Un helper superficiale è di solito *facile* (vicino, veloce), non *semplice* (pochi concetti intrecciati). Preferisci semplice. |
| **Metz** — duplicazione rispetto a astrazione sbagliata | Questo codice ripetuto protegge un invariante condiviso, o solo sembra simile (regola di questo programma, estendendo Metz)? | Metz: la duplicazione costa meno di un'astrazione sbagliata — reinserisci un'astrazione sbagliata piuttosto che piegarla. Questo programma estende la sua regola: **non** centralizzare perché si ripete; centralizza solo quando protegge un vero invariante. Tollerare la duplicazione finché l'invariante non si rivela. |
| **Legge di Hyrum** — comportamento osservabile | I chiamanti dipenderanno da comportamenti oltre il contratto di questa interfaccia? | Sostiene interfacce piccole e stabili: ogni comportamento osservabile diventa alla fine portante. |

## La Ricetta di Combinazione

Applica in questo ordine — le lenti successive contano solo se quelle precedenti passano:

1. **Metz — il cancello di ammissione.** Questo confine/astrazione merita di esistere? Regola di questo programma, estendendo Metz: estrai solo quando il codice protegge una regola condivisa — tre somiglianze non sono un invariante rivelato. Se no, fermati qui.
2. **Parnas / Ousterhout** — Nascondi la decisione volatile (ambito di autorizzazione, regola di arrotondamento, guardia di transizione, regola di conservazione) dietro un modulo profondo.
3. **Evans** — Dai a quel modulo un nome nel linguaggio del dominio, non `utils`.
4. **Beck / Fowler** — Per codice esistente, fissa il comportamento attuale con test, poi rifattorizza verso di esso con piccoli passi sicuri. Per codice appena generato non c'è comportamento attuale da fissare — scrivi invece il test che definisce il comportamento previsto.
5. **Hickey** — Rifiuta interfacce che mescolano concetti non correlati solo perché i flussi di lavoro sembrano simili.

## L'Anti-Pattern Strutturale

**SOLID / Clean Code meccanico produce moduli superficiali.** Una lettura dogmatica —
una classe per responsabilità, estrai ogni funzione, mantieni tutto minuscolo —
produce uno sciame di classi le cui interfacce sono complesse quanto i loro corpi. Quando
una regola dice "dividi questo", chiedi quale *decisione* la divisione nasconde (Parnas) e
se nasconde più di quanto espone (Ousterhout). Se non nasconde nulla che
cambia, non dividere. Questa guardia è più importante sotto pressione di refactoring ("pulisci
questo", "questo file è troppo grande") — in analisi calma, i revisori già la resistono; a metà refactoring, con un mandato di produrre cambiamenti visibili, è quando lo sciame
di file superficiali viene scritto.

## Errori Comuni

- **Dividere solo per dimensione.** Un modulo query di 400 righe che nasconde una decisione coerente può essere più profondo di quattro moduli da 100 righe che perdono gli stessi join.
- **Chiamare la divisione `helpers`/`utils`.** Se non riesci a nominarlo nel linguaggio del dominio (Evans), probabilmente il confine è sbagliato.
- **Estrarre alla seconda occorrenza.** Regola di questo programma, estendendo Metz: aspetta l'invariante, non la terza somiglianza.
- **Approfondire prima di fissare il comportamento.** Beck: senza un test che dimostri il comportamento attuale, un refactoring di "approfondimento" è una riscrittura.
- **Considerare un pass-through come modulo.** Un wrapper che inoltra i suoi argomenti aggiunge un'interfaccia e non nasconde nulla — superficiale per definizione.
- **Confondere una rima con un invariante.** La migliore prova di un invariante condiviso è il co-cambiamento: le copie sono state corrette o modificate insieme nella storia (lo stesso bug corretto in due posti). Somiglianze che cambiano indipendentemente sono rime; lasciale duplicate.
- **Rifinire un odore invece di rimuoverlo.** Centralizzare sei cast in un helper generico è la versione ordinata della stessa oscurità. La correzione profonda nomina il confine che il cast stava coprendo.

## Costo per il Lettore: il Terzo Test

Profondità e invariante decidono se un confine dovrebbe esistere. Il costo per il lettore
decide se il codice intorno è economico da modificare. Il prossimo lettore, umano
o agente, paga per ogni riga che deve caricare per cambiare qualcosa in sicurezza.
Gli agenti pagano in token e navigano con ricerca testuale, letture parziali e
cicli di typecheck/test, quindi gli stessi difetti costano loro di più. Chiedi:

- **Trovabile?** Un nome per concetto, scritto sempre allo stesso modo, raggiungibile tramite ricerca in testo semplice. Difetti: nomi assemblati da stringhe, collegamenti tramite effetti collaterali di import, catene di re-export che nascondono la definizione, due nomi per un concetto.
- **Il lettore può fermarsi presto?** Il contratto si trova in cima al file o sopra l'export: cosa promette, cosa nasconde, cosa non fa mai. Difetto: il contratto si può ricavare solo leggendo il corpo.
- **Verificabile automaticamente?** Tipi precisi in ingresso e uscita da ogni confine, così un controllo di tipo sostituisce la lettura dei chiamanti. Difetti: `any`, dizionari nudi, flag booleani il cui significato vive nel corpo.
- **Il coupling è visibile?** I punti che devono cambiare insieme sono forzati (un tipo condiviso, un test, una singola fonte) o, in mancanza, marcati in entrambi i siti. La prova di coupling nascosto è il co-cambiamento nella storia che nulla nel codice menziona.
- **Senza rumore?** Nessun commento che ripete il codice, nessun codice commentato, nessun ramo morto, nessun commento sulla storia delle modifiche, nessun percorso obsoleto mantenuto accanto alla sua sostituzione.
- **Prevedibile?** Il layout segue il modello esistente del repo; il test è dove un lettore lo cercherà e si esegue da solo.

La dimensione del file è volutamente assente. Un file molto grande è un motivo per cercare una seconda decisione nascosta, mai un motivo per tagliare: i lettori possono cercare e leggere un intervallo, e una divisione che non nasconde nulla aggiunge interfacce senza rimuovere carico.

Per marcatori in codice e una mappa del repo, usa `context-audit` dove disponibile: il suo ancora `AIDEV-NOTE:` (un fatto non recuperabile più un riferimento di provenienza, al massimo due righe, nel sito) è la convenzione per il coupling che non può essere forzato.

## Rifattorizzare un codice esistente a questo standard

Un retrofit si giudica allo stesso modo del codice nuovo; ciò che cambia è l'ordine e la moderazione. La maggior parte di un codice dovrebbe restare intatta.

1. **Censimento, sola lettura.** Elenca i confini (moduli, servizi, helper condivisi). Per ogni record: la decisione che nasconde, o "nessuna"; dimensione dell'interfaccia rispetto al corpo; partner di co-cambiamento dalla storia; difetti di costo per il lettore. Non cambiare ancora nulla.
2. **Classifica per frequenza di cambiamento, non per bruttezza.** La priorità è quante volte il codice cambia moltiplicato per quanto costa leggerlo. Il codice freddo che funziona resta com'è, per quanto superficiale. La complessità essenziale del dominio resta dove è (Brooks).
3. **Assegna un rimedio per ogni riscontro:**
   - livello pass-through o wrapper che non nasconde nulla: cancellalo, i chiamanti usano ciò che avvolgeva;
   - astrazione sbagliata piegata da flag e casi speciali: reinseriscila inline (Metz), poi cerca la vera invariante;
   - fratelli superficiali che condividono una decisione: uniscili dietro un'interfaccia unica;
   - decisione trapelata (i chiamanti conoscono il formato, la regola, lo schema): spostala nel modulo che la possiede;
   - nome generico (`utils`, `helpers`, `manager`): rinominalo per la decisione che nasconde, o dissolvilo nei suoi chiamanti;
   - confine non tipizzato: tipizzalo, e sostituisci i cast con il mapper che stavano coprendo;
   - coupling nascosto: forzalo, o marca entrambi i siti;
   - rumore: cancellalo.

   Le rime che cambiano indipendentemente non hanno rimedio.
4. **Fissa prima il comportamento.** Nessun rimedio inizia finché un test non dimostra il comportamento attuale del codice toccato (Beck). I refactor preservano il comportamento; un cambiamento di comportamento è un commit separato.
5. **Dividi il lavoro in unità che un agente può completare da solo.** Un confine per unità. Ogni unità nomina i file che possiede, il contratto che deve preservare e il comando che lo dimostra da solo. Nessuna due unità concorrenti scrivono lo stesso file; i file condivisi (barili, registri, tabelle di routing) hanno un solo proprietario o aspettano l'integrazione. Le modifiche di interfaccia da cui dipendono più unità arrivano prima, come unità a sé.
6. **Misura il risultato.** Scegli un cambiamento rappresentativo prima di iniziare e conta i file e le righe che un lettore deve caricare per farlo; conta di nuovo dopo. I nomi esportati e le righe totali dovrebbero diminuire o restare stabili. Un refactor che aggiunge interfacce deve motivarlo esplicitamente.
7. **Fermati** quando ciò che resta è freddo, essenziale o una rima.

Skill correlate, dove disponibili: `repo-review` (tipo design) produce il censimento come artefatto solo di consiglio; `design-cleanup` esegue il ciclo fix-and-rescan per la complessità accidentale; `context-audit` aggiunge ancore e la mappa del codice; `ousterhout-build-deep` è la checklist per l'autore per gli agenti che fanno le unità.

## Dove si colloca

Questa skill è il livello di revisione e giudizio: usala per decidere se un'astrazione è profonda, nominata per la decisione giusta e vale la pena estrarla. `find-shared-code` la usa come test di ammissione quando scansiona la storia recente per codice da condividere. L'Appendice sotto dà il ragionamento di ogni autore.

---

## Appendice: Le Lenti in Profondità

La modalità di fallimento che ogni autore cattura, e la mossa che ciascuno ti dà. La tabella sopra è il riferimento rapido; questo è il ragionamento dietro.

### Ousterhout — Moduli Profondi (la spina dorsale)

*Una Filosofia del Design del Software.*

- **Profondità** = beneficio (funzionalità nascosta) ÷ costo (complessità dell'interfaccia). Un modulo profondo nasconde molto dietro poco. L'interfaccia di un modulo superficiale è quasi complessa quanto il suo corpo, quindi non guadagna nulla.
- **Complessità** è tutto ciò che nel sistema rende difficile capire o modificare. Due fonti:
  - **Dipendenze** — non puoi cambiare una parte senza toccarne un'altra.
  - **Oscurità** — l'informazione importante non è ovvia dal codice.
- **Sintomi:** amplificazione del cambiamento (una decisione, molte modifiche), carico cognitivo (quanto devi tenere a mente), sconosciuti sconosciuti (non puoi dire quale codice un cambiamento influenzerà).
- **Mossa chiave:** sposta la complessità *verso il basso* — il modulo assorbe il caso difficile così i chiamanti non devono farlo. Parametri di configurazione e pass-through spingono la complessità *verso l'alto* al chiamante; quello è superficialità.

Cattura: interfacce che perdono la loro implementazione; helper che non aiutano.

### Parnas — Nascondere l'Informazione (perché la profondità conta)

*On the Criteria To Be Used in Decomposing Systems into Modules (1972).*

- Decomporre attorno a **decisioni di design probabilmente soggette a cambiamenti**, non attorno ai passaggi di un calcolo. Ogni modulo nasconde una di queste decisioni.
- Questo è l'antenato diretto del modulo profondo. Un modulo è profondo *perché* nasconde una decisione che altrimenti si propagherebbe ai chiamanti.

Trappole: un "modulo" che non nasconde nulla di volatile — la sua profondità è solo estetica. Chiedi: cosa cambia dietro questa interfaccia che i chiamanti non vedono mai? Se la risposta è "niente", il confine è una decorazione.

### Brooks — Complessità Essenziale vs Accidentale

*Nessuna Bacchetta Magica.*

- La complessità **essenziale** è intrinseca al dominio (la valutazione è davvero così intricata). La complessità **accidentale** è ciò che i nostri strumenti e la struttura impongono.
- Solo la complessità accidentale è rimovibile. Un refactoring che "pulisce" spostando la complessità essenziale del dominio da un file a un altro non ha fatto nulla.

Trappole: riorganizzazioni mascherate da semplificazione. Chiedi: la complessità totale è diminuita o si è solo spostata?

### Evans — Domain-Driven Design

*Domain-Driven Design.*

- I confini dovrebbero essere nominati nel **linguaggio ubiquo** del dominio, non in termini generici di utilità. Un modulo chiamato `helpers` non nomina nulla; un modulo chiamato `AccessScope` o `PricingPolicy` nomina un invariante.
- I bounded contexts impediscono che gli invarianti di business trapelino attraverso le giunture.

Trappole: decomposizione corretta con nomi privi di significato. Se non riesci a nominare il modulo nel linguaggio del dominio, probabilmente hai tagliato il confine nel posto sbagliato.

### Fowler — Refactoring e Code Smells

*Refactoring.*

- Fornisce mosse concrete, sicure e nominate (Extract Function, Move Field, Replace Conditional with Polymorphism) per passare dal design attuale a quello più profondo.
- Ogni mossa preserva il comportamento ed è piccola, quindi resta reversibile.

Trappole: il divario tra "questo dovrebbe essere più profondo" e sapere quale sarà la prossima commit. Ousterhout fissa l'obiettivo; Fowler è la strada.

### Beck — Simple Design, Test-First

*Test-Driven Development; XP.*

- Quattro regole del design semplice, nell'ordine pubblicato da Beck: passa i test, niente duplicazioni, rivela l'intenzione, meno elementi possibile. Questo programma segue il successivo riordino di Fowler/Haines — intenzione prima della duplicazione — perché serve alla regola invariabile di estensione di Metz (vedi Metz, sotto): non agire sulla duplicazione finché non puoi nominare l'intenzione che protegge.
- Test-first è un freno contro l'architettura prematura. Fai funzionare e prova il comportamento *prima*, poi approfondisci la giuntura che i test ora proteggono.

Trappole: architettura costruita prima che il comportamento sia fissato. Senza un test che provi il comportamento attuale, un refactoring di "approfondimento" è una riscrittura non verificata.

### Hickey — Simple vs Easy

*Simple Made Easy.*

- **Simple** = non intrecciato: un concetto, non mescolato con altri (oggettivo).
- **Easy** = a portata di mano, familiare, rapido da raggiungere (relativo a te).
- I due sono indipendenti. Un helper superficiale è di solito *easy* — veloce da scrivere, vicino — ma non *simple* se intreccia preoccupazioni non correlate.

Trappole: comodità che si spaccia per design. Preferisci costrutti che mantengano i concetti non intrecciati anche quando uno intrecciato è più veloce da scrivere.

### Metz — Preferire la Duplicazione alla Astrazione Sbagliata

*"The Wrong Abstraction" (2016).*

- La duplicazione è molto meno costosa dell'astrazione sbagliata. Un'astrazione estratta troppo presto costringe ogni chiamante futuro a piegarsi attorno ad assunzioni che non sono mai state vere per tutti.
- Quando un'astrazione si rivela sbagliata, il rimedio di Metz è di reinserirla inline e lasciare che la duplicazione ritorni, piuttosto che piegarla per adattarla a un caso per cui non è stata costruita.
- **La regola di questo programma, che estende Metz: non centralizzare perché il codice si ripete. Centralizza quando protegge un vero invariante condiviso.** Finché l'invariante non si rivela, tollera la duplicazione.

Trappole: sovra-centralizzazione — l'helper condiviso superficiale che ora tutti devono aggirare. Questo è il contrappeso a un "DRY a tutti i costi" meccanico.

### Legge di Hyrum — Il Comportamento Osservabile Diventa Contratto

*"Con un numero sufficiente di utenti, ogni comportamento osservabile del tuo sistema sarà dipendente da qualcuno."*

- Qualunque cosa un'interfaccia *faccia* — ordinamento, tempistica, testo di errore — qualcuno alla fine si affiderà a essa. Quindi la superficie che esponi è più ampia di quella che hai documentato.
- Questo supporta la preferenza di Ousterhout per **interfacce piccole e stabili**: meno esponi, meno può diventare portante per caso.

Trappole: interfacce ampie che si ossificano. Ogni osservabile extra diventa un vincolo futuro.

### Come Si Integrano

- **Parnas → Ousterhout:** nascondi una decisione volatile → il modulo è profondo.
- **Brooks:** conferma che la profondità ha rimosso complessità anziché spostarla.
- **Evans:** nomina il confine nel linguaggio del dominio.
- **Beck → Fowler:** fissa il comportamento, poi refactoring con mosse piccole e sicure.
- **Metz:** resisti a centralizzare finché l'invariante non è reale.
- **Hickey:** mantieni l'interfaccia su un solo concetto.
- **Hyrum:** mantieni quell'interfaccia piccola così può restare stabile.

Il pericolo è mescolare Ousterhout con una lettura meccanica di SOLID o Clean Code: questo produce molte classi e funzioni minuscole con interfacce superficiali — l'esatto opposto dei moduli profondi. Ousterhout, con Metz come contrappeso, è l'antidoto.

Tag