Tekoälyn sanakirja

Liikkuva nimike, ei teknologia. ”Tekoäly” ei tarkoita pysyvää asiaa kuten malli tai token — se viittaa siihen, mitä tietokoneet osaavat tehdä uutena ja vaikuttavana. Tällä hetkellä sillä tarkoitetaan suuria kielimalleja. Aiemmin se on viitannut hyvin erilaisiin asioihin:

Nimitys liikkuu tunnetun mekanismin ansiosta, jota kutsutaan joskus tekoälyvaikutukseksi: kun tekniikka toimii luotettavasti, se nimetään uudelleen — se onkin ”vain” hakua, ”vain” tilastoja — ja ”tekoäly” siirtyy seuraavaan ratkaisemattomaan asiaan. Havainto on vanha. Bertram Raphael muotoili sen näin vuonna 1971: ”Tekoäly on yhteisnimitys ongelmille, joita emme vielä osaa ratkaista kunnolla tietokoneella.” Larry Teslerin noin vuodelta 1979 peräisin oleva versio kuuluu: ”Älykkyyttä on kaikki se, mitä koneet eivät vielä osaa.”

Siksi tekoälystä käytävissä keskusteluissa puhutaan niin usein toistensa ohi. Väitteeseen ”tekoäly ei osaa päätellä” tai ”tekoäly on ylihypetettyä” sisältyy piilotettu aikaleima — se voi koskea asiantuntijajärjestelmiä, 2010-luvun kuvantunnistimia tai viime kuun kielimallia, ja jokainen viittaus tukee eri päätelmää. Kun tekoälyä koskeva keskustelu jumittuu, ratkaisuna on yleensä korvata sana sillä täsmällisellä termillä, jota oikeasti tarkoitetaan: malli, agenttiympäristö, agentti tai sille annettu konteksti.

Vältä: sanaa ”tekoäly” teknisissä väitteissä — nimeä sen sijaan se osa, jota tarkoitat. ”Tekoälyavusteinen koodaus” käytännön nimityksenä sopii; ”tekoäly hallusinoi” ei.

Käyttö:

”Teknologiajohtaja haluaa tietää, voisiko tekoäly hoitaa triagejonon.”

”Tarkenna ennen rajauksen tekemistä — hän tarkoittaa kielimallia agenttiympäristössä, jolla on pääsy tikettijärjestelmään. Pelkkä ’tekoäly’ ei ole määrittely.”

Parametrit. Tilaton — tekee seuraavan tokenin ennustusta eikä mitään muuta. ”Claude Opus 4.x” ja ”GPT-5.x” ovat malleja. Malli ei yksinään kykene agenttimaiseen toimintaan; se on liitettävä agenttiympäristöön.

Mallit eivät pysty lukemaan tiedostoja, suorittamaan komentoja, selaamaan verkkoa eivätkä muistamaan eilistä — ne ottavat tokeneita sisään ja ennustavat tokeneita ulos kerran jokaisella mallintarjoajan pyynnöllä. Kaikki, mikä tuntuu agentin työskentelyltä — työkalujen valitseminen, tulosten lukeminen ja toistaminen tehtävän valmistumiseen saakka — on agenttiympäristö, joka orkestroi useita tällaisia ennustuksia peräkkäin.

Mallintarjoajat toimittavat malleja eri tasoina: suuri, älykkäin mutta hidas ja kallis malli sekä pienemmät, nopeammat ja halvemmat mutta vähemmän kyvykkäät mallit. Tason valinta on todellinen päätös — raskas malli suunnitteluun ja vaikeaan virheenjäljitykseen, kevyt mekaanisiin muutoksiin — ja agenttiympäristöissä voi vaihtaa tasoa kesken istunnon.

Sanan tarkka käyttö terävöittää myös diagnostiikkaa. ”Malli on tässä huono” on täsmällinen väite — sama malli käyttäytyy usein täysin eri tavoin toisessa agenttiympäristössä tai eri kontekstissa. Ennen mallin syyttämistä tarkista, mitä sille annettiin: useimmat pettymykset johtuvat kontekstista tai agenttiympäristöstä, eivät parametreista.

Käyttö:

”Pitäisikö suunnitteluvaiheessa vaihtaa Sonnet Opukseen?”

”Kokeile — mutta agenttiympäristö tekee tässä suurimman osan työstä. Mallin vaihto ei auta, jos järjestelmäkehote ja työkalut ovat väärät.”

Mallin sisällä olevat luvut — niitä on usein miljardeja — joita säädetään koulutuksen aikana. Kaikki, mitä malli ”tietää”, on niissä. Koulutus asettaa ne; päättely käyttää niitä muuttumattomina. Kutsutaan myös painoiksi.

Mekaanisesti parametrit muuttavat syötteen tulosteeksi. Seuraavan tokenin ennustaminen on valtava laskutoimitus: konteksti-ikkunan tokenit syötetään sisään, kerrotaan parametrien läpi, ja tuloksena saadaan ennuste seuraavasta tokenista. Mallissa ei ole faktatietokantaa eikä koodin hakutaulukkoa — ainoastaan nämä luvut järjestettyinä niin, että lasku tuottaa yleensä hyödyllistä tulosta. Koulutuksesta muistettavat faktat, kuten standardikirjaston API, ovat parametrista tietoa: ne ovat parametreissa eivätkä haetu muualta.

Tärkeää on ymmärtää, että parametrit jäädytetään koulutuksen jälkeen. Mikään istunnossa tekemäsi ei muuta niitä — ei antamasi korjaus, näyttämäsi koodikanta eikä opittu virhe. Jokainen istunto toimii samoilla luvuilla. Siksi malli on tilaton, sen sisäinen tieto päättyy tietorajaukseen ja kaikki projektikohtainen tieto täytyy tuoda kontekstin kautta. Parametrit muuttuvat vain lisäkoulutuksella, joka tuottaa käytännössä eri mallin.

Käyttö:

”Voimmeko hienosäätää sen koodikannallamme?”

”Se päivittäisi parametrit — tuloksena olisi eri malli. Yhden projektin tapauksessa koodikannan lataaminen kontekstiksi on lähes aina uudelleenkoulutusta halvempaa.”

Prosessi, joka asettaa mallin parametrit altistamalla sen valtaville tekstimäärille ja säätämällä parametreja seuraavan tokenin ennustamisen parantamiseksi. Kertaluonteinen, kallis mallintarjoajan tekemä prosessi. Sisältää sekä esikoulutuksen (laajan päävaiheen) että jälkikoulutuksen (myöhemmät tarkennukset, kuten ohjeiden seuraaminen ja turvallisuus); tällä sanakirjan tarkkuustasolla erottelulla ei ole merkitystä.

Mekanismi on toisto suuressa mittakaavassa: näytä mallille tekstijakso, pyydä sitä ennustamaan seuraava token, siirrä parametreja kohti todellista seuraavaa tokenia ja toista biljoonien tokenien ajan. Faktoja tai sääntöjä ei tallenneta sellaisinaan — kaikki, mitä malli ”tietää”, on ennustamisessa kehittymisen sivuvaikutus, joka tiivistyy parametreihin parametriseksi tiedoksi.

Kaksi seurausta vaikuttaa jokapäiväiseen työhön. Koulutus päättyy tiettynä ajanhetkenä, joten mallilla on tietoraja — se ei ole nähnyt viime kuussa päivittämääsi kirjastoversiota. Et myöskään voi kouluttaa mallia itse: kun malli ei tunne koodikantaasi, käytäntöjäsi tai sisäisiä API:eitasi, ratkaisu ei koskaan ole ”opeta mallia” — lisää aineisto sen sijaan kontekstiin, joka on ainoa hallitsemasi syöte.

Käyttö:

”Voimmeko saada sen tuntemaan sisäisen API:mme?”

”Ei kouluttamalla — se on mallintarjoajalta kuukausia vievä prosessi. Lataa API-dokumentit kontekstiin sen sijaan; se on vipu, johon voit oikeasti vaikuttaa.”

Koulutetun mallin ajamista tulosteiden tuottamiseksi — näin tapahtuu jokaisella mallintarjoajan pyynnöllä. Parametrit pysyvät muuttumattomina; malli vain tekee seuraavan tokenin ennustusta sille annetussa kontekstissa. Halpaa koulutukseen verrattuna, mutta laskutetaan tokeneittain, ja se on mallin käytön suurin kustannuserä.

Mallin elinkaari jakautuu kahteen vaiheeseen:

Mikään, mitä teet päättelyn aikana, ei kirjoita tietoja takaisin parametreihin — siksi tänään tekemäsi korjaus ei säily huomiseen. Seuraavassa istunnossa saman virheen tekevä malli ei ole sivuuttanut sinua, vaikka selitit korjauksen huolellisesti; se ei pysty oppimaan keskustelusta. Malli on tilaton, joten jatkuvuuden täytyy tulla sen ulkopuolelta — konteksti-ikkunasta tai muistijärjestelmästä.

Mekanismi selittää myös laskutuksen. Jokainen pyyntö ajaa mallin koko kontekstin yli, joten kustannus kasvaa syöte- ja tulostetokenien määrän mukana, ja kymmeniä työkalu-kutsuja tekevä agentti maksaa päättelystä jokaisella kierroksella. Siksi kontekstin koko on sekä kustannus- että laatukysymys.

Käyttö:

”Miksi lasku kasvaa käytön mukana eikä ole kiinteä lisenssi?”

”Maksat päättelystä — jokaisessa mallintarjoajan pyynnössä malli ajetaan tarjoajan laitteistolla. Koulutus on jo tehty, mutta päättelystä kertyy kustannuksia pyyntökohtaisesti, ja yhdestä vuorosta voi tulla monta pyyntöä työkalukutsujen vuoksi.”

Ponnistus on säädin sille, kuinka paljon malli käyttää päättelyyn ennen vastaamista. Se asetetaan kullekin mallintarjoajan pyynnölle ja säätelee, kuinka pitkään malli ajattelee ennen kuin alkaa kirjoittaa näkyvää vastausta. Ajattelu tuotetaan päättelyn aikana kuten kaikki muukin; agenttiympäristö usein piilottaa sen, mutta se on todellista mallin tekemää työtä.

Suurempi ponnistus maksaa enemmän ja kestää kauemmin. Päättely tuotetaan tokeneina, laskutetaan tulostetokeneina, vaikka et koskaan näkisi niitä, ja tuotetaan yksi token kerrallaan — joten ponnistuksen kasvattaminen pidentää vastausta edeltävää odotusta ja kasvattaa laskua. Kompromissina harkinta lisääntyy nopeuden ja kustannusten kustannuksella.

Useimmat agenttiympäristöt esittävät ponnistuksen lyhyenä portaikkona:

Väärän asetuksen oireet toimivat molempiin suuntiin. Jos ponnistus on vaikeaan ongelmaan liian matala, saat itsevarman mutta pinnallisen vastauksen, joka ohitti tarvittavan päättelyn — se näyttää hyvältä mutta on väärä tavalla, joka maksaa myöhemmin. Aseta tasoksi maksimi yhden rivin uudelleennimeämiseen, niin odotat pitkää mietintää, joka ei tuota mitään sellaista, mitä alin taso ei olisi antanut.

Sovita ponnistus tehtävään, älä istuntoon. Nosta sitä osuudelle, joka todella vaatii vaikeaa päättelyä, ja laske sitä ympärillä tehtävään rutiinityöhön.

Käyttö:

”Se mokaa tätä samanaikaisuuskorjausta jatkuvasti — olen selittänyt sen uudelleen kolmesti.”

”Nosta ponnistusta. Tämä virhe vaatii paljon päättelyä, eikä oletusasetus ajattele tarpeeksi pitkään ennen lähestymistavan valitsemista.”

Pienin yksikkö, jota malli lukee ja kirjoittaa. Suunnilleen sanan kokoinen, mutta ei täsmälleen — tavalliset sanat ovat yksi token, harvinaiset tai pitkät jakautuvat useiksi. Konteksti-ikkunan koko, kustannus ja viive mitataan tokeneina.

Teksti muuttuu tokeneiksi tokenisoijan avulla: kymmenistä tuhansista paloista koostuvaksi kiinteäksi sanastoksi, joka opitaan ennen koulutusta ja jonka mukaan mikä tahansa syöte jaetaan sanaston osien jonoksi. Malli ei koskaan näe merkkejä tai sanoja — jokainen tekstinpala muunnetaan tokeneiksi syötettäessä, ja seuraavan tokenin ennustus tuottaa tulosteen yksi token kerrallaan.

Nyrkkisääntönä yksi token on noin kolme neljäsosaa englanninkielisestä sanasta, joten tuhat tokenia on noin 750 sanaa. Koodi on vähemmän ennakoitavaa: tavalliset avainsanat ja ilmaukset tokenisoituvat tiiviisti, mutta luodut tunnisteet, tiivisteet, base64-merkkijonot ja minifioitu tuloste jakautuvat moneksi tokeniksi ”sanaa” kohden. Usein tokenisoijan lähdemateriaalissa esiintyvä teksti saa lyhyet ja tehokkaat koodaukset; harvinainen teksti pilkotaan moniksi pieniksi osiksi. Tiiviste `a3f9c2e1` ei ole esiintynyt missään, joten se jakautuu moneksi tokeniksi, kun taas `function` on yksi token. Siksi pieneltä näyttävä, epätavallisia merkkijonoja sisältävä tiedosto voi viedä yllättävän suuren osan konteksti-ikkunasta.

Tokenit ovat kaiken muun mittayksikkö. Kustannus lasketaan tokeneittain — tarjoajat laskuttavat syötetokenit ja tulostetokenit erikseen. Nopeus mitataan tokeneina sekunnissa, koska tuloste tuotetaan yksi token kerrallaan. Konteksti-ikkunassa on kiinteä määrä tokeneita, joten tiedostojesi tokenmäärä ratkaisee, kuinka paljon sinne mahtuu.

Vältä: ”sana” — tokenrajat eivät vastaa sanarajoja, ja tokenit sekunnissa tai tokenit dollaria kohti ovat käytännössä olennaisia yksiköitä.

Käyttö:

”Kuinka suuri tästä kehotteesta tulee?”

”Aja se tokenisoijan läpi — skeema on tiivis, mutta JSON-avaimet ovat outoja, joten ne jakautuvat useammaksi tokeniksi kuin arvaat.”

Mitä malli todella tekee. Se saa kontekstin, näytteistää yhden seuraavan tokenin, liittää sen ja suorittaa taas. Jokainen tuloste — virke, työkalukutsu tai tuhannen rivin tiedosto — rakennetaan yksi token kerrallaan. Mallilla ei ole muuta toimintatilaa.

Jokainen askel toimii samalla tavoin: konteksti-ikkunan tokenit kulkevat parametrien läpi, ja tuloksena saadaan todennäköisyys jokaiselle sanaston tokenille — tämän todennäköisyys seuraavana on suuri, tuon pienempi. Yksi token näytteistetään näistä todennäköisyyksistä, liitetään mukaan ja silmukka suoritetaan uudelleen hieman pidemmällä kontekstilla. Näytteistys selittää, miksi sama kehote tuottaa eri ajokerroilla eri tulosteita: epädeterminismi kuuluu mekanismiin eikä ole päälle lisätty virhe.

Kun mekanismi pidetään mielessä, muuten kummallisilta näyttävät toimintatavat selittyvät. Malli ei koskaan tarkista, onko token tosi ennen sen tuottamista — ainoastaan sen, onko se todennäköinen — ja tämä on hallusinaation juuri. Se sitoutuu tokeneihin yksi kerrallaan, joten itsevarmalta kuulostava aloitusvirke voi ohjata loppuvastauksen väärään suuntaan. Koska tulostetokenit syntyvät ehdottomasti yksi kerrallaan, generointinopeus asettaa alarajan sille, kuinka nopeasti agentti voi työskennellä.

Käyttö:

”Miten agentti ’päättää’ kutsua työkalua?”

”Ei se päätä — kaikki perustuu seuraavan tokenin ennustamiseen. Työkalukutsu on vain rakenteinen merkkijono, jonka agenttiympäristö poimii tulostevirrasta.”

Sama syöte voi tuottaa eri tulosteen. Suorita malli kahdesti samalla kontekstilla, niin voit saada kaksi erilaista vastausta — joskus vaihtuu yksi sana, joskus koko lähestymistapa. Mikään koodissasi ei tarvitse muuttua, jotta näin kävisi.

Tämä on mallien tekstintuotannon ja mallintarjoajien pyyntöjen käsittelyn ominaisuus. Päättelyn aikana malli muodostaa todennäköisyysjakauman mahdollisista seuraavista tokeneista ja valitsee niistä yhden näytteistämällä — yleensä mukana on tarkoituksellisesti jonkin verran satunnaisuutta, koska todennäköisimmän tokenin toistuva valinta tuottaa itseään toistavaa ja heikompilaatuista tekstiä. Yksi varhain eri tavalla näytteistetty token muuttaa kaikkia vastauksen myöhempiä tokeneita; näin yhdestä eri sanasta tulee kokonaan eri lähestymistapa. Tarjoajan puolella tulee lisää vaihtelua: pyynnöt niputetaan jaetulla laitteistolla, ja pienet liukulukuerot nippujen välillä voivat ratkaista kahden tokenin tasaisen valinnan. Tätä kaikkea ei voi poistaa yhdellä asetuksella.

Odota vaihtelua siinä, miten agentti käsittelee saman tehtävän. Useimmat vastaukset osuvat laadultaan järkevän kellokäyrän sisään — muuten epädeterminismi ei olisi siedettävää — mutta ääripäitä on: joinakin päivinä malli tuntuu terävältä, toisina siltä kuin se olisi menettänyt juonen. Sama tehtävä, eri nopanheitot. Tästä seuraa kaksi käytännön asiaa. Uusi yritys on kelvollinen strategia: epäonnistunut yritys on yksi otos jakaumasta, ja uusi yritys samalla tehtävällä voi yksinkertaisesti onnistua paremmin. Varmennus on myös tärkeämpää kuin deterministisillä työkaluilla — agentin toimintaa ei voi testata kerran ja olettaa sen toistuvan, joten automaattisten tarkistusten täytyy havaita huonot otokset.

Älä paisuttele tästä kertomusta. Ihmiset etsivät kuvioita, ja huonojen ajojen sarja voi tuntua todisteelta siitä, että ”malli huononi tällä viikolla”. Tavallisesti kyse on vain jakaumasta.

Käyttö:

”Claude on ollut tänään surkea. Julkaisivatko he huonomman version?”

”Tuskin — mallin tuloste ei ole deterministinen. Samassa tehtävässä tulee hyviä ja huonoja päiviä. Yritä huomenna uudelleen ennen kuin alat etsiä syytä.”

