Come scrivere un blog tecnico con l’AI: ricerca, verifica del codice e revisione umana

Un articolo tecnico contiene tre blocchi di codice, ma nessuno è stato eseguito. I lettori copiano gli esempi, ricevono errori e scoprono che il problema non era lo stile: fatti e codice non avevano superato alcun controllo.

Una bozza AI può sembrare completa mentre indovina versioni, argomenti e formati di output. Un progetto dichiara "type": "module" nel package.json, ma l’esempio usa direttamente require. Un altro testo afferma che GitHub Actions offre “2.000 minuti al mese” senza spiegare che il numero è la quota di uno specifico piano per repository privati.

Scrivere un blog tecnico non significa affidare un tema a un modello e rifinire la risposta. Prima si raccolgono fonti e prove eseguibili, poi l’AI organizza la spiegazione e infine una persona controlla fatti, codice e stile. Il flusso seguente assegna un controllo e un responsabile a ogni fase per mantenere affermazioni corrette, esempi eseguibili e conclusioni riproducibili.

Fare ricerca prima di chiedere una bozza all’AI

Che cosa va ricercato e che cosa può scrivere l’AI?

La prima decisione separa i fatti che devono arrivare dall’esterno dalle parti che il modello può organizzare.

La ricerca si divide in tre casi.

Versioni, modifiche ai campi API, limiti documentati, prezzi o quote e configurazioni di sicurezza vanno ricercati prima. Un errore può bloccare il progetto di un lettore o generare costi imprevisti. La documentazione attuale di Next.js usa, per esempio, la chiave turbopack, mentre le versioni da 13.0.0 a 15.2.x usavano experimental.turbo. Scrivere soltanto “configura Turbopack” senza indicare la versione può far copiare una configurazione incompatibile.

L’AI può redigere concetti generali, uso dei framework, buone pratiche ed errori comuni, ma una persona deve verificarli. Una spiegazione sui React hooks può sembrare corretta; il numero delle regole, le convenzioni di denominazione e le differenze tra versioni vanno confrontati con la documentazione ufficiale.

L’organizzazione strutturale, l’editing dello stile e la formattazione possono essere affidati all’AI. Riformulare una spiegazione o riunire paragrafi collegati normalmente non richiede ulteriore ricerca.

Confronto:

Tipo di ricerca	Contenuto tipico	Intensità del controllo	Fase
Ricercare prima	Versioni, campi API, prezzi o quote, sicurezza	Alta: estrarre dalla documentazione ufficiale e segnare [VERIFY]	Preparare durante la pianificazione e ricontrollare il giorno della scrittura
Bozza AI + revisione	Concetti generali, framework, buone pratiche	Media: confrontare la bozza con la documentazione ufficiale	Scrivere e verificare durante la revisione
Scrittura AI	Struttura, stile, formattazione	Bassa: nessuna ricerca aggiuntiva	Completare durante la scrittura

Albero decisionale:

Incontri un contenuto di tipo X
  ↓
Riguarda versione, API, prezzo o sicurezza?
  ├─ Sì → Estrarre dalla documentazione ufficiale, segnare [VERIFY] e ricontrollare il giorno della scrittura
  └─ No → Riguarda una regola tecnica o una buona pratica?
      ├─ Sì → L’AI redige; la revisione confronta con la documentazione ufficiale
      └─ No → L’AI organizza la spiegazione

Come inserire i risultati della ricerca nell’input dell’outline?

Dopo la ricerca, i risultati vanno inseriti nell’outline input affinché la fase di scrittura possa citarli direttamente.

Da research.md si estraggono le fonti ufficiali ad alta affidabilità contrassegnate come high, come le indicazioni di Google Search Central sugli helpful content, l’esempio ufficiale di CI Node.js per GitHub Actions e la documentazione di Astro Content Collections.

I fatti variabili ricevono il marcatore [VERIFY]: “La quota inclusa di GitHub Actions per i repository privati dipende dal piano dell’account [VERIFY]” oppure “Controllare se la versione Node di destinazione è ancora supportata [VERIFY]”.

