Tre pezzi che rendono un compito assegnabile
La documentazione del Copilot cloud agent descrive il compito ideale in tre parti, e conviene prenderle alla lettera. La prima è una descrizione chiara del problema da risolvere o del lavoro richiesto. La seconda sono acceptance criteria completi, che dicano che cosa è una buona soluzione: l’esempio portato dalla doc è proprio la domanda se siano attesi test unitari. La terza sono indicazioni su quali file vanno modificati.
Il terzo punto è quello che si tende a sopravvalutare. Il cloud agent sa cercare nel repository e dispone di semantic code search, che trova codice pertinente in base al significato e non solo alla corrispondenza testuale esatta; l’indice si aggiorna in background e tenerlo fresco migliora la qualità delle risposte sul codice. Un percorso indicato male, quindi, spesso non è fatale: l’agente ritrova il file da solo. Un criterio di accettazione mancante non è invece recuperabile da nessuna ricerca, perché non è un’informazione contenuta nel codice — esiste solo nella testa di chi ha assegnato il compito. È questa asimmetria che spiega il sommario dell’unità.
Un esercizio utile è riscrivere l’input come una coppia: stato attuale osservabile e stato finale verificabile. “Il form non valida l’email” diventa “il campo email rifiuta gli indirizzi senza dominio, con test unitari che coprono tre casi non validi, senza toccare il layer di persistenza”.
Che cosa conta come output, superficie per superficie
L’output non è la stessa cosa nelle quattro superfici, e confonderle è l’errore più costoso.
Il cloud agent lavora su un branch in un ambiente basato su GitHub Actions e produce una pull request in bozza: rivedi il diff, iteri e crei la pull request quando sei pronto, oppure lo chiedi già nel prompt iniziale. In revisione contano due dettagli operativi: la tua approvazione di una pull request di Copilot non conta ai fini delle approvazioni richieste, e i workflow di Actions sul branch partono solo dopo Approve and run workflows. La sessione ha inoltre un tempo massimo di esecuzione, quindi un compito troppo grande non rallenta: si interrompe.
La Copilot CLI agisce sulla tua macchina, nel working tree locale. Qui l’output è l’insieme delle modifiche ai file più l’esito dei comandi, e il perimetro lo definisci con i permessi sui tool, con flag come --allow-tool, --deny-tool e --available-tools; le regole di negazione hanno sempre la precedenza su quelle di permesso.
Il Copilot SDK rende il criterio di successo un problema di codice. Nell’agent loop invii il prompt con session.send e ricevi eventi: session.idle è il segnale affidabile che il ciclo di uso dei tool è terminato, mentre session.task_complete viene emesso solo se il modello dichiara di aver completato il compito, con un campo summary facoltativo. La lezione è netta: la fine del loop non è la riuscita del compito. Se il tuo sistema deve sapere se il lavoro è andato a buon fine, la verifica la scrivi tu attorno agli eventi.
I GitHub Agentic Workflows sono l’unica superficie in cui l’output è dichiarato prima di essere prodotto. Scrivi il workflow in Markdown dentro .github/workflows/, lo compili con gh aw compile in un file .lock.yml irrobustito che gira come workflow di Actions, e le operazioni di scrittura sono permesse soltanto attraverso i safe-outputs dichiarati nel frontmatter.
---
on: weekly on monday
permissions:
issues: read
safe-outputs:
create-issue:
---Criteri stabili e criteri del singolo compito
Alcuni criteri si ripetono in ogni compito: convenzioni di naming, framework in uso, struttura delle cartelle, standard di codice. Quelli non vanno nel prompt ma nelle custom instructions: .github/copilot-instructions.md per l’intero repository, file NAME.instructions.md in .github/instructions per ambiti specifici, oppure un AGENTS.md, che ha però un supporto più limitato di funzionalità. Un custom agent del cloud agent, in .github/agents/NOME.md, porta lo stesso ragionamento più avanti: description dice a che serve, prompt definisce comportamento e specializzazione, tools restringe gli strumenti disponibili.
Attenzione a non scambiare i guardrail per criteri di successo. Un CODEOWNERS sui file di configurazione, un ruleset sul branch, un copilot-setup-steps.yml che prepara l’ambiente delimitano che cosa l’agente può fare; non dicono che cosa conta come lavoro finito. Sono complementari, non sostitutivi.
Il rimedio a un compito vago
La doc del cloud agent elenca senza giri di parole che cosa non affidargli: refactoring ad ampio raggio che richiedono conoscenza cross-repository, questioni critiche per la produzione, lavoro su sicurezza, dati personali o autenticazione, e compiti con requisiti ambigui o aperti. Anche l’autopilot della CLI, che porta avanti i passi da solo finché non ritiene il compito completo, avverte che può avere difficoltà con istruzioni vaghe o ambigue e con valutazioni che richiedono giudizio sfumato.
Da qui la confusione tipica che l’esame ama mettere alla prova: davanti a un risultato deludente si alza l’autonomia — --yolo sulla CLI, un automation level più permissivo sulle automations del cloud agent — invece di riscrivere il compito. Alzare l’autonomia riduce le interruzioni, non l’ambiguità: un agente più libero eseguirà solo più in fretta una specifica incompleta. Vale la pena ricordare che le automations registrano una rationale per ogni azione supportata e ne valutano la confidenza come alta, media o bassa, e che le modifiche sotto la soglia impostata restano sempre come suggerimenti da accettare o rifiutare, qualunque cosa tu abbia chiesto nel prompt.
Aspettati domande che ti mostrano un compito mal scritto e ti chiedono che cosa manca: la risposta corretta indica i criteri di accettazione assenti, non un cambio di superficie né un livello di autonomia più alto.