Mikä tahansa mallille päättelyä tarjoava palvelu. Yleensä etäpalvelu (Anthropic, OpenAI, Google), mutta se voi toimia myös paikallisesti — Ollama, LM Studio tai llama.cpp omalla koneellasi. Agenttiympäristö ei aja mallia itse vaan pyytää tarjoajaa tekemään sen.

Tarjoaja omistaa koneiston: parametrit ovat sen laitteistolla, ja jokaisessa mallintarjoajan pyynnössä agenttiympäristö lähettää tokeneita verkon yli ja saa ennusteet takaisin. Siksi tarjoaja aiheuttaa kokonaisen joukon ongelmia, jotka luetaan virheellisesti mallin tai agenttiympäristön syyksi — nopeusrajoitukset, heikentynyt kapasiteetti ja käyttökatkot ovat tarjoajan puolella. Kun agentti jumiutuu kesken istunnon tai antaa virheen jokaisella vuorolla, tarkista ensin tarjoajan tilasivu.

Tarjoaja määrittää myös kaupalliset ehdot: syöte- ja tulostetokenien hinnat, etuliitevälimuistin alennukset sekä ylipäänsä saatavilla olevat mallit. Tarjoaja ja mallin valmistaja voivat olla eri yrityksiä — Bedrock, Vertex ja OpenRouter tarjoavat muiden tekemiä malleja.

Paikalliset tarjoajat vaihtavat suorituskyvyn hallintaan: omalle laitteistolle mahtuvat mallit ovat paljon pienempiä kuin huippumallit, mutta mitään ei poistu koneelta eikä tokeneista tule laskua.

Käyttö:

”Voimmeko ajaa tämän offline-tilassa asiakkaan eristetyssä verkossa?”

”Vaihda mallintarjoajaksi paikallinen palvelu — Ollama tai llama.cpp heidän koneellaan. Agenttiympäristö ei välitä, se kutsuu vain eri päätepistettä.”

Kaikki mallin ympärillä, mikä tekee siitä agentin: työkalut, järjestelmäkehote, konteksti-ikkunan hallinta, käyttöoikeudet ja koukut. Claude.ai ja Claude Code käyttävät samaa mallia mutta käyttäytyvät eri tavoin, koska niiden agenttiympäristöt eroavat toisistaan.

Malli itse tekee vain yhden asian: ottaa tekstiä sisään ja tuottaa tekstiä ulos. Se ei pysty lukemaan tiedostoa, suorittamaan komentoa tai muistamaan edellistä vuoroa. Agenttiympäristö tarjoaa kaiken tämän. Se kokoaa kontekstin jokaiselle mallintarjoajan pyynnölle, suorittaa mallin pyytämät työkalukutsut, palauttaa työkalutulokset, tallentaa istunto-historian, kysyy lupaa riskialttiisiin toimiin ja päättää, milloin tiivistetään. Agenttisilmukka — malli ehdottaa, agenttiympäristö suorittaa, ja sama toistuu — on agenttiympäristön toteuttama.

Tämä on tärkeää vianmäärityksessä. Kun käyttäytyminen eroaa kahden tuotteen välillä tai eilisen ja tämän päivän välillä, muuttuja ei usein ole malli vaan agenttiympäristö. Erilainen järjestelmäkehote, työkalujoukko, muuttunut oletuskäyttöoikeus tai uusi kontekstinhallintastrategia muuttaa käyttäytymistä muuttamatta mallia lainkaan. Se tarkoittaa myös, että suurin osa asetuksistasi sijaitsee agenttiympäristössä: AGENTS.md-tiedostot, käyttöoikeusasetukset ja koukut ovat ohjeita agenttiympäristölle, eivät mallille.

Esimerkkejä: Claude Code, Cursor, Codex CLI — sekä Claude.ai, joka on chat-agenttiympäristö eikä koodausagenttiympäristö.

Käyttö:

”Sama malli — miksi Claude Code muokkaa tiedostoja ja Claude.ai vain vastaa kysymyksiin?”

”Eri agenttiympäristöt — Claude Codessa on tiedostojärjestelmä-työkalut, erilainen järjestelmäkehote ja käyttöoikeuskerros. Malli ei ole tässä muuttuja.”

Yksi kierros agenttiympäristöstä mallintarjoajalle. Agenttiympäristö lähettää nykyisen kontekstin; tarjoaja palauttaa yhden vastauksen (työkalukutsun tai lopullisen vastauksen). Yksi käyttäjäviesti voi synnyttää monta mallintarjoajan pyyntöä, jos agentti kutsuu työkaluja — jokainen työkalutulos käynnistää uuden pyynnön.

Jokainen pyyntö sisältää kaiken: järjestelmäkehotteen, koko keskustelun siihen asti ja kaikki työkalutulokset. Malli on tilaton, joten tarjoaja ei säilytä mitään pyyntöjen välillä — pyyntö neljäkymmentä lähettää uudelleen sen, mitä pyyntö kolmekymmentäyhdeksän lähetti, sekä yhden uuden työkalutuloksen. Etuliitevälimuisti tekee tämän toiston kohtuuhintaiseksi.

Pyyntö on myös laskutuksen yksikkö. Syötetokenit, tulostetokenit ja välimuivialennukset lasketaan pyynnöittäin. Siksi harmittomalta näyttävä kysymys voi maksaa yllättävän paljon: kustannus ei ole verrannollinen viestiisi vaan pyyntöjen määrään kerrottuna kunkin pyynnön kantaman kontekstin koolla.

Pyyntö kannattaa erottaa vuorosta. Vuoro on yksi keskustelunvaihto kanssasi, ja yksi vuoro — ”korjaa epäonnistuva testi” — voi edetä pyyntöketjuna:

Kuusi pyyntöä yhtä vuoroa kohti — jokainen lähettää koko kontekstin uudelleen. Kun ihmettelet, minne tokenit katosivat, laske pyynnöt äläkä vuoroja.

Käyttö:

”Yksi kysymys kulutti neljäkymmentätuhatta tokenia?”

”Katso työkalukutsuja — kaksitoista grep-hakua, kahdeksan lukua ja neljä muokkausta. Jokainen työkalutulos käynnistää uuden mallintarjoajan pyynnön, ja koko istunnon etuliite lähetetään joka kerta uudelleen.”

Tokenit, jotka agenttiympäristö lähettää jokaisessa mallintarjoajan pyynnössä — järjestelmäkehotteen, keskusteluhistorian, työkalutulokset ja kaiken, mitä malli lukee ennen kirjoittamista. Laskutetaan alemmalla hinnalla kuin tulostetokenit, koska niiden käsittely on halvempaa kuin tulostetokenien tuottaminen.

AI-koodauksessa syötetokenit muodostavat suurimman osan laskusta. Malli on tilaton, joten jokainen vuoro lähettää koko istunnon uudelleen syötteenä: ensimmäisen viestisi, jokaisen vastauksen ja kaikki työkalutulokset sen jälkeen. Vuoron viisikymmentä syöte sisältää edelliset neljäkymmentäyhdeksän vuoroa. Yhdellä mallintarjoajan pyynnöllä voidaan tuottaa muutama sata tulostetokenia mutta lähettää uudelleen satatuhatta kertynyttä historiaa sisältävää syötetokenia.

Etuliitevälimuisti vähentää kustannusta: aiempaa pyyntöä täsmälleen vastaava historia laskutetaan halpoina välimuistitokeneina täysihintaisten syötetokenien sijaan. Jos syötekustannukset silti tuntuvat, pienennä uudelleen lähetettävää sisältöä — tyhjennä tai tiivistä istunto tehtävien välissä.

Käyttö:

”Lasku on suuri, vaikka agentti kirjoittaa tuskin mitään.”

”Syötetokenit — jokainen vuoro lähettää koko istunnon uudelleen. Ilman etuliitevälimuistia maksat historiasta jokaisessa pyynnössä.”

Tokenit, jotka malli tuottaa. Laskutetaan suuremmalla hinnalla kuin syötetokenit — usein noin viisinkertaisella — sillä niiden tuottaminen vaatii enemmän laskentatehoa.

Kaikki mallin kirjoittama lasketaan: lukemasi teksti, sen tuottama koodi, työkalukutsut ja mahdollinen laajennettu ajattelu ennen vastausta. Viimeksi mainittu yllättää monia — päättelytokenit laskutetaan tulosteena silloinkin, kun agenttiympäristö ei niitä usein näytä. Ponnistuksen kasvattaminen kuluttaa niitä enemmän.

Tulostetokenit määrittävät myös istunnon tahdin. Malli lukee syötteen nopeasti mutta tuottaa tulosteen yksi token kerrallaan, joten kun vuoro tuntuu hitaalta, lähes aina tulostetta kirjoitetaan eikä syötettä lueta. Pitkä odotus tarkoittaa tavallisesti, että pitkä vastaus on tulossa.

Käyttö:

”Refaktorointi-istunto kuluttaa saldoa, vaikka syötteet ovat pieniä.”

”Agentti kirjoittaa kokonaisia tiedostoja uudelleen eikä tee korjaustiedostoja. Tulostetokenit maksavat noin viisinkertaisesti syötetokenien hinnan — pyydä sitä tuottamaan muokkaukset, niin lasku pienenee.”

Tarjoajan puolella oleva tietovarasto, jonka ansiosta peräkkäiset mallintarjoajan pyynnöt voivat jättää yhteisen etuliitteen uudelleenkäsittelyn väliin. Kun pyynnön alku vastaa äskettäisen pyynnön alkua — sama järjestelmäkehote, sama historia tiettyyn kohtaan saakka — tarjoaja käyttää aiemman työn uudelleen ja laskuttaa nämä tokenit välimuistitokeneina paljon alemmalla hinnalla.

Välimuisti kannattaa, koska istunnot kasvavat vain lisäämällä sisältöä loppuun. Jokainen pyyntö lähettää koko historian uudelleen syötetokeneina (katso kyseinen termi syyksi), ja tavallisessa istunnossa historia muuttuu vain lopusta — jokainen pyyntö on edellinen pyyntö muutamalla uudella viestillä lisättynä. Tarjoaja käsittelee pitkän yhteisen alun kerran, tallentaa tuloksen ja jatkaa etuliitteen lopusta. Ilman välimuistia 50 vuoron istunnossa maksettaisiin ensimmäisen vuoron uudelleenkäsittelystä viisikymmentä kertaa.

Myös välimuistimerkinnät vanhenevat. Lämpimän merkinnän kesto vaihtelee mallintarjoajittain — tyypillisesti minuutteja, ei tunteja. Jos istunto on käyttämättömänä ikkunaa pidempään, seuraava pyyntö rakentaa etuliitteen kerran uudelleen täyteen hintaan ennen välimuistin toiminnan jatkumista. Tämä koskee lähinnä agenttiympäristöjen kehittäjiä; käyttäjänä huomaat, että pitkän tauon jälkeiset pyynnöt maksavat enemmän kuin sitä edeltäneet.

Käyttö:

”Miksi lasku kasvoi kesken istunnon?”

”Agenttiympäristö alkoi lisätä nykyisen ajan järjestelmäkehotteeseen jokaisella vuorolla. Etuliitevälimuisti rikkoutuu ensimmäisen muuttuneen tokenin kohdalla, joten jokainen sitä seuraava pyyntö laskutettiin täydellä hinnalla.”

Syötetokenit, jotka tarjoaja on tallentanut välimuistiin aiemmasta mallintarjoajan pyynnöstä, jotta niitä ei tarvitse käsitellä uudelleen. Kun peräkkäisillä pyynnöillä on yhteinen etuliite, tarjoaja käyttää työn uudelleen etuliitevälimuistin avulla ja laskuttaa välimuistissa olevan osuuden paljon halvemmalla. Tämä tekee pitkistä istunnoista kohtuuhintaisia — ilman sitä jokainen vuoro maksaisi koko historiasta uudelleen.

Tämä on tärkeää istuntojen laskutustavan vuoksi. Malli on tilaton, joten jokainen pyyntö lähettää koko keskustelun uudelleen — järjestelmäkehotteen, jokaisen viestin ja jokaisen työkalutuloksen — syötetokeneina. Viidennenkymmenennen vuoron kohdalla jokainen pyyntö sisältää viidenkymmenen vuoron historian, josta maksaisit joka kerta täyden hinnan. Välimuisti muuttaa laskelmaa: aiemmin identtisessä etuliitteessä käsitellyt tokenit laskutetaan välimuistitokeneina, usein kymmenesosalla syötetokenien hinnasta tai vielä vähemmällä. Pitkässä istunnossa suurin osa lähettämistäsi tokeneista on välimuistitokeneita ja lasku pysyy järkevänä.

Esimerkistä näkee, mitkä tokenit välimuistitetaan ja mitkä eivät. Kukin kirjain tarkoittaa keskustelusisältölohkoa; jokainen pyyntö lähettää tähänastisen keskustelun:

Välimuisti on tietyllä tavalla hauras: se vastaa vain täsmällisiä etuliitteitä. Jos jokin aiempi keskustelun osa muuttuu — agenttiympäristö järjestää sisällön uudelleen, aikaleima päivittyy tai tiedoston esitysmuoto muuttuu — välimuistiosuma katkeaa siitä kohdasta, ja kaikki sen jälkeinen laskutetaan täydellä syötetokenien hinnalla. Välimuistit vanhenevat myös muutaman minuutin käyttämättömyyden jälkeen, joten pitkän tauon jälkeen jatkettu istunto maksaa historiastaan kerran uudelleen. Kun istunnon kustannus kasvaa ilman selvää syytä, vertaa välimuistitokeneita ja syötetokeneita käyttöraportissa — rikkoutunut välimuisti näkyy siellä ensimmäisenä.

Käyttö:

”Pitkien istuntojen kustannukset ovat kamalat — kahdeksan dollaria refaktoroinnista.”

”Tarkista välimuistitokenit. Jos agenttiympäristö muuttaa järjestelmäkehotteen tai tiedostojen järjestystä vuorojen välillä, etuliite katkeaa ja jokainen pyyntö maksaa uudelleen täyden syötetokenien hinnan.”

Ei vie tietoa eteenpäin. Malli on tilaton mallintarjoajan pyyntöjen välillä — jokainen pyyntö lähettää koko konteksti-ikkunan uudelleen, koska malli ei pysty näkemään mitään muuta. Agentti on oletuksena tilaton istuntojen välillä: uusi istunto alkaa tyhjänä, jälkiä aiemmista ei ole. Vastakohta termille tilallinen.

Itse malli on pysyvästi tilaton: sen parametrit jäädytetään koulutuksen jälkeen, eikä mikään, mitä teet päättelyn aikana, muuta niitä. Malli ei opi korjauksistasi, muista, että sille sanottiin sama asia eilen, eikä tutustu sinuun — vaikka keskustelu tuntuisi kuinka jatkuvalta. Istunnon jatkuvuuden tunteen luo agenttiympäristö, joka säilyttää keskustelulokin ja lähettää sen uudelleen joka pyynnöllä. Malli ei muista keskustelua; se lukee sen uudelleen.

Käytännön seuraus: jos haluat jonkin asian säilyvän istuntojen välillä, sinun on kirjoitettava se johonkin, josta agentti lukee sen myöhemmin. Sitä AGENTS.md-tiedostot, muistijärjestelmät ja luovutusartefaktit ovat — tiedostoja, jotka ladataan tulevien istuntojen kontekstiin korvaamaan mallilta puuttuva muisti. Kun agentti tekee toistuvasti uudelleen virheen, jonka olet jo korjannut, kysymys ei ole siitä, miksei se oppinut — se ei voi — vaan siitä, mihin korjaus kirjoitetaan, jotta jokainen tuleva istunto lukee sen.

Käyttö:

”Miksi se unohtaa käytännön aina, kun tyhjennän istunnon?”

”Malli on tilaton — uusi istunto alkaa tyhjästä. Jos haluat asian mukaan, kirjoita se AGENTS.md-tiedostoon tai muistifileen, jonka agenttiympäristö lataa istunnon alussa.”

Olennaiset tiedot, joihin agentilla on juuri nyt pääsy. Abstrakti substantiivi — ei mallin näkemä raaka syöte (se on konteksti-ikkuna), ei jatkuva historia (se on istunto), vaan se tehtävän kannalta olennainen tieto, jonka agentti tietää. ”Tietojen lataaminen kontekstiin” tarkoittaa niiden lisäämistä tähän joukkoon; ”kontekstisuunnittelu” tarkoittaa sen huolellista kokoamista.

Kolme termiä eroavat selkeästi:

Erottelu on tärkeä, sillä konteksti mittaa laatua, ei määrää. Konteksti-ikkuna voi olla lähes täynnä ja konteksti silti huono — tuhansia tokeneita vanhentunutta työkalutulostetta, eikä mitään käsillä olevasta tehtävästä. Ikkuna voi myös olla lähes tyhjä ja konteksti erinomainen: yksi tyyppimäärittely, joka ratkaisee tehtävän.

Useimmat arkipäiväiset virheet johtuvat kontekstista. Kun agentti keksii API:n, on päätöksen kanssa ristiriidassa tai arvaa skeeman, ensimmäinen kysymys on, mitä kontekstissa oli sen tehdessä näin — tavallisesti olennaista faktaa ei koskaan ladattu tai se hautautui huomion heikkenemisen alle. Ratkaisu on huolellinen valikointi: lataa tehtävän tarvitsema sisältö ja jätä muu pois.

Käyttö:

”Se keksii jatkuvasti kenttiä, joita tyypissä ei ole.”

”Tyyppitiedosto ei ole kontekstissa — se lukee kutsukohtia ja arvaa. Lue määrittely ensin.”

Kaikki, mitä malli näkee jokaisella mallintarjoajan pyynnöllä. Rajallinen, mallikohtainen ja ainoa pinta, jonka kautta malli havaitsee mitään.

Se on yksi tokeneiden jono: järjestelmäkehote, keskustelu siihen asti ja jokainen työkalutulos, jonka agenttiympäristö on syöttänyt takaisin. Jos jokin on tässä jonossa, malli voi käyttää sitä; jos se ei ole siinä, malli ei tiedä sen olevan olemassa — ei koodikantaasi, eilen muokkaamaasi tiedostoa eikä kolme istuntoa sitten antamaasi ohjetta. Kaikki ikkunan ulkopuolinen on tuotava mukaan, yleensä työkalukutsulla, ennen kuin se voi vaikuttaa mihinkään.

