Mon usine logicielle à l'heure de l'IA

Punti chiave

1. ⭐ La griglia delle tre domande — l'insegnamento più riutilizzabile. tutto lo strumentario risponde a "Cosa sa l'agente?" (contesto, memoria, code graph), "Cosa può fare in modo deterministico, senza improvvisare?" (skills, procedure), "Cosa lo ferma quando sbaglia?" (hook, test di architettura, quality gate). Griglia di audit istantanea: applicata a qualsiasi setup agentico, rivela in tre minuti quale delle tre è vuota. Quasi sempre è la terza.
2. ⭐⭐ Il principio guida, da memorizzare alla lettera. "Ciò che conta deve essere eseguibile. Un'istruzione viene seguita 'quasi sempre', ma può essere dimenticata. Un hook o un test viene seguito sempre." Formulato in modo ancora più netto altrove a proposito dei test di architettura: "non può essere aggirato, a differenza di una regola." → Una regola è un'intenzione, un test è una garanzia. È la stessa tesi dell'anello di vincoli in [[sfeir-code-review-anneau-contraintes-2026-07-30]] (pubblicato due giorni dopo) e dell'harness in [[osmani-agent-harness-engineering-2026-04-19]], ma dimostrata su un setup reale e solista, non enunciata come dottrina.
3. Esplicitamente contro il vibe coding. "Il vibe coding come definito da Karpathy era sperimentazione e lasciar fare. Qui parlerò di context engineering." E la conseguente clausola di responsabilità: "Anche se non scrivo il codice, ne sono responsabile e devo mantenerne il controllo." Cfr. [[karpathy-vibe-coding-agentic-engineering-software-3-0-2026-04-29]].
4. La qualità del software non è la qualità del codice. include l'intenzione (perché, per chi) e i quattro rischi di Marty Cagan — Value, Usability, Feasibility, Viability — oltre a prestazioni e affidabilità. È ciò che giustifica il livello 6 (processo di prodotto) e spiega perché una fabbrica del software puramente tecnica manca il punto.
5. Livello 1 — il contesto, e la mossa da copiare. tre livelli separati per momento di caricamento. CLAUDE.md alla radice (architettura, convenzioni trasversali, indice delle spec) → permanente e breve; .claude/rules/.md → condizionale, attivato da un frontmatter paths: (la regola Kotlin si carica solo quando si tocca api//); .agents/.md → contesto non tecnico (posizionamento di prodotto, persona, tono). ⭐ La regola, vista per intero, è una tabella di instradamento: non contiene le procedure, elenca nove skill con il compito che attiva ciascuna, da aprire solo quando serve. "Se l'IA non sta facendo una modifica dello schema, non ha senso aprire la skill db-migration." → Il contesto permanente porta l'indice, non il contenuto.*
6. ⭐ Un vincolo a lungo termine codificato come contesto e come test. — il miglior esempio del testo: l'autore prevede di rendere open source parte del codice. La regola "il codice destinato all'open source non deve mai dipendere da codice proprietario" è scritta nelle regole e verificata da un test di architettura (nessun file sul lato "open" fa riferimento al lato "proprietario"; ogni file di produzione appartiene all'uno o all'altro). "Scrivere un vincolo futuro nel contesto evita di pagarne il prezzo con una riscrittura più tardi." → Una decisione che non esiste ancora può già essere garantita meccanicamente.
7. La frase che uccide il prompt magico. "Non serve a nulla dire a un'IA di 'scrivere codice di qualità', non ha senso. Bisogna esplicitare i propri vincoli." Accompagnata da una rara onestà: "Un vincolo è specifico a un progetto e a una persona… Usare i feature flag non è meglio né peggio, è solo una mia preferenza."
8. Livello 2 — le skill. "una procedura scritta una volta, rieseguita identicamente." Criterio di esistenza: la terza ripetizione. Una trentina, suddivise in sei famiglie (backend, frontend, dati, ciclo di prodotto, operazioni/runbook, scrittura). Due lezioni: le skill di "procedura multi-file" sono le più redditizie ("aggiungere un blocco all'editor di contenuti tocca tre superfici di rendering; senza una skill, l'agente ne dimentica sistematicamente una"), e le skill di "documentazione aggiornata" sono critiche su codice in rapida evoluzione. ⚠️ Sfumatura operativa: "Questo caricamento automatico a volte può fallire. In quel caso, bisogna chiedere esplicitamente di usare la skill." Cfr. [[shihipar-claude-code-lessons-building-skills-2026-06-03]], [[agent-skills-anthropic-2025-10-16]], [[vincent-superpowers-agentic-skills-framework-github-2026-04-02]].
9. I sub-agent, in declino. riservati a compiti "che generano molta lettura senza molta decisione" (audit, esplorazione ampia, redazione di documentazione) — "consumano il proprio contesto e restituiscono una conclusione, non un dump di file." Ma: "li uso sempre meno, i modelli recenti fanno da soli una delega abbastanza mirata." Segnale di evoluzione: una pratica di strumentazione resa in parte obsoleta dal modello.
10. ⭐ Livello 3 — GitNexus, lo strumento più interessante del setup. il repository viene indicizzato come un grafo (simboli, relazioni, flussi di esecuzione), il che permette impact(symbol) prima di modificare (raggio d'impatto, chiamanti, livello di rischio), detect_changes() prima di committare ("ho toccato solo quello che intendevo toccare?"), cercare un flusso di esecuzione invece di fare grep sul nome di una funzione, e rinominare tramite il call graph invece del find-and-replace. E la giustificazione, che conta più dello strumento in sé: "Il vero problema non è la velocità, è rilevare tutti gli effetti collaterali di una modifica." → ripresa nella regola n°4: "Misurare gli impatti prima e dopo la modifica. Vogliamo evitare l'effetto '1 bug corretto, 10 introdotti'." Da confrontare con il contesto strutturato a code-graph rispetto al RAG vettoriale — la stessa famiglia di argomentazione del risultato di Compare the Market citato in [[sfeir-code-review-anneau-contraintes-2026-07-30]].
11. MCP, con una riserva sul costo. "cerco di evitare gli MCP che consumano più contesto, ma ne ho comunque alcuni" — IDE JetBrains (build, inspection, refactoring, ricerca indicizzata), GitNexus, servizi di business (pagamento, monitoraggio), database, browser. L'MCP è trattato come una spesa di contesto da giustificare, non come un dato di fatto.
12. Livello 4 — gli hook: la definizione che conta. "script attivati dall'harness dell'agente, non dall'agente stesso." Due usi in produzione: prima di una chiamata shell, rifiutare la build nativa e reindirizzare verso la build dell'IDE (più veloce, errori strutturati) spiegando il fallback; dopo la scrittura di un file, eseguire il formatter/linter. Altri usi citati: bloccare le modifiche ai file generati, richiedere un test per ogni nuovo modulo, vietare un pattern pericoloso.
13. ⭐ Pattern linting — la distinzione da tenere a mente. ESLint per la sintassi, ast-grep per le decisioni di architettura (esempio: vietare qualsiasi chiamata fetch che aggiri il client OpenAPI), typecheck per la tipizzazione. → Una decisione di architettura può diventare una regola di lint. È l'anello mancante tra "abbiamo deciso" e "viene applicato", e costa poche righe.
14. Livello 5 — il gate. push su main → quality gate (lint → pattern lint → typecheck → test) → build immagine docker → push sul registry → webhook di deployment. Il punto strutturale: il job di deployment ha un needs: sul job di qualità. "Niente va in produzione senza passare il gate. È essenziale come regola generale, ancora di più per il codice prodotto automaticamente." Cinque fasi di test: unitari (in modo massiccio), integrazione con container usa e getta ("database e broker reali, niente mock"), architettura, componenti front-end, end-to-end solo sui percorsi critici. Cfr. [[williams-adlc-3-tests-are-the-spec-2026-06-12]] e [[williams-adlc-2-two-human-gates-2026-06-12]].
15. Livello 6 — il processo di prodotto, e il passaggio che tutti dimenticano. spec numerate (una per dominio funzionale, indicizzate nel contesto permanente) incorniciate da due skill — una per redigere la spec e il suo piano, una per chiuderla aggiornandola con ciò che è stato effettivamente realizzato. "Senza di essa, le spec diventano obsolete entro sei mesi," e come regola finale: "La documentazione delle spec muore se la sua chiusura non fa parte del processo." ⭐ La chiusura è la parte del ciclo di documentazione che quasi mai esiste altrove.
16. Regola anti-allucinazione per le spec. "Se una spec non è chiara o è incoerente con il sistema esistente, l'agente deve chiedere, non indovinare." Una singola riga di contesto che affronta la modalità di fallimento più costosa dello sviluppo agentico.
17. La consegna a tappe, e la sua motivazione. la spec è pensata per essere consegnata a tappe protette da un feature flag, "mi permette di fare diverse piccole sessioni di implementazione invece di una grande sessione, che tende a degradare in qualità una volta che si riempie troppo." → Qui, la scomposizione del prodotto è dettata dal degrado del contesto lungo, non dalla gestione di progetto. Distinzione utile: feature flipping (Unleash — attivare/disattivare senza ridistribuire: rollout, kill switch, manutenzione) contro gating (tabella di configurazione + servizio — restrizione per contratto cliente o piano). Due meccanismi, due esigenze, e una skill affinché gli agenti non li confondano.
18. Da dove iniziare (ordine indicato, ed è un buon ordine). (1) prima di tutto il quality gate, se non esiste già; (2) un CLAUDE.md leggero che descrive l'essenziale e il perché; (3) regole aggiunte in modo incrementale per i pattern di architettura importanti; (4) skill non appena una procedura si ripete; (5) CLI e MCP per gli strumenti principali. ⚠️ Avvertenza di sicurezza: "qualsiasi skill, MCP o codice importato dall'esterno deve essere esaminato con attenzione. Sono dipendenze che possono costituire vettori di attacco." Da confrontare con la superficie d'attacco agentica descritta in [[clinton-anthropic-secure-ai-native-sdlc-2026-07-21]].
19. ⚠️ Limiti vissuti — la sezione che rende credibile la pagina. 1. L'obsolescenza di una regola non è misurabile. "A metà 2025, 'scrivi un test per ogni nuovo servizio' aveva senso. Oggi è rumore e Claude lo fa naturalmente… non ho modo di misurare o sapere se una vecchia regola sia diventata obsoleta." → Il contesto accumulato decade al ritmo dei modelli, e nulla traccia questo decadimento. È la vera lacuna metodologica del settore, e qui viene nominata senza soluzione. 2. Il rabbit hole. Una regola boyscout.md ("lasciare sempre il codice un po' migliore… segnalarmi i miglioramenti") produce "sessioni infinite" e sovraccarico cognitivo. Correzione prevista: instradare questi rilevamenti in una lista TODO e spostare la manutenzione in un workflow separato e parzialmente automatizzato. → Una buona istruzione di miglioramento continuo diventa un generatore di deriva quando l'agente non si ferma da solo. 3. Nessun packaging. Skill e regole vengono copiate e incollate da un progetto all'altro, a volte dipendenti dalla macchina. Manca: un modo per pacchettizzarle per il deployment e centralizzare la manutenzione. 4. Dipendenza da Claude, giudicata un "rischio moderato" ("tutto l'ecosistema sta salendo di livello"), con l'interesse a testare modelli open-weight — bloccato dall'hardware. E l'IDE è diventato poco adatto: "uso ancora IntelliJ ma non lo trovo più adatto alla nostra epoca. Non ho ancora visto un'alternativa interessante."
20. ⭐⭐ L'ammissione di fondo, da citare alla lettera. "Le ultime versioni di Opus sono sempre più autonome… È al limite dell'inquietante, e più rigoroso del 99% degli esseri umani. Diciamocelo, divento sempre meno utile nelle fasi di implementazione, ma non voglio perdere il controllo del codice prodotto. Sono diviso tra la soddisfazione di avere una fabbrica del software sempre più efficiente e il rischio di perdere la conoscenza." → È esattamente il comprehension debt di [[osmani-cognitive-surrender-comprehension-debt-2026-05-05]], espresso dall'interno da qualcuno che ha costruito l'harness più completo possibile e osserva che l'harness non risolve questo problema specifico. Il setup garantisce che il codice sia corretto; non garantisce che l'essere umano lo capisca ancora. La domanda aperta del testo: "devo trovare un modo per verificare a posteriori le scelte progettuali, per fare mio il risultato."
21. ⚠️ Portata da non sopravvalutare. un setup solista, su prodotti personali, con un unico decisore. Nessun coordinamento multi-sviluppatore, nessuna peer review, nessun vincolo di compliance o audit — il livello "chi convalida" è occupato da una sola persona, che è anche l'autrice delle regole. Ciò che si trasferisce a un contesto aziendale: la griglia delle tre domande, il principio dell'eseguibilità, la chiusura delle spec, il pattern linting. Ciò che non si trasferisce tale e quale: l'assenza totale di qualsiasi gate umano diverso da se stessi.
22. Meta / correlati. una dimostrazione pratica di [[osmani-agent-harness-engineering-2026-04-19]] e un cugino diretto di [[sfeir-code-review-anneau-contraintes-2026-07-30]] (pubblicato 2 giorni dopo, stessa tesi: la qualità vive nell'anello di vincoli, non nel codice); lo stesso vocabolario di "fabbrica del software" di [[wescale-usine-logicielle-augmentee-juge-strategique-2026-05-03]], ma su scala individuale; si contrappone al vibe coding di [[karpathy-vibe-coding-agentic-engineering-software-3-0-2026-04-29]]; converge con [[klaassen-teach-ai-think-senior-engineer-every-2025-11-07]] sull'esplicitazione dei vincoli; da leggere insieme a [[shihipar-claude-code-lessons-building-skills-2026-06-03]] sulle skill e [[williams-adlc-3-tests-are-the-spec-2026-06-12]] sui test.