Le custom instructions sono la leva principale

Quando l’analisi dei fallimenti mostra che l’agente ha capito il compito ma ha lavorato con i criteri sbagliati — convenzioni ignorate, test lanciati con il comando errato, stile di commit fuori standard — la correzione va nelle custom instructions, non nel prompt della singola sessione. Il prompt vive un turno; le istruzioni valgono per tutte le esecuzioni successive.

La documentazione distingue quattro famiglie. Le personal instructions esprimono preferenze individuali. Le istruzioni di repository esistono in tre varianti: path-specific instructions in .github/instructions/**/*.instructions.md, repository-wide instructions in .github/copilot-instructions.md e agent instructions in file come AGENTS.md, CLAUDE.md o GEMINI.md. Infine ci sono le organization custom instructions, disponibili sui piani Copilot Business ed Enterprise.

L’ordine di precedenza documentato è: personal instructions, poi le istruzioni di repository (nell’ordine path-specific, repository-wide, agent), poi quelle di organizzazione. Il punto che fa la differenza nel tuning è un altro, però: anche quando si applicano più tipi contemporaneamente, tutti gli insiemi pertinenti vengono forniti a Copilot. Precedenza non significa esclusione. Se la regola di repository dice una cosa e quella di organizzazione l’opposto, il modello riceve entrambe: non si annullano, si sommano in rumore, e la documentazione raccomanda esplicitamente di evitare insiemi di istruzioni in conflitto. Quindi il tuning corretto non è “aggiungo una riga più forte in cima”, ma “trovo la riga che contraddice e la rimuovo”.

Seconda trappola, questa da esame: non tutte le superfici leggono tutti i tipi. La tabella di supporto assegna le organization custom instructions alle superfici su GitHub.com, non alla Copilot CLI. Una regola scritta solo a livello di organizzazione non raggiunge chi lavora in locale. Se il fallimento si ripete sulla CLI e la regola esiste solo in organizzazione, la causa non è il modello: è che l’istruzione non è mai arrivata.

Memoria: spesso si toglie, non si aggiunge

Copilot memory conserva conoscenza fra le sessioni ed è attiva su tre superfici: cloud agent, Copilot code review e Copilot CLI. Le informazioni si dividono in repository-level facts — convenzioni e decisioni architetturali, create da chi ha accesso in scrittura e poi disponibili a tutti su quel repository — e user-level preferences, legate al singolo utente. Fatti e preferenze catturati da una feature possono essere usati da un’altra: è potente, ed è anche il motivo per cui un fatto sbagliato si propaga.

Nell’analisi dei fallimenti la memoria compare in un modo tipico: l’agente porta nel ragionamento un vincolo che non esiste più, perché è stato registrato quando il repository era diverso. Qui non si scrive un’istruzione in più, si cancella. Le preferenze personali si rivedono ed eliminano dalle Copilot settings, voce Memory; i fatti di repository si trovano nelle impostazioni del repository, sotto Copilot e poi Memory, e il proprietario può eliminarli. La stessa pagina delle impostazioni permette di portare Copilot Memory su Enabled o Disabled: disattivarla è un intervento di tuning legittimo quando serve stabilire una baseline pulita. Vale ricordare che i fatti e le preferenze non utilizzati vengono comunque rimossi automaticamente dopo un periodo di inattività, e che i fatti di repository sono validati contro il codice prima di essere applicati.

Accesso agli strumenti: restringere dopo un abuso, allargare dopo un blocco

L’analisi produce due esiti opposti, e ciascuno ha la sua leva sulla sua superficie.

Sulla Copilot CLI si agisce con --allow-tool e --deny-tool (che accettano anche pattern sui sottocomandi, per esempio consentire shell(git:*) negando shell(git push)), oppure si riduce l’insieme disponibile con --available-tools ed --excluded-tools. Le approvazioni salvate vivono in permissions-config.json sotto ~/.copilot/ e si azzerano con /reset-allowed-tools. Se il problema è la scelta dello strumento in presenza di troppi tool, esiste tool search, che carica i tool esterni solo quando servono; si può spegnere con toolSearch: false nelle impostazioni personali o modulare per server MCP con deferTools.

Un custom agent è il modo più stabile di fissare un perimetro ristretto e riusarlo:

---
name: test-fixer
description: Ripara i test che falliscono, senza toccare la configurazione CI
tools: ["read", "write", "shell"]
---

Nella CLI questi file hanno estensione .agent.md e stanno in .github/agents/ o ~/.copilot/agents/, e si invocano con /agent o con --agent. Nel Copilot SDK gli agenti si definiscono invece a codice, passando customAgents alla creazione della sessione, dove tools limita gli strumenti e mcpServers aggiunge server specifici. Sul cloud agent l’estensione degli strumenti passa dalla configurazione MCP in formato JSON nelle impostazioni del repository, con il campo tools per esporre solo ciò che serve; per progettazione il cloud agent non ha accesso ai tool MCP di scrittura, e il server GitHub predefinito usa un token in sola lettura. Nei GitHub Agentic Workflows il perimetro è nel frontmatter: tools per i toolset, permissions in sola lettura per default e safe-outputs per dichiarare le scritture ammesse. Attribuire un flag della CLI al cloud agent, o safe-outputs all’SDK, è l’errore più costoso su questo dominio.

Quando il problema è l’ambiente, non il modello

Se l’analisi mostra dipendenze installate a tentativi o comandi di rete falliti, non c’è istruzione che salvi. Per il cloud agent si predispone l’ambiente con copilot-setup-steps.yml, e si verifica il firewall: è attivo per default con una allowlist raccomandata, si estende con domini o URL da Settings poi Copilot poi Internet access a livello di organizzazione o repository, e quando un indirizzo viene bloccato la segnalazione compare nel corpo della pull request o in un commento, con l’indirizzo e il comando che l’ha richiesto. Per imporre un vincolo in modo deterministico, invece che sperare che il modello obbedisca, si usano gli hooks: preToolUse può restituire una permissionDecision di allow, deny o ask e modificare gli argomenti della chiamata.

Ultima regola, valida su tutte e quattro le superfici: si cambia una cosa per volta e si rimisura sullo stesso insieme di casi. Senza un segnale definito prima dell’intervento, il tuning non è tuning: è una sequenza di impressioni.