Modellen är svag på breda frågor om kod den inte kan överblicka, och stark på smala frågor med rätt kontext. Kartlägg terrängen med tre konkreta frågor, följ sedan ett enda verkligt användarfall rakt genom koden. Behandla varje förklaring som en hypotes: den ska verifieras mot körning, test eller historik innan du bygger vidare på den.
Varför "förklara kodbasen" ger ett svar som inte går att använda
Frågan har ingen avgränsning, så svaret får ingen heller. Modellen ser ett filträd och kanske några filer, känner igen ramverket och mönstren, och skriver den beskrivning som stämmer för de flesta projekt som ser ut så. Det blir en beskrivning av en typisk kodbas av den sorten — inte av din.
Det problematiska är att svaret är svårt att avfärda. Det innehåller riktiga filnamn, det använder projektets egen terminologi och det är internt konsekvent. Ingenting i formen skiljer det från ett svar som faktiskt bygger på att modellen läst koden. Du får en karta med rätt kustlinje och uppfunna vägar.
Lägg till att kontexten är ändlig. Ett modernt verktyg kan indexera och söka igenom hela repot, men modellen arbetar ändå med ett urval av de filer och kodstycken som verkar relevanta för frågan. En sökning, en indexering, verktygets eget urval eller din inklistring avgör därför svaret minst lika mycket som modellen gör. Frågan "förklara kodbasen" ger verktyget få ledtrådar om vad som ska hämtas in.
Det kostar sällan något att få en luddig översikt. Det kostar däremot att ta med sig den in i första ändringen. Du bygger på att "behörigheten kontrolleras i mellanlagret", för det stod i sammanfattningen, och upptäcker tre veckor senare att det gäller sex av åtta ingångar. Felet var aldrig i koden — det var i beskrivningen du aldrig kontrollerade.
Kartan först: tre frågor som ger dig terrängen
Innan detaljerna behöver du veta ungefär var saker händer. Tre frågor räcker längre än en generell översikt, eftersom var och en har ett svar som går att peka på i en fil.
Notera vad frågorna har gemensamt: de går att besvara med en lista över platser. Det gör dem billiga att stämma av. Öppnar du tre av åtta påstådda ingångar och alla tre finns där de sades finnas, har du både en karta och ett skäl att lita på resten av listan. Stämmer inte den första, vet du det innan du byggt något på den.
Ställ frågorna mot koden, inte mot minnet
- Använd ett verktyg som faktiskt kan söka i repot. Ett chattfönster utan filåtkomst kan bara gissa utifrån det du klistrat in.
- Be uttryckligen om fil och radnummer för varje påstående. Formuleringen "om du inte hittar det, säg att du inte hittar det" är värd att ha med.
- Fråga en sak i taget. Tre separata frågor ger tre kontrollerbara svar; en sammanslagen fråga ger en essä.
Läs vertikalt, inte horisontellt
Den vanligaste ansatsen är att gå igenom kodbasen mapp för mapp. Den är också den sämsta. Du får veta vad som finns, aldrig hur det hänger ihop, och du glömmer det första innan du är klar med det sista.
Alternativet är att välja ett verkligt användarfall och följa det hela vägen. En kund lägger en order. En användare byter lösenord. Ett nattjobb skickar fakturor. Börja i ingången, ta dig fram till det som skrivs till databasen, och gå inte utanför spåret på vägen.
Här är AI-hjälpen som mest värd. Att följa ett anrop genom fem lager av indirektion — ett gränssnitt, en fabrik, en konfigurerad implementation, en dekorator — är exakt det tålamodsarbete där en modell med sökåtkomst är snabbare än du. Frågan "vilken implementation av det här gränssnittet används när jobbet körs, och var kopplas den in?" har ett svar som går att slå upp och som tar tjugo minuter att gräva fram för hand.
När spåret är kartlagt, skriv ned det. Sju rader i en fil, från ingång till lagring. Det är den första sidan i din egen dokumentation, och den är värd mer än vilken genererad översikt som helst eftersom du har följt varje steg.
Förklaringen är en hypotes
Det här är artikelns kärna. En modells beskrivning av vad koden gör är inte dokumentation. Den är en kvalificerad gissning, formulerad med samma självsäkerhet oavsett om den bygger på lästa rader eller på mönsterigenkänning.
Skillnaden syns inte i texten. Den syns bara om du kontrollerar. Tre kontroller räcker långt, och alla tre tar minuter:
git log och git blame på den konstiga raden kan svara på frågan som koden ensam inte besvarar: varför. Har verktyget åtkomst till historiken kan det hjälpa dig att hitta och sammanfatta den, men kontrollera committen själv. Ett commit-meddelande från 2021 som säger "fix: kunden i Norge har annan momsregel" förklarar mer än fem stycken generell text.
En förklaring som är uppenbart fel upptäcker du direkt. En som är nästan rätt — rätt mekanism, fel villkor; rätt fil, fel gren av en if — går rakt in i din mentala modell och ligger kvar där i månader. Det är därför kontrollen ska göras på det du tänker bygga vidare på, inte på det som låter tveksamt.
Fyra saker AI regelmässigt missar i ärvd kod
Det finns kategorier där koden ensam inte ger modellen förutsättningar att ha rätt. Den visar vad systemet gör, men inte ett motiv som aldrig skrevs ned i kod, historik eller dokumentation.
if-sats. Modellen beskriver villkoret korrekt och missar att det är en policy som någon kan ändra.Börja med historik, dokumentation och produktionsloggar. Om svaret inte finns där har alla fyra samma motmedel, och det är inte en bättre prompt: det är en människa som var med. Spara frågorna som faller i de här kategorierna till en lista och ta dem samlat med den som kan projektet. Femton minuter med rätt person kan besvara sådant som en halv dag med modellen inte kommer åt.
Utforskningsprompten
En prompt som fungerar i ärvd kod ser annorlunda ut än en som ber om ny kod. Den ber om platser i stället för beskrivningar, och den ger uttryckligt utrymme att svara "vet inte". Utan det utrymmet fylls luckan med något som låter rätt.
Jag är ny i den här kodbasen och ska förstå [ett användarfall].
Följ flödet från ingången till det som skrivs till databasen. Ange fil och radnummer för varje steg.
Markera varje påstående som antingen läst i koden eller antaget utifrån mönster. Hittar du inte ett steg, skriv att du inte hittar det — gissa inte.
Avsluta med de tre frågor om det här flödet som du inte kan besvara utifrån koden.
Sista raden är den som ger mest. Frågorna som återstår är nästan alltid de intressanta — de handlar om affärsregler, historik och konventioner, alltså precis de kategorier där du behöver en människa. Du får en färdig agenda till samtalet med den som kan systemet, i stället för att sitta med en känsla av att något saknas.
Uppdelningen i "läst" och "antaget" är inte vattentät. Modellen kan ha fel om vad den själv har läst. Men den flyttar ändå de svagaste påståendena överst i högen, och det räcker för att du ska veta var kontrollen ska börja. Samma tänk som promptguiden beskriver: be om det verifierbara, inte om det som låter komplett.
Anteckningarna blir kontextfilen
Under den första veckan svarar du på samma frågor flera gånger, både för dig själv och för modellen. Det är slöseri att låta svaren bo i chatthistoriken. De hör hemma i en fil i repot.
Skriv ned det du har verifierat, inte det du har läst dig till. Fem rader efter första dagen, femton efter första veckan. Det är den kontextfil som verktygsguiden beskriver, byggd underifrån av saker du själv kontrollerat i stället för nedskriven i ett svep.
Vad som är värt en rad
- Ingångarna och vad var och en gör, i en mening styck.
- Var affärsreglerna bor — den enskilt mest tidsbesparande raden för nästa person.
- Så kör du projektet lokalt, inklusive steget som inte står i README men som krävs.
- Fällorna du gick i. Att två kataloger heter nästan lika och att fel är den som används.
När du därefter börjar fatta beslut om hur kodbasen ska utvecklas hör de inte hemma här, utan i en beslutslogg. Kontextfilen beskriver hur det ser ut; beslutsloggen varför det ser ut så.
Första ändringen
Målet med kartläggningen är inte fullständig förståelse. Det är att kunna göra en liten ändring med rimlig säkerhet om vad den påverkar. Den säkerheten kommer tidigare än man tror — ofta efter ett enda ordentligt genomgånget flöde.
Låt därför första ändringen vara liten på riktigt. En textsträng, en validering, en loggrad. Inte för att uppgiften är obetydlig, utan för att en liten diff i okänd kod är det billigaste sättet att ta reda på om din mentala modell stämmer. Går bygget igenom, gör testerna det de ska, hamnar ändringen där du trodde — då höll kartan. Det är samma resonemang som i små diffar vinner, med den skillnaden att du här inte bara verifierar koden utan din egen bild av systemet.