Le schede delle fonti, gli output dei comandi e gli esiti della revisione entrano nei campi source_cards e risk_notes dell’outline input:

{
  "source_cards": [
    {
      "url": "https://developers.google.com/search/docs/fundamentals/creating-helpful-content",
      "type": "official/docs",
      "confidence": "high",
      "usable_info": "Il contenuto deve offrire informazioni originali e una descrizione completa, senza dipendere soprattutto dall'automazione su larga scala"
    }
  ],
  "risk_notes": [
    {
      "fact": "Quota gratuita di GitHub Actions",
      "status": "[VERIFY]",
      "check_date": "2026-06-24",
      "source": "https://docs.github.com/en/billing/managing-billing-for-github-actions"
    }
  ]
}

Una volta pronti i marcatori, la fase di scrittura non deve ripetere tutta la ricerca: ricontrolla solo i fatti variabili segnalati.

Verificare gli esempi di codice: sembrare corretti non basta

Quattro casi di verifica del codice

Gli esempi di un articolo tecnico spesso sembrano funzionare, ma falliscono quando vengono eseguiti. Quando il lettore copia il codice e incontra un errore, la fiducia nell’articolo scompare.

La verifica del codice si divide in quattro casi.

L’esecuzione locale comprende comandi di installazione, esempi di configurazione e script semplici, come npm install, git clone e modifiche ai file di configurazione. Questi comandi vanno eseguiti localmente e l’output va registrato.

I test CI comprendono build, test e dipendenze dell’ambiente, come npm ci, npm run build e npm test in GitHub Actions. Il CI è adatto perché rende l’ambiente coerente.

La gestione delle versioni comprende Node, dipendenze e versioni API, come .nvmrc, package.json e modifiche agli endpoint. Il testo deve indicare le versioni e spiegare le differenze. La coerenza dell’ambiente riguarda le differenze fra sviluppo, produzione e CI, come variabili, immagini Docker e sistemi operativi. Dichiarare l’ambiente di esecuzione evita errori in condizioni diverse.

Confronto:

Caso di verifica	Contenuto tipico	Metodo	Prova obbligatoria
Esecuzione locale	Installazione, file di configurazione	Eseguire in locale	Testo dell’output o schermata
Test CI	Build e test	GitHub Actions o altro CI	Log CI o schermata del risultato
Gestione delle versioni	Node e dipendenze	Comando di versione	Output di node --version + versione dichiarata
Coerenza dell’ambiente	Variabili e Docker	Test in più ambienti o dichiarazione esplicita	Ambiente + condizioni

Come registrare le prove di esecuzione?

Ogni esempio di codice deve avere una prova di esecuzione; scrivere solo “ha funzionato” non basta. I comandi e gli output seguenti mostrano il formato di una registrazione e non costituiscono una prova reale riutilizzabile. In un altro articolo vanno sostituiti con versioni e log reali del progetto di destinazione.

Esempio di comandi per una CI Node.js:

# Ambiente locale: macOS + Node 18.20.0 LTS
$ node --version
v18.20.0

# Ambiente CI: GitHub Actions
$ npm ci
added 245 packages in 12s

$ npm run build
✓ Built in 1.23s

$ npm test
✓ 12 tests passed

Confronto:

✅ Corretto: fornire una schermata o il testo dell’output, indicando versione e punti rilevanti.

❌ Errato: scrivere “esecuzione riuscita” senza alcuna prova.

Per i blocchi di codice, usare fenced code block e un identificatore di linguaggio, come bash o typescript. Per output lunghi, usare una sezione comprimibile o mostrare solo le parti importanti. Nei comandi in più passaggi, indicare l’ambiente, per esempio locale, CI o Docker. Nei controlli di versione, includere l’output di node --version o npm --version.

Esempio:

