🤖 machine learning

What Context Does a Coding Agent Actually Need to Act?

Questo articolo dimostra che, per gli agenti di codifica che modificano codice, il contesto essenziale è strettamente limitato ai file specifici oggetto della modifica, poiché i riassunti in linguaggio naturale e il contenuto circostante dei file contribuiscono in modo trascurabile alla risoluzione del problema rispetto al codice sorgente stesso, rivelando al contempo un significativo livello di rumore nei risultati dei benchmark causato dall'inferenza non deterministica delle API.

Autori originali: Brian Sam-Bodden

Pubblicato 2026-07-14✓ Author reviewed ⓘ

📖 4 min di lettura☕ Lettura da pausa caffè

CC BY 4.0

Autori originali: Brian Sam-Bodden

Articolo originale sotto licenza CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ Questa è una spiegazione generata dall'IA dell'articolo qui sotto. Non è stata scritta dagli autori. Per precisione tecnica, consulta l'articolo originale. Leggi il disclaimer completo

Immagina di dover riparare un rubinetto che perde in un grattacielo enorme, di 100 piani. Non hai bisogno di leggere le planimetrie dell'intero edificio, il menù della mensa o i registri della sicurezza per trovare la chiave inglese. Hai solo bisogno di sapere esattamente quale tubo sta perdendo e vedere l'area circostante.

Questa è la sorprendente lezione di questo nuovo studio sugli "agenti di codifica": i bot di IA che scrivono e correggono software. Per molto tempo, il mondo tecnologico ha assunto che questi bot dovessero ingerire l'intero codice sorgente di un progetto (a volte milioni di righe) nel loro "cervello" per poter svolgere il proprio lavoro. Il pensiero era: "Più contesto è sempre meglio".

Ma questo articolo dice: Smettetela di riempire il cervello. Si scopre che per l'atto effettivo di correggere il codice, l'IA non ha bisogno di quasi nulla se non delle righe specifiche che sta per modificare.

Il "Trovare" vs. Il "Fare"

I ricercatori hanno diviso il problema in due parti:

Il Trovare: Localizzare il codice rotto.
Il Fare: Effettuare effettivamente la riparazione una volta trovato.

Per testare questo, hanno usato una "mappa magica" (un oracle) per dire all'IA esattamente dove si trovasse il codice rotto. Ciò significava che l'IA non doveva indovinare dove guardare; doveva solo concentrarsi su come ripararlo. Hanno poi fornito all'IA diverse "visioni" di quel codice per vedere cosa funzionasse meglio.

La Grande Delusione: I Riassunti Non Funzionano

Un'idea popolare era: "Diamo all'IA un riassunto in linguaggio naturale del codice, come la quarta di copertina di un libro".

Il Test: Hanno chiesto all'IA di rispondere a domande difficili su come si comporta il codice, usando o il codice sorgente completo o un riassunto scritto da un'IA super intelligente (un "modello di frontiera").
Il Risultato: Il codice sorgente completo ha risposto correttamente a 27 su 45 domande. I riassunti? Ne hanno risposte correttamente solo 4 su 45.
Il Colpo di Scena: Non importava se il riassunto fosse scritto dalla IA più intelligente del mondo o da un modello minuscolo e basilare. Entrambi fallivano allo stesso modo. Il problema non era chi scriveva; il problema era il formato. Un riassunto semplicemente non può trasportare i dettagli "comportamentali" specifici necessari per correggere un bug. È come cercare di riparare il motore di un'auto leggendo un opuscolo turistico sull'auto; l'opuscolo è bello, ma non ti dice quale bullone è allentato.

Lo "Scheletro" vs. Il "Corpo Intero"

Successivamente, hanno testato se l'IA avesse bisogno del codice completo, con tutta la sua "carne", o solo dello "scheletro" (la struttura, come nomi di funzioni e firme).

La Configurazione: Hanno preso 70 problemi reali di programmazione. Per alcuni, hanno dato all'IA i file completi. Per altri, hanno dato solo lo "scheletro" (diagrammi UML e firme) o una versione "mantieni/elimina" (mantenendo solo le parti essenziali e cancellando il resto).
Il Risultato: Le versioni "scheletro" e "mantieni/elimina" hanno risolto tantissimi problemi quanto i file completi. In effetti, il metodo "mantieni/elimina" ne ha risolti leggermente di più (25 su 70) rispetto ai file completi (19 su 70), anche se la differenza era abbastanza piccola da poter essere attribuita al caso.
Il Costo: Ecco il punto cruciale. Risolvere un problema con i file completi è costato all'IA 94.000 token (un'unità di testo). Risolvere lo stesso problema con il metodo compresso "mantieni/elimina" è costato solo 19.000 token. È un risparmio enorme, circa 3 o 3,7 volte meno economico — con nessuna perdita di prestazioni.

L'Avvertimento sul "Rumore"

I ricercatori hanno anche scoperto una cosa strana e importante: anche quando eseguivano lo stesso identico test con le stesse impostazioni, l'IA a volte dava risposte diverse. Circa il 9% delle volte, l'esito cambiava tra un'esecuzione e l'altra. Questo significa che se vedete una piccola differenza tra due metodi (come un miglioramento del 2%), potrebbe trattarsi solo di rumore casuale, non di una vera scoperta.

Il Punto Fondamentale

L'articolo conclude che per il compito specifico di correggere il codice, meno è meglio.

Cosa funziona: Dare all'IA le righe esatte di codice che deve modificare, depurate fino alle loro essenzialità.
Cosa non funziona: Inondare l'IA con riassunti, cronologie complete dei file o complessi diagrammi strutturali.
Il Verdetto: Il "segnale" risiede nel codice stesso, non nella storia che raccontiamo sul codice. Tagliando via il superfluo, possiamo correggere i bug per una frazione del costo, senza dover leggere l'intero grattacielo per riparare un singolo rubinetto che perde.

Gli autori precisano con molta cautela che questo si applica alle correzioni "single-shot" (dove l'IA prova una volta sola e non ha la possibilità di rileggere o chiedere aiuto). Ma per quel momento specifico, ad alta intensità, di editing, i dati sono chiari: non serve l'intera biblioteca; serve solo la pagina giusta.

Riepilogo Tecnico: Di quale contesto ha realmente bisogno un Agente di Codifica per agire?

Definizione del Problema

I moderni agenti di codifica possiedono finestre di contesto abbastanza ampie da contenere interi repository di codice, eppure le evidenze suggeriscono che gran parte di questo contesto rimanga inutilizzato. Sebbene vengano spesso impiegati la generazione aumentata dal recupero (RAG) e sofisticate impalcature (scaffolding) per gestire il contesto, benchmark come ContextBench indicano che questi sistemi complessi superano a malapena dei baseline banali. La domanda centrale affrontata non è quanto contesto un agente possa contenere, ma quale sia il contesto minimo necessario affinché un agente possa modificare il codice con successo, e in quale rappresentazione.

Gli autori distinguono tra due sottoproblemi spesso confusi nel design degli agenti:

Trovare (Find): Localizzare le funzioni o i file specifici dove deve avvenire il lavoro.
Agire (Act): Data la posizione, possedere informazioni sufficienti per eseguire la modifica correttamente.

Questo studio isola la fase di Azione (Act). Mantenendo fissa la localizzazione (utilizzando un oracle per fornire esattamente i file "gold standard" da modificare), gli autori variano solo la rappresentazione di quel codice per determinare il contesto minimo richiesto per la risoluzione.

Metodologia

Strumento Sperimentale: `resolve@cost`

Gli autori hanno costruito uno strumento auditato per misurare i tassi di risoluzione rispetto ai costi di contesto.

Dataset: 70 istanze multi-file da SWE-bench Verified (dopo aver escluso un'istanza in cui la patch gold falliva la propria validazione ambientale).
Localizzazione Oracle: Per isolare gli effetti della rappresentazione dagli errori di recupero, ogni "braccio" sperimentale (condizione) riceve esattamente lo stesso set di file modificati (gold-changed files). L'unica variabile è come il contenuto di tali file viene renderizzato.
Agente: Una singola esecuzione di Claude Sonnet 4.6 (Temperatura 0, max 8000 token). L'agente produce blocchi SEARCH/REPLACE, che vengono convertiti in diff unificati tramite un builder deterministico (difflib) e verificati tramite un harness Docker.
Validazione:
- Gate di Espressività: Prima di ogni chiamata all'agente, viene verificato che ogni riga eliminata o ogni ancora inserita nella patch gold sia presente verbatim nel contesto renderizzato per ogni braccio.
- Determinismo: Le patch sono costruite deterministicamente per evitare confondimenti derivanti da una generazione di diff non riproducibile.
- Pre-registrazione: Ipotesi e protocolli sono stati congelati prima della raccolta dei dati.

Bracci di Rappresentazione

Lo studio confronta tre rappresentazioni primarie per i file modificati (gold-changed files):

oracle_full: I file sorgente completi e non modificati.
oracle_tier: Una rappresentazione strutturata in cui il codice non appartenente al locus viene reso come scheletri UML (strutture di classe) e firme di metodi, mentre il locus della modifica rimane completo.
oracle_keep_drop: Un approccio binario in cui il codice non appartenente al locus viene eliminato interamente, lasciando solo le funzioni/classi specifiche oggetto della modifica.

Probi Comportamentali (Il confine "Find/Act")

Per testare se le rappresentazioni compresse trasportino segnali azionabili, gli autori hanno utilizzato dei probi comportamentali:

Setup: 15 classi tenute in riserva da seaborn, pylint e pytest. Tre probe (domande comportamentali) sono state create dai file di test per ogni classe.
Task: L'agente (Sonnet 4.6) legge una rappresentazione (Full Source, Frontier Summary, 3B Model Summary o Signatures) e risponde alla probe.
Giudizio: Un giudice indipendente (GPT-4o-mini) valuta le risposte.
Controllo: Un riassumitore di frontiera (Sonnet 4.6) e un modello piccolo (Qwen-3B) hanno generato i riassunti per garantire che il fallimento del "riassunto" non fosse dovuto alla scarsa qualità della sintesi.

Risultati Chiave

1. Il contesto per l'"Azione" è estremamente minimale

L'ipotesi registrata ( $H_2$ ) prevedeva che i livelli strutturati (scheletri UML/firme) avrebbero risolto più problemi rispetto a un semplice approccio binario keep/drop. Questa ipotesi è fallita.

Tassi di Risoluzione:
- oracle_keep_drop: 25/70 risolti (35.7%)
- oracle_tier: 23/70 risolti (32.9%)
- oracle_full: 19/70 risolti (27.1%)
Significatività Statistica: La differenza tra i livelli strutturati e il keep/drop è nulla (McNemar $p=0.75$ ). Renderizzare il codice circostante come scheletri UML non fornisce alcun beneficio misurabile rispetto alla sua totale eliminazione quando la localizzazione è perfetta.
Efficienza dei Costi: I contesti compressi risolvono i problemi con 3–3.7× meno token rispetto ai file completi.
- Costo per risoluzione: ~19K token (keep/drop) vs. ~94K token (full files).

2. I riassunti in linguaggio naturale non trasportano segnali azionabili

I probe comportamentali hanno rivelato un divario enorme in termini di informazioni azionabili tra il codice sorgente e i riassunti.

Accuratezza: Il codice sorgente completo ha risposto correttamente al 60% (27/45) dei probe comportamentali. I riassunti in linguaggio naturale (sia quelli di modelli di frontiera che di modelli 3B) hanno risposto solo al ~9% (4/45).
Rappresentazione vs. Riassumitore: Il divario è inerente alla classe di rappresentazione, non alla qualità del riassumitore. I riassunti di frontiera hanno performato in modo identico ai riassunti del modello 3B.
Firme: Le firme dei metodi + docstring hanno performato leggermente meglio dei riassunti in prosa (6/45), ma hanno comunque fallito nel eguagliare il codice sorgente.
Conclusione: I riassunti in linguaggio naturale non rispondono alle domande comportamentali che il codice sorgente risponde; il "segnale" risiede nella struttura del codice, non nella narrazione.

3. Non-determinismo tra le esecuzioni

Un risultato metodologico critico riguarda la stabilità dell'inferenza degli LLM a Temperatura 0.

Osservazione: Rieseguire il braccio keep/drop con protocolli byte-identici (stesso modello, stessi prompt, T=0) ha causato il cambio di esito (~9%) in circa il 9% delle istanze (25/70 risolti originariamente vs. 23/70 nella seconda esecuzione).
Implicazione: Questo rumore di fondo (~9%) pone un limite all'interpretazione di piccoli effetti dimensionali. Differenze di 1–2 istanze (come l'ipotesi registrata $H_2$ ) sono statisticamente indistinguibili dal rumore di inferenza.

Contributi e Significato

Il documento rivendica quattro contributi primari:

Uno Strumento Auditato: Un framework resolve@cost con verifica dell'espressività per singola istanza, costruzione deterministica della patch ed ipotesi pre-registrate, garantendo che ogni numero sia tracciabile agli artefatti grezzi.
Un Risultato Nullo Potenziato: La prova che i livelli di rappresentazione strutturata (UML/scheletri) non portano alcun segnale di risoluzione aggiuntivo rispetto al approccio binario keep/drop in presenza di localizzazione oracle. Ciò sfida l'assunto che "più struttura" equivalga a "migliore azione".
Una De-circolarizzazione del Confine Find/Act: La dimostrazione che il codice sorgente trasporta circa 7× il segnale azionabile dei riassunti in linguaggio naturale. Fondamentalmente, un riassumitore di frontiera non può colmare questo divario, indicando che la limitazione è il formato della rappresentazione, non la capacità del riassumitore.
Cautela Metodologica: La quantificazione di un rumore di fondo del ~9% nell'inferenza API single-shot a T=0. Ciò suggerisce che molti piccoli effetti riportati nella letteratura di SWE-bench (inclusi i risultati nulli di questo stesso studio) potrebbero essere artefatti della non-determinazione piuttosto che segnali reali.

Ambito e Limitazioni

Gli autori dichiarano esplicitamente che le loro conclusioni si applicano ad agenti single-shot senza loop di feedback di esecuzione. Riconoscono che gli agenti multi-turno potrebbero recuperare da un contesto compresso leggendo di più, ma nel regime single-shot, il passo di "trovare" (find) deve essere perfetto (oracle) e il contesto per "agire" (act) deve essere minimo. Lo studio non sostiene che i riassunti siano inutili per la navigazione (trovare il codice), ma solo che sono insufficienti per l'azione (modificare il codice) rispetto al codice stesso.

Il documento conclude che, per il compito specifico di modificare il codice data la posizione corretta, il contesto minimo richiesto è il codice stesso che si sta modificando, e il contesto circostante (anche in forme strutturate) aggiunge un valore trascurabile pur comportando costi di token significativi.