Come verifico che un agente autonomo ha fatto quello che gli ho detto

Perché la verifica non è il log di esecuzione

Ho 5 job Cloud Run in produzione da febbraio 2026. Per tre giorni, uno di questi job diceva SUCCESS nel build log. Il reel non usciva. Non me ne sono accorto subito: il log diceva tutto ok, la coda sembrava vuota, il publish non arrivava.

Il problema non era il codice: era che il mio unico criterio di verifica era "il job ha girato". Questo non dice nulla. Un job può girare e non produrre l'output atteso. Può girare e scrivere in un percorso sbagliato. Può girare e chiudersi con exit code 0 su una riga che non era quella giusta.

Da quell'incident ho formalizzato 3 criteri che ora metto in ogni job autonomo.

1) Il risultato atteso scritto nel system prompt, non nel codice

Quando istruisco un agente o un job autonomo, la prima regola è che il criterio di successo deve stare nel system prompt, non essere implicito nel codice.

Non scrivo "esegui il task". Scrivo:

Compito: scrivi il file reel-queue/<slug>.json nel repo ops.
Criterio di completamento: il file esiste in reel-queue/ con il campo slug corretto.
Se non riesci a completarlo: scrivi nella sezione ## instagram-publish di system-signals.md il motivo e la data.

Questo fa due cose:

1. Rende il criterio verificabile in modo esterno (posso controllare che il file esiste).
2. Obbliga il job a dichiarare esplicitamente il suo output, non solo a "girare".

La differenza tra "il job ha finito" e "il file è lì" sembra piccola. In produzione è la differenza tra 3 giorni di silenzio e un alert immediato.

2) Ogni azione lascia un commit

Per i job che operano su un repository, uso una regola semplice: ogni azione significativa lascia un commit su git. Non un log interno, non un file di stato nascosto: un commit visibile con messaggio descrittivo.

Questo funziona come audit trail automatico:

• Se guardo git log --oneline e non vedo il commit del giorno, so che il job non ha girato o ha fallito prima della fase di commit.
• Il messaggio del commit è standardizzato: reel: <slug> o evening: <slug>. Se il pattern cambia, so che qualcosa si è rotto nel flow di output.
• Git è il sistema più affidabile che ho per "questa cosa è successa": è immutabile, con timestamp, e non dipende da nessun database esterno.

Alcuni job non operano su git. Per questi uso un pattern alternativo: il job scrive una riga con timestamp nel bus (system-signals.md). Stessa logica: ogni esecuzione riuscita lascia una traccia esplicita.

3) Il silenzio è una fail loggata, non un ok

Questo è il criterio più importante, e quello che ho formalizzato per ultimo.

In un sistema autonomo, il silenzio non è neutralità: è un segnale ambiguo. Se un job non scrive nulla, non so se ha avuto successo o se si è fermato prima di produrre output. Entrambe le situazioni sembrano uguali dall'esterno.

La regola che ho implementato: ogni job autonomo ha un obbligo di segnalazione esplicita nei casi di fallimento.

Nel system prompt scrivo:

Se non riesci a completare il compito per qualsiasi motivo (file non trovato,
errore di scrittura, gate fallito, dato mancante): scrivi nel bus la riga:
<data> | skip: <motivo breve> | <tuo nome job>
Non terminare silenziosamente.

Se il job tace, ho due possibilità:

1. Ha fatto tutto e non c'era niente da segnalare.
2. Si è fermato prima del punto di segnalazione, per un bug nel sistema di segnalazione stesso.

Distinguere questi due casi richiede di guardare i log di Cloud Build. Ma almeno so che devo guardare.

Come uso questi 3 criteri insieme

Per ogni nuovo job autonomo che metto in produzione, aggiungo al system prompt una sezione "Contratto di output":

## Contratto di output
Output atteso: [descrizione specifica del file/azione/stato]
Criterio di completamento: [condizione verificabile esternamente]
In caso di fail: scrivi nel bus la riga [formato standard]
Non produrre output silenzioso.

Da quando ho formalizzato questi 3 criteri, il guasto silenzioso di 3 giorni non si è ripetuto.