# Ambiente di esecuzione: macOS + Node 18.20.0
$ npm install
added 124 packages in 8s

$ node --version
v18.20.0

Se l’output è lungo, mostrare soltanto la parte essenziale:

$ npm run build
✓ Built in 1.23s
  ├─ dist/index.html
  ├─ dist/assets/index.js
  └─ dist/assets/index.css

La documentazione ufficiale di GitHub raccomanda fenced code block ed evidenziazione della sintassi in Creating and highlighting code blocks. Un blog tecnico dovrebbe rispettare lo stesso standard, non mascherare il codice come testo narrativo.

La revisione umana controlla fatti, codice e struttura

Revisione dei fatti: versioni, parametri e prezzi devono essere tracciabili

La revisione umana comprende tre livelli: fatti, codice e struttura. Considerarla soltanto una correzione delle parole lascia passare versioni errate, parametri non validi e conclusioni che non corrispondono al codice.

Il nucleo della revisione dei fatti è la tracciabilità. Ogni versione, campo API, argomento di comando, valore di configurazione, prezzo, quota e data di rilascio deve essere confrontato con documentazione ufficiale o esecuzione reale.

Checklist:

Elemento	Come revisionare	Segnale di errore	Esempio corretto
Versione	Confrontare con release o documentazione ufficiale	Versione inesistente o funzione descritta male	Link ufficiale + output di node --version
Argomento del comando	Confrontare con la documentazione CLI	Argomento inesistente o formato errato	Link ufficiale + output reale
Campo API	Confrontare con la documentazione API	Campo inesistente o tipo errato	Link ufficiale + richiesta reale
Prezzo o quota	Confrontare con la pagina ufficiale	Prezzo errato o condizione pubblico/privato assente	Link ufficiale + condizioni d’uso
Data di rilascio	Confrontare con annuncio o blog ufficiale	Data errata o evento inesistente	Link all’annuncio ufficiale

Esempi errati:

Il progetto dichiara "type": "module" nel package.json, ma il codice usa direttamente require di CommonJS senza passare a .cjs né spiegare il confine tra moduli.

L’articolo dice che “GitHub Actions ha solo 2.000 minuti al mese”, senza spiegare che i runner standard ospitati da GitHub sono gratuiti nei repository pubblici e che i minuti inclusi nei repository privati dipendono dal piano.

Esempi corretti:

“Node 18 supporta sia ES modules sia CommonJS; .mjs, .cjs e il campo type di package.json influenzano l’interpretazione dei file. Il registro usa Node 18.20.0 e conserva l’output di node --version (fonte: documentazione ufficiale Node.js).”

“Al 26 luglio 2026, i runner standard ospitati da GitHub sono gratuiti nei repository pubblici. I repository privati ricevono minuti in base al piano, per esempio 2.000 con GitHub Free e 3.000 con GitHub Pro (fonte: GitHub Actions billing).”

Revisione del codice: esecuzione, output e ambiente

La revisione del codice controlla tre punti: il comando viene eseguito, l’output corrisponde al testo e l’ambiente è dichiarato.

Checklist:

Elemento	Come revisionare	Segnale di errore	Esempio corretto
Esecuzione del comando	Eseguire in locale o CI	Errore o dipendenza assente	Log o schermata
Corrispondenza dell’output	Confrontare con il testo	Output diverso dalla descrizione	Testo e output coerenti
Ambiente	Controllare la dichiarazione	Versione Node o sistema assente	Node 18.20.0 + macOS
Versione della dipendenza	Controllare package.json	Versione diversa da quella descritta	package.json o output della versione

Esempi errati:

Il testo dice che “la build ha generato tre file”, ma l’output reale di npm run build ne mostra cinque.

Il testo dice che “ha funzionato in locale”, ma l’esempio dipende da Docker e non dichiara la differenza.

Esempi corretti:

“npm run build ha generato tre file: index.html, index.js e index.css”, come mostra l’output.

