Miksi AI-koodausagenttisi ei muista projektia (ja miten se korjataan)

Oletko törmännyt tähän? AI-assistentti rakentaa sovellusta päiväkausia, mutta seuraavana aamuna uusi istunto alkaa tyhjästä. Selität projektin rakenteen uudelleen, etsit vanhoja päätöksiä chat-historiasta ja yrität koota kokonaisuuden sirpaleista.

Ongelma ei ole pelkästään konteksti-ikkunassa. Ongelma on, että projektin tila tallennetaan väärään paikkaan.

Miksi chat-pohjainen muisti ei toimi

Keskustelut toimivat ihmisten ja tekoälyn välisessä yhteistyössä, mutta ne ovat huonoja projektitietokantoina. Päätökset katoavat vierityspalkin alle, eikä ole yhtä totuuden lähdettä. Uusi istunto tarkoittaa aina alusta aloittamista.

Tämä näkyy konkreettisesti:

• Päätöksiä on vaikea löytää myöhemmin
• Eri istunnoissa syntyy ristiriitaisia valintoja
• Kukaan ei seuraa, mikä on ajan tasalla ja mikä vanhentunutta
• Agentti ei ymmärrä, mitä ollaan rakentamassa ja miksi

Nykyiset kielimallit osaavat kirjoittaa koodia. Pullonkaula on siinä, ymmärtävätkö ne projektin kokonaisuuden.

Ratkaisu: tallenna tila tiedostoihin

Paras tapa säilyttää projektin tila on tallentaa se samaan paikkaan kuin koodikin – versionhallittuihin tiedostoihin.

Ei wikejä. Ei erillisiä projektinhallintatyökaluja. Pelkkiä Markdown-tiedostoja, joissa on kevyt metatietolohko.

Esimerkki:

# Projektin arkkitehtuuripäätös

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

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

## Yleiskatsaus

Käytetään Stripen suoraa APIa wrapper-kirjaston sijaan, koska...

## Keskeiset päätökset

- Idempotency-avain kaikissa operaatioissa
- Asynkroninen webhook-käsittely eksponentiaalisella takaisinpalautuksella
- PII-tietoja ei tallenneta paikallisesti

## Avoimet kysymykset

- Pitäisikö rate limit -tila tallentaa välimuistiin?

Yksinkertaista, ei erikoissyntaksia. Vain otsikko, elinkaari, rooli, suhteet muihin tietueisiin ja sisältö.

CLI-työkalu tuo järjestyksen

Kun tila on tiedostoissa, CLI-työkalu voi hallita sitä:

• Luo uusia tietueita yhtenäisellä rakenteella
• Arkistoi valmiit tietueet poistamatta niitä
• Päivittää suhteet automaattisesti
• Listaa ja suodattaa tietueita
• Tarkistaa suhteiden eheys
• Luo indeksin automaattisesti

Agentti kysyy, ei kaiva

Sen sijaan että agentti yrittää ymmärtää projektia chat-historiasta, sille annetaan komento:

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

Agentti näkee, mitä on päätetty, mikä on kesken ja mikä on estynyt. Se voi myös muokata tilaa komennoilla:

docs create --role=log "Toteutettiin rate limiting"
docs archive --record=spec-v2-deprecated

Komennot pitävät huolen siitä, että metatiedot, sijainti ja indeksit pysyvät johdonmukaisina.

Uusi istunto, tunnettu tila

Uusi istunto ei enää tarkoita kontekstin menetystä. Agentti käynnistyy, hakee aktiiviset tietueet komennolla ja tietää heti, missä ollaan menossa. Vanha keskustelu voidaan sulkea – tila elää repositoriossa.

Kenelle tämä sopii

Lähestymistapa auttaa, jos:

• Käytät AI-pariohjelmointityökaluja usean päivän projekteissa
• Hallinnoit agenttien työnkulkua, joka jatkuu istunnosta toiseen
• Tarvitset CI/CD-putkessa projektin eheyden tarkistuksen
• Työskentelet tiimissä, jossa tarvitaan yhteinen käsitys päätöksistä
• Iteroit nopeasti ja haluat tietää, mikä spec on voimassa

Tämä ei korvaa Gitiä tai testejä. Se on kerros, joka pitää AI-avusteisen kehityksen johdonmukaisena ajan kuluessa.

Tylsä mutta tehokas

Paras osa tässä on sen tavallisuus. Ei uutta tietokantaparadigmaa. Ei erikoistyökaluja. Vain Markdown, Git ja CLI – työkalut, joita kehittäjät jo käyttävät.

Kun agentti vahingossa rikkoo suhteen, validointi huomaa sen. Kun indeksi on ristiriidassa, se on joko oikein tai väärin. Tämä infrastruktuuri erottaa tilanteen, jossa "agentti toimi jotenkin" tilanteesta, jossa "agentti ymmärsi projektin ja toimitti sen.