Fornisci all'agente un contesto utile sul repository

Parti dal checkout attuale

Un agente deve sapere quale repository e branch sta modificando. Deve anche sapere se la directory di lavoro contiene modifiche non pertinenti. Questi fatti determinano cosa può modificare in sicurezza e come interpretare il diff finale.

Chiedi all’agente di esaminare le istruzioni del progetto e la configurazione dei pacchetti prima dell’implementazione. Un comando ricordato da un altro repository può essere sbagliato qui. Il nome familiare di un framework non dimostra quale versione sia installata o quali convenzioni segua il progetto.

Per una piccola modifica, fornisci il modulo pertinente, i chiamanti, i test e la decisione architetturale. Aggiungi informazioni quando l’indagine evidenzia un’esigenza precisa.

Usa le istruzioni del repository per le regole stabili

Un file di istruzioni può descrivere comandi previsti, confini dei moduli, requisiti di revisione e azioni che richiedono una decisione del responsabile. La convenzione AGENTS.md offre agli strumenti di programmazione un posto riconoscibile per queste informazioni. Gli strumenti possono gestirla diversamente e applicare precedenze diverse alle istruzioni: verifica il comportamento del tuo strumento.

Conserva nel repository le regole stabili del progetto. Mantieni il compito attuale nel brief. Non trasformare il file di istruzioni in una cronologia di ogni conversazione o in un elenco di piani temporanei.

Un’istruzione utile dice: «Esegui i test di integrazione sull’autorizzazione quando una route cambia il comportamento di accesso». Un’istruzione vaga dice: «Presta sempre attenzione alla sicurezza». La prima individua una condizione e un’azione verificabili dal revisore.

Confronta le istruzioni con il codice

Le istruzioni diventano obsolete quando cambiano comandi, directory o architettura. Se una guida indica uno script mancante, esamina la configurazione dei pacchetti. Se un documento dice che un servizio è di sola lettura, esamina i permessi prima di fidarti dell’affermazione.

Registra il conflitto. Usa prove dirette sulla versione attuale per capire il comportamento dell’implementazione. Non scartare tacitamente una policy intenzionale perché il vecchio codice la viola. La policy e il comportamento attuale rispondono a domande diverse.

Per esempio, la guida può vietare scritture dirette su un branch condiviso mentre un vecchio script le esegue ancora. La risposta corretta è mantenere la policy e correggere lo script. Il codice esistente non autorizza a ripetere un’azione vietata.

Mantieni il contesto pertinente e sicuro

Un repository intero può contenere credenziali, fixture private, esportazioni di clienti e vecchi log di assistenza. L’accesso al repository non rende automaticamente ogni file adatto a un servizio di modelli.

Usa strumenti approvati e regole per il trattamento dei dati. Escludi i segreti dal contesto. Dove possibile, sostituisci gli esempi dei clienti con dati inventati. Verifica anche gli strumenti collegati, oltre ai file caricati: un connettore di ricerca può recuperare informazioni assenti dal prompt iniziale.

L’istruzione «non leggere segreti» nel repository è utile. Non sostituisce i limiti di accesso agli archivi di segreti e alle directory sensibili.

Lascia informazioni utili a chi viene dopo

Al termine, registra nella pull request il comportamento modificato, le verifiche e i limiti irrisolti. Aggiorna la documentazione stabile del progetto quando cambia il flusso di lavoro previsto. Evita di copiare nel repository l’intera trascrizione dell’agente.

La documentazione deve aiutare chi manterrà il progetto a ripetere il lavoro senza ricostruire una lunga conversazione. Collega i documenti canonici e conserva una sola descrizione autorevole di ogni regola stabile.

Un buon contesto riduce le indagini ripetute. Rende anche più facile individuare gli errori, perché il comportamento atteso e i comandi funzionanti sono espliciti.