Indice
Introduzione
Per anni abbiamo misurato la seniority di un tecnico dalla quantità e qualità del codice prodotto. Oggi questo metro di giudizio è miope. Il valore vero non sta più nello scrivere righe di codice, ma nel saper progettare e formalizzare ciò che il codice deve realizzare, così che persone e agenti AI possano eseguirlo in modo affidabile. La svolta è semplice da dire e complessa da praticare: fermiamoci a scrivere documenti prima di scrivere codice.
Questa non è l’ennesima crociata contro i programmatori né l’elogio della burocrazia. È la presa d’atto che l’AI non sostituisce l’intelligenza di progetto: la amplifica se trova input di qualità. Chi guida tecnologia e prodotto deve spostare l’attenzione dall’output del compilatore all’input del sistema: user guide, technical design, piani eseguibili, criteri di accettazione, style guide, test plan, flussi di approvazione. Sono questi i nuovi leverage points.
Cos’è davvero “scrivere documenti” nel 2025
Parlo di documenti operativi, non di whitepaper autoreferenziali. Al minimo comune denominatore:
- User Guide / Intent Brief: perché stiamo costruendo questa cosa, per chi, con quali vincoli e metriche di successo.
- Technical Design: architettura proposta, alternative scartate, decisioni e trade-off espliciti, rischi e piani di mitigazione.
- Working Agreement: definizioni di fatto e di pronto, style guide del codice e della prosa, convenzioni sul naming, checklist di qualità.
- Task Plan: scomposizione in micro-obiettivi ordinati, con dipendenze, criteri di done e test di regressione.
- Context Map: sorgenti informative, repo, dataset, feature flags, ambienti, chi approva cosa.
Questi artefatti sono l’API semantica tra team e agenti AI. Senza, l’AI “indovina”. Con, esegue.
Perché scrivere bene batte scrivere tanto
La collaborazione con agenti AI ha un’implicazione brutale: la prosa guida il codice. Se il documento è ambiguo, l’AI amplifica l’ambiguità. Se è preciso, l’AI moltiplica la velocità.
Tre effetti pratici:
- Velocità cumulativa: documentare l’intento rallenta l’avvio ma accelera tutto il resto. Gli agenti eseguono task in parallelo perché le dipendenze sono esplicite.
- Qualità verificabile: criteri di accettazione scritti ex ante fanno da guardrail agli agenti. Il refactoring non è “creativo”, è misurabile.
- Transfer learning organizzativo: il sapere non resta nella testa del singolo. Le decisioni diventano asset riusabili dal team e dagli agenti in nuovi contesti.
La conseguenza manageriale: premiare chi scrive specifiche eccellenti e ridisegnare i ruoli perché l’ingegneria torni a essere ingegneria, non produzione di ticket.
Dall’AI coding all’Agentic coding
Il salto non è dall’editor alla chat, ma dalla chat alla regia. Gli agenti non completano solo funzioni: leggono contesto, pianificano, invocano tool, verificano output e itera- no. Il flusso diventa ciclico:
- Intent: obiettivi, vincoli, metriche.
- Decomposizione: piano di lavoro con micro-task autonomizzabili.
- Esecuzione strumentata: test prima del codice, strumenti CLI e API per osservabilità.
- Verifica e correzione: loop automatici fino al superamento dei check.
- Promozione e monitoraggio: dall’IDE al runtime, con feedback che rientra in design e piano.
Tradotto: l’AI non è più un autocompleter. È un membro del team che rispetta processi, policy e definizioni di done. Se non li trova, li inventa. Ed è qui che si rompe tutto.
Il terminale è tornato: meno UI, più sostanza
La produttività reale si ottiene nel terminale: controllo fine, integrazione naturale con repo, test, strumenti di deploy e osservabilità. Le interfacce testuali sono l’ambiente più adatto agli agenti perché:
- riducono il rumore dell’interazione;
- espongono comandi idempotenti e tracciabili;
- forniscono un log strutturato perfetto per audit e retry.
Non serve romanticismo unixiano: serve intenzionalità. Un workflow testuale ben progettato batte qualsiasi UI “magica”.
Il nuovo mestiere del programmatore
Il programmatore che “vince” è un progettista-scrittore. Le competenze discriminanti:
- Scrittura tecnica: chiarezza, sintesi, rigore, definizioni misurabili. La prosa è parte dell’architettura.
- Decomposizione: dal problema al grafo di task autonomizzabili. Senza questa abilità, nessun agente scala.
- Pattern di collaborazione con AI: prompt design operativo, gestione del contesto, handoff, verifica e rollback.
- Osservabilità by design: test prima del codice, metriche come parte del contratto, log e tracing come strato nativo.
Chi punta solo sulla manualità di codice puro resterà schiacciato dall’automazione. Chi padroneggia design + documentazione guida gli agenti e quindi il valore.
Architettura della collaborazione: come strutturare i documenti
Pensiamo ai documenti come moduli di un sistema operativo di progetto:
- /intent: user guide, success criteria, anti-goal.
- /design: ADR (Architecture Decision Records), diagrammi, modello dati, threat model.
- /policy: style guide prosa e codice, convenzioni, definizioni di done, controlli di sicurezza.
- /plan: WBS, dipendenze, owner, lead time atteso, check di qualità.
- /tests: suite minima, golden files, harness per i test di integrazione.
- /context: repo, dataset, feature flags, env, credenziali gestite via secret manager.
- /status: diario di bordo automatico, log di tool run e degli agenti, metriche di avanzamento.
Questo layout non è “documentazione”: è infrastruttura cognitiva su cui si appoggiano persone e agenti. Se manca, l’AI si costruisce da sola un’immagine del mondo. E sbaglia.
Come istruire agenti che non vanno fuori strada
Gli errori più comuni nascono da tre carenze:
- Ambiguità: requisiti vaghi che generano soluzioni sbagliate ma plausibili.
- Contesto incontrollato: gli agenti leggono file irrilevanti o vecchi e apprendono pattern errati.
- Assenza di criteri di stop: nessun vincolo esplicito per dire “basta, è abbastanza buono”.
Le contromisure operative:
- Contract-first: definire input, output, precondizioni e postcondizioni dei task. Ogni task è un mini-contratto.
- Context curation: fornire all’agente solo ciò che serve per il task, non l’intero repo. Meglio 20 file giusti che 2.000 a caso.
- Test-driven: chiedere all’agente di scrivere test e farli passare, non solo di scrivere implementazioni.
- Status markdown: il diario di bordo che ogni agente aggiorna, letto da altri agenti e dal team.
- Guardrail di sicurezza: policy per segreti, permessi minimi, approvazioni umane su step sensibili.
Il principio è sempre lo stesso: l’AI esegue ciò che capisce. Se capisce male, è colpa nostra.
L’astrazione successiva: dall’algoritmo all’intento
Abbiamo scalato le astrazioni: dal codice macchina a C, poi a Java e Python, poi ai framework. L’astrazione successiva è l’intento. Non “come” farlo, ma “cosa” ottenere e “a quali condizioni”. Questo non elimina il codice: lo delegittima come output primario. Il codice diventa un dettaglio implementativo generato e mantenuto in gran parte da agenti, sottoposto ai vincoli che noi abbiamo definito.
Per questo i linguaggi “per umani” potrebbero convivere con linguaggi “per agenti”: poco leggibili per noi, ma perfetti per la generazione automatica. Ciò che resta in carico alle persone è la progettazione: modelli mentali, principi architetturali, coerenza di sistema, responsabilità etiche e di rischio.
Operazionalizzare il cambiamento: roadmap per aziende e team
1. Ridefinire i KPI
- % di feature con Intent Brief approvato prima dello sviluppo
- Copertura di ADR per le decisioni architetturali
- % di task con criteri di accettazione misurabili
- Tempo medio “design-to-merge”, non solo “commit-to-deploy”
- Tasso di rework post-release legato ad ambiguità di requisiti
2. Formazione e ruoli
- Portare training sulla scrittura tecnica ai team tecnici e di prodotto
- Introdurre il ruolo di Design Conductor: facilitatore della documentazione e della scomposizione in task agent-ready
- Incentivi legati alla qualità della documentazione, non alla quantità di codice
3. Tooling e processi
- Standardizzare template per Intent, Design, ADR, Test Plan, Status
- Integrare CLI e agenti nel flusso SDLC con policy di approvazione
- Osservabilità by default: log, metriche e tracing richiesti nei criteri di done
- Repository del contesto per ogni iniziativa, separato dal codice applicativo
4. Governance e sicurezza
- Libreria di guardrail riusabili per agenti: gestione segreti, limiti di scrittura, ambienti di prova isolati
- Audit trail degli agenti: chi ha fatto cosa, con quale input e quale output
- Revisione periodica dei modelli di rischio: cosa può andare storto quando un agente “obbedisce” troppo
Cosa cambia per i leader
I leader devono fare una scelta: continuare a misurare la performance come produzione di righe di codice o spostare il baricentro sul progetto, cioè sul pensiero chiaro espresso bene. Nel primo caso, si rimane ostaggi di un’illusione produttiva. Nel secondo, si guida l’adozione dell’AI come forza moltiplicatrice.
Tre mosse immediate:
- Mettere a budget la scrittura: tempo ufficiale per Intent, Design e Test Plan. Se non esiste in agenda, non esiste in realtà.
- Dare l’esempio: i leader devono scrivere i primi Intent Brief delle iniziative strategiche. È una competenza di leadership, non un compito delegabile a valle.
- Pretendere misurabilità: ogni documento termina con criteri oggettivi. Se non sono misurabili, non sono criteri: sono opinioni.
“Meno codice” non significa “meno ingegneria”
L’equivoco più pericoloso è pensare che l’AI tolga complessità. In verità la rialloca: meno tempo nel dettaglio di implementazione, più tempo in progettazione, vincoli, coerenza e verificabilità. È un upgrade, non una scorciatoia. Smettere di scrivere codice è una provocazione utile per ricordarci che senza pensiero scritto, l’AI è inutile.
Conclusione
La domanda che dobbiamo porci non è “quanto codice abbiamo consegnato”, ma “quanto chiara era l’istruzione che ha guidato persone e agenti”. In un mondo dove la capacità esecutiva è quasi infinita, il vantaggio competitivo torna alla chiarezza di intenti. E la chiarezza, nel nostro mestiere, passa dalla scrittura.
Chi impara a progettare sulla pagina prima che sull’editor guiderà i team, gli strumenti e l’AI. Il resto inseguirà il log degli errori.