“L’esempio è stato provato su macOS con Node 18.20.0. Linux, Windows o un’altra versione possono richiedere modifiche ai percorsi.”

Revisione di struttura e stile: H2/H3, link interni e residui AI

Questo livello controlla che H2/H3 corrispondano all’outline, che i link interni siano nelle posizioni previste e che le formule vaghe tipiche dell’AI siano state rimosse.

Checklist:

Elemento	Come revisionare	Segnale di errore	Esempio corretto
Coerenza H2/H3	Confrontare con outline.md	Titolo rimosso o aggiunto	Registrare il motivo della modifica
Link interni	Confrontare con il piano	Link assente o anchor text errato	Inserire secondo il piano
Residui AI	Confrontare con anti-ai-words.json	Formula d’epoca o promessa vaga	Sostituire con un fatto concreto o eliminare

Il file anti-ai-words.json del progetto definisce due categorie di espressioni da evitare. Durante la revisione si sostituiscono o eliminano generalizzazioni, attribuzioni vaghe e promesse eccessive.

Esempi errati:

Aprire con una formula generica sul periodo storico.

Promettere “un’analisi completa” senza specificare che cosa verrà verificato.

Esempi corretti:

Eliminare la formula e iniziare dal problema: “Quando si scrive un blog tecnico con l’AI, la prima domanda è quali fatti debbano arrivare dall’esterno.”

Sostituire la promessa vaga con un criterio concreto: “Questo articolo presenta un flusso eseguibile di scrittura, verifica e revisione.”

Chiudere il processo con il QA prima della pubblicazione

Checklist di QA prima della pubblicazione

Finire il testo non significa poterlo pubblicare. Il QA finale controlla marcatori di ricerca, verifica del codice, tracciabilità, struttura, link interni, residui AI e immagini.

Elemento	Come controllare	Condizione di approvazione	Gestione dell’errore
Marcatori di ricerca	Cercare [VERIFY]	Nessun marcatore in sospeso	Tornare alla ricerca
Esempi di codice	Confrontare con i log	Tutti hanno prove di esecuzione	Tornare alla verifica
Fatti tracciabili	Controllare le schede delle fonti	Ogni fatto ha una fonte o un limite dichiarato	Aggiungere la fonte o eliminare l’affermazione
Struttura	Confrontare con outline.md	H2/H3 coerenti o modifica spiegata	Aggiornare outline o registrare il motivo
Link interni	Confrontare con il piano	Tutti inseriti con anchor text corretto	Aggiungere link o modificare il piano
Residui AI	Controllare anti-ai-words.json	Nessuna espressione vietata	Sostituire o riscrivere
Immagini	Controllare inventario e percorsi Markdown	Tutti i percorsi sono validi e processati	Caricare l’immagine o correggere il percorso

Stati:

✅ Approvato: si può pubblicare

⚠️ In sospeso: serve una nuova revisione o una fonte

❌ Errore: occorre riscrivere o tornare a ricerca/verifica

Controllare un elemento alla volta e segnare subito lo stato quando emerge un problema. Solo dopo l’approvazione di tutti gli elementi lo stato della task diventa “pronto per la pubblicazione”.

Dove tornare quando il QA trova un problema?

Il problema deve tornare alla fase responsabile, non essere ignorato.

Un errore nei fatti torna alla ricerca: si aggiunge documentazione ufficiale, si eliminano affermazioni non tracciabili e si ricontrollano i fatti variabili.

Un errore nel codice torna alla verifica: si riesegue il comando, si registra l’output, si aggiorna l’esempio e si dichiara l’ambiente.

Una differenza strutturale richiede l’aggiornamento dell’outline o una motivazione, indicando quali H2/H3 sono stati rimossi o aggiunti.

Un link mancante torna alla cluster map e all’inventario del sito, usando un anchor text descrittivo invece di “clicca qui”.

I residui AI tornano all’editing con anti-ai-words.json; se non esiste una sostituzione concreta, il paragrafo va riscritto.

Esempio:

