DotMDCome rivedere una specifica scritta da un'AI:una checklist prima che l'agente costruisca.
Un agente AI scrive in un minuto una specifica sicura di sé e ordinata. È proprio il pericolo: si legge bene anche quando è sbagliata. Questa checklist mostra cosa cercare prima di dire all'agente di iniziare a costruire.
macOS 14 o successivo. Leggere è gratis; modificare e revisionare si pagano una volta sola.
Risposta rapida
Rivedi una specifica scritta da un'AI come rivedi una pull request: verifica che risolva il problema giusto, poi cerca ciò che manca. Passa in rassegna ambito e non-obiettivi, casi limite, dati e migrazioni, test e rollback, e lascia un commento su ogni passaggio che vuoi cambiare prima che l'agente scriva codice.
- [ ] Scope matches what I asked for
- [ ] Non-goals are listed
- [ ] Edge cases and errors are covered
- [ ] Data and migrations are explicit
- [ ] Tests prove each requirement
- [ ] There is a rollback·
Perché le specifiche AI richiedono una revisione diversa
Chi scrive una specifica tende a lasciare vuoti dove è incerto. Un modello scrive testo fluente su tutto, comprese le parti che ha tirato a indovinare. Così i segnali consueti di una specifica debole, formulazioni vaghe e buchi evidenti, mancano, e i problemi sono nascosti in frasi sicure. Rivedi cercando le cose su cui un buon autore avrebbe fatto domande.
La checklist
-
Ambito: risolve quello che hai chiesto?
Confronta il primo paragrafo con la tua richiesta. Cerca un problema diverso risolto al posto del tuo e funzioni che nessuno ha chiesto.
-
Non-obiettivi: cosa non farà?
Una specifica senza non-obiettivi non ha confini. Aggiungi gli extra che non vuoi.
-
Ipotesi: cosa ha tirato a indovinare?
Cerca "presumibilmente", "probabilmente" e tutto ciò che è affermato come fatto su codice o dati che potrebbe non aver letto. Chiedigli di citare i file.
-
Casi limite: cosa succede quando qualcosa va storto?
Input vuoto, input molto grande, nessun permesso, nessuna rete, due utenti insieme, la stessa azione due volte.
-
Dati: cosa viene salvato, modificato o eliminato?
Campi, formati, chi può leggerli e cosa succede ai record esistenti.
-
Migrazioni: come passano i vecchi dati?
Una modifica allo schema richiede un ordine di passaggi, un piano per un fallimento a metà e un modo per eseguirla due volte in sicurezza.
-
Interfacce: cos'altro viene toccato?
API, schermate, job, codice di altri team. Tutto ciò che la specifica cambia ma non elenca sarà una sorpresa più avanti.
-
Sicurezza e privacy: chi può fare cosa?
Nuovi permessi, nuovi dati che escono dal sistema, segreti nei log.
-
Test: come saprai che funziona?
Ogni requisito dovrebbe corrispondere a un controllo. Se un requisito non si può testare, riscrivilo.
-
Rilascio e rollback: come lo annulli?
Un flag, un rilascio graduale, una via del ritorno. "Correggeremo andando avanti" non è un piano.
-
Domande aperte: chi le decide?
Una specifica onesta elenca ciò che non sa. Se non ce ne sono, sii sospettoso.
Un commento che funziona
Un feedback vago ottiene una riscrittura vaga. Un buon commento di revisione indica un solo passaggio, dice cosa non va e cosa vuoi al suo posto:
> The export runs when the user taps Export.
Missing: what happens with a 2 GB file? Add a limit (R4) and an
error message, and say whether the export can be cancelled.Tieni i commenti separati dal testo della specifica così il file resta pulito, e raggruppali: leggi tutta la specifica una volta, poi commenta, così l'agente riscrive una volta sola invece di dieci.
Il ciclo di revisione
-
Leggila prima per intero
Prima di commentare, assicurati di aver capito tutto il piano.
-
Commenta i passaggi esatti
Un problema per commento.
-
Lascia che l'agente riveda
Corregge ogni commento e produce una nuova versione.
-
Controlla cosa è cambiato, non l'intero documento
Leggi le differenze. Una correzione può rompere qualcosa che andava bene.
-
Approva solo quando la checklist è pulita
Poi lascia che costruisca, in base ai requisiti numerati.
La stessa checklist funziona quando un agente rivede la specifica di un altro. Chiedi al revisore di rispondere a ogni voce con una citazione dalla specifica.
Farlo in DotMD
Puoi fare tutto questo direttamente sulla pagina. In DotMD selezioni il passaggio e scrivi un commento; i commenti restano in DotMD, non nel file. L'agente li corregge e rimanda il documento, e rivedere le modifiche mostra il testo vecchio in rosso e il nuovo in verde, così puoi accettarle una a una. La configurazione è descritta in rivedere le specifiche AI. La lettura è gratuita; vedi i prezzi per le revisioni.
Errori comuni
- Rivedere lo stile, non la sostanza. Una specifica ordinata può comunque essere sbagliata.
- Approvare perché è lunga. Lunghezza non significa copertura.
- Saltare non-obiettivi e rollback, le due sezioni che i modelli lasciano più spesso scarne.
- Correggere il codice invece della specifica. Se il piano è sbagliato, correggilo per primo.
- Nessun secondo sguardo. Dopo che l'agente ha rivisto, controlla il diff.
Domande sulla revisione delle specifiche scritte da un'AI
Come rivedo una specifica scritta da un'AI?
Verifica che risolva il problema giusto, poi cerca ciò che manca: non-obiettivi, casi limite, dati e migrazioni, test e rollback. Commenta ogni passaggio e fai rivedere l'agente prima che scriva codice.
Cosa dovrebbe includere una checklist di revisione delle specifiche?
Ambito, non-obiettivi, ipotesi, casi limite, dati, migrazioni, interfacce, sicurezza, test, rilascio e rollback, e domande aperte.
Un agente AI può rivedere la specifica di un altro agente?
Sì. Dai al revisore la checklist e chiedigli di rispondere a ogni voce con una citazione dalla specifica. Sei sempre tu a decidere cosa accettare.
Perché non leggere direttamente il codice?
A quel punto le decisioni sono prese e costose da cambiare. Un'ipotesi sbagliata costa meno da correggere nella specifica.