Därför glömmer din AI-kodagent hela projektet (och hur du fixar det)

Det är ett klassiskt mönster. Du kör ett längre projekt med en AI-kodassistent. Första dagen flyter det på – API:t läggs upp, testerna skrivs och dokumentationen kommer på plats. Andra dagen startar du en ny chatt och möts av en agent som inte vet vad som hänt. Tredje dagen sitter du med tiotusentals tokens och försöker pussla ihop vad som egentligen beslutades förra gången.

Felet ligger inte i kontextfönstret. Det ligger i var projektets tillstånd sparas.

Chatt som minne är en dålig idé

Chattar fungerar bra för samtal. De fungerar dåligt som projektarkiv.

När du använder AI-verktyg dag efter dag märker du snabbt problemen:

• Beslut försvinner i chattflödet och går inte att hitta utan att scrolla igenom tusentals rader.
• Det finns ingen enda källa till sanning. Vilken version av API-specen gäller egentligen?
• Varje ny session börjar från noll, oavsett hur mycket historik som finns.
• Olika agenter tar olika beslut och motsägelserna staplas på varandra.

Det som egentligen begränsar AI-assisterad utveckling är inte kodgenereringen. Det är agentens förmåga att förstå vad som byggs och varför.

Spara tillstånd som kod

Lösningen är enkel: behandla projektets tillstånd som vanliga filer i repot.

Inga wikis. Inga separata verktyg. Bara strukturerade Markdown-filer med ett lätt metadata-block högst upp.

Exemplet nedan visar hur en sådan fil kan se ut:

# Projektbeslut: API-arkitektur

Lifecycle: active
Role: spec
Project: payment-service
Updated: 2024-01-15

Related:
- implements: charter-payment-api
- pairs-with: implementation-log-payment-core

## Översikt

Vi använder Stripes direkta API istället för ett wrapper-bibliotek eftersom...

## Viktiga beslut

- Idempotency keys på alla operationer
- Asynkron webhook-hantering med exponential backoff
- PII får aldrig lagras lokalt

## Öppna frågor

- Ska vi cacha rate limit-tillstånd?

Formatet är medvetet enkelt. En titel, lite metadata och själva innehållet. Inget speciellt syntax, ingen databas.

Vad du får med ett CLI-verktyg

Med ett enkelt CLI-verktyg kan du:

• Skapa nya poster med rätt struktur
• Arkivera färdiga poster utan att ta bort dem
• Flytta poster och uppdatera relationer automatiskt
• Lista poster med filter
• Validera att relationer pekar på riktiga poster
• Generera ett index utan manuellt arbete

Agenten frågar istället för att gissa

Istället för att be agenten "läsa chatten och förstå läget" ger du den ett kommando:

docs list --project=payment-service --role=spec
docs list --lifecycle=active
docs check

Agenten kan nu söka efter projektets tillstånd istället för att gräva i chattloggar. Den ser vad som är beslutat, vad som pågår och vad som är blockerat.

Ännu viktigare: agenten kan ändra tillstånd via kommandon istället för att redigera filer direkt. Kommandon som docs create, docs archive och docs touch ser till att metadata, plats och index hålls synkade.

Nytt chattfönster – samma projektläge

Det intressanta händer när du startar en ny session. Istället för att tappa kontext gör agenten följande:

1. Den kör docs list för att se vad som är aktivt
2. Den läser implementationsloggen från igår
3. Den kollar specen för att veta vad som ska byggas

Ingen chatthistorik behövs. Tillståndet ligger i repot där det hör hemma.

När det här spelar roll

Det här mönstret är värt att titta på om du:

• Bygger med AI-parprogrammering över flera dagar
• Kör agentflöden som behöver återupptas utan att skicka hela kontexten
• Vill ha CI/CD som kan validera att projektet hänger ihop
• Arbetar i team och behöver en gemensam bild av vad som är beslutat
• Itererar snabbt och lätt tappar bort vad specen egentligen säger

Det ersätter inte Git eller kodgranskning. Det är limmet som gör att AI-assisterad utveckling håller ihop över tid.

Det tråkiga som faktiskt fungerar

Det bästa med det här är hur enkelt det är. Du använder Markdown, Git och CLI – verktyg du redan har. Inga nya databaser, inga specialverktyg.

Valideringen fångar fel. Indexet visar vad som är aktuellt. State drift upptäcks innan det blir ett problem.

Det är den typen av infrastruktur som känns självklar i efterhand. Men det är också det som skiljer "agenten funkade hyfsat" från "agenten förstod projektet och levererade".