Il QA rileva che la quota GitHub Actions non distingue fra pubblico e privato
  ↓
Segnare come errore
  ↓
Tornare alla ricerca
  ↓
Aggiungere la fonte ufficiale di fatturazione e le condizioni
  ↓
Eseguire di nuovo il QA

Il percorso di ritorno rende visibile la responsabilità. Chi esegue la revisione finale non deve ereditare una modifica priva di spiegazione.

Sette segnali che l’articolo si è allontanato dai fatti

I sette segnali

Lo scostamento dai fatti si accumula. Questi segnali aiutano a trovarlo prima della pubblicazione.

Segnale 1: affermazione senza fonte. Il testo dice “ultima versione”, “raccomandazione ufficiale” o “buona pratica” senza un link. Per esempio, afferma che una chiave Turbopack funziona in tutte le versioni di Next.js senza citare la documentazione.

Segnale 2: codice non eseguito. Non esistono output o log, solo “funziona”.

Segnale 3: versione o parametro classificato male. La versione può esistere, ma la linea di rilascio o lo stato di supporto è errato; anche parametri ed endpoint cambiano. Node 20.1.0 era Current, non LTS.

Segnale 4: ambiente incoerente. La prova indica un ambiente, ma il comportamento è stato verificato in un altro.

Segnale 5: conclusione non riproducibile. Il testo afferma un miglioramento senza metodo, dati o passaggi.

Segnale 6: link interno interrotto. L’articolo punta a /posts/ai/ai-xxx, ma il percorso non esiste.

Segnale 7: una frase vaga nasconde l’assenza di prove. “Analisi completa” sostituisce una fonte o un risultato.

Esempi:

Segnale	Esempio errato	Problema
Senza fonte	“Questa chiave Turbopack funziona in tutte le versioni di Next.js”	Nessuna documentazione ufficiale
Codice non eseguito	“Esegui npm install; funziona”	Nessuna prova
Versione errata	“Node 20.1.0 LTS”	20.1.0 era Current
Ambiente incoerente	Il registro indica un vecchio ambiente e la verifica avviene in un altro	Versione e ambiente non coincidono
Conclusione non riproducibile	“Le prestazioni migliorano molto”	Nessun metodo o dato
Link interrotto	Link a /posts/ai/ai-xxx	Percorso inesistente
Residuo AI	“Analisi completa della scrittura con AI”	Promessa vaga

Quando compare un segnale, segnare [VERIFY] e riportarlo alla fase responsabile.

Un’affermazione senza fonte torna alla ricerca, il codice non eseguito alla verifica e una versione errata al release ufficiale. Un ambiente incoerente richiede le condizioni corrette o l’eliminazione dell’affermazione. Una conclusione non riproducibile richiede metodo, dati e passaggi, oppure va rimossa. Un link interrotto usa un percorso reale. Una frase vaga diventa concreta o viene eliminata.

Il ritorno deve essere immediato. Altrimenti piccole incertezze si accumulano e producono un articolo impossibile da tracciare.

Scrivere onestamente senza un ambiente completo

Tre modi onesti

A volte manca un servizio a pagamento, un cluster complesso, un sistema operativo o un hardware specifico. Non si devono inventare prove. Esistono tre alternative.

La prima è dichiarare condizioni e limiti. Si indicano la versione provata e le possibili differenze, oppure che è stato testato solo il piano gratuito. Esempio: “L’esempio è stato verificato soltanto con Node 18.20.0; altre versioni possono comportarsi diversamente.”

La seconda è fornire una verifica alternativa. Può essere una riproduzione minima, dati Mock o un issue ufficiale. Esempio: “Non era disponibile un cluster Kubernetes; viene fornita soltanto una riproduzione minima che deve ancora essere provata in un cluster reale.”

La terza è ammettere ciò che non è stato verificato. Si scrive “Questa conclusione sulle prestazioni non è stata riprodotta nell’ambiente attuale” oppure si elimina l’affermazione.

