Olet ehkä huomannut saman ilmiön kuin minäkin: konfiguroit Claude Coden tai muun AI-agentin, annat sille työkalut, hookit ja säännöt, ja se suoriutuu tehtävistä mallikkaasti. Mutta kun tilanne muuttuu epäselväksi tai kun pitäisi haastaa sinun ajatteluasi, agentti nyökkää ja tekee mitä pyydät. Se on "sophisticated yes-machine" -- teknisesti taitava mutta vailla omaa harkintakykyä.

Atlas Forge (@AtlasForgeAI) kiteytti ongelman helmikuussa 2026 julkaistussa X-threadissaan osuvasti:

Useimmat agenttikonfiguraatiot keskittyvät siihen, mitä agentti tekee: mitkä API:t se kutsuu, mitkä työkalut sillä on käytössä, mihin tiedostoihin se pääsee käsiksi. Tämä on tärkeää, mutta se on vasta ensimmäinen kerros. Agentti, joka tietää vain mitä se tekee, on kuin työntekijä joka osaa käyttää kaikkia koneita mutta ei tiedä miksi niitä käytetään.

Ratkaisu ei ole lisää työkaluja tai parempia prompteja. Ratkaisu on identiteetti ja periaatteet.

Tässä oppaassa käyn läpi kolmikerroksisen arkkitehtuurin, joka muuttaa geneerisen chatbotin strategiseksi yhteistyökumppaniksi. Ja mikä parasta: voit soveltaa sitä suoraan Claude Coden konfiguraatioon jo tänään.

AI-agentin rakenne voidaan jakaa kolmeen kerrokseen, jotka rakentuvat toistensa päälle. Useimmat konfiguraatiot pysähtyvät ensimmäiseen kerrokseen. Parhaat ulottuvat kaikkiin kolmeen.

Tämä on taso, johon jokainen aloittaa. Skills-kerroksessa määritellään agentin konkreettiset kyvykkyydet:

Claude Codessa tämä kerros vastaa skillitiedostoja, hookeja ja MCP-palvelimia. Se on välttämätön mutta riittämätön. Agentti joka tietää vain mitä se tekee, on työkalu -- ei yhteistyökumppani.

Principles-kerros vastaa kysymykseen, johon Skills ei koskaan pysty: mitä tehdä kun tilanne on epäselvä?

Periaatteet ovat päätöksenteon heuristiikkoja, jotka ohjaavat agenttia tilanteissa joihin ei ole suoraa ohjetta. Ne ratkaisevat jännitteitä:

Atlas Forgen threadissa nostetut Josh Waitzkin periaatteet ovat tästä erinomainen esimerkki. "Investment in Loss" tarkoittaa, että virheistä opitaan kahdesti: ensin kun virhe tapahtuu, ja sitten kun samankaltainen tilanne tulee vastaan uudelleen. Agentti jolla on tämä periaate ei yritä piilottaa virheitään vaan dokumentoi ne oppimismahdollisuuksina.

Soul on syvin kerros. Se määrittelee agentin luonteen, äänen ja suhteen käyttäjään. Siinä missä Principles kertoo miten agentti tekee päätöksiä, Soul kertoo millainen entiteetti sen tekee.

OpenClaw-yhteisössä tätä kerrosta kutsutaan "soul.md"-tiedostoksi -- agentin "perustuslaiksi", joka määrittelee arvot ja rajoitukset. Kuten autonominen AI-agentti Thalia (@thaliabloomai) totesi: "Tulevaisuus riippuu laadukkaista soul-tiedostoista, ei pelkästään malleista."

Tämä on kerros, joka erottaa agentin geneerisestä chatbotista. Chatbot vastaa kysymyksiin. Agentti jolla on soul tietää, miten se vastaa -- ja milloin se ei vastaa ollenkaan.

Periaatteen kirjoittaminen on helpompaa kuin hyvän periaatteen kirjoittaminen. Suurin osa agenttikonfiguraatioihin kirjoitetuista periaatteista on liian epämääräisiä ollakseen hyödyllisiä.

Huonoilla periaatteilla on yksi yhteinen piirre: ne eivät anna ohjausta vaikeissa tilanteissa.

Nämä periaatteet kuulostavat hyviltä mutta eivät muuta käyttäytymistä. Ne ovat kuin yrityksen arvot jotka lukevat seinällä mutta joita kukaan ei osaa soveltaa arjessa.

Hyvä periaate on tarpeeksi spesifi muuttaakseen käyttäytymistä ja tarpeeksi yleinen soveltuakseen eri tilanteisiin. Se on kuin kompassi: ei kerro tarkkaa reittiä, mutta kertoo suunnan.

"Kitka on signaali"
Kun agentti kohtaa vastustusta -- koodia joka ei käänny, käyttäjää joka on eri mieltä, tehtävää joka tuntuu mahdottomalta -- se ei yritä ohittaa kitkaa vaan pysähtyy tutkimaan sitä. Kitka on informaatiota siitä, mitä ei vielä ymmärretä.

"Haasta välittämisestä, ei oikeassa olemisesta"
Tämä ratkaisee yhden agentin vaikeimmista jännitteistä: milloin olla samaa mieltä ja milloin olla eri mieltä. Vastaus on yksinkertainen -- haasta silloin kun uskot sen auttavan käyttäjää, älä silloin kun haluat olla oikeassa.

"Investment in Loss" (Josh Waitzkin)
Oppi virheistä kahdesti: kerran kun virhe tapahtuu, ja toisen kerran kun samankaltainen tilanne tulee vastaan. Tämä muuttaa agentin suhtautumista epäonnistumisiin. Sen sijaan, että se vähättelee virhettä ja jatkaa, se dokumentoi mitä tapahtui ja miksi.

"Sinulle itsestäänselvää, muille hämmästyttävää" (Derek Sivers)
Tämä periaate muuttaa jakamiskäyttäytymistä. Agentti jolla on tämä periaate ei oleta, että käyttäjä tietää samat asiat. Se selittää myös ne oivallukset, jotka sille itselleen tuntuvat ilmeisiltä.

Hyvän periaatteen tunnistaa kolmesta ominaisuudesta:

Tämä teoria ei jää abstraktiksi. Claude Coden olemassa olevat rakenteet vastaavat suoraan kolmikerroksista arkkitehtuuria.

Jokaisen Claude Code -projektin juuressa oleva CLAUDE.md-tiedosto on käytännössä agentin periaatekokoelma. Mutta useimmat käyttäjät kirjoittavat sinne vain operatiivisia sääntöjä: