La oss rydde én ting av veien før jeg starter: dette er på ingen måte min oppfinnelse. For en stund siden plukket jeg opp en ganske spesifikk måte å bruke AI-agenter på, beskrevet i et dokument om "avansert kontekst-engineering" (som for øvrig er bra lesestoff i seg selv). Et selskap som heter HumanLayer hadde over tid utforsket og undersøkt hvordan man kan løse en del av utfordringene man får når man slipper løs en AI-agent i en større kodebase.

Utfordringene

Kort oppsummert kan det virke som at jo større og eldre en kodebase er, jo vanskeligere er det å få en AI-agent til å prestere konsistent på et høyt nivå. I såkalte greenfield-prosjekter er gjerne størrelsen på kodebasen begrenset, og færre utviklere har vært innom kodebasen slik at tankegangen er konsistent. I såkalte brownfield-kodebaser finnes det kanskje flere ulike termer for samme konsept, det er kanskje kodet på flere menneskelige språk, og standarder har endret seg underveis. Alt dette er med på å forvirre AI-agenten, og utfallet man får kan virke litt mer tilfeldig.

I tillegg til dette er det fortsatt mange av oss som behandler AI-agenter som en "chatbot". Vi starter en ny samtale hvor vi beskriver et problem, og snakker fram og tilbake om dette problemet. Underveis leser AI-agenten nye filer som mates inn i konteksten og tar plass. Disse filene og diskusjonen man har kan være relevant, men det kan også hende at samtalen tar flere vendinger underveis. Dette virker kanskje ikke problematisk, men hvis vi tenker på at hele samtalen man har hatt evalueres for hvert spørsmål er det lett å skjønne at AI-agenten blir mer og mer "forvirret" jo mer man putter inn i samme samtale.

Løsningen på dette er, som så ofte ellers, å jobbe litt smartere.

En trestegsprosess

Når utviklere koder hopper vi sjeldent rett på en løsning. Vi starter kanskje med å lage en liten mental plan over hva vi trenger å gjøre for å løse et problem. En oversikt. Vi bruker litt tid på å undersøke den eksisterende kodebasen slik at vi treffer best mulig. Vi kommer opp med noen ulike løsninger, og vurderer dem opp mot hverandre. Og til slutt implementerer vi. Dette skjer ikke nødvendigvis som separate, sekvensielle, prosesser: vi hopper gjerne litt fram og tilbake mellom utforskning og planlegging, og kanskje prøver vi til og med på litt implementasjon midt i for å teste en lite hypotese. Dette kan vi gjøre fordi at vi kjenner kodebasen og bygger på tidligere erfaringer vi har. Jo bedre vi kjenner kodebasen, jo enklere er det for oss å forstå hvordan vi skal løse noe på en god måte.

AI-agenter fungerer annerledes. De er riktignok trent opp på vanvittige mengder kode og tekst og kan sies å ha en slags erfaring, men har ingen kjennskap til kodebasen vi sitter i. Hver eneste gang vi starter en ny samtale med Claude Code, Codex eller Copilot, må den finne ut hvordan kodebasen fungerer. Den må forstå hvordan kodebasen er strukturert, hvilket språk som brukes, konvensjoner og arkitektur. Hver gang en ny samtale starter, er all tidligere kunnskap borte.

Trestegsprosessen vi skal se på nå kan sies å tilnærme seg hvordan mennesker tenker når vi skal løse problemer. Den starter med å utforske kodebasen og potensielle løsninger, før den legger en plan basert på utforskningen, og til slutt implementeres planen. Hvert steg er her implementert som en egendefinert kommando i Claude, men det finnes helt sikkert også andre måter å oppnå det samme på. Det vi ønsker er tydelige og konkrete instruksjoner for hva vi ønsker å oppnå i hvert steg.

Research-fasen

Research-fasen er første steget, og handler om å forstå kodebasen og hvordan et problem best kan løses med det som finnes der allerede. Agenten skal forstå hvordan informasjon flyter, og finne fram til relevante filer og relevante linjenumre. Målet er å ende opp med et kompakt dokument som forklarer kodebasen opp mot problemstillingen på en best mulig måte, uten noe unødvendig informasjon.

I denne fasen skal agenten kun undersøke kodebasen, den skal ikke produsere noe utover research-dokumentet. Dette kan kanskje minne om "planning mode" i Claude Code, men går ganske mye lengre i å instruere AI-agenten i hva den skal utføre.

Et godt eksempel på hvordan en slik kommando ser ut finner du her: research.md. Kopier filen inn i din .claude/commands-mappe, og kjør den med /research.

Før du går videre til planleggingsfasen er det lurt å lese gjennom research-dokumentet for å se om du er enig. Husk at dette er utgangspunktet for koden som skal genereres senere, så jo mer presist dette dokumentet er jo bedre vil den endelige løsningen bli.

Planleggingsfasen

Når researchfasen er over er det på tide å lage en plan for hvordan problemstillingen kan løses. Den tar inn dokumentet fra research-fasen, og all tilhørende research. Siden research-dokumentet peker så presist på relevante deler av kodebasen trenger ikke AI-agenten å lete seg rundt og bruke unødvendig kontekst på å forstå kodebasen – alt som trengs er enten en del av research-dokumentet eller lenket til slik at agenten kan lese de relevante delene i kodebasen direkte.

Som i researchfasen er heller ikke planleggingsfasen en plass vi skal generere noe kode, men heller ende opp med en tydelig og konkret plan for hvordan problemstillingen skal angripes. Den er delt opp i flere steg som sier noe om hva som skal gjøres, og hva som er suksesskriteriene for å komme videre. Hver del kan for eksempel avslutte med å kjøre tester eller starte en tjeneste for å få verifisert om alt fungerer. Planen kan også si hva vi spesifikt ikke ønsker å gjøre, og den bør beskrive hvordan sluttilstanden skal se ut.

Et eksempel på hvordan en slik kommando ser ut finner du her: plan.md. Kopier filen inn i din .claude/commands-mappe, og kjør den med /plan.

Også her er det lurt å lese gjennom planen før du går videre til neste steg. Dette skal være en oppskrift på alt som skal utføres i implementasjonsfasen, så det er viktig at du er enig. Skulle du være uenig er det bare å kaste planen, og enten lage en ny ut i fra research-dokumentet med litt ekstra instruksjoner, eller starte helt på begynnelsen igjen med en enda mer detaljert prompt.

Implementasjonsfasen

Når du er fornøyd med planen som er generert kan du starte på implementasjonen. Implementasjonsfasen tar inn planleggingsdokumentet, og gjennomfører planen steg for steg. Dette kan ta tid, og agenten kan gjerne iterere litt på hvert steg dersom verifiseringen feiler. Her ser vi viktigheten av å ha en god oppdeling og verifisering. Når problemet er delt opp i mindre steg, er det ofte enklere for agenten å komme fram til en god løsning. Og når stegene må verifiseres underveis har vi hele tiden trygghet i at agenten ikke "går seg vill" og endrer på store deler av kodebasen.

Et eksempel på hvordan en slik kommando ser ut finner du her: implement.md. Kopier filen inn i .claude/commands-mappen, og kjør den med /implement.

I praksis

Dette har blitt min goto-prosess for omtrent alt jeg gjør som er litt større enn bare noen få kodelinjer. Det hender at jeg hopper over f.eks. research-fasen hvis jeg klarer å peke agenten til en veldig isolert del av kodebasen, men som oftest bruker jeg alle tre stegene. Det som kanskje skjer oftere er at jeg starter på nytt. Hvis jeg er misfornøyd med en plan som blir generert hender det at jeg sletter både research- og planleggingsdokumentet og starter om igjen med en bedre og mer presis prompt. Ofte får jeg like gode resultater av det som å jobbe fram og tilbake med planen, og det tar omtrent like mye tid. Her er det lov å prøve seg fram!

Det er også viktig å huske på å «nullstille konteksten» mellom hvert steg. Konteksten er alt én samtale inneholder, som er både tekst og bruk av verktøy. En ny fase startes alltid med en tom kontekst slik at man har mest mulig tilgjengelig kontekst til å utføre oppgaven, og ikke forvirrer AI-agenten med tidligere innhold. Selv om kontekstvinduene etter hvert nå begynner å bli veldig store er det ingen grunn til å fylle dem helt opp: det er alltid bedre med en frisk kontekst enn en som inneholder detaljer som er irrelevant for det man holder på med.

Research-dokumentene og planene som blir produsert kan også være fine å ta vare på. De har i alle fall to funksjoner. De er oppskriften på funksjonalitet som har blitt laget tidligere, og kan inneholde viktige avveininger som er tatt. Kommandoene jeg har linket til her er også satt opp til å bruke tidligere planer som referanser. Hvis man for eksempel for en stund siden har lagt til noe grunnleggende funksjonalitet, og så senere skal utvide den, er sjansen stor for at AI-agenten finner ut av dette i research-fasen og bruker denne kunnskapen når utvidelsen lages. Slik passer du på at tidligere avgjørelser også påvirker senere kode som skrives.

Lykke til!