Confronto:

Situazione	Formulazione ingannevole	Formulazione onesta
Differenza di versione	“Tutte le versioni lo supportano”	“Verificato con Node 18.20.0; altre versioni possono variare”
Differenza di ambiente	“Ha funzionato in locale”	“Provato su macOS con Node 18.20.0; Linux, Windows o un’altra versione possono richiedere modifiche”
Servizio a pagamento	“È gratuito”	“È stato provato solo il piano gratuito; le funzioni a pagamento possono variare”
Affermazione non verificata	“Le prestazioni migliorano molto”	“L’ambiente attuale non ha riprodotto questa conclusione sulle prestazioni”

Esempi validi:

“Il test ha usato il piano gratuito di Cloudflare Workers, che al momento include 100.000 richieste al giorno. Le condizioni a pagamento possono cambiare; controlla la pagina ufficiale dei prezzi.”

“Non era disponibile un cluster Kubernetes. La riproduzione minima deve ancora essere verificata in un cluster reale considerando limiti dei Pod e configurazione di rete.”

“Non esistono misurazioni su un progetto di grandi dimensioni, quindi non si fanno affermazioni sulle prestazioni di build di Turbopack. Misura una baseline e un confronto nel tuo progetto.”

Esempi non validi:

“Cloudflare Workers è gratuito.” Manca la quota.

“Funziona in ogni ambiente.” Manca l’ambiente.

“Le prestazioni migliorano molto.” Mancano metodo e dati.

Google Search Central raccomanda informazioni originali, spiegazioni complete e analisi utili in Creating helpful, reliable, people-first content. Spiegare un limite non abbassa lo standard: distingue ciò che è stato verificato da ciò che richiede ancora una prova.

Decidere quando pubblicare e quando rivedere la bozza

Albero decisionale per la pubblicazione

La decisione non dipende dal numero di parole né dall’aspetto finito. Ricerca, verifica, revisione e QA devono passare.

Ricerca: se tutte le fonti affidabili sono disponibili e i dati variabili sono segnati, si passa alla verifica. Se manca una fonte centrale, si continua la ricerca.

Verifica: se tutti gli esempi funzionano, si passa alla revisione. Gli esempi falliti vengono corretti o eliminati. Quelli non verificabili dichiarano i limiti o vengono rimossi.

Revisione umana: se i fatti sono tracciabili, si passa al QA. Un’affermazione senza fonte viene documentata o eliminata. Una modifica strutturale spiegata può procedere; uno scostamento senza spiegazione torna alla pianificazione.

QA prima della pubblicazione: se tutto passa, l’articolo procede. Un elemento in sospeso richiede un nuovo controllo e un errore torna alla fase responsabile.

Un articolo procede quando ricerca e aggiornamento sono completi, il codice ha prove, la revisione conferma fatti e struttura, i residui AI sono stati rimossi e il QA passa.

Se manca una fonte, un registro, un link interno o la pulizia dello stile, il lavoro non è finito.

Una versione, un parametro, un prezzo o un altro fatto centrale errato, una conclusione principale non riproducibile o una struttura fuori obiettivo senza spiegazione richiedono una revisione.

Ogni fase ha un controllo. L’errore torna alla causa e non raggiunge la pubblicazione.

Priorità:

Prima si correggono o eliminano gli errori fattuali. Seguono gli errori di codice che un lettore potrebbe copiare. Struttura e link hanno priorità inferiore, ma vanno risolti prima della pubblicazione.

Letture correlate

Per fornire all’AI il contesto del progetto, leggi come usare CLAUDE.md per ridurre il codice errato. Per trasformare scrittura e revisione in fasi riutilizzabili, consulta i flussi con Claude Code Skills.

Nel sito trovi anche un flusso di scrittura con l’AI per contenuti generali. Quel testo privilegia la velocità; questo privilegia fatti tecnici, prove di esecuzione e controlli di pubblicazione. I due flussi possono essere combinati.