Ikkuna on rajallinen, joten se täyttyy. Jokainen vuoro lisää sisältöä — viestisi, mallin vastaukset ja työkalutulokset — ja pitkä istunto saavuttaa lopulta rajan, mikä pakottaa tiivistämään tai tyhjentämään. Ikkunassa oleva sisältö myös kilpailee keskenään: jokainen ladattu token vähentää muille käytettävissä olevia, ja tarpeetonkin sisältö kuluttaa mallin huomiobudjettia. Käytännössä ikkuna kannattaa nähdä budjettina — lataa vain tehtävän tarvitsema sisältö ja jätä muu ulkopuolelle.

Vältä: ”muisti” — konteksti-ikkuna on työtilaa eikä säily istuntojen välillä. Muisti on erillinen käsite, joka rakennetaan sen päälle.

Käyttö:

”Voinko vain liittää koko monorepon kehotteeseen?”

”Konteksti-ikkunaan mahtuu 200k tokenia — se on ehkä viidennes reposta. Valitse tehtävään liittyvät tiedostot ja jätä loput työkalukutsun taakse.”

Vie tietoa eteenpäin. Istunto säilyttää tilan vuorojen välillä — konteksti karttuu istunnon aikana, minkä vuoksi pitkät istunnot ajautuvat tylsälle vyöhykkeelle. Agentti voidaan tehdä tilalliseksi istuntojen välillä lisäämällä muistijärjestelmä, joka tallentaa tiedot ympäristöön ja lataa ne tulevien istuntojen alussa. Malli ei ole koskaan tilallinen; näennäisen jatkuvuuden tuottaa agenttiympäristö, joka syöttää kontekstin uudelleen. Vastakohta termille tilaton.

Missä tila sijaitsee kullakin tasolla:

Kunkin kerroksen tilallisuus syntyy lukemalla uudelleen alempaan kerrokseen tallennettua tietoa: istunto tuntuu jatkuvalta, koska agenttiympäristö lähettää viestihistorian uudelleen tilattomalle mallille, ja agentti muistaa istuntojen välillä, koska agenttiympäristö lataa tiedostot uudelleen ympäristöstä. Tilaa ei koskaan tallenneta itse malliin.

Tilallisuus ei ole aina toivottavaa. Kaikki eteenpäin kannettu vaikuttaa tulevaan, joten myös istunnon alussa tehty väärä oletus kulkee mukana. Tyhjentäminen tarkoittaa istunnon tilan tietoista hylkäämistä ja aloittamista uudelleen kirjoitetun tiedon pohjalta.

Käyttö:

”Se muisti eiliseltä mieltymykseni — oppiko malli ne?”

”Ei, agentti on tilallinen, koska agenttiympäristö kirjoitti mieltymykset muistitiedostoon ja latasi sen uudelleen istunnon alussa. Itse malli ei nähnyt mitään eilisestä.”

Työkaluihin, järjestelmäkehotteeseen ja konteksti-ikkunaan liitetty malli, johon on liitetty agenttiympäristö, ja joka ottaa vuoroja käyttäjän kanssa. Claude Code on agentti. Cursor on agentti. Claude.ai on agentti. Agentti on se, jonka kanssa oikeasti puhut — tarkoitukseen määritetty malli toiminnassa.

Toisin kuin useimmat tämän sanakirjan termit, ”agentti” ei nimeä mekaanista osaa. Malli on parametrit sisältävä tiedosto; agenttiympäristö on ohjelmisto, jonka voi ottaa käyttöön. Agentti ei ole kumpikaan — se on yksikkö, jolle puhut. Ihmiset inhimillistävät tekoälyä alituiseen, ja agentti on inhimillistetty yksikkö: olento, jolle delegoit, joka lukee viestisi ja vastaa, ”se” lauseessa ”se rikkoi taas koontiversion”. Kun sanot agentin tehneen jotakin, tarkoitat mallin ja agenttiympäristön tehneen sen, mutta puhuttelet tätä yhdistelmää yhtenä toimijana.

Ajatus on tätä tekoälyaaltoa vanhempi. Ohjelmistoagentit — ohjelmat, joille delegoit tavoitteen ja jotka toimivat puolestasi — ovat olleet käsitteenä olemassa yhtä kauan kuin tekoälykin.

Vältä: ”tekoäly”, ”botti” (liian epämääräisiä — niistä ei käy ilmi, tarkoitatko parametreja vai agenttiympäristöön liitettyä kokonaisuutta).

Käyttö:

”Mitä agenttia käytät siirtoon?”

”Claude Code paikallisesti, Cursor käyttöliittymätyöhön — sama malli alla, eri agenttiympäristöt.”

Ohjeet, jotka agenttiympäristö lisää jokaisen mallintarjoajan pyynnön alkuun — agentin pysyvä ohjeistus: kuka se on, miten sen tulisi käyttäytyä, mitä työkaluja se voi kutsua ja mitä käytäntöjä noudattaa. Tavallisesti vakaa istunnon ajan.

Järjestelmäkehotteen kirjoittaa agenttiympäristön toimittaja, et sinä. Koodausagenttiympäristöissä se on suuri — usein kymmeniätuhansia tokeneita käyttäytymissääntöjä, työkalukuvauksia ja poikkeustilanteiden käsittelyä, kaikki laskutetaan syötetokeneina jokaisella vuorolla. Myös sinun pysyvät ohjeesi kulkevat mukana: AGENTS.md-tiedostot ladataan järjestelmäkehotteen viereen istunnon alussa, joten malli lukee toimittajan ja sinun ohjeesi yhdessä ennen kuin se näkee viestisi.

Koska järjestelmäkehote on sama jokaisessa pyynnössä, se muodostaa etuliitevälimuistin alun — osittain siksi agenttiympäristöt pitävät sen muuttumattomana koko istunnon ajan eivätkä muokkaa sitä työn edetessä.

Mallien koulutuksessa järjestelmäkehote asetetaan käyttäjäviestien edelle. Jos agentti siis vaatii käytäntöä, jota et ole pyytänyt, tai muotoilee tulosteen tavalla, josta et saa sitä luopumaan, se noudattaa tavallisesti järjestelmäkehotetta — ja viestisi häviää kiistan. Jotkin agenttiympäristöt ovat muokattavia: niissä voit tarkastella järjestelmäkehotetta kokonaan, lukea mitä agentille todella kerrotaan ja muuttaa sitä.

Käyttö:

”Kaksi agenttiympäristöä, sama malli, täysin erilainen toiminta samalla kehotteella.”

”Eri järjestelmäkehotteet. Toinen on viritetty ytimekkäisiin koodimuutoksiin, toinen selittämiseen — ero syntyy jo ennen viestisi saapumista.”

Yksi rajattu vuorovaikutusjakso agentin kanssa. Se alkaa tyhjänä, kerää viestejä, työkalutuloksia ja luettuja tiedostoja ja päättyy, kun istunto tyhjennetään, suljetaan tai tiivistetään uudeksi istunnoksi. Istunto täyttää konteksti-ikkunan: jos konteksti-ikkuna on laatikko, istunto on sen hitaasti kertyvä sisältö. Yhden konteksti-ikkunan työtä suurempi työ on jaettava useisiin istuntoihin.

Istunnon viestihistoria on agentin työmuisti. Malli on tilaton, joten kaikki, mitä se näyttää muistavan — mitä pyysit, mitä testit sanoivat ja mitä se päätti kolme vuoroa sitten — on viestihistoriassa, joka lähetetään uudelleen jokaisella mallintarjoajan pyynnöllä. Kaikki, mikä ei ole istunnossa, ei ole olemassa agentille.

Tämä muisti päättyy istuntoon. Uusi istunto alkaa tyhjästä: agentti, joka tunsi koodikantasi hyvin eilisen istunnon lopussa, ei tiedä siitä tänä aamuna mitään. Tiedostojärjestelmä säilyy — yhden istunnon aikana kirjoitetut tiedostot voidaan lukea seuraavassa, ja siihen luovutukset, muistijärjestelmät ja AGENTS.md perustuvat.

Sinä päätät, milloin istunto päättyy. Kaikki istunnon sisältö vaikuttaa jokaiseen myöhempään vuoroon, joten samassa istunnossa tehdyt asiaan kuulumattomat tehtävät jättävät jälkiä, jotka värittävät seuraavaa vastausta. Yksi tehtävä istuntoa kohti pitää kontekstin olennaisena; tehtävän valmistuminen on luonnollinen hetki tyhjentää se.

Käyttö:

”Kuinka kauan yksi istunto voi jatkua ennen kuin se hajoaa?”

”Riippuu työstä — keskittynyt refaktorointi pysyy terävänä kauemmin kuin avoin tutkimustyö. Kun istunto paisuu, tee luovutus tai tiivistä, älä puske läpi.”

Yksi käyttäjäviesti ja kaikki, mitä agentti tekee vastaukseksi, siihen asti kun se palauttaa vuoron käyttäjälle. Sisältää yhden tai useamman mallintarjoajan pyynnön — monia, jos agentti kutsuu työkaluja. Tarkentava kysymys päättää vuoron; vastauksesi aloittaa seuraavan. Hierarkia on istunto > Vuoro > Mallintarjoajan pyyntö.

Vuoroa kannattaa kutsua juuri siksi, että sen pituuden päättää agentti, ei sinä. Annat yhden viestin, ja agentti päättää, kuinka monta työkalukutsua se ketjuttaa ennen vuoron palauttamista. Vuoro voi olla yhden virkkeen vastaus tai kaksikymmentä minuuttia lukemista, muokkaamista ja testien suorittamista. Sama ominaisuus näkyy kahdesta suunnasta: pitkät vuorot mahdollistavat AFK-työn, mutta pitkissä vuoroissa tapahtuu myös valvomatta virheitä — kun agentti palauttaa vuoron, se on voinut ajautua kauas tarkoituksestasi.

Vuoro on myös luonteva ohjaamisen yksikkö. Kaikki vuoron sisällä tapahtuu ilman sinua; vuorojen välissä voit suunnata työtä uudelleen. Useimmat agenttiympäristöt lieventävät tätä: voit keskeyttää kesken vuoron pysäyttääksesi agentin ja ohjataksesi sen uudelleen tai kirjoittaa viestin työn aikana, jolloin se luetaan vuoron valmistuttua. Jos olet toistuvasti tyytymätön vuorojen tuloksiin, yleensä kannattaa pyytää pienempiä vuoroja — ensin suunnitelma, sitten yksi vaihe kerrallaan — ja vaihtaa autonomia useampiin ohjausväleihin.

Käyttö:

”Kestikö yksi vuoro kaksi minuuttia?”

”Se teki neljätoista työkalukutsua vuoron aikana — jokainen niistä on erillinen mallintarjoajan pyyntö. Viiveet kasaantuvat ennen kuin agentti lopulta palauttaa vuoron sinulle.”

Maailma, jossa agentti toimii — kaikki agenttiympäristön ulkopuolinen, jonka agentti havaitsee työkalutulosten kautta ja jota se muuttaa työkalukutsuilla. Agenttiympäristö ajaa agentin; ympäristössä agentti työskentelee. `AGENTS.md`-tiedosto sijaitsee ympäristössä; agenttiympäristö lataa sen konteksti-ikkunaan. Tiedostojärjestelmä on tavallisin ympäristötyyppi, muttei ainoa (ympäristöjä voivat olla myös tietokanta, etä-API tai selainistunto).

Agentti näkee ympäristön vain tarkastellessaan sitä. Kaikki sen ympäristöstä tietämä tulee työkalutuloksista, joten sen kuva muodostuu tilannekuvista, joista kukin on oikea ottohetkellään. Jos tiedosto muuttuu agentin luettua sen — muokkaat sitä käsin tai koontivaihe luo sen uudelleen — agentti jatkaa päättelyä vanhentuneen kopion pohjalta, kunnes jokin saa sen lukemaan tiedoston uudelleen. Kun agentti kuvailee itsevarmasti tiedostoa, joka ei enää näytä siltä, kyse on yleensä tästä: ympäristö muuttui, mutta tilannekuva ei.

Ympäristö on myös säilyvä kerros — ainoa, joka on aina tilallinen. Istunnon konteksti katoaa istunnon päättyessä, mutta ympäristöön kirjoitetut tiedostot säilyvät seuraavaa istuntoa varten — ja tähän muistijärjestelmät, luovutusartefaktit ja `AGENTS.md` perustuvat. Kaikkien asioiden, jotka agentin pitäisi tietää vielä huomenna, täytyy päätyä ympäristöön.

Päätät ympäristön koon. Hiekkalaatikko pienentää sitä rajaamalla, minne agentti pääsee; työkalu laajentaa sitä tuomalla tietokannan tai API:n käyttöön. Rajojen sisällä olevaa agentti voi havaita ja muuttaa; ulkopuolista ei ole agentille olemassa. Koodikannan AX kuvaa, kuinka hyvin ympäristö on järjestetty agentin työn tukemiseen.

Vältä: ”ympäristön” käyttämistä ajonaikaisesta järjestelmästä tai agenttiympäristöstä — agenttiympäristö on kääre, ympäristö on työtila.

Käyttö:

”Agentti ei näe staging-tietokannan skeemaa.”

”Kytke se ympäristöön — anna agentille `psql`-työkalu, jonka oikeudet stagingiin ovat vain luku. Agenttiympäristö on kunnossa, mutta sillä ei ole mitään, mitä käyttää.”

Tiedostojen ja hakemistojen puu, josta agentti lukee, johon se kirjoittaa ja jonka sisällä se suorittaa komentoja — koodausagentin ympäristön oletustyyppi. AGENTS.md, taidot, lähdekoodi, koontiskriptit ja työkalu-määritykset sijaitsevat kaikki tiedostojärjestelmässä. Kun agenttiympäristö ”käynnistyy projektissasi”, se ohjaa agentin tiedostojärjestelmään.

Agentti koskee siihen vain työkalukutsuilla — lukemalla tai kirjoittamalla tiedoston tai suorittamalla komentotulkkikomennon. Mitään levyllä olevaa ei ole konteksti-ikkunassa, ennen kuin työkalukutsu lataa sen. Tämän ansiosta agentti voi työskennellä paljon ikkunaa suuremmassa repossa: tiedostojärjestelmä sisältää kaiken, konteksti vain sen, mitä nykyinen tehtävä on lukenut. Jotkin agenttiympäristöt lataavat nykyisen hakemiston tiedostonimet oletusarvoisesti konteksti-ikkunaan — eivät tiedostojen sisältöä, vain puurakenteen — joka toimii kontekstiviitteenä: agentti näkee mitä on olemassa ja lukee tarvitsemansa tiedostot.

Tiedostojärjestelmä on myös yhteinen sinun ja agentin välillä. Agentin muokkaamat tiedostot ovat samoja, jotka avaat editorissa ja joiden erot tarkistat gitissä — tiedostojärjestelmä on yhteinen työtila, jossa tarkistat agentin tekemiset.

Käyttö:

”Miksi se ei löydä AGENTS.md:täni?”

”Se käyttää eri tiedostojärjestelmää — hiekkalaatikko liitti vanhempaan hakemistoon, ei projektin juureen. Ohjaa agenttiympäristö uudelleen.”

Funktio, jonka agenttiympäristö tarjoaa agentin kutsuttavaksi — Read, Write, Bash, Search. Työkalujen avulla agentti havaitsee ympäristön ja toimii siinä: se ei näe ympäristöä muuten kuin työkalutulosten kautta eikä voi muuttaa sitä muuten kuin työkalukutsuilla. Jokainen työkalukutsu maksaa ylimääräisen mallintarjoajan pyynnön, koska tuloksen on palattava mallille ennen kuin se voi päättää, mitä tehdä seuraavaksi.

Työkaluja, joita useimmat koodausagentit tarjoavat:

Työkalun määrittävät kolme asiaa: sen nimi, kuvaus toiminnasta ja parametrien skeema. Agenttiympäristö lähettää nämä määritelmät mallille jokaisen pyynnön yhteydessä, ja malli valitsee työkalun samalla tavalla kuin se tuottaa kaiken muunkin — kirjoittamalla tokeneita, tässä tapauksessa rakenteisen kutsun argumentteineen. Malli ei suorita mitään itse; agenttiympäristö lukee kutsun, suorittaa funktion ja lähettää tuloksen takaisin.

Työkaluluettelo määrittää, mitä agentti voi tehdä. Kyvykäs malli suppealla työkalujoukolla on kapea agentti: se ohjaa kaiken käytettävissä olevien työkalujen kautta, minkä vuoksi agentit tukeutuvat vahvasti Bashiin — komentotulkki on yksi työkalu, jolla pääsee käsiksi useimpiin järjestelmän osiin. Anna agentille jokin kyky selkeästi lisäämällä sitä varten työkalu; MCP on standardi työkalujen liittämiseen agenttiympäristön ulkopuolelta.

Työkalumääritelmät vievät kontekstia jokaisessa pyynnössä, joten suuri työkalujoukko maksaa jo ennen ensimmäistäkään työkalukutsua — ja monet samankaltaisesti kuvatut työkalut vaikeuttavat oikean valitsemista.

Käyttö:

”Voiko agentti kysellä suoraan staging-ympäristöstä?”

”Lisää agenttiympäristöön `psql`-työkalu, jolla on vain lukuoikeus stagingiin. Ilman sitä varten olevaa työkalua agentti ei näe mitään tiedostojärjestelmän ulkopuolelta.”

Mallin tuloste, jossa nimetään työkalu ja sen argumentit — pelkkää rakenteista tekstiä. Se ei tee mitään itsestään; agenttiympäristön on luettava ja suoritettava kutsu. Malli tuottaa sen yhdellä mallintarjoajan pyynnöllä.

Työkalukutsun elinkaari:

Yksi agentin työskentely-vuoro koostuu tavallisesti monista tällaisista peräkkäisistä kierroksista.

Koska kutsu tuotetaan seuraavan tokenin ennustuksena kuten kaikki muukin, se voi olla väärä samalla tavalla kuin mikä tahansa mallin tuloste: olematon polku, komennolta puuttuva valitsin tai uskottavilta näyttävät mutta väärät argumentit. Agenttiympäristö suorittaa sen, mitä kirjoitettiin, ei sitä, mitä tarkoitettiin — väärin kirjoitettu polku ei välttämättä epäonnistu hallitusti vaan voi muokata väärää tiedostoa.

Käyttö:

”Se sanoi ajaneensa testit, mutta tiedostojen aikaleimat eivät muuttuneet.”

”Katso keskustelulokia — tuottiko se oikeasti työkalukutsun vai vain kuvailiko testien ajamista? Malli tuottaa kutsun, mutta jos agenttiympäristö ei suorittanut sitä, mitään ei tapahtunut.”

