SWE-Adept: An LLM-Based Agentic Framework for Deep Codebase Analysis and Structured Issue Resolution

SWE-Adept is een tweeledig agentisch framework dat de prestaties van grote taalmodellen op repository-niveau verbetert door middel van een gespecialiseerde agent voor contextbewuste code-localisatie en een tweede agent voor gestructureerde, versiebeheerde probleemoplossing, wat resulteert in een significante stijging van de eindoplossingsgraad op SWE-Bench-benchmarks.

De kern

Stel je voor dat je een enorme, oude bibliotheek bent binnengegaan om een specifiek boek te vinden dat een fout bevat, en dat boek vervolgens te repareren. De bibliotheek heeft duizenden verdiepingen, miljoenen boeken en de planken zijn door elkaar gehaald.

SWE-Adept is een slimme robot-assistent die je helpt bij deze taak. In plaats van dat één persoon (of een simpele computer) alles zelf moet doen, heeft SWE-Adept twee gespecialerde helpers: een Zoeker en een Reparateur.

Hier is hoe het werkt, vertaald naar alledaagse taal:

1. De Zoeker (De "Detective")

Het grootste probleem bij het zoeken naar een fout in grote software is dat je vaak de verkeerde boeken opent. Je leest duizenden pagina's die niets met het probleem te maken hebben, waardoor je hersenen (of de computergeheugen) vollopen.

• Hoe de Zoeker werkt:
  De Zoeker gebruikt een slimme strategie die we een "diepte-zoektocht" noemen. Stel je voor dat je een boom hebt met takken. De Zoeker kijkt niet naar alle takken tegelijk (dat zou te veel werk zijn). In plaats daarvan kiest hij één tak die er belangrijk uitziet, loopt die helemaal uit tot aan het einde, en kijkt of de fout daar zit.
  • De slimme truc: Hij pakt alleen de "skeleton" (het geraamte) van de boeken mee om te kijken of het de juiste tak is. Pas als hij zeker weet dat hij op het goede spoor zit, pakt hij het hele boek erbij. Dit houdt zijn geheugen schoon en zorgt dat hij niet verdwaalt in onbelangrijke details.
  • Het resultaat: Hij vindt veel sneller en nauwkeuriger waar de fout zit dan eerdere methoden.

2. De Reparateur (De "Handige Klusser")

Zodra de Zoeker de plek heeft gevonden, komt de Reparateur in actie. Het probleem hier is vaak dat als je iets repareert, je per ongeluk iets anders kapotmaakt. Als je dan vastloopt, is het lastig om terug te gaan naar de situatie van daarvoor.

• Hoe de Reparateur werkt:
  De Reparateur werkt niet zomaar "probeer maar wat". Hij werkt met een plan en een tijdbalk.
  • Hypothese-bomen: Stel je voor dat hij drie verschillende manieren bedenkt om de fout te fixen. Hij maakt voor elke manier een aparte "tijdbalk" (een tak in een boom). Hij werkt aan de eerste manier. Als die niet werkt, gooit hij die tak niet weg, maar hij springt terug naar het begin van die tak en probeert de tweede manier.
  • Tijdsbewaking (Checkpointing): Dit is het belangrijkste. Elke keer als hij een kleine stap zet (bijvoorbeeld: "ik heb deze regel code veranderd"), maakt hij een foto van de hele bibliotheek op dat exacte moment.
  • De "Terugspoel"-knop: Als hij merkt dat zijn laatste stap de fout erger maakt, kan hij niet zomaar "ongedaan maken". Hij kan gewoon die foto van daarvoor weer ophalen en de bibliotheek exact terugzetten naar hoe het was. Dit voorkomt dat hij in een doolhof van fouten belandt.

Waarom is dit zo goed?

Vroeger deden robots dit vaak als een "probeer-en-fout" spelletje zonder plan. Ze veranderden code, keken of het werkte, en als het mislukte, waren ze vaak vergeten hoe het er eerst uitzag.

SWE-Adept is als een super-georganiseerde architect:

1. Hij zoekt heel slim en snel naar de juiste plek (zonder de hele bibliotheek te hoeven lezen).
2. Hij repareert met een plan, maakt foto's van elke stap, en kan altijd veilig terugspringen als een idee niet werkt.

Het eindresultaat:
In tests (waarbij ze echte softwareproblemen oplossen) bleek SWE-Adept veel succesvoller te zijn dan eerdere systemen. Hij lost meer problemen op, maakt minder fouten en doet dit efficiënter. Het is alsof je van een amateur-reparateur bent gegaan naar een professioneel team dat precies weet wat het doet, zelfs in de grootste en ingewikkeldste bibliotheken.

Technische samenvatting

Probleemstelling

Grote Taalmodellen (LLMs) presteren uitstekend op geïsoleerde programmeertaken, maar worstelen nog steeds met software-engineeringproblemen op repository-niveau (SWE). De auteurs identificeren twee hoofduitdagingen:

1. Moeilijke code-localisatie: Real-world codebases zijn groot (gemiddeld >3.000 bestanden per repository in SWE-Bench) en hebben dichte cross-file afhankelijkheden. Het vinden van de juiste code voor een probleem is lastig omdat LLMs vaak in hun contextlimiet raken door te veel irrelevante informatie te laden. Bestaande methoden gebruiken vaak breedte-georiënteerde zoekopdrachten of grove indexering, wat leidt tot context-overload en lage nauwkeurigheid.
2. Gebrek aan systematische oplossingsstrategieën: Bestaande agenten werken vaak in een vrije "denk-en-bewerk"-lus zonder expliciete planning of voortgangsregistratie. Zonder een mechanisme om tussenstappen vast te leggen (checkpointing), kunnen agenten niet betrouwbaar terugkeren naar een eerdere staat na een mislukte poging, wat leidt tot een ongeorganiseerde en onbetrouwbare oplossingscyclus.

Methodologie: Het SWE-Adept Framework

SWE-Adept is een framework gebaseerd op twee gespecialiseerde agents die werken in aparte contextvensters om contextvervuiling te voorkomen: een Localisatie-agent en een Oplossings-agent.

1. Codebase Representatie en Indexering

• Definitie-niveau indexering: De codebase wordt opgesplitst in fijne, zelfstandige eenheden (classes en functies) met behulp van tree-sitter. Overige code wordt in vaste chunks van 200 regels opgesplitst.
• Code-structuurbomen: In plaats van een monolithische graaf, wordt voor elke code-eenheid een lichte adjacency-lijst opgeslagen die de "child units" (bijv. aangeroepen functies) definieert. Dit maakt afhankelijkheidsbewuste navigatie efficiënter.

2. Issue Localisatie (De Localisatie-agent)

Deze agent is ontworpen om de juiste code te vinden met minimale contextgebruik:

• Agent-gestuurde diepte-eerst-zoekopdracht (DFS): De agent voert een selectieve diepte-eerst-zoekopdracht uit over de code-structuurbomen. In plaats van alles te laden, gebruikt het zoektools om alleen lichte structurele informatie (skeletten, previews en metadata) op te halen.
• Twee-traps filtering:
  1. Fase 1: Kandidaten worden gefilterd en gerangschikt op basis van code-skeletten en locatie-metagegevens.
  2. Fase 2: Pas voor de top-kandidaten wordt de volledige broncode opgehaald voor een diepere analyse en her-rangschikking. Dit voorkomt dat de contextvenster volloopt met irrelevante bestanden.

3. Issue Oplossing (De Oplossings-agent)

Deze agent implementeert en valideert de fixes met een gestructureerde aanpak:

• Hypothese-gedreven planning: De agent formuleert één of meerdere hypotheses (alternatieve oplossingen). Voor elke hypothese wordt een dynamische "to-do" lijst gemaakt.
• Tool-Memory Interface: De agent gebruikt twee families van CLI-achtige tools:
  • hypothesis_plan: Beheert hypotheses, to-do lijsten en logt inzichten.
  • hypothesis_git: Voert Git-gebaseerde versiebeheeroperaties uit (branching, commits, revert).
• Checkpointing Mechanisme: Na elke voltooide to-do-stap wordt de code-status vastgelegd als een checkpoint (Git hash) in een gedeeld werkgeheugen.
  • Branching: De agent kan een nieuwe branch maken om een alternatieve hypothese te verkennen zonder de huidige te verstoren.
  • Reverting: Als een stap mislukt, kan de agent terugkeren naar een eerdere checkpoint via een semantische referentie (in plaats van harde Git-hashes) en een nieuwe tak starten.
• Samenvoegen: Na het testen van alle hypotheses, wordt de beste tak samengevoegd met de originele code voor de uiteindelijke patch.

Belangrijkste Bijdragen

1. SWE-Adept Framework: Een end-to-end agentic systeem dat nauwkeurige localisatie combineert met gestructureerde, langdurige probleemoplossing.
2. Agent-gestuurde DFS met Twee-traps Filtering: Een nieuwe methode voor code-navigatie die context-efficiëntie maximaliseert door diepe afhankelijkheidsnavigatie te combineren met een gefaseerde laadstrategie.
3. Tool-Memory Interface voor Versiebeheer: Een innovatief ontwerp waarbij agents via semantische tools en een werkgeheugen betrouwbaar Git-checkpoints kunnen beheren, wat essentieel is voor het herstellen van fouten en het verkennen van meerdere oplossingsrichtingen.

Resultaten

Het framework is getest op SWE-Bench Lite en SWE-Bench Pro met modellen zoals GPT-5.2 en Claude-Sonnet-4.5.

• Localisatie: SWE-Adept behaalde de beste resultaten in zowel bestands- als functieniveau-localisatie. Op SWE-Bench Lite verbeterde de nauwkeurigheid op functieniveau (Acc@5) met 5,4% (ten opzichte van de sterkste baseline) en verbruikte minder tokens dan graafgebaseerde methoden.
• Oplossing (Resolve Rate): De framework verbeterde de end-to-end oplosbaarheid met tot 4,7% op SWE-Bench Pro.
• Analyse: De resultaten tonen aan dat de combinatie van nauwkeurige localisatie en systematische, checkpoint-gestuurde oplossing de prestaties aanzienlijk verbetert. Ablatiestudies bevestigen dat het gebruik van de hypothesis_git tools (in plaats van ruwe Git-commando's) cruciaal is voor de betrouwbaarheid op lange trajecten.

Betekenis en Impact

SWE-Adept adresseert de fundamentele beperkingen van huidige LLM-agenten bij het oplossen van complexe softwareproblemen: contextoverload en gebrek aan staatbeheer. Door een systematische aanpak te introduceren die lijkt op hoe menselijke ontwikkelaars werken (diepe navigatie, hypothesevorming, versiebeheer en het kunnen "ongedaan maken" van fouten), zet het een nieuwe standaard voor autonome software-engineering. Het bewijst dat gestructureerde agenten, ondersteund door slimme tooling en geheugen, veel effectiever zijn dan vrije "trial-and-error" benaderingen voor repository-level taken.