Come dico a un agente IA cosa significa «fatto»?

Scrivi cosa significa «fatto» sull'attività stessa, come checklist markdown, prima che l'agente cominci. In Done è il campo acceptance_criteria dell'attività: una riga per condizione verificabile, scritta come «- [ ] i test passano sulla punta del branch». L'agente la legge per prima cosa, spunta ogni riga con check_criterion man mano che la soddisfa davvero, poi chiede il completamento. Spuntare tutte le caselle non chiude l'attività: approva ancora una persona.

Perché una buona descrizione dell'attività non basta?

Una descrizione dice all'agente cosa fare. Non dice com'è un risultato finito, quindi lo decide l'agente, e un agente lasciato a decidere si ferma spesso al primo output plausibile. I criteri di accettazione sono l'altra metà: il traguardo verificabile con cui si giudica il risultato, non altre istruzioni. Le descrizioni degli strumenti di Done tracciano questa linea e chiedono all'agente di confrontare il lavoro con quel traguardo prima di proporre il completamento.

Com'è fatto un criterio che un agente può usare?

• Verificabile da qualcun altro: «i test passano sulla punta del branch», «la pagina carica in meno di 200 ms», «il riepilogo elenca ogni fattura scaduta». «Sembra a posto» non è una condizione.
• Una riga per condizione, così ciascuna si può spuntare da sola e un'attività a metà si legge come 2/4 anziché come niente.
• Scrivilo come checklist markdown, con righe che iniziano con «- [ ] ». Un elenco puntato normale o un paragrafo viene salvato, ma per Done è prosa: l'attività non riporta criteri e l'agente non ha nulla da spuntare.
• Metti il come in notes_for_agent o nella descrizione e lascia ai criteri solo il cosa. Mescolarli fa spostare il traguardo insieme alle istruzioni.

Come riferisce l'agente l'avanzamento rispetto ai criteri?

Chiama get_task, che restituisce i criteri con met, total e l'indice (da zero) di ogni voce, poi check_criterion con l'id dell'attività e quell'indice man mano che soddisfa ogni riga. Con done:false se ne toglie una, e spuntare una casella già spuntata non cambia nulla. Ogni cambiamento reale lascia una riga nella cronologia dell'attività, come «met 'tests pass' (2/4 criteria met)», così vedi come è andato il lavoro senza un commento continuo nel thread. Si può spuntare solo su attività nella corsia dell'agente.

Spuntare tutti i criteri conclude l'attività?

No, ed è voluto. check_criterion è un rapporto di avanzamento; la risposta dice solo all'agente che tutti i criteri sono soddisfatti e che può proporre il completamento. Chiudere è un altro atto. Un'attività non agent_ok passa a pending_approval con propose_completion e aspetta te; solo su un'attività agent_ok l'agente può chiamare complete_task da sé. La checklist rende più facile verificare ciò che l'agente afferma, e la porta di approvazione impedisce che l'affermazione sia definitiva.

L'agente può riscrivere i propri criteri?

Può modificare il campo con update_task, ed è proprio per questo che non conviene fidarsi di una lista tutta spuntata. Sull'attività di una persona può invece usare propose_edit, che mostra la modifica come diff attuale contro proposto, da accettare o scartare campo per campo. In revisione, get_evidence restituisce l'avanzamento dei criteri con ogni ricevuta, deliverable e traccia di esecuzione, più la cronologia delle modifiche e agent_edits_since_human, il numero di modifiche dell'agente da quando una persona ha toccato l'attività l'ultima volta. Se non è zero, leggi i criteri prima di fidarti delle spunte: criteri riscritti dopo l'inizio del lavoro non sono il traguardo concordato.