Mitä agenttiympäristö lähettää takaisin työkalukutsun suorittamisen jälkeen — tiedoston sisällön, komennon tulosteen tai virheen. Agentin ainoa näkymä ympäristöön. Tulos kulkee takaisin mallille seuraavassa mallintarjoajan pyynnössä, jossa malli päättää, mitä sille tehdään. Työkalukutsu ja työkalutulos ovat saman vaihdon kaksi päätä, molemmat yhden vuoron sisällä.

Työkalutuloksen elinkaari:

Tulos pysyy kontekstissa istunnon loppuun asti. Työkalutulokset muodostavat yleensä suurimman osan koodausistunnon kontekstista: jokainen luettu tiedosto, ajettu testi ja haku päätyy mukaan kokonaisena ja kuluttaa tokeneita kauan sen jälkeen, kun se on lakannut olemasta hyödyllinen. Muutama suuri tulos — pitkä testiloki tai kokonaan luettu generoitu tiedosto — voi työntää istuntoa konteksti-ikkunan reunalle nopeammin kuin itse keskustelu.

Koska tulos on kaikki, mitä malli näkee, se ei voi tarkistaa taustalla olevaa ympäristöä. Jos tuloste typistettiin, komento epäonnistui siitä ilmoittamatta tai agenttiympäristö palautti sisällön sijaan virheen, malli päättelee saamansa perusteella. Kun agentin kuva järjestelmästä vaikuttaa väärältä, tarkastele työkalutuloksia: jossain keskustelulokissa on tulos, joka kertoo jotakin muuta kuin mitä tiedät todeksi.

Käyttö:

”Se päättelee kuin tiedosto olisi tyhjä.”

”Työkalutulos oli käyttöoikeuden epääminen, ei sisältö. Malli näki vain virhetekstin — sillä ei ole muuta tapaa tarkastella tiedostoa.”

Model Context Protocol. Protokolla ulkoisten työkalupalvelinten liittämiseen agenttiympäristöön — tapa, jolla agentti saa työkaluja sen lisäksi, mitä agenttiympäristössä on valmiina. Agentti ei koskaan ”kutsu MCP:tä”; se kutsuu työkalua, ja agenttiympäristö on sattumalta saanut työkalun MCP-palvelimelta. Protokolla tarjoaa myös resursseja (vain luettavaa dataa) ja kehotteita (uudelleenkäytettäviä malleja), mutta työkalujen tarjoaminen on sen ensisijainen käyttötarkoitus.

Protokolla ratkaisee integraatio-ongelman. Ilman standardia jokainen agenttiympäristö tarvitsisi oman Linear-integraation, oman Slack-integraation ja oman tietokantaintegraation — jokainen niistä kirjoitettaisiin ja ylläpidettäisiin erikseen. MCP:n ansiosta integraatio kirjoitetaan kerran palvelimeksi, ja kaikki MCP-yhteensopivat agenttiympäristöt voivat käyttää sitä. Agenttiympäristö yhdistää palvelimeen, palvelin ilmoittaa tarjoamansa työkalut, ja ne tulevat agentin käyttöön sisäänrakennettujen työkalujen rinnalle.

Kustannus maksetaan kontekstissa. Jokainen palvelimen ilmoittama työkalu tuodaan mukaan määritelmänä — nimi, kuvaus ja parametriskeema — ja malli voi kutsua vain työkaluja, joista se tietää. Naiivi tapa lataa kaikki määritelmät konteksti-ikkunaan heti alkuun: asenna muutama antelias palvelin, niin istunto alkaa tuhansilla työkaluskeemojen tokeneilla ennen kuin olet kirjoittanut mitään. Näin kuluu huomiobudjettia työkaluihin, joita tehtävä ei koskaan tarvitse.

Monet agenttiympäristöt lieventävät tätä nyt hakutoiminnolla: kaikkien määritelmien sijasta konteksti sisältää käytettävissä oleviin työkaluihin johtavan kontekstiviitteen — agentti etsii työkalua nimen tai tarkoituksen perusteella ja lataa määritelmän vasta tarvitessaan sitä. Jos agenttiympäristösi ei tee näin, alkukustannus jää voimaan, joten kannattaa ottaa käyttöön vain ne palvelimet, joita projekti todella tarvitsee.

Käyttö:

”Agentin on luettava Linear-tehtäviä.”

”Määritä agenttiympäristö käyttämään Linearin MCP-palvelinta — se tarjoaa Linearin API:n työkaluina, joita agentti voi kutsua. Sinun ei tarvitse kirjoittaa mukautettuja työkalukääreitä.”

Mitä agenttiympäristö näyttää käyttäjälle ennen sellaisen työkalukutsun suorittamista, jota ei ole hyväksytty etukäteen. Malli tuottaa työkalukutsun, mutta agenttiympäristö pysähtyy kysymään sen suorittamisen sijaan. Hyväksy, niin se suoritetaan; kiellä, niin agenttiympäristö ilmoittaa kiellosta mallille työkalutuloksena. Näin agenttiympäristö ottaa ihmisen mukaan riskialttiisiin tai arkaluontoisiin toimiin.

Käyttöoikeuspyynnön elinkaari:

Pyynnön kieltäminen ohjaa agenttia. Malli lukee kiellon kuten minkä tahansa työkalutuloksen ja reagoi siihen — se kokeilee toista lähestymistapaa tai kysyy, mitä haluaisit. Useimmissa agenttiympäristöissä voit liittää kieltoon viestin, jolloin pyynnöstä tulee ohjauspiste: ”älä noin, käytä sen sijaan migraatioskriptiä” tavoittaa mallin juuri, kun se päättää, mitä tehdä seuraavaksi.

Kustannuksena on, että jokainen pyyntö odottaa sinulta vastausta. Agentti on pysäytettynä, kunnes vastaat, mikä on hyvä, kun seuraat työtä, ja ongelma, kun et seuraa — jatkuvasti pyyntöjä käynnistävää agenttia ei voi jättää työskentelemään AFK. Käyttöoikeustila on säädin: mitkä kutsut suoritetaan vapaasti ja mitkä kysyvät ensin, mielellään hiekkalaatikon suojatessa, jos vapaita kutsuja lisätään.

Käyttö:

”Se on odottanut käyttöoikeuspyyntöä kymmenen minuuttia — olin kokouksessa.”

”Se on human-in-the-loopin hinta. Hyväksy turvalliset työkalut etukäteen, niin pyyntö tulee vain aidosti riskialttiista kutsuista.”

Agenttitilan käyttöoikeuksia hallitseva osa — mitkä työkalukutsut käynnistävät käyttöoikeuspyynnön ja mitkä suoritetaan automaattisesti. Tilajärjestelmien alkuperäinen tarkoitus ennen kuin agenttiympäristöt alkoivat liittää niiden päälle toimintaohjeita.

Agenttiympäristöissä on useita tällaisia tiloja portaikkona:

Tason valinta on kompromissi turvallisuuden ja keskeytysten välillä, ja kummankin virhetilan tuntee. Liian tiukka tila tekee sinusta pullonkaulan: agentti pysähtyy muutaman sekunnin välein harmittomiin lukuihin, napsautat hyväksyntää autopilotilla ja hyväksynnät menettävät merkityksensä — kumileimasinhyväksyntä on molempien maailmojen huonoin puoli, kaikki keskeytykset ilman suojaa. Liian väljä tila saa agentin muokkaamaan tiedostoja ja suorittamaan komentoja, jotka olisit halunnut nähdä etukäteen.

Väljää asetusta on helpointa puolustaa hiekkalaatikossa, jossa huonon työkalu-kutsun vaikutusalue on rajattu. Sen ulkopuolella useimmat hyväksyvät luvut automaattisesti mutta pitävät ihmisen mukana kaikessa peruuttamattomassa.

Käyttö:

”Se pysähtyi jokaisessa grep-haussa — AFK-ajo meni täysin pilalle.”

”Löysää vain luku -työkalujen käyttöoikeustilaa, mutta pidä kirjoitukset ja komentotulkki hyväksynnän takana. Useimmat tutkimus-istunnon käyttöoikeuspyynnöt ovat kohinaa.”

Esiasetus, joka määrittää, miten agentti toimii ajon aikana — yhdistää käyttöoikeustilan järjestelmäkehotteeseen lisättäviin toimintaohjeisiin. Esimerkkejä: oletustila, joka kysyy riskialttiista kutsuista; suunnittelutila, joka estää muokkaukset ja ohjaa agentin tutkimiseen; muokkausten hyväksyntä -tila, joka hyväksyy muokkaukset automaattisesti; käyttöoikeuksien ohitus (puhekielessä YOLO-tila), joka hyväksyy kaiken automaattisesti. Tilaa voi vaihtaa istunnon aikana.

Kahden asian yhdistäminen erottaa tilan pelkästä käyttöoikeusasetuksesta. Käyttöoikeustila on vain portti: se ratkaisee, mitkä työkalukutsut pääsevät läpi. Pelkkä portti tuottaa agentin, joka haluaa muokata mutta ei pysty — se ehdottaa kirjoitusta, saa eston ja yrittää toista tapaa. Lisätyt ohjeet poistavat halun: suunnittelutila ei vain estä muokkauksia, vaan kertoo agentille, että se on suunnitteluvaiheessa, joten se lukee, kysyy ja ehdottaa sen sijaan, että yrittäisi päästä portin ohi. Portti ja ohjaus osoittavat samaan suuntaan.

Käytännössä tilaa vaihdetaan luottamuksen kasvaessa tehtävän edetessä. Sama tehtävä voi kulkea usean tilan läpi: suunnittelutila lähestymistavan muotoutuessa, kehotteita käyttävä oletustila ensimmäisiä hienovaraisia muokkauksia varten, muokkausten hyväksyntä sen jälkeen kun agentti on osoittanut ymmärtävänsä muutoksen, käyttöoikeuksien ohitus AFK-ajossa hiekkalaatikossa. Tilan vaihtaminen ei maksa mitään: keskustelu jatkuu täsmälleen samasta kohdasta uusilla käyttöoikeuksilla ja ohjeilla. Jos hyväksyt jokaisen kehotteen lukematta sitä, tila on todellista luottamustasi tiukempi; jos hylkäät jatkuvasti muokkauksia, se on liian väljä.

Toimittajien termit: Claude Code kutsuu näitä ”käyttöoikeustiloiksi”, Codex ”hyväksyntätiloiksi” — molemmat nimitykset ovat käyttäytymisohjeiden yhdistämistä vanhempia.

Käyttö:

”Se muokkaa jatkuvasti tiedostoja, vaikka haluan vain suunnitelman.”

”Vaihda suunnittelutilaan — se estää kirjoitukset ja pysyy tutkimustyössä.”

”Entä myöhemmin AFK-ajossa?”

”Ohitustila, mutta vain hiekkalaatikossa.”

Eristetty ympäristö, jonka sisällä agentti toimii — kontti, virtuaalikone, väliaikainen tiedostojärjestelmä tai rajoitetuin käyttöoikeuksin toimiva komentotulkki. Rajoittaa agentin toimien vaikutusaluetta: vaikka agentti suorittaisi tuhoisia komentoja tai hakisi jotakin haitallista, vahinko pysyy rajattuna. Turva-alusta, joka tekee AFK-työstä käytännöllistä.

Hiekkalaatikko ja käyttöoikeustila ratkaisevat saman ongelman vastakkaisista suunnista. Käyttöoikeudet kysyvät ennen toiminnon suorittamista; hiekkalaatikko rajoittaa toiminnon ulottuvuutta, jos se suoritetaan. Käyttöoikeuskysely edellyttää, että olet mukana — jokainen kehote keskeyttää — ja jatkuvasti kysyvä istunto on tuskin autonominen. Hiekkalaatikko kuluttaa infrastruktuuria huomion sijaan: mitä vahvempi eristys, sitä vähemmän tarvitsee kysyä.

Eristystasoja on useita:

Mikään hiekkalaatikko ei rajaa toimia, jotka poistuvat siitä luvallisesti. Agentti, jolla on git-tunnistetietosi, voi tehdä pushin; agentti, jolla on verkkoyhteys, voi kutsua tuotannon API:a. Päätä, mitä rajan yli päästetään, ennen kuin päätät eristyksen vahvuuden.

Käyttö:

”Haluaisin antaa sen suorittaa käyttöoikeuksien ohituksen yön yli, mutta en ole vielä valmis siihen.”

”Aseta se hiekkalaatikkoon — uusi kontti, ei liitettyjä tunnistetietoja eikä ulosmenevää verkkoyhteyttä. Pahimmillaan se tuhoaa oman tiedostojärjestelmänsä, ja voit hylätä kontin.”

Itsevarman myötäilevä malli-vastaus. Johtuu koulutuksesta: mallia muokattiin suosimaan vastauksia, joista ihmiset pitivät, ja ihmiset pitävät myötäilystä usein enemmän kuin siitä, että heille sanotaan heidän olevan väärässä. Niinpä malli oppi, että myötäilystä palkitaan — silloinkin, kun se on väärin.

Näkyy näin:

• Antaa periksi vastustettaessa — peruu oikean vastauksen, kun sanot ”oletko varma?”.
• Kehuu huonoja syötteitä — kutsuu kelvotonta suunnitelmaasi loistavaksi ennen sen analysointia.
• Puolueellinen kehystys — katselmointi on myönteinen, kun annat ymmärtää kirjoittaneesi sen, ja kielteinen, kun annat ymmärtää jonkun muun kirjoittaneen. Sama artefakti, eri arvio.
• Matkiminen — toistaa virheesi vahvistuksena.

Diagnostinen testi: olisiko malli sanonut tämän ilman ohjaustasi? Jos vain sävysi tai kehystyksesi muuttui, kyse on mielistelystä, ei analyysin aidosta muutoksesta.

Ratkaisu: piilota mieltymyksesi. Muotoile kehotteet neutraalisti — ”katselmoi tämä koodi”, älä ”onko tämä koodi hyvää?”.

Vältä: termin ”mielistely” käyttämistä jokaisesta väärästä vastauksesta, joka sattuu miellyttämään sinua. Ilman diagnostista testiä sana ei tarkoita sen enempää kuin ”väärä”.

Käyttö:

”Se sanoi, että refaktorointisuunnitelmani näytti loistavalta. Kysyin sitten ’oletko varma?’, ja se perui koko suunnitelman.”

”Klassista mielistelyä — ensin se myötäili, koska kuulostit varmalta, sitten se antoi periksi, koska kuulostit epäilevältä. Suunnitelman laatu ei muuttunut, äänensävysi muuttui. Tyhjennä ja kysy uudelleen ilmaisematta kantaasi.”

Väärässä oleva mutta itsevarma malli-vastaus. Tässä on kaksi eri syistä johtuvaa muotoa, joihin tarvitaan erilaiset korjaukset:

Seuraavan tokenin ennustaminen tuottaa sujuvaa tekstiä riippumatta siitä, ovatko taustalla olevat faktat todellisia — mallilla ei ole sisäistä signaalia siitä, ettei se tiedä jotakin, joten keksitty menetelmä esitetään yhtä varmassa sävyssä kuin oikea. Hallusinoitu koodi on rakenteeltaan uskottavaa: se näyttää sellaiselta kuin API näyttäisi, jos se olisi olemassa. Juuri siksi se menee pintapuolisessa tarkistuksessa läpi ja epäonnistuu vasta ajettaessa.

On tiedettävä, kumpaa muotoa tarkastelet, koska toisen korjaus pahentaa toista. Faktapuute tarkoittaa puuttuvaa tietoa: korjaus on kontekstin lisääminen — dokumentit, tyyppimäärittelyt tai tiedosto. Uskollisuusongelmassa tieto on mukana mutta häviää huomiokilpailun: korjaus on kontekstin poistaminen. Jos tulkitset uskollisuusongelman faktapuutteeksi ja liität lisää dokumentteja, konteksti kasvaa ja poikkeama pahenee. Kun agentti tekee virheen, tarkista ennen ongelman määrittelyä, oliko oikea tieto jo kontekstissa.

Vältä: ”hallusinaatiota” pelkkänä ”väärän” synonyymina — määrittelemättä muotoa termillä ei ole diagnostista arvoa.

Käyttö:

”Se hallusinoi skeemaan `parseAsync`-metodin.”

”Faktapuute vai uskollisuusongelma?”

”Metodi on liittämissäni dokumenteissa — se vain lakkasi lukemasta niitä neljännenkymmenennen vuoron jälkeen.”

”Sitten kyse on uskollisuudesta. Tiivistä ja lataa uudelleen, älä lisää dokumentteja.”

Se, mitä malli ”tietää” koulutuksesta, parametreihinsa tallennettuna. Jäädytetään koulutuksen aikana — malli ei voi nähdä omia parametrejaan eikä päivittää niitä. Yksityiskohtia katoaa tiivistyksessä: miljardeja faktoja puristetaan kiinteään parametrimäärään, ja harvinaiset hämärtyvät. Tavallisten aiheiden sujuvan käsittelyn lähde ja harvinaisten aiheiden sepittelyn syy. Vastakohta kontekstuaaliselle tiedolle.

Parametrista tietoa ei tallenneta faktoina. Koulutuksessa mallille ei anneta hakukelpoista faktatietokantaa; sen parametreja säädetään, kunnes se ennustaa tekstiä hyvin. Aiheesta hyvin tekstiä ennustava malli käyttäytyy kuin se tietäisi aiheesta. Tiedon luotettavuus riippuu siitä, kuinka usein asia esiintyi koulutusdatassa: miljoonia esimerkkejä sisältävä aihe toistetaan tarkasti, mutta vain muutaman esimerkin aiheesta malli arvaa samankaltaisten aiheiden perusteella. Toistaminen ja arvaaminen ovat mallille sama prosessi, joten se ei pysty erottamaan niitä. Keksitty vastaus tulee yhtä sujuvasti kuin oikea. Hallusinaatio tarkoittaa, että malli arvaa väärin.

Parametrinen tieto myös vanhenee. Parametrit lakkaavat muuttumasta tietorajauksessa, joten sen jälkeen julkaistu tai uudelleen nimetty kirjasto ei sisälly niihin, ja muuttunut API muistetaan vanhassa muodossaan.

Molempiin aukkoihin — tietoon, joka on liian harvinaista tai liian uutta — auttaa sama keino: tietoa ei voi lisätä parametreihin, joten se on annettava kontekstuaalisena tietona.

Käyttö:

”Se kirjoittaa virheetöntä Reactia mutta keksii menetelmiä sisäiseen SDK:homme.”

”Reactia on parametrisessa tiedossa runsaasti — miljoonia koulutusesimerkkejä. SDK:täsi ei ole, joten malli täyttää aukon uskottavan näköisillä rakenteilla. Lataa SDK-dokumentit kontekstiin.”

Päivämäärä, jonka jälkeen mallilla ei ole parametrista tietoa. Rajauksen jälkeiset kirjastot, API:t ja tapahtumat ovat keksimisen ansoja, ellei niiden dokumentaatiota ladata kontekstuaaliseksi tiedoksi. Jokaisella mallijulkaisulla on oma rajauksensa.

Rajaus johtuu mallien valmistustavasta: koulutus leipoo tekstin tilannekuvan mallin parametreihin, minkä jälkeen parametrit jäädytetään. Malli ei tiedä, että sen tiedoilla on raja — kun siltä kysytään rajauksen jälkeisestä asiasta, se ei kieltäydy vaan ekstrapoloi lähimmästä tuntemastaan asiasta. Tämän vuoksi ansa on huomaamaton: vanhaa kirjastoversiota käyttävä koodi näyttää uskottavalta, kääntyy usein ja epäonnistuu vain muuttuneissa osissa.

Ratkaisu on aina sama: tuo ajantasainen tieto kontekstiin. Lataa muutosloki, viittaa asennetun version tyyppimäärittelyihin tai pyydä agenttia lukemaan dokumentaatio verkosta. Mikä tahansa kontekstissa oleva tieto voittaa parametreista puuttuvan tiedon.

Käyttö:

”Se kirjoittaa jatkuvasti SDK v3:n syntaksia — meillä on v5.”

”v5 julkaistiin tietorajauksen jälkeen. Lataa v5:n muutosloki kontekstuaalisena tietona, muuten se jatkaa sepittämistä vanhemman parametrisen version pohjalta.”

Faktoja, jotka agentti voi lukea suoraan kontekstista juuri nyt — käyttäjän tehtävä, agentin lukemat tiedostot, työkalutulokset ja istunnon alussa ladattu AGENTS.md-sisältö. Vastakohta parametriselle tiedolle: parametrinen tieto palautetaan mieleen parametreista, kontekstuaalinen tieto luetaan ikkunasta. Hallusinaatiot ovat paljon harvinaisempia, kun agentti toimii kontekstuaalisen tiedon pohjalta — vastaus on aivan sen edessä eikä sitä kaiveta esiin sumeasta muistista.

Kahdesta tietotyypistä vain kontekstuaalista voit hallita. Parametrit on jäädytetty, joten ainoa tapa antaa mallille siltä puuttuvaa tietoa — sisäinen SDK, tietorajauksen jälkeen julkaistu kirjasto tai eilen tehty päätös — on lisätä se kontekstiin. Suuri osa käytännön tekoäly-koodaustyöstä tiivistyy tähän: oikeat faktat tuodaan mallin eteen juuri silloin, kun se niitä tarvitsee.

Kun kontekstuaalinen ja parametrinen tieto ovat ristiriidassa, kontekstuaalinen yleensä voittaa. Liitä nykyinen API-dokumentaatio, niin malli seuraa sitä vanhentuneen muistinsa sijaan — vaikka vanha versio voi yhä tihkua mukaan, etenkin pitkän istunnon loppupuolella. Jos agentti palaa vanhentuneeseen käytäntöön, vaikka dokumentaatio on ladattu, parametrinen tieto vuotaa kontekstuaalisen ohi; korjauksen toistaminen tai siirtäminen lähemmäksi työtä voi auttaa.

Toisin kuin parametrisen tiedon käyttö, kontekstuaalinen tieto maksaa. Kaikki ikkunaan ladattu kuluttaa tokeneita ja kilpailee mallin huomiobudjetista, joten lisätieto ei automaattisesti ole parempi — tavoitteena ovat ikkunassa olevat olennaiset faktat, eivät kaikki faktat.

Käytä tätä termiä vain verratessasi sitä parametriseen tietoon; muuten sano vain konteksti.

Vältä: ”työmuisti” — kontekstuaalinen tieto on sitä, mitä ikkunassa on nyt; muistijärjestelmä tuo istuntojen välisen sisällön ikkunaan. Eri mittakaavat, älä sekoita niitä.

Käyttö:

”Miksi se onnistuu API:ssa, kun liitän dokumentit, mutta keksii asioita, kun en liitä niitä?”

”Dokumenttien kanssa se käyttää kontekstuaalista tietoa — lukee suoraan sivulta. Ilman niitä tieto on parametrisoitua, ja harvinaiset päätepisteet hämärtyvät.”

Kun mallissa ennustetaan kutakin tokenia, se ottaa huomioon kaikki muut kontekstin tokenit — jotkin vahvasti, toiset tuskin lainkaan. Kahden tokenin välinen pari on huomiosuhde, ja merkitykselliset parit (”häntä” ja ”Sarah” tai `getUser()`-kutsu ja sen `function getUser` -määrittely) vaikuttavat toisiinsa enemmän kuin toisiinsa liittymättömät parit. N tokenin kontekstissa on suuruusluokaltaan N² suhdetta.

Parituksissa piilee mallin näennäinen ymmärrys. Kun se ratkaisee pronominin, syynä on vahva huomiosuhde sanojen ”häntä” ja ”Sarah” välillä. Kun se kutsuu funktiota oikeilla argumenteilla, aiemmin luetun määrittelyn ja kutsukohdan välinen suhde tekee työn. Mitään ei haeta — kaikki lasketaan uudelleen jokaisessa mallintarjoajan pyynnössä kaikkien parien osalta.

N²-lukua kannattaa pysähtyä miettimään, sillä se kasvaa intuitiota nopeammin:

Jokainen pari lasketaan lisäksi useammin kuin kerran. Malleissa on useita huomiointipäitä — huippumallien täsmällisiä määriä ei julkaista, mutta viidestäkymmenestä sataan on kohtuullinen arvio — ja kukin pää laskee jokaisen suhteen omalla tavallaan. Jokainen yllä olevan taulukon pari toistetaan siis jokaiselle päälle. Pareja riittää.

Kussakin tehtävässä vain pieni osa näistä suhteista on merkityksellisiä. Ohjeesi ja sen hallitseman koodin välinen pari on yksi harvoista tärkeistä; lähes kaikki muut joukon parit ovat kohinaa. Niiden kasvuvauhti on erilainen: tärkeiden suhteiden määrä pysyy suunnilleen vakiona, kun taas kokonaismäärä kasvaa kontekstin koon neliössä. Tuhannen tokenin kohdalla sinua kiinnostava pari on yksi miljoonasta; sadantuhannen tokenin kohdalla yksi kymmenestä miljardista. Tämä on huomiobudjetin taustalla oleva laskutoimitus, ja huomion heikkeneminen kuvaa sitä, miltä tärkeiden suhteiden osuuden kutistuminen tuntuu.

Käyttö:

”Se sekoittaa jatkuvasti diffin kaksi `user`-symbolia — taitaa olla tylsällä vyöhykkeellä.”

”Niin, kunkin kutsukohdan ja sen määrittelyn välinen huomiosuhde taistelee toisen kanssa — sama tokenmuoto, eri sidokset. Nimeä toinen uudelleen, niin parit erottuvat.”

Jokaisella tokenilla on rajallinen määrä vaikutusvaltaa, jonka se voi jakaa kontekstin muihin osiin. Suuri vaikutus yhteen suhteeseen jättää vähemmän muille. Budjetti on tokenkohtainen eikä kasva kontekstin mukana, minkä vuoksi pitkät istunnot laimentuvat.

Ajattele sitä signaalina ja kohinana. Ohjeesi on voimakkuudeltaan vakio signaali; jokainen muu konteksti-ikkunan token on kilpailevaa ääntä. Ohje ei koskaan hiljene — se on siellä merkki merkiltä — mutta kontekstin kasvaessa huone sen ympärillä muuttuu meluisammaksi ja signaali-kohinasuhde laskee. Ohje, joka oli äänekkäin asia kontekstin ollessa 10k tokenia, on taustahuminaa 150k tokenin kohdalla. Tämä on huomion heikkenemisen mekanismi: malli ei unohda, vaan signaali hukkuu kohinaan.

Oire näyttää tottelemattomuudelta — agentti hyväksyi rajoitteen istunnon alussa mutta alkaa poiketa siitä, ja rajoitteen liittäminen uudelleen auttaa vain hetken. Syy ei ole ohjeessa vaan kaikessa muussa, joka kilpailee sen kanssa ikkunassa.

Voit hallita sitä, mitä kontekstiin päätyy. Tehtävää palvelematon sisältö ei ole neutraalia — se lisää kohinaa kaiken hyödyllisen päälle. Pidä ikkuna pienenä, tyhjennä se, kun kertyneen kontekstin hyöty ei enää kata sen kustannusta, ja toista tärkeät rajoitteet sen sijaan, että luottaisit niiden varhain mainitsemisen riittävän.

Käyttö:

”Miksi se sivuuttaa jatkuvasti ylimpänä liittämääni skeemaa?”

”Olemme syvällä tylsällä vyöhykkeellä — jokaisen tokenin huomiobudjetti on kiinteä, mutta konteksti kasvoi edelleen. Skeemaa koskeva signaali kilpailee nyt tuhansien uudempien tokenien kanssa.”

Istunnon kasvaessa kunkin tokenin huomiobudjetti jakautuu useammalle kilpailijalle. Yhden merkityksellisen suhteen signaali heikkenee, ja epäolennaisen kontekstin kohina tunkeutuu mukaan. Sama malli, samat parametrit — vain enemmän suita ruokittavana samalta lautaselta. Syy terävän/tylsän vyöhykkeen vaikutukseen.

Tämä näkyy niin, että malli vaikuttaa huonommalta kesken istunnon: tunnin ajan noudattamansa rajoitteet alkavat lipsua, se kyselee asioita, joista sille jo kerrottiin, ja kirjoittaa koodia välittämättä aiemmin lukemastaan tiedostosta. Mallissa ei muuttunut mikään — ainoa muuttuja on se, kuinka paljon kontekstia se nyt käsittelee.

Muutos on asteittainen, minkä vuoksi sitä on vaikea huomata istunnon aikana. Virhettä tai kynnystä ei ole; jokainen vuoro on vain hieman edellistä huonompi, ja lipsahdusten tullessa ilmeisiksi olet ollut tylsällä vyöhykkeellä jo jonkin aikaa.

Toipuminen edellyttää kontekstin vähentämistä, ei lisäämistä. Ohitetun ohjeen liittäminen uudelleen lisää kilpailijan samaan ahtaaseen ikkunaan ja auttaa vain hetken. Toimivat keinot: tyhjennä istunto ja lataa vain tehtävän tarvitsemat asiat, tiivistä tai luovuta työ uudelle istunnolle. Käsittele ohjeiden noudattamisen heikkenemistä merkkinä kontekstin pituudesta, älä mallista.

Käyttö:

”Se on syvällä tylsällä vyöhykkeellä — keksii geneerisiä tyyppejä, joita tyyppitiedostossa ei ole.”

”Huomion heikkeneminen. Tyyppimääritykset ovat yhä kontekstissa, mutta niiden signaali hautautui kaiken myöhemmin lisäämämme alle. Tyhjennä ja lataa uudelleen.”

Istunnon alussa agentti on ”terävällä vyöhykkeellä” — tarkka, keskittynyt ja muistaa hyvin. Istunnon kasvaessa se ajautuu ”tylsälle vyöhykkeelle”: huolimattomammaksi, unohtelevammaksi, virhealttiimmaksi — ja tuottaa enemmän uskollisuuteen liittyviä hallusinaatioita. Sama malli, sama agenttiympäristö — vain enemmän kontekstia. Tämä on huomion heikkenemisen tuntuva vaikutus. Kehittyneimmissä malleissa tylsä vyöhyke alkaa tavallisesti noin 125K–150K tokenin kohdalla, mutta asiasta kiistellään. Tyhjennä tai tiivistä istunto sen paisuessa; älä puske läpi.

Heikkeneminen on asteittaista, joten se jää helposti huomaamatta. Virheilmoitusta tai näkyvää rajaa ei ole; agentti vain alkaa suoriutua hieman huonommin ja sitten selvästi huonommin. Yleisiä merkkejä ovat kaksikymmentä vuoroa aiemmin annetun ohjeen unohtaminen, jo korjatun virheen toistaminen tai kontekstin vastaisen asian itsevarma väittäminen. Koska heikkeneminen on tasaista, tavallinen reaktio on puskea eteenpäin ja selittää uudelleen — mikä lisää kontekstia ja pahentaa ongelmaa.

Vyöhykkeet eivät seuraa konteksti-ikkunan rajaa. Istunto voi olla syvällä tylsällä vyöhykkeellä, vaikka suurin osa ikkunasta olisi vielä vapaana: raja tarkoittaa hetkeä, jolloin agenttiympäristö kieltäytyy jatkamasta, mutta laatu heikkenee paljon aiemmin. Suunnittele terävän vyöhykkeen, älä ikkunan mukaan — tehtävän käytännön budjetti on tokenien määrä, jonka agentti pystyy käsittelemään hyvin, ei määrä, jonka se pystyy teknisesti pitämään.

Terävä vyöhyke on budjetti, ja asiaan kuulumaton työ kuluttaa sitä. Jokainen istunnon tehtävä käyttää tokeneita, joten toisen tehtävän aloittaminen samassa istunnossa tarkoittaa lähempänä tylsää vyöhykettä aloittamista. Yksi tehtävä istuntoa kohden antaa kullekin tehtävälle istunnon terävimmän osan. Jos yksittäinen tehtävä on yhtä terävää vyöhykettä suurempi, jaa se: luovuta työ tai tiivistä luonnollisessa rajakohdassa ja anna uuden istunnon tehdä seuraava osuus.

Käyttö:

”Se sai kolme ensimmäistä komponenttia oikein ja pilasi neljännen.”

”Olet terävän vyöhykkeen ulkopuolella — sama malli, vain syvällä tylsällä vyöhykkeellä nyt. Tiivistä ja lataa suunnitelma uudelleen; seuraava komponentti onnistuu.”

Nykyisen istunnon lopettaminen ja uuden aloittaminen. Seuraava viesti alkaa tyhjästä istunnosta ja tyhjästä konteksti-ikkunasta. Yleensä käyttäjän käynnistämä.

Tyhjentäminen parantaa saastuneen kontekstin. Istuntoon kertyy kaikkea: epäonnistuneita yrityksiä, vääriä polkuja, vanhentuneita työkalutuloksia ja hylättyjä suunnitelmia. Malli lukee ne kaikki uudelleen jokaisella vuorolla, ja huono historia painaa uutta työtä. Pitkän istunnon loppupuolella agentista tulee epämääräisempi ja vähemmän kuuliainen — selkeästi annetut ohjeet sivuutetaan, laatu laskee, eikä parempaan kehottaminen auta, koska kahlaamaansa kohinaa agentti kantaa yhä kontekstissaan. Tyhjennys poistaa kohinan.

Tyhjennys ei pyyhi keskustelua. Useimmat agenttiympäristöt säilyttävät istuntohistorian tietokoneellasi, joten keskustelulokia voi edelleen lukea tai käyttää istunnon jatkamiseen. Agentin työtila kuitenkin katoaa: malli on tilaton, joten uusi istunto ei tiedä mitään siitä, mitä edellinen tiesi. Jos istunnossa on päätöksiä tai edistymistä, joita seuraava tarvitsee, pyydä agenttia kirjoittamaan ensin luovutusartefakti ja viittaa siihen uuden istunnon alussa.

Vertaa tiivistämiseen, jossa istunto tiivistetään uuden kontekstin osaksi sen sijaan, että aloitettaisiin tyhjästä. Tyhjentäminen on karkeampi työkalu: mitään ei siirry mukana, myöskään roskat.

Käyttö:

”Se on jumissa epäonnistuvan testin toistuvassa ajossa.”

”Tyhjennä vain — aloita uusi istunto suunnitelmadokumentin ja testitiedoston kanssa. Nykyistä kontekstia vastaan taistelemisessa ei ole järkeä.”

Siirrä agentin konteksti yhdestä istunnosta toiseen. Siirtotapa vaihtelee — kirjoitettu luovutusartefakti, muistissa oleva yhteenveto (tiivistys) tai jokin muu. Eroaa tyhjentämisestä, jossa mitään ei siirry. Syitä ovat esimerkiksi roolin vaihto (suunnittelija → toteuttaja), AFK-ajon käynnistys, työn jakaminen rinnakkaisiin istuntoihin tai tilan vapauttaminen konteksti-ikkunaan.

Vastaanottava istunto aloittaa ilman kontekstia — malli on tilaton, eikä mikään vanhasta istunnosta näy uudelle. Kaikki seuraavan istunnon tarvitsema on siirrettävä erikseen; muu katoaa. ”Ei paluureittiä” on siirron muotoa rajaava ehto: uusi istunto ei voi kysyä vanhalta, mitä tämä tarkoitti, joten siirretyn aineiston täytyy toimia itsenäisesti.

Huonon luovutuksen näkyvä virhe on asian uudelleenkäsittely: uusi istunto avaa vanhan istunnon ratkaisemia päätöksiä, koska siirto tallensi mitä päätettiin muttei miksi. Arvioi luovutusta sen perusteella, mitä täysin kontekstiton istunto voisi tehdä sen avulla.

Käyttö:

”Suunnitteluistunto on käymässä raskaaksi — pitäisikö vain jatkaa?”

”Tee luovutus. Kirjoita päätökset dokumenttiin, tyhjennä istunto ja aloita toteutus uudessa istunnossa, joka lukee dokumentin.”

Alkuperäisessä muodossaan oleva tiedon lähde — koodi, keskusteluloki, raakamuotoinen loki tai todellinen API-vastaus. Ei kuvaus asiasta vaan itse asia. Vastakohta toissijaiselle lähteelle.

Jos haluat tietää, mitä koodikantasi tekee, koodi on ensisijainen lähde. Dokumentit, arkkitehtuurikaavio ja README ovat sen kuvauksia — paikkansapitäviä kirjoitushetkellä, mutta sen jälkeen omassa aikataulussaan. Kun agentti väittää itsevarmasti jotakin projektistasi väärin, kysy, minkä lähteen perusteella se toimi: dokumentin lukenut agentti perii sen vanhentuneisuuden; koodin lukenut agentti tarkastelee nykyistä totuutta.

Kustannus estää ensisijaisia lähteitä olemasta oletusvalinta. Niiden lataaminen konteksti-ikkunaan on kallista — koko tiedosto, koko keskusteluloki ja jokainen token laskutettuna syötteenä sekä kilpailemassa huomiobudjetista. Saat vastineeksi täydellisyyden: kukaan ei ole esisuodattanut sisältöä oman arvionsa mukaan siitä, mikä oli tärkeää. Viime kuussa kirjoitettu tiivistelmä ei voi sisältää yksityiskohtaa, joka osoittautui tärkeäksi tänään; ensisijaisessa lähteessä se on yhä mukana.

Tartu ensisijaiseen lähteeseen, kun tarkkuudella on väliä — tarkka allekirjoitus, todellinen virhe tai poikkeuksen aiheuttava rivi. Suuri osa kontekstin hallinnasta on sen päättämistä, milloin ensisijaisen lähteen kustannus kannattaa maksaa ja milloin toissijainen lähde riittää.

Käyttö:

”Agentti sanoo, että uudelleenyrityslogiikka kasvattaa viivettä eksponentiaalisesti, mutta näen sen pommittavan päätepistettä.”

”Se luki sen suunnitteludokumentista. Ohjaa se varsinaiseen uudelleenyritysmoduuliin — käytä ensisijaista lähdettä, kun toiminnalla on väliä.”

Ensisijaisen lähteen kuvaus, yhden askeleen päässä kohteesta — koodia kuvaava dokumentaatio, keskustelulokia kuvaava tiivistelmä tai hakutuloksia kuvaava raportti. Halvempi ladata konteksti-ikkunaan kuin sen kuvaama lähde ja rakenteeltaan häviöllinen: kirjoittaja päätti, mikä oli tärkeää, ja pois jätetty jää piiloon lukijalta, jolla on käytössään vain tiivistelmä.

Suuri osa kontekstin suunnittelusta on toissijaisten lähteiden tuottamista. Tiivistys muuttaa istunnon historian tiivistelmäksi, josta seuraava istunto aloittaa. Aliagentti käyttää omaa kontekstiaan meluisaan hakuun ja palauttaa lyhyen raportin. Luovutusartefakti tiivistää istunnon päätökset asiakirjaksi, jonka seuraava istunto lukee. Muistijärjestelmät kiteyttävät istunnon oppiman muistiinpanoiksi. Kaikissa tehdään sama vaihtokauppa: tarkkuudesta luovutaan liikkumavaran hyväksi.

Toissijaiset lähteet pettävät kahdella tavalla. Ne ovat häviöllisiä — tiivistelmä kadottaa skeemapäätöksen tai raportti ei mainitse reunatapausta. Lisäksi ne vanhenevat — ensisijainen lähde muuttuu mutta kuvaus ei seuraa mukana, joten dokumentit kuvaavat viime neljänneksen arkkitehtuuria tämän neljänneksen varmuudella. Kun agentti toimii kummalla tahansa tavalla epäonnistuneen toissijaisen lähteen perusteella, se työskentelee itsevarmasti väärällä tiedolla; ratkaisuna on palauttaa se ensisijaisen lähteen äärelle.

Kumpikaan puute ei tee toissijaisista lähteistä virhettä. Konteksti-ikkuna on rajallinen ja ensisijaiset lähteet kalliita; ilman tiivistelmiä, raportteja ja luovutusasiakirjoja mikään suuri ei mahtuisi mukaan. Taito on tietää, mitkä yksityiskohdat kestävät pois jättämisen — ja varmistaa tieto ensisijaisesta lähteestä silloin, kun ne eivät kestä. Hyvin laadittu toissijainen lähde sisältää kontekstiviitteen takaisin alkuperäiseen — tiivistelmä nimeää käyttämänsä keskustelulokin, dokumentti nimeää kuvaamansa tiedoston — joten kun kuvaus ei riitä, lukija voi seurata viitettä sen sijaan, että toimisi menetyksen varassa.

Käyttö:

”Luovutusdokumentin mukaan tunnistautuminen on valmis, mutta uusi istunto löytää jatkuvasti rikkinäisen tunnisteiden päivityksen.”

”Dokumentti on toissijainen lähde — edellinen istunto kirjasi uskomuksensa, ei totuutta. Pyydä uutta istuntoa suorittamaan tunnistautumistestit ja luottamaan ensisijaiseen lähteeseen.”

Luovutuksen kantomekanismina käytettävä asiakirja — yksi istunto kirjoittaa sen ympäristöön, jotta toinen voi lukea sen. Määrittelyt, liput ja suunnitelma-asiakirjat ovat kaikki luovutusartefakteja.

Syy kirjoittamiseen: malli on tilaton, joten istunnosta ei säily mitään sen tyhjentämisen jälkeen. Päätökset, rajoitteet ja keskeneräiset suunnitelmat katoavat niitä sisältävän kontekstin mukana. Ympäristö säilyy. Kun tärkeä tila kirjoitetaan tiedostoon, se siirtyy paikkaan, josta seuraava istunto voi lukea sen.

Artefakti on toissijainen lähde — kuvaus istunnon työstä, ei itse työ. Siksi se on tarpeeksi pieni uuden istunnon perehdyttämiseen, ja siksi se voi myös johtaa harhaan: se kirjaa kirjoittaneen istunnon uskomukset, ja kaikki pois jätetty tai väärin ymmärretty jää lukijalta piiloon. Kun jokin väite on tärkeä, seuraavan istunnon pitäisi varmistaa se ensisijaisesta lähteestä — koodista ja testeistä — eikä vain periä väitettä.

Hyvä artefakti kirjoitetaan istuntoa varten, jolla ei ole lainkaan kontekstia. Konkreettiset tiedostopolut ”sen tiedoston, josta keskustelimme” sijaan. Mitä päätettiin ja miksi, jotta seuraavan istunnon ei tarvitse kiistellä asiaa uudelleen. Mikä on tehty ja mikä jäljellä. Kirjoitusistunnolle kannattaa kertoa, minne artefakti on menossa: ”kirjoita luovutusdokumentti uudelle istunnolle, joka ei tiedä tästä työstä mitään”.

Toinen kantomekanismi on tiivistäminen, joka tiivistää muistin sisällön. Artefaktilla on kaksi etua: se sijaitsee levyllä, josta voit lukea ja korjata sen ennen kuin mikään perustuu siihen, ja sitä voi käyttää uudelleen — sama määrittely voi perehdyttää viisi rinnakkaista istuntoa.

Käyttö:

”Miten jaan tämän suunnittelevan agentin ja toteuttavan agentin välillä?”

”Pyydä suunnittelijaa kirjoittamaan luovutusartefakti — tiedostopolut, päätökset ja rajoitteet. Toteuttajan istunto aloittaa artefaktiin osoittavalla viitteellä ja käyttää sitä tehtävänantona.”

Luovutusartefakti, joka kuvaa usean istunnon mittaista työtä — mitä rakennetaan, ei sitä, miten kukin istunto hoitaa oman osuutensa. Muuttuu työn edetessä. Koostuu lipuista.

Määrittelyä tarvitaan, koska istunnot ovat kertakäyttöisiä mutta suuri työ ei ole. Kaikki yli yhden konteksti-ikkunan vaativa työ tarvitsee kodin kontekstin ulkopuolelta — jonkin paikan agentin ympäristössä, joka säilyy tyhjennyksen jälkeenkin, olipa se repossa oleva tiedosto, GitHub-issue tai agentin tavoittama tehtävienhallinta. Määrittely on tuo koti: tavoite, rajoitteet, tähän asti tehdyt päätökset ja lippujen luettelo tiloineen. Mikä tahansa uusi istunto voi lukea sen ja tietää työn tilanteen perimättä edellisen istunnon kertynyttä kohinaa.

Määrittelyillä on tunnistettavia tyylejä, jotka ovat enimmäkseen peräisin siitä, miten tiimit jo ennestään kirjaavat asioita. Tuotevaatimusmäärittely (PRD) painottuu käyttäjälle näkyvään mitä- ja miksi-kysymykseen — ominaisuuksiin, toimintaan ja hyväksymiskriteereihin. Suunnitteludokumentti tai RFC painottuu tekniikkaan — valittuun lähestymistapaan, hylättyihin vaihtoehtoihin ja kompromisseihin. Pienessä päässä yksinkertainen `plan.md`, jossa on lippujen tarkistuslista, hoitaa saman tehtävän usean istunnon ominaisuudelle. Tyyli on roolia vähemmän tärkeä: agentille nämä kaikki ovat sama asia — pysyvä tarkoituksen kuvaus, jonka se lukee jokaisen istunnon alussa.

Käyttö:

”Pitäisikö tämän kaiken olla yhdessä istunnossa?”

”Ei, kirjoita siitä määrittely — jaa se lipuiksi ja käsittele kukin omassa istunnossaan. Koko työn yrittäminen yhdessä kontekstissa vie tylsälle vyöhykkeelle jo ennen puoliväliä.”

Luovutusartefakti, joka rajaa yhden työskentely-istunnon. Toimii itsenäisesti tai on määrittelyn lapsiosa. Liput voivat estää sisaruslippuja tai olla niiden estämiä, joten työn järjestys seuraa riippuvuuskaaviosta eikä lineaarisesta suunnitelmasta.

Määrittävä rajoite on koko: yksi istunto. Lipun pitäisi valmistua ennen kuin istunto ajautuu terävältä vyöhykkeeltä pois — ja tätä voi testata. Jos istunnot tavallisesti heikkenevät ennen lippujen valmistumista, liput ovat liian suuria; jaa ne. Jos jokaisesta istunnosta kuluu suurin osa kontekstista alustukseen ennen viiden minuutin työrupeamaa, ne ovat liian pieniä; yhdistä niitä.

Hyvä lippu on kirjoitettu lukijalle, jolla ei ole muuta kontekstia. Tavoite, hyväksymiskriteerit ja kontekstiviitteet asiaankuuluviin tiedostoihin ja päätöksiin — tarpeeksi, jotta istunto voi aloittaa työn johtamatta uudelleen siitä, mitä edellinen tiesi.

Riippuvuuskaavio mahdollistaa myös rinnakkaisuuden. Riippumattomat liput — kaavion lehdet — voidaan kukin suorittaa omassa istunnossaan samaan aikaan. Tämä on tehokas tapa ajaa useita agentteja rinnakkain. Ohjelmistotehtaassa lipun merkitseminen valmiiksi käynnistää itsessään sen istunnon.

Käyttö:

”Mistä aloitan siirtomäärittelyn?”

”Katso lippukaaviota — skeemamuutos estää tietojen täydennyksen, ja täydennys estää API-vaihdon. Valitse lehtisolmu ja käynnistä sille istunto.”

Muistissa tehtävä luovutus: edellisen istunnon historia tiivistetään, ja tiivistelmä käynnistää uuden istunnon. Tarkoituksella häviöllinen: keskusteluloki on ensisijainen lähde, tiivistelmä toissijainen lähde — yksityiskohtia vaihdetaan liikkumavaraksi. Käyttäjä käynnistää sen manuaalisesti tai se tapahtuu automaattisesti automaattitiivistyksen kautta.

Mekanismi: konteksti-ikkuna on rajallinen ja pitkä istunto täyttää sen — jokainen työkalutulos, tiedostonluku ja väärä käänne jää historiaan. Kun ikkunasta tulee raskas, agenttiympäristö pyytää mallia tiivistämään istunnon siihenastisen sisällön, heittää alkuperäisen historian pois ja käynnistää uuden istunnon tiivistelmän pohjalta. Kaikki, mikä ei päätynyt tiivistelmään, katoaa kontekstista. Jotkin agenttiympäristöt lieventävät tätä säilyttämällä vanhan keskustelulokin levyllä ja jättämällä tiivistelmään kontekstiviitteen siihen — toissijainen lähde viittaa takaisin ensisijaiseen, joten tiivistelmästä kadonneen yksityiskohdan voi palauttaa lukemalla alkuperäisen uudelleen.

Tiivistelmän kirjoittaa malli, joten siihen voi vaikuttaa kehotteella. ”Säilytä skeemaa koskevat päätökset” tekee luodusta artefaktista harkitumman. Myös ajoituksella on merkitystä — tiivistä vaiherajalla, kun suunnitelma on valmis, älä kesken tehtävän.

Vertaa tyhjentämiseen, joka pudottaa kaiken ja aloittaa puhtaalta pöydältä: tiivistys yrittää kuljettaa olennaiset asiat mukana, tyhjentäminen luottaa siihen, että ne on jo kirjoitettu johonkin parempaan paikkaan.

Käyttö:

”Konteksti alkaa käydä raskaaksi, ja testit pitää vielä ajaa.”

”Tiivistä ennen kuin aloitat — kirjoita tiivistelmäkehotteeseen, mitä on säilyttävä, jotta uusi istunto pitää skeemaa koskevat päätökset ja pudottaa tutkimusretken.”

Agenttiympäristön automaattisesti käynnistämä tiivistys, kun konteksti-ikkuna alkaa täyttyä.

Agenttiympäristö tarkkailee konteksti-ikkunan täyttöastetta. Kun se ylittää rajan — usein noin 80 % — agenttiympäristö keskeyttää, pyytää mallia tiivistämään istunnon siihenastisen sisällön ja alustaa uuden istunnon tiivistelmällä. Työ jatkuu sitten aivan kuin mitään ei olisi tapahtunut.

Mutta jotakin tapahtui. Tiivistys on häviöllistä, ja automaattitiivistys on häviöllistä hetkellä, jota et valinnut. Manuaalinen tiivistys tehdään vaiherajalla, jolloin voit kertoa mallille, mitä säilytetään. Automaattitiivistys käynnistyy kesken tehtävän heti, kun raja saavutetaan — mahdollisesti refaktoroinnin puolivälissä, jolloin tiivistelmä päättää itse, mitkä päätöksesi kannattaa säilyttää. Tyypillinen oire: agentti jatkaa itsevarmana mutta on hiljaa unohtanut tunti sitten asettamasi rajoitteen, ja huomaat sen vasta, kun työ alkaa olla ristiriidassa sen kanssa.

Puolustuskeino on estää käynnistyminen. Tarkkaile konteksti-ilmaisinta ja tiivistä manuaalisesti luonnollisessa rajakohdassa tai kirjoita päätökset suunnitelma-asiakirjaan tai levyllä olevaan luovutusartefaktiin, josta tiivistelmä ei voi kadottaa niitä. Useimmissa agenttiympäristöissä voit myös muokata puskuria — siirtää rajaa aiemmaksi tai myöhemmäksi tai poistaa automaattitiivistyksen kokonaan käytöstä — ja säätää siten, kuinka paljon pelivaraa jätät ennen sen laukeamista.

Käyttö:

”Se ei tunnu muistavan, mitä aiemmin päätimme skeemasta.”

”Automaattitiivistys käynnistyi vuorojen välissä — varhaiset päätökset tiivistettiin ja jotakin taisi kadota. Lataa suunnitelma-asiakirja uudelleen tai tiivistä ensi kerralla manuaalisesti, jotta voit päättää mitä säilytetään.”

Järjestelmä, joka yrittää tehdä agentista tilallisen istuntojen välillä. Se tallentaa tietoa ympäristöön istunnon aikana ja lataa sitä tulevien istuntojen alussa konteksti-ikkunaan, jotta agentti säilyttää jatkuvuuden senkin jälkeen, kun käyttäjä tyhjentää istunnon.

Muistijärjestelmässä on kaksi puoliskoa. Kirjoituspolku: istunnon aikana agentti tallentaa oppimansa — käyttäjän ilmaiseman mieltymyksen tai projektiin liittyvän tiedon — ympäristön tiedostoihin. Lukupolku: istunnon alussa agenttiympäristö lataa nämä tiedostot tai niiden hakemiston takaisin konteksti-ikkunaan. Monissa agenttiympäristöissä on oma muistijärjestelmä — Claude Coden `/memory` on yksi sellainen — mutta voit rakentaa oman: muistiinpanohakemisto ja AGENTS.md:hen lisätty ohje AGENTS.md-tiedostossa sen lukemisesta.

Samat kompromissit koskevat kaikkea aina mukana olevaa sisältöä. Muistoja kertyy, joten useimmat järjestelmät lataavat yhden rivin hakemiston ja jättävät varsinaiset sisällöt kontekstiviitteiden taakse sen sijaan, että upottaisivat kaiken. Muistot ovat lisäksi toissijaisia lähteitä, joten ne vanhenevat: maaliskuussa tallennettu tieto ladataan kesäkuussa samalla varmuudella, vaikka projekti on edennyt. Muistijärjestelmä tarvitsee karsimista siinä missä AGENTS.md:kin.

Käyttö:

”Joudun jatkuvasti kertomaan sille uudestaan, että käytämme Postgresia, emme MySQL:ää.”

”Ota muistijärjestelmä käyttöön — tallenna sen oppimat asiat tiedostojärjestelmään ensimmäisellä vuorolla ja lataa ne uudelleen istunnon alussa. Malli itse on tilaton; muistikerros teeskentelee jatkuvuutta.”

Ympäristössä oleva tiedosto, jonka agenttiympäristö lataa konteksti-ikkunaan istunnon alussa — projektin pysyvä ohje agentille. Ympäristöjen välinen käytäntö; joillakin ympäristöillä on lisäksi oma versionsa (Claude Coden tiedosto on CLAUDE.md).

Automaattisen latautumisen ansiosta tämä auttaa välttämään samojen asioiden toistelua eri istunnoissa. Malli on tilaton — yhdessä istunnossa annettu korjaus katoaa seuraavassa, ja joudut kertomaan jokaiselle uudelle istunnolle, että projekti käyttää pnpm:ää, testit suoritetaan tietyllä lipulla ja hakemisto on generoitu eikä sitä saa muokata. Kun olet korjannut agenttia samasta asiasta kahdesti, korjaus sopii lisättäväksi AGENTS.md-tiedostoon.

Sopivaa sisältöä on kaikki, mitä agentti ei voi päätellä koodista: koonti- ja testikomennot, koodikannan epäselvät käytännöt ja tiukat rajoitteet (”älä koskaan muokkaa generoituvaa asiakasohjelmaa”). Lyhyesti ja toteavasti — se on ohje, ei dokumentaatio.

Kompromissina kaikkea sen sisältöä ladataan aina. Ohjeita kertyy, ja useimmat eivät liity yksittäiseen tehtävään; pitkä AGENTS.md maksaa tokeneita ja laimentaa itseään — mitä enemmän ohjeita kontekstissa on, sitä huonommin malli noudattaa kutakin niistä.

Vältä: AGENTS.md:n käyttämistä sisällölle, joka pitäisi paljastaa vaiheittain — kaikki sen sisältö maksaa tokeneita jokaisella vuorolla, jokaisessa istunnossa, tarvitsipa istunto niitä tai ei. Tyylioppaan voi sijoittaa taidon taakse tai tuoda esiin kontekstiviitteellä; pidä AGENTS.md niille ohjeille, jotka pätevät kaikkialla.

Käyttö:

”Miksi jokainen istunto alkaa niin, että 4k tokenia on jo kulunut?”

”Tarkista AGENTS.md — joku liitti sinne koko tyylioppaan sen sijaan, että olisi asettanut sen taidon taakse.”

Lataa vain se konteksti, jota agentti tarvitsee juuri nyt, ja käytä kontekstiviitteitä muuhun. Käsite on lainattu käyttöliittymäsuunnittelusta, jossa käyttäjille näytetään vain heidän nykyiseen tehtäväänsä liittyvät ohjaimet ja loput piilotetaan napsautuksen taakse.

Tekniikka on olemassa, koska konteksti maksaa kahdesti. Jokainen etukäteen ladattu token laskutetaan syötetokenina jokaisella vuorolla, ja jokainen token kuluttaa huomiobudjettia riippumatta siitä, tarvitseeko agentti sitä. AGENTS.md, johon on tungettu koko tyyliopas, käyttöönoton toimintaohje ja tietokantakäytännöt, heikentää agentin suoriutumista niissä kaikissa — nykyisen tehtävän kannalta tärkeät ohjeet laimenevat tarpeettomien joukkoon. Tämän huomaa siitä, että agentti sivuuttaa sääntöjä, joiden tiedät olevan sen kontekstissa: ne ovat mukana mutta hautautuneina.

Vaiheittainen paljastaminen kääntää tämän päinvastaiseksi. Pidä aina ladattava kerros pienenä — yksi lause aihetta kohden ja viite yksityiskohtien sijaintiin. Agentti lukee tyylioppaan komponenttia kirjoittaessaan, käyttöönoton toimintaohjeen ottaessaan järjestelmää käyttöön eikä kumpaakaan korjatessaan testiä. Taidot ovat agenttiympäristöön sisäänrakennettu toimintamalli: lyhyt kuvaus ladataan jokaisessa istunnossa, ja täydet ohjeet vasta taidon aktivoituessa.

Käyttö:

”Pitäisikö koko tyyliopas lisätä AGENTS.md:hen?”

”Ei — vaiheittainen paljastaminen. Viittaa tyylioppaaseen taitona, jonka agentti lataa, kun sen todella pitää kirjoittaa komponentti. AGENTS.md:hen laitettuna se kuluttaa tokeneita joka vuorolla.”

Maininta yhdessä asiakirjassa, joka osoittaa toiseen, jotta agentti voi tuoda sen konteksti-ikkunaan vasta silloin, kun tehtävä sitä edellyttää. Vaiheittaisen paljastamisen perusrakenne.

Viitteen käytön syy sisällön upottamisen sijaan on kustannus. Viite vie konteksti-ikkunassa yhden rivin. Sen takana oleva asiakirja voi sisältää tuhansia tokeneita, mutta ne eivät maksa mitään, ennen kuin agentti todella seuraa viitettä. Upota 2 000 tokenin toimintaohje AGENTS.md-tiedostoon, niin jokainen istunto maksaa siitä; korvaa se ilmauksella ”käyttöönotto: katso `internal/deploy.md`”, niin vain käyttöönottoja tekevät istunnot lataavat sisällön. Agentti seuraa viitettä työkalukutsulla, kun tehtävä sopii siihen.

Viite tarvitsee kaksi asiaa toimiakseen: pysyvän polun ja riittävän kuvauksen, jotta agentti tietää, milloin sitä kannattaa seurata. Pelkkä polku ei anna agentille syytä seurata viitettä; ”katso `internal/deploy.md`” ilman vihjettä sisällöstä jää lukematta istunnolta, joka sitä tarvitsisi. Muotoile rivi tehtäviä vastaavaksi: ”julkaisu, käyttöönotto tai palautus — lue ensin `internal/deploy.md`”.

Viitteitä on kaikkialla, kun niitä alkaa etsiä: AGENTS.md-riveillä, taito-kuvauksissa (agenttiympäristö lataa kuvauksen, mutta taidon varsinainen sisältö pysyy sen takana), hakemistolistauksen tiedostonimissä ja dokumenttien välisissä linkeissä.

Viite voi myös yhdistää toissijaisen lähteen siihen ensisijaiseen lähteeseen, josta se on johdettu — tiivistelmän alkuperäiseen keskustelulokiin tai tiedoston sitä kuvaavaan asiakirjaan. Näin toissijaisen lähteen häviöllisyys voidaan korjata: kun käy ilmi, ettei tiivistelmä riitä, agentti seuraa viitettä ja lukee alkuperäisen sen sijaan, että toimisi vain tiivistelmässä säilyneen tiedon perusteella.

Vältä: ”viite” — liian kuiva eikä ilmaise, että sen seuraaminen tuo lisää kontekstia. ”Portaali” — liian koristeellinen.

Käyttö:

”AGENTS.md:stä tulee valtava.”

”Suurimman osan pitäisi olla kontekstiviitteitä, ei sisältöä. Pidä aina voimassa olevat säännöt mukana; tee käyttöönottokäsikirjasta ja tyylioppaasta taitoja ja jätä niiden taakse kontekstiviite.”

Yksikkönä paketoitu opetettava kyky — ohjeet ja resurssit yhden tehtävän hyvään suorittamiseen. Se pysyy ympäristössä, kunnes kontekstiviite tuo sen konteksti-ikkunaan käsillä olevaa tehtävää varten. Vaiheittaisen paljastamisen yksikkö agenttiympäristössä.

Taidot ovat avoin standardi, joka määritellään osoitteessa agentskills.io — Anthropic kehitti standardin alun perin, ja useimmat suuret agenttiympäristöt ovat sittemmin ottaneet sen käyttöön, joten kerran kirjoitettu taito toimii niissä kaikissa. Tiedostomuoto on kansio, jossa on:

• `SKILL.md`-tiedosto — metatiedot (vähintään nimi ja kuvaus) sekä varsinaiset ohjeet
• Valinnaisesti skriptejä, joita agentti voi suorittaa
• Valinnaisesti malleja ja viitemateriaalia, joihin ohjeet viittaavat

Oletuksena kontekstissa ovat vain nimi ja kuvaus. Kun agentin tehtävä vastaa taitoa, agentti lataa loput. Sitä ennen taito vie tuskin lainkaan tilaa — pari tokenia, vaikka täydet ohjeet olisivat kuinka laajat.

Tämä erottaa taidot AGENTS.md-tiedostosta, joka ladataan jokaiseen istuntoon tehtävästä riippumatta. Taito luetaan, kun tietynlainen työ tulee vastaan — julkaisu, uuden palvelun rungon luominen tai migraation kirjoittaminen — ja muulloin se jätetään huomiotta.

Vältä: ”työkalu” — työkalu on se, jota agentti kutsuu; taito sisältää ohjeet, jotka se lukee.

Käyttö:

”Mihin käyttöönoton toimintaohje pitäisi laittaa?”

”Taidoksi — agentti lataa sen vain, kun tehtävä liittyy käyttöönottoon. AGENTS.md:ssä se kuluttaisi tokeneita jokaisella vuorolla, vaikka käytämme sitä vain viikoittain.”

Agentin työkalukutsulla käynnistämä aliagentti. Toimii omassa istunnossaan ja omassa konteksti-ikkunassaan ja palauttaa yhden työkalutuloksen. Eri asia kuin luovutus — yläagentti odottaa nimenomaan paluuviestiä; luovutuksella ei ole paluureittiä. Ei voi käynnistää uusia aliagentteja — puussa on vain yksi taso. Aliagenttien tarkoitus on eristää konteksti, ei rakentaa hierarkioita.

Tarkoitus on pitää häly työstä poissa yläagentin kontekstista. Laaja haku tai pitkä tiedostonlukuretki tuottaa sivukaupalla työkalutuloksia, joista useimmilla on merkitystä vain niin kauan kuin vastausta etsitään. Jos työ tehdään yläagentin sisällä, kaikki jää sen kontekstiin istunnon loppuajaksi. Aliagentin sisällä häly täyttää kertakäyttöisen ikkunan — yläagentin kontekstiin päätyy vain loppuraportti. Raportti on toissijainen lähde: yläagentti saa aliagentin kuvauksen löydöksistä raakamuotoisten tulosten sijaan, joten kaikki pois jätetty jää yläagentilta piiloon.

Aliagentit voivat myös työskennellä rinnakkain — yläagentti voi lähettää useita agentteja yhtä aikaa eri osatehtäviin.

Käyttö:

”Grepin tulokset paisuttavat kontekstiani.”

”Käynnistä haku aliagenttina — se kuluttaa oman konteksti-ikkunansa kohinaan ja raportoi takaisin kaksi tarvitsemaasi tiedostopolkua.”

Työskentelymalli, jossa yksi tai useampi ihminen työskentelee agentin kanssa saman istunnon aikana — tarkistaa, ohjaa uudelleen tai tekee yhteistyötä reaaliajassa. Ihminen on läsnä ja mukana, eikä vain hyväksy yksittäisiä toimia.

Vastakohtana on AFK-työ, jossa agentti toimii ilman valvontaa ja arvioit tuloksen jälkikäteen. Human-in-the-loop tarkoittaa ongelmien havaitsemista silloin, kun niiden korjaaminen on vielä halpaa: huomaat agentin valitsevan väärän tiedoston, lukevan vaatimuksen väärin tai lähtevän harhapolulle ja ohjaat sitä uudelleen yhdellä virkkeellä sen sijaan, että löytäisit vasta kahdenkymmenen minuutin päästä itsevarman työn, joka perustuu tähän virheeseen. Agentit eivät luotettavasti tiedä olevansa väärällä polulla; yksin jätettyinä ne jatkavat yleensä eteenpäin pysähtymisen ja kysymisen sijaan.

Sopiva toimintamalli riippuu työstä. Hyvin määritellyt, vähäriskiset ja helposti varmennettavat tehtävät sopivat AFK-tilaan. Epäselvät, peruuttamattomat tai vaikeasti jälkikäteen tarkistettavat tehtävät — skeemamuutto, hankala suunnittelupäätös, kaikki tuotantoon liittyvä — sopivat siihen, että pysyt mukana. Arvioinnissa kysytään käytännössä: kuinka kallis väärä käänne on ja kuinka myöhään huomaisit sen?

Osa työstä on luonteeltaan jatkuvan osallistumisen varassa, sillä reaktiosi ovat sen syöte. Tenttaaminen toimii vain, kun olet paikalla vastaamassa kysymyksiin; prototypointi vain, kun olet paikalla reagoimassa artefaktiin.

Mukana pysyminen vie huomiotasi, joka on niukka resurssi. Agenttien käytön kehittämiseen kuuluu yhä suuremman työmäärän siirtäminen turvallisesti pois silmukasta — suunnitelmien, automaattisten tarkistusten ja lopussa tehtävän ihmisen suorittaman katselmoinnin avulla jatkuvan valvonnan sijaan. Ohjelmistotehdas vie tämän pidemmälle käynnistämällä istuntoja laukaisimista, jolloin edes työn käynnistäminen ei vaadi sinua.

Käyttö:

”Ajetaanko tätä AFK-tilassa yön yli?”

”Ei, tämä on skeemamuutto — pidä ihminen mukana. Haluan nähdä jokaisen vaiheen ja ohjata, jos se valitsee väärän sarakkeen tietojen täydennystä varten.”

Poissa näppäimistöltä. Työskentelymalli, jossa käyttäjä käynnistää istunnon ja jättää agentin toimimaan valvomatta. AI-avusteisen koodauksen läpimenokyvyn kerroin — useita AFK-istuntoja voi ajaa rinnakkain sillä aikaa kun nukut, syöt tai teet muuta. Turvallinen käyttö edellyttää yleensä sallivaa käyttöoikeustilaa ja hiekkalaatikotusta.

Kun et ole paikalla, agentti käsittelee epäselvyyksiä eri tavalla. Kun seuraat työtä, epäselvästä päätöksestä esitetään kysymys ja vastaat siihen; kun olet lähtenyt, agentti valitsee oletusarvon ja jatkaa, ja jokainen myöhempi päätös rakentuu tämän arvauksen varaan. Tyypillinen epäonnistuminen on palata tuntien valmiin, itsevarman työn ääreen ja huomata sen perustuvan kymmenen ensimmäisen minuutin aikana tehtyyn väärään valintaan. Työ ei ole huolimatonta — se on johdonmukaista, mutta väärän asian suhteen.

Koska et voi antaa palautetta ajon aikana, anna sitä ennen ja jälkeen. Ennen ajoa: ratkaise epäselvyydet etukäteen — tenttausistunnolla tai kirjallisella määrittelyllä — jotta agentille jää vähemmän yksin täytettäviä aukkoja. Ajon aikana: automaattiset tarkistukset ja automaattinen katselmointi korvaavat puuttuvan huomiosi ja pysäyttävät koneellisesti havaittavat ongelmat nopeasti. Ajon jälkeen: tuloksena pitää olla tarkistettava artefakti — PR, ei jo yhdistettyjä muutoksia. AFK ei poista ihmisen tekemää katselmointia; se siirtää sen kokonaan loppuun. Siksi lopuksi saapuvan työn täytyy olla tarkistamisen arvoista. Tästä syystä AX on tärkein juuri AFK-ajoissa — ilman valvojaa ympäristö on agentin ainoa tuki.

Vältä: ”tausta-agentti” — se korostaa konetta (”toimii taustalla”) ihmisen toimintamallin (”käyttäjä on lähtenyt”) sijaan. AFK nimeää olennaisen: käyttäjä ei valvo.

Käyttö:

”Ajan tämän yön yli AFK-tilassa — kolme hiekkalaatikkoon rajattua agenttia refaktoroi, ja tarkistan PR:t aamulla.”

”Ohitetaanko käyttöoikeudet?”

”Kyllä, tiedostojärjestelmä vain luku -tilassa, ei verkkoyhteyttä.”

Määrämuotoinen varmennus, joka suoritetaan ympäristössä — testit, tyyppitarkistukset, linttaus, koonti ja pre-commit-koukut. Hyväksytty/hylätty, ei harkintaa. Signaali, josta agentti voi korjata itse itsensä ilman, että ketään muuta tarvitaan. Hajanainen testi on rikkoutunut tarkistus, ei tarkistuksen puuttuminen; automaattiset tarkistukset ovat suunnittelultaan määrämuotoisia.

Itsenäinen korjaus toimii silmukkana. Agentti tekee muutoksen, suorittaa tarkistuksen työkalukutsuna, ja virhetuloste päätyy sen konteksti-ikkunaan — tyyppivirhe tiedostoineen ja riveineen, epäonnistunut väite odotettuine ja toteutuneine arvoineen. Näin agentti voi korjata ongelman ja suorittaa tarkistuksen uudelleen yhä uudelleen, kunnes se menee läpi, ilman ihmistä välissä. Määrämuotoisuus tekee silmukasta luotettavan: sama koodi tuottaa aina saman tuloksen, joten läpäisy merkitsee jotakin. Hajanaiset tarkistukset myrkyttävät tämän — agentti ”korjaa” koodia, joka oli kunnossa, tai yrittää uudelleen aidon virheen ohi.

Siksi hyvät tarkistukset ovat suuri osa koodikannan AX:ää. Tiukkojen tyyppien, nopean testisarjan ja lintterin sisältävässä repossa agentti havaitsee useimmat virheensä ennen kuin näet niitä; repossa, jossa niitä ei ole, agentti toimittaa mitä sattuu syntymään. Ero on tärkein AFK-ajoissa, jolloin tarkistukset ovat ainoa ajon aikana tapahtuva varmennus. Tarkistus havaitsee kuitenkin vain sen, mitä se väittää tarkistavansa — vihreät tarkistukset merkitsevät väitettyjen ominaisuuksien toteutumista, eivät sitä, että koodi on oikein. Harkintaa vaativat aukot ovat automaattisen katselmoinnin ja ihmisen tekemän katselmoinnin tehtävä.

Vältä: ”palautesilmukka” / ”takapaine” — molemmat niputtavat tarkistukset ja katselmoinnin yhteen. Vältä: ”testi” — testit ovat automaattisia tarkistuksia, mutta kaikki automaattiset tarkistukset eivät ole testejä.

Käyttö:

”Agentti toimittaa jatkuvasti rikkinäistä koodia AFK-ajoissa.”

”Mitä automaattisia tarkistuksia hiekkalaatikossa on kytketty käyttöön?”

”Vain yksikkötestit.”

”Lisää tyyppitarkistus ja linttaus — agentti korjaa virheet niiden avulla itse ennen PR:n valmistumista.”

Agentti, joka tarkistaa toisen agentin työn, usein eri mallilla tai järjestelmäkehotteella. Ei-määrämuotoinen: se muodostaa arvion. Voi toimia missä tahansa — PR:n yhdistämistä ennen, jälkikäteen commit-historiasta tai kesken istunnon aliagenttina. CI:ssä toimiva LLM-arvioija tekee automaattista katselmointia, ei automaattista tarkistusta; luokan ratkaisee väitteen sisältö, ei suorituspaikka.

Toimivan agentin erottaminen tarkastavasta saa tämän toimimaan. Koodin kirjoittaneen agentin pyytäminen tarkastamaan oma työnsä ei anna paljonkaan — virheen tuottanut istunto sisältää myös sen synnyttäneen päättelyn, ja agentti lukee omat johtopäätöksensä vahvistuksena. Uuden konteksti-ikkunan saanut tarkastaja ei ole yhtä kiintynyt työhön: se näkee diffin ulkopuolisen tavoin, kuten katselmointi edellyttää. Eri malli tai katselmointiin suunnattu järjestelmäkehote terävöittää tätä entisestään — sillä on eri sokeat pisteet, ja kehote rajataan siihen, mikä todella kiinnostaa (tietoturvaan, API-sopimuksiin tai suorituskykyyn) epämääräisen ”etsi ongelmia” -pyynnön sijaan.

Automaattinen katselmointi asettuu muiden tarkastuskerrosten väliin. Automaattiset tarkistukset ovat määrämuotoisia ja havaitsevat mekaanisesti väitettävät asiat; ihmisen tekemä katselmointi on kallista eikä skaalaudu hyvin. Automaattinen katselmointi sijoittuu keskelle: se havaitsee harkintaa vaativia ongelmia — harhaanjohtavan funktionimen tai huomaamatta jääneen reunatapauksen — konekustannuksella. Koska toiminta ei ole määrämuotoista, katselmointi voi ohittaa asioita ja liputtaa ongelmattomia kohtia; käsittele sitä suodattimena, joka nostaa vähimmäistasoa ennen ihmisen tarkastusta, ei sen korvaavana porttina.

Vältä: ”tekoälykatselmointi” / ”agenttikatselmointi” — liian epämääräisiä erottamaan sitä itse työskentelevästä agentista.

Käyttö:

”AFK-ajoista tulee liikaa huonoja PR:iä.”

”Lisää ennen yhdistämistä automaattinen katselmointivaihe — eri malli, erillinen järjestelmäkehote, rajaus tietoturvaan ja sopimusmuutoksiin.”

Käyttäjä lukee agentin tuottaman koodin ja muodostaa siitä arvion. Diffin tai muutettujen tiedostojen lukeminen lasketaan; agentin tekemän työn kuvauksen lukeminen ei — selostus ei ole artefakti. Kuvaus on toissijainen lähde, jonka tarkastelun kohde kirjoitti; diffi on ensisijainen lähde, ja katselmointi tarkoittaa sen lukemista.

Agentit kasvattavat tuotetun koodin määrää, joten katselmoinnista tulee pullonkaula. Yksi hyödyllinen ajatus on kerrostaa erilaisia katselmointitapoja. Automaattiset tarkistukset havaitsevat mekaaniset virheet, automaattinen katselmointi havaittavat, kuvattavissa olevat ongelmat, ja ihmisen tekemä katselmointi varataan asioille, joita vain sinä voit arvioida — onko muutos oikea, sopiiko toteutustapa koodikantaan ja pitäisikö ominaisuutta olla olemassa lainkaan.

Katselmointi on sitä halvempaa, mitä aikaisemmin se tehdään. Suunnitelman lukeminen ennen työn alkua tai pienen diffin tarkistus työn aikana vie minuutteja; valmiin haaran perkaaminen AFK-ajon jälkeen vie kauemmin. Katselmointitarkistuspisteen paikka on human-in-the-loop-päätös, ei jälkikäteen mietitty asia.

Vältä: pelkkää termiä ”koodikatselmointi” — se on epäselvä ihmisen ja automaattisen katselmoinnin välillä.

Käyttö:

”Tarkastin AFK-tulosteen ihmisenä.”

”Luitko diffin vai vain yhteenvedon?”

”Diffin. Yhteenvedossa sanottiin, että kuollut koodi poistettiin — funktiota kutsuttiinkin generoitu tiedostosta.”

Työskentelymalli, jossa käyttäjä hyväksyy agentin koodin ilman ihmisen tekemää katselmointia. Diffiä käsitellään läpinäkymättömänä — tärkeää on ohjelman käyttäytyminen, ei sen sisältö. Automaattinen katselmointi ja automaattiset tarkistukset voivat silti toimia; vibekoodaus ei ota kantaa kumpaankaan.

Termin keksi Andrej Karpathy, joka otti sen käyttöön vuoden 2025 alussa: ”antautuu täysin fiilikselle” ja ”unohtaa, että koodia on olemassakaan” — kuvaat, mitä haluat, hyväksyt tuloksen ja arvioit sitä ajamalla.

Vibekoodaus vaihtaa tarkastelun nopeuteen. Diffien lukeminen on yleensä agenttivetoisen työn hitain vaihe, joten sen pois jättäminen poistaa tärkeimmän pullonkaulan. Koodissa, jonka virheet ovat halpoja — prototyypit, kertakäyttöskriptit ja sisäiset työkalut — tämä on järkevä kompromissi. Riski kasvaa koodin käyttöiän ja panosten mukaan.

Kustannus tulee myöhemmin. Vibekoodatut muutokset kasaantuvat koodikannaksi, jota kukaan ei ole lukenut, ja vain käyttäytyminen tarkistettiin — joten kaikki, mikä ei näy käyttäytymisessä, jää huomaamatta: lokeihin kirjoitettu salaisuus, puuttuva reunatapaus tai huomaamatta väärin käsitelty data. Ensimmäinen järjestelmän virheenjäljittäjä on ensimmäinen, joka lukee koodin. Kun ihmisen tekemää katselmointia ei ole, jäljelle jäävä automaattinen varmennus — testit, tyypit ja automaattinen katselmointi — on ainoa portti, jonka kautta koodi kulkee. Sama asenne koko koodikantaan tai sen osaan, jonka muutokset tulevat ohjelmistotehtaalta, on pimeä tehdas.

Vältä: ”vibekoodausta” ilmauksen ”heikkolaatuinen tekoälykoodaus” synonyymina — termi nimeää katselmointitavan, ei syntyvän koodin laatua.

Käyttö:

”Luitko, mitä se muutti kirjautumisen kulussa?”

”Vibekoodasin sen — kirjautuminen toimii yhä, se oli ainoa asia, jonka tarkistin.”

”Lue diffi ennen puskemista; kirjautumisen vibekoodaus vuotaa salaisuuksia lokeihin.”

Yhteinen käsitys rakennettavasta asiasta, joka käyttäjällä ja agentilla on mielessään mutta joka on erillään mistään artefaktista. Brooksin termi (The Design of Design): keskustelu, luovutusartefaktit ja koodi yrittävät kaikki tavoittaa tai kuvata suunnittelukonseptia, mutta mikään niistä ei ole se. Suunnittelukonseptin laadun tuntee sen muodostaneen keskustelun laadusta.

Termi nimeää tutun turhautumisen taustalla olevan aukon: agentti kirjoittaa täsmälleen pyytämäsi asian, ja se on silti väärin. Tavallinen syy on, ettet ollut itse täysin selvittänyt, mitä halusit. Suunnittelukonsepti ei ollut valmis omassa mielessäsi — kehotteeseen päätyivät selvittämäsi osat, mutta ne osat, joita et ollut selvittänyt, jäivät mainitsematta. Agentti täytti hiljaiset kohdat omilla oletuksillaan, koska sillä ei ollut yhteistä tavoitetta, jota vasten sovittaa niitä. Mikään ei mennyt rikki. Yhteistä suunnittelukonseptia ei ollut, koska jaettavaksi ei vielä ollut kokonaista konseptia.

Huomaat yhteisen suunnittelukonseptin samalla tavalla kuin kollegan kanssa: toinen alkaa vastata kysymyksiin, joita et ole vielä esittänyt, niin kuin itse vastaisit. Siihen asti työ on keskustelua — tenttaaminen on sen tarkoituksellinen muoto — ja määrittelyn kirjoittaminen liian aikaisin vain tallentaa epäsopivuuden pysyvämpään artefaktiin. Suunnittelukonsepti myös muuttuu oppimisen myötä; artefaktit laahaavat sen perässä. Siksi viime viikon ymmärrystä uskollisesti kuvaava määrittely voi johtaa tämän viikon istuntoa harhaan.

Käyttö:

”Se kirjoittaa täsmälleen mitä pyysin ja se on silti väärin.”

”Teillä ei ole vielä yhteistä suunnittelukonseptia — se täyttää aukot oletuksilla. Jatkakaa keskustelua, kunnes peruutus, hyvitykset ja osittainen toimitus ovat molemmille selviä, ennen kuin annat sen kirjoittaa määrittelyn.”

Tekniikka suunnittelukonseptin kehittämiseen agentin kanssa: agentti haastattelee käyttäjää sokraattisesti yksi päätös kerrallaan ja ehdottaa kuhunkin suositeltua vastausta. Se hidastaa kiirehtimistä valmiiseen suunnitelmaan — luovutusartefaktia ei kirjoiteta ennen kuin konsepti vakiintuu.

Tekniikkaa tarvitaan, koska agentit täyttävät aukot hiljaisesti. Kun agenttia pyydetään kirjoittamaan määrittely kahden rivin kehotteesta, se ei pysähdy odottamaan päätöksiä, joita et ole vielä tehnyt — se valitsee oletusarvot ja kirjoittaa ne mukaan. Tulos näyttää valmiilta, eivätkä arvaukset erotu valinnoista, joten huomaat ne myöhään: katselmoinnissa tai silloin, kun valmis ominaisuus käsittelee reunatapauksen tavalla, jota et koskaan valinnut. Tenttaaminen kääntää tämän toisinpäin — arvaamisen sijasta agentin täytyy kysyä.

Se on human-in-the-loop-tekniikka: vastauksesi ovat syöte. Kun kysymykseen ei voi vastata keskustelussa — asia täytyy nähdä — vaihda prototypointiin.

Käyttö:

”Se ryhtyi heti kirjoittamaan määrittelyä ja teki peruutuslogiikasta väärän.”

”Tenttaa sitä ensin — pyydä kysymään osittaisista peruutuksista, hyvityksistä ja ajoituksesta ennen kuin se sitoutuu kirjoittamaan mitään dokumenttiin. Keskustelussa asian ratkaiseminen on halvempaa kuin koodissa.”

Anna agentin rakentaa jostakin nopeasti karkea versio, kun keskustelu on liian vähätarkkuuksista ja tarvitset oikean artefaktin keskustelun pohjaksi.

Tenttaaminen ratkaisee suunnittelupäätöksiä keskustelussa. Keskustelu on edullista mutta vähätarkkuuksista: joihinkin kysymyksiin ei voi vastata sanoin — miltä vuorovaikutus tuntuu, onko API:n muoto luonteva todellisessa kutsukoodissa tai toimiiko asettelu todellisen kokoisella datalla. Haastattelu osuu kysymykseen, johon rehellinen vastauksesi on ”en tiedä, minun pitäisi nähdä se”. Sen jälkeen keskustelu kiertää kehää. Pyydä sen sijaan agenttia rakentamaan asia, katso sitä ja palaa keskusteluun vastauksen kanssa.

Agentit vähentävät rakentamisen kustannusta, mikä tekee tästä käytännöllistä. Karkea versio, jonka mallintaminen vei ennen päivän, valmistuu nyt minuuteissa, joten se kannattaa tehdä säännöllisesti. Tämä on human-in-the-loop-tekniikka: prototyyppi on olemassa, jotta voit reagoida siihen.

Tavallisesti et tyydy yhteen katselukertaan. Iteroi prototyypin kanssa — reagoi, pyydä muutos, reagoi uudelleen — niin jokainen kierros ratkaisee uuden päätöksen todellista artefaktia vasten tarkemmin kuin keskustelu mahdollistaa.

Prototyypin ei tarvitse olla kokonaan karkea. Voit rakentaa juuri arvioitavat osat tuotantolaatuisiksi, jolloin päätöksen synnyttyä komponentti tai API, johon reagoit, voidaan siirtää todelliseen koodikantaan. Siksi prototypointi on tärkeää aineistoa määrittelyyn.

Käyttö:

”Olemme väitelleet puoli tuntia siitä, pitäisikö ohjatun toiminnon olla yksi sivu vai kolme vaihetta.”

”Sanat eivät ratkaise sitä — pyydä agenttia prototypoimaan molemmat. Napsauttelemme niitä läpi ja tiedämme viidessä minuutissa.”

Kehittäjäkokemus — kuinka helposti koodikanta ja sen työkaluketju auttavat ihmisiä tekemään hyvää työtä. Hyvä DX tarkoittaa nopeaa palautetta, selkeitä virheilmoituksia, dokumentaatiota, joka vastaa juuri siihen kysymykseen, joka sinulla on, sekä asetuksia, jotka toimivat ensimmäisellä yrittämällä. Termi on paljon tekoälykoodausta vanhempi; se on mukana sanakirjassa lähinnä AX:n vastakohtana.

DX kuvaa ihmisen ja koodikannan vuorovaikutusta — ei muuta. Näiden kahden yleisön tärkein ero on, että ihmiset ovat tilallisia ja agentit tilattomia. Ihminen oppii koodikannan kerran ja kantaa tiedon mukanaan joka päivä sen jälkeen. Siksi huonon DX:n kanssa voi pärjätä: ihminen kiertää hitaan CI:n niputtamalla pushit, puuttuvan dokumentaation kysymällä kerran Slackissa ja sekavan rakenteen muistamalla, missä asiat sijaitsevat. Kiertotiet kasaantuvat, ja tiimi päätyy tuottavaksi koodikannassa, joka hankaloittaa sen työtä.

Agentit kohtaavat saman koodikannan ilman tällaista kertymää. Istuntojen välillä tilaton agentti opettelee koodikannan joka kerta alusta — se hyötyy nopeasta testisarjasta ja selkeistä virheilmoituksista, mutta kaikki eilen opittu katoaa, ellei sitä kirjoitettu ympäristöön, jonka agentti havaitsee vain työkalutulosten kautta. Tätä kuilua AX kuvaa: DX:n osat, jotka säilyvät kehittäjän ollessa agentti, sekä asiat, joita ihmisten ei tarvitse huomioida, kuten konteksti-ikkunan pitäminen vapaana.

Päällekkäisyys tarkoittaa, että DX:ään panostaminen parantaa usein AX:ää siinä sivussa — tiukat tyypit, nopeat testit ja ennakoitava rakenne auttavat molempia. Ero tarkoittaa, ettei näin aina käy: hieno perehdytysdokumentti auttaa ihmistä viikon ajan mutta agenttia ei lainkaan, ellei se löydy AGENTS.md-tiedostosta.

Käyttö:

”Meillä on hyvä DX — uudet työntekijät pääsevät tuottavaan työhön viikossa.”

”Tuottaviksi, koska joku työskentelee heidän kanssaan koko viikon. Agentti ei saa sitä viikkoa; arvioi AX erikseen.”

Agenttikokemus — kuinka hyvin ympäristö on valmisteltu agentin hyvää työskentelyä varten koodikannassa. Agenttien vastine DX:lle. Kun sama agentti suoriutuu hyvin yhdessä repossa ja huonosti toisessa — sama malli, sama agenttiympäristö — ero on tavallisesti AX:ssä. Vaisto käskee syyttää mallia tai kirjoittaa kehote uudelleen; ratkaisu löytyy useammin repossa.

Hyvässä AX:ssä on kolme pääulottuvuutta:

AX ja DX menevät päällekkäin — hyvät tarkistukset ja selkeä arkkitehtuuri auttavat molempia kohderyhmiä — mutta myös eroavat toisistaan. Ihmiset sietävät hiljaista tietoa, hidasta CI:tä ja ”kysy Saaralta laskutusmoduulista”; agentit eivät. IDE:n työkaluvihjeet tai kauniit hallintapaneelit eivät auta agentteja; ne tarvitsevat virheet tekstinä työkalutuloksessa. Koodikannassa voi olla hyvä DX mutta huono AX.

Vältä: AX:n käsittelemistä DX:n synonyymina — eri kohderyhmät tarvitsevat erilaisia panostuksia.

Käyttö:

”Agentti kirjoittaa API-repossa hyvää koodia mutta käyttöliittymärepossa roskaa.”

”API-repossa on tiukat tyypit ja nopea testisarja; käyttöliittymärepossa ei kumpaakaan ja neljäkymmentä aina ladattavaa taitoa. Se on AX-kuilu, ei malliongelma.”

Työskentelyjärjestelmä, jossa agentin istunnot käynnistyvät laukaisimista — issuesta, aikataulusta, CI-virheestä tai toisen istunnon valmistumisesta — eivätkä ihmisen toimesta. Näin enemmän työtä tapahtuu AFK-tilassa ja ihmisen huomio kohdistuu jäljellä oleviin human-in-the-loop-päätöksiin.

Ilman tehdasta jokainen istunto alkaa siksi, että joku käynnistää sen. Täysin AFK-tilassa tehtykin työ odottaa ihmistä avaamaan istunnon, osoittamaan sille lipun ja käynnistämään sen. Tiimit haluavat toimittaa enemmän kuin tämä sallii. Tehdas poistaa ihmisen istuntojen käynnistämisestä, ei välttämättä mistään muusta.

Yleisiä käynnistimiä ja niiden aloittamia istuntoja:

Tehtaan ei tarvitse kattaa koko ohjelmistoprosessia. Yksi cron-tehtävä, joka suorittaa yhdenlaisen istunnon ja avaa yhden tarkistettavan PR:n, on tehdas. Pienestä aloittaminen on hyödyllistä: kapea silmukka tuottaa pieniä, samankaltaisia PR:iä, ja niiden tarkastelu osoittaa, kuinka paljon silmukkaan voi luottaa ennen sen laajentamista.

Ihmiset voivat osallistua tehtaan mihin tahansa kohtaan — kirjoittaa ja merkitä istuntoja käynnistävät issuet, hyväksyä suunnitelman ennen toteutuksen alkua tai tehdä ihmisen suorittaman katselmoinnin ennen yhdistämistä. Tärkein suunnittelukysymys on päättää, mitkä näistä päätöksistä jäävät ihmisille. Koodikanta tai sen osa, jonka tuotosta kukaan ei tarkista, on pimeä tehdas.

Käyttö:

”Kuka korjasi kaikki `no-floating-promises`-rikkomukset?”

”Tehdas. Cron-tehtävä valitsee joka yö yhden linttaussäännön ja avaa PR:n. Minä vain tarkistan sen aamulla.”

Koodikanta tai sen osa, jossa ohjelmistotehdas kirjoittaa koodin eikä kukaan ihminen lue sitä. Ihmisen tekemää koodikatsausta ei ole. Ihmiset voivat edelleen kirjoittaa työn käynnistävät tiketit, mutta kukaan ei lue tuloksena syntyvää koodia. Nimi tulee ”valot sammuksissa” toimivista tehtaista, joissa tuotanto tapahtuu ilman henkilöstöä.

Pimeä tehdas on vibekoodausta koodialueelle eikä yksittäiseen muutokseen. Vibekoodatessa päätät olla lukematta pyytämääsi muutosta, mutta tiedät muutoksen olevan olemassa. Pimeässä tehtaassa tiimi tekee saman päätöksen kerran koko alueesta. Sen jälkeen kukaan ei pyydä eikä näe yksittäisiä muutoksia. Muutoksia syntyy niin nopeasti kuin käynnistimet aloittavat uutta työtä.

Ongelma paljastuu, kun jokin rikkoutuu. Et tiedä, mikä muuttui, koska kukaan ei lukenut muutoksia. Sinun on selvitettävä koodi, jota kukaan tiimissä ei ole lukenut. Syy voi olla missä tahansa monista muutoksista, ja jokainen niistä läpäisi tarkistukset.

Vain automaattiset tarkistukset ja automaattinen katselmointi toimivat portinvartijoina. Jos ne eivät löydä ongelmaa, ongelma päätyy koodiin.

Vältä: koodikannan kutsumista ”pimeäksi” vain siksi, että tehdas toimii ilman valvontaa. Jos agentin istunnot toimivat AFK-tilassa ja ihminen katsoo niiden PR:t, kyseessä on ohjelmistotehdas. Se ei ole pimeä tehdas.

Käyttö:

”Kuka muutti laskutuspalvelun uudelleenyrityslogiikkaa? Kukaan tiimistä ei muista tehneensä sitä.”

”Laskutuspalvelu on pimeä tehdas. Agentit yhdistävät kaikki CI:n läpäisevät muutokset. Kukaan ei lukenut tuota muutosta.”