Harness Engineering: Kattava opas AI-agentteja todella hyödyntävien järjestelmien rakentamiseen

Maaliskuu 2026 — Jos vuosi 2025 oli vuosi, jolloin AI-agentit osoittivat pystyvänsä kirjoittamaan koodia, vuosi 2026 on vuosi, jolloin opimme, että agentti ei ole se vaikea osuus — vaan valjaat (harness).

OpenAI:n Codex-tiimi on juuri rakentanut tuotantosovelluksen, jossa on yli miljoona riviä koodia, mutta josta ihmiset eivät ole kirjoittaneet riviäkään. Insinöörit eivät kirjoittaneet koodia. He suunnittelivat järjestelmän, joka antoi tekoälyn kirjoittaa koodia luotettavasti. Tätä järjestelmää — rajoitteita, palautesilmukoita, dokumentaatiota, lintereitä ja elinkaaren hallintaa — ala kutsuu nyt nimellä harness.

Harness engineering on uusi tieteenala näiden järjestelmien suunnittelussa. Ja se muuttaa sitä, mitä ohjelmistoinsinöörinä olo tarkoittaa.

---

Mitä on Harness Engineering?

Hevosmetafora

Termi "harness" tulee hevosen valjaista — ohjaksista, satulasta ja kuolaimista — eli varusteista, joilla ohjataan voimakasta mutta ennalta-arvaamatonta eläintä oikeaan suuntaan. Metafora on harkittu:

• Hevonen on AI-malli — voimakas ja nopea, mutta se ei tiedä itse, mihin mennä.
• Valjaat (harness) ovat infrastruktuuri — rajoitteet, suojakaiteet ja palautesilmukat, jotka kanavoivat mallin voiman tuottavasti.
• Ratsastaja on ihminen (insinööri) — joka antaa suunnan, mutta ei tee itse juoksemista.

Ilman valjaita AI-agentti on kuin täysiverinen hevonen avoimella pellolla. Nopea, vaikuttava ja täysin hyödytön minkään työn suorittamiseen.

Muodollinen määritelmä

Harness engineering on sellaisten järjestelmien suunnittelua ja toteutusta, jotka:

1. Rajoittavat (Constrain) sitä, mitä AI-agentti voi tehdä (arkkitehtuuriset rajat, riippuvuussäännöt).
2. Informoivat (Inform) agenttia siitä, mitä sen tulisi tehdä (kontekstisuunnittelu, dokumentaatio).
3. Varmistavat (Verify), että agentti teki sen oikein (testaus, lintaus, CI-validointi).
4. Korjaavat (Correct) agenttia, kun se tekee virheen (palautesilmukat, itsepuhdistusmekanismit).

Martin Fowler kuvailee sitä "työkaluiksi ja käytännöiksi, joita voimme käyttää pitääksemme AI-agentit kurissa" — mutta se on enemmän kuin vain turvallisuutta. Hyvät valjaat tekevät agenteista kyvykkäämpiä, eivät vain hallitumpia.

---

Miksi Harness Engineering on tärkeää juuri nyt

Malli on hyödyke. Valjaat ovat kilpailuetu.

Tässä on epämiellyttävä totuus, jota tekoälyala kohtaa: itse mallilla on vähemmän merkitystä kuin sen ympärillä olevalla järjestelmällä.

LangChain todisti tämän lopullisesti. Heidän koodausagenttinsa tulos parani 52,8 %:sta 66,5 %:iin Terminal Bench 2.0 -testissä — hypäten Top 30:stä Top 5:een — muuttamatta mallia lainkaan. He muuttivat vain valjaita:

Muutos	Mitä he tekivät	Vaikutus
Itsevarmistussilmukka	Lisättiin väliohjelmisto tarkistuslistalle ennen valmistumista	Virheet saatiin kiinni ennen lähetystä
Kontekstisuunnittelu	Hakemistorakenteiden kartoitus käynnistyksessä	Agentti ymmärsi koodikannan alusta alkaen
Silmukan havaitseminen	Toistuvien tiedostomuokkausten seuranta	Estettiin "doom loops" (ikuiset silmukat)
Päättelyvoileipä (Reasoning sandwich)	Korkea päättelykyky suunnitteluun, keskitaso toteutukseen	Parempi laatu aikarajojen puitteissa

Sama malli. Eri valjaat. Huomattavasti paremmat tulokset.

OpenAI:n miljoonan rivin todiste

OpenAI:n kokeilu on tähän asti vakuuttavin näyttö:

• 5 kuukautta kehitystä.
• Yli miljoona riviä koodia lopullisessa tuotteessa.
• Nolla manuaalisesti kirjoitettua riviä — jokainen rivi oli Codex-agenttien tuottama.
• Rakennettu noin 1/10 ajassa siitä, mitä ihmisiltä olisi mennyt.
• Tuotteella on sisäisiä päivittäisiä käyttäjiä ja ulkoisia alfa-testaajia.
• Se julkaissee, integroituu, hajoaa ja tulee korjatuksi — kaikki agenttien toimesta valjaiden sisällä.

Insinöörien tehtävä? Valjaiden suunnittelu. Tarkoituksen määrittely. Palautteen antaminen. Ei koodin kirjoittaminen.

---

Harness Engineeringin kolme pilaria

OpenAI:n viitekehys jakaa harness engineeringin kolmeen ydinkategoriaan:

1. Kontekstisuunnittelu (Context Engineering)

Kontekstisuunnittelussa varmistetaan, että agentilla on oikea tieto oikeaan aikaan.

Staattinen konteksti:

• Repositorion paikallinen dokumentaatio (arkkitehtuurispesifikaatiot, API-sopimukset, tyylioppaat).
• AGENTS.md- tai CLAUDE.md-tiedostot, joihin on koodattu projektikohtaiset säännöt.
• Ristiinlinkitetyt suunnitteludokumentit, jotka linterit validoivat.

Dynaaminen konteksti:

• Observabiliteettidata (logit, metriikat, jäljitykset), johon agenteilla on pääsy.
• Hakemistorakenteen kartoitus agentin käynnistyessä.
• CI/CD-putken tila ja testitulokset.

Kriittinen sääntö: Agentin näkökulmasta mitään, mihin se ei pääse käsiksi kontekstissa, ei ole olemassa. Tieto Google Docsissa, Slack-ketjuissa tai ihmisten päissä on järjestelmälle näkymätöntä. Repositorion on oltava ainoa totuuden lähde.

2. Arkkitehtuuriset rajoitteet

Tässä harness engineering eroaa jyrkimmin perinteisestä AI-promptauksesta. Sen sijaan, että sanoisit agentille "kirjoita hyvää koodia", pakotat mekaanisesti sen, miltä hyvä koodi näyttää.

Riippuvuuskerrostus:

Tyypit → Konfiguraatio → Repo → Palvelu → Ajoaika → UI

Kukin kerros voi tuoda asioita vain vasemmalla puolellaan olevista kerroksista. Tämä ei ole ehdotus — se pakotetaan rakenteellisilla testeillä ja CI-validoinnilla.

Rajoitteiden valvontatyökalut:

• Deterministiset linterit — Mukautetut säännöt, jotka liputtavat rikkomukset automaattisesti.
• LLM-pohjaiset tarkastajat — Agentit, jotka tarkistavat muiden agenttien koodia arkkitehtuurin noudattamisen osalta.
• Rakenteelliset testit — Kuten ArchUnit, mutta AI-generoidulle koodille.
• Pre-commit hookit — Automaattiset tarkistukset ennen koodin tallentamista.

Miksi rajoitteet parantavat tulosta: Paradoksaalisesti ratkaisuvaihtoehtojen rajoittaminen tekee agenteista tuottavampia, ei vähemmän. Kun agentti voi generoida mitä tahansa, se tuhlaa tokeneita kokeilemalla umpikujia. Kun valjaat määrittelevät selkeät rajat, agentti konvergoituu nopeammin oikeisiin ratkaisuihin.

3. Entropian hallinta ("Roskienkeruu")

Tämä on usein vähiten arvostettu osa-alue. Ajan myötä AI-generoidut koodikannat keräävät entropiaa — dokumentaatio erkanee todellisuudesta, nimeämiskäytännöt alkavat hajota, turhaa koodia kertyy.

Harness engineering puuttuu tähän säännöllisillä siivousagenteilla:

• Dokumentaation johdonmukaisuusagentit — Varmistavat, että dokumentit vastaavat nykyistä koodia.
• Rajoiterikkomusten skannerit — Löytävät koodin, joka pääsi aiemmista tarkistuksista läpi.
• Käytäntöjen valvontagentit — Tunnistavat ja korjaavat poikkeamat vakiintuneista malleista.
• Riippuvuustarkastajat — Seuraavat ja selvittävät kehäriippuvuuksia tai tarpeettomia riippuvuuksia.

Nämä agentit ajetaan aikataulun mukaan — päivittäin, viikoittain tai tiettyjen tapahtumien laukaisemana — pitäen koodikannan terveenä sekä ihmisille että tuleville AI-agenteille.

---

Harness Engineering käytännössä: Miten tiimit todella toimivat

OpenAI:n lähestymistapa: Nolla ihmiskoodia

OpenAI:n tiimirakenne harness engineeringissä:

Rooli	Perinteinen	Harness Engineering
Koodin kirjoittaminen	Pääasiallinen työ	Ei koskaan
Arkkitehtuurin suunnittelu	Osa työtä	Pääasiallinen työ
Dokumentaation kirjoittaminen	Jälkiajatus	Kriittinen infrastruktuuri
PR-tarkistukset	Koodin katselmointi	Agentin tuloksen ja valjaiden tehokkuuden arviointi
Virheenkorjaus	Koodin lukeminen	Agentin käyttäytymismallien analysointi
Testaus	Testien kirjoittaminen	Agenttien suorittamien testistrategioiden suunnittelu

Stripen lähestymistapa: Minionit suuressa mittakaavassa

Stripen sisäiset koodausagentit, nimeltään Minionit, tuottavat nykyään yli 1 000 hyväksyttyä pull requestia viikossa:

1. Kehittäjä antaa tehtävän Slackissa.
2. Minion kirjoittaa koodin.
3. Minion läpäisee CI-testit.
4. Minion avaa PR:n.
5. Ihminen tarkistaa ja yhdistää koodin.

Kehittäjän ja agentin välillä ei ole vuorovaikutusta vaiheiden 1 ja 5 välillä. Valjaat hoitavat kaiken — testien suorituksen, CI-validoinnin, tyylin noudattamisen ja dokumentaation päivitykset.

LangChainin lähestymistapa: Middleware-painotteinen

LangChain rakentaa valjaansa koostettavina väliohjelmistokerroksina (middleware):

Agenttipyyntö
  → LocalContextMiddleware (kartoittaa koodikannan)
  → LoopDetectionMiddleware (estää toiston)
  → ReasoningSandwichMiddleware (optimoi laskennan)
  → PreCompletionChecklistMiddleware (pakottaa varmistuksen)
  → Agentin vastaus

Jokainen väliohjelmistokerros lisää tietyn kyvykkyyden muuttamatta agentin ydinlogiikkaa. Tämä modulaarinen lähestymistapa tekee valjaista testattavia ja kehitettäviä.

---

Ensimmäisten valjaiden rakentaminen: Käytännön viitekehys

Taso 1: Perusvaljaat (Yksittäinen kehittäjä)

Jos käytät Claude Codea, Cursoria tai Codexia yksittäisissä projekteissa:

Mitä asentaa:

• CLAUDE.md- tai .cursorrules-tiedosto projektin käytännöillä.
• Pre-commit hookit lintausta ja muotoilua varten.
• Testipatteristo, jonka agentti voi ajaa itsenäisesti.
• Selkeä hakemistorakenne johdonmukaisella nimeämisellä.

Käyttöönottoaika: 1–2 tuntia Vaikutus: Estää yleisimmät agenttien tekemät virheet.

Taso 2: Tiimivaljaat (Pieni tiimi)

3–10 kehittäjän tiimeille, jotka jakavat koodikannan:

Lisää Tasoon 1:

• AGENTS.md tiimin laajuisilla käytännöillä.
• CI:n valvomat arkkitehtuuriset rajoitteet.
• Jaetut prompt-mallit yleisiin tehtäviin.
• Linterien validoima dokumentaatio-koodina (documentation-as-code).
• Erityisesti agenttien luomille PR:ille suunnatut tarkistuslistat.

Käyttöönottoaika: 1–2 päivää Vaikutus: Agenttien yhtenäinen käyttäytyminen koko tiimissä.

Taso 3: Tuotantovaljaat (Insinööriorganisaatio)

Organisaatioille, joilla on kymmeniä samanaikaisia agentteja:

Lisää Tasoon 2:

• Kustomoidut väliohjelmistokerrokset (silmukan havaitseminen, päättelyn optimointi).
• Observabiliteetti-integraatio (agentit lukevat lokeja ja metriikkaa).
• Aikataulutetut entropian hallinta -agentit.
• Valjaiden versiointi ja A/B-testaus.
• Agenttien suorituskyvyn seurantapaneelit.
• Eskalointikäytännöt tilanteisiin, joissa agentit juuttuvat.

Käyttöönottoaika: 1–2 viikkoa Vaikutus: Agentit toimivat autonomisina tekijöinä.

---

Yleisimmät virheet harness engineeringissä

1. Ohjausvirran ylisuunnittelu

"Jos ylisuunnittelet ohjausvirran (control flow), seuraava mallipäivitys rikkoo järjestelmäsi."

Mallit kehittyvät nopeasti. Kyvykkyydet, jotka vaativat monimutkaisia putkia vuonna 2024, hoituvat nyt yhdellä kehotteella. Rakenna valjaasi irrotettaviksi — sinun pitäisi voida poistaa "älykäs" logiikka, kun malli tulee riittävän viisaaksi pärjätäkseen ilman sitä.

2. Valjaiden kohtelu staattisina

Valjaiden on kehityttävä mallin mukana. Kun uusi mallijulkaisu parantaa päättelykykyä, päättelyn optimointiin tarkoitettu väliohjelmistosi saattaa muuttua haitalliseksi. Tarkista ja päivitä valjaiden komponentit jokaisen suuren mallipäivityksen yhteydessä.

3. Dokumentaatiokerroksen laiminlyönti

Vaikuttavin parannus valjaisiin on usein yksinkertaisin: parempi dokumentaatio. Jos AGENTS.md-tiedostosi on epämääräinen, agentin tuotos on epämääräinen. Panosta tarkkaan, koneellisesti luettavaan dokumentaatioon, joka toimii agentin totuuden lähteenä.

4. Palautesilmukan puute

Valjaat ilman palautetta ovat häkki, eivät opas. Agentin on tiedettävä, milloin se onnistuu ja milloin epäonnistuu. Rakenna sisään:

• Itsevarmistusvaiheet ennen tehtävän valmistumista.
• Testien suoritus osana agentin työnkulkua.
• Metriikkaa agenttien onnistumisprosenteista tehtävätyypeittäin.

5. Vain ihmisille tarkoitettu dokumentaatio

Jos arkkitehtuuriset päätökset elävät vain ihmisten päissä tai Confluence-sivuilla, joihin agentti ei pääse käsiksi, valjaissa on aukko. Kaiken, mitä agentti tarvitsee, on oltava repositoriossa.

---

Harness Engineering vs. liittyvät käsitteet

Käsite	Laajuus	Fokus
Prompt Engineering	Yksittäinen vuorovaikutus	Tehokkaiden kehotteiden laatiminen
Context Engineering	Mallin konteksti-ikkuna	Mitä tietoa malli näkee
Harness Engineering	Koko agenttijärjestelmä	Ympäristö, rajoitteet, palaute, elinkaari
Agent Engineering	Agentin arkkitehtuuri	Agentin sisäinen suunnittelu ja reititys
Platform Engineering	Infrastruktuuri	Julkaisu, skaalaus, operointi

Harness engineering sisältää kontekstisuunnittelun ja hyödyntää prompt engineeringiä, mutta se toimii korkeammalla tasolla — kyse on kokonaisvaltaisesta järjestelmästä, joka tekee agenteista luotettavia, ei vain yksittäisen vuorovaikutuksen syötteistä.

---

Mitä tämä tarkoittaa ohjelmistoinsinööreille

Työ muuttuu

Harness engineering edustaa todellista evoluutiota siinä, mitä ohjelmistoinsinöörit tekevät:

Ennen	Jälkeen
Koodin kirjoittaminen	Ympäristöjen suunnittelu, joissa AI kirjoittaa koodia
Koodin debuggaus	Agentin käyttäytymisen debuggaus
Koodin katselmointi	Agentin tuloksen + valjaiden tehokkuuden katselmointi
Testien kirjoittaminen	Testistrategioiden suunnittelu
Dokumentaation ylläpito	Dokumentaation rakentaminen koneellisesti luettavaksi

Tämä ei tarkoita, että insinööreistä tulisi vähemmän teknisiä. Päinvastoin, harness engineering vaatii syvempää arkkitehtuurista ajattelua — suunnittelet järjestelmiä, joiden on toimittava ilman jatkuvaa väliintuloasi.

Taidot, joilla on merkitystä

Perustuen kokemuksiimme AI-pohjaisten tuotteiden rakentamisesta NxCodella:

1. Systeeminen ajattelu — Ymmärrys siitä, miten rajoitteet, palautesilmukat ja dokumentaatio vaikuttavat toisiinsa.
2. Arkkitehtuurisuunnittelu — Sellaisten rajojen määrittely, jotka ovat valvottavissa ja tuottavia.
3. Spesifikaatioiden kirjoittaminen — Tarkoituksen ilmaiseminen niin tarkasti, että agentit voivat toteuttaa sen.
4. Observabiliteetti — Seurannan rakentaminen, joka paljastaa agenttien käyttäytymismallit.
5. Iteraationopeus — Valjaiden kokoonpanojen nopea testaaminen ja hienosäätö.

Kokemuksemme: Mikä toimii käytännössä

Olemme rakentaneet AI-pohjaisia verkkosovelluksia käyttäen useita agenttijärjestelmiä (Claude Code, Codex, Cursor). Mallit, jotka ovat tehneet suurimman eron meille:

• Repositorio-lähtöinen dokumentaatio: Jokainen arkkitehtuurinen päätös, nimeämiskäytäntö ja julkaisuprosessi on repositoriossa. Mikään ei elä Slackissa tai Google Docsissa.
• Inkrementaalinen rajoitteiden rakentaminen: Aloita peruslintauksesta, lisää arkkitehtuurisia rajoitteita mallien vakiintuessa; älä yritä suunnitella täydellisiä valjaita heti kättelyssä.
• Agenttikohtaiset tarkistuslistat: AI-generoidulla koodilla on erilaisia vikatiloja kuin ihmisen koodilla. Katselmusprosessimme huomioi yleiset agenttien tavat (ylianalysointi, tarpeeton virheen käsittely, dokumentaation vanhentuminen).
• Monen tarjoajan valjasarkkitehtuuri: Valjaamme toimivat Claude-, GPT- ja Gemini-mallien kanssa. Malliriippumaton suunnittelu tarkoittaa, että voimme vaihtaa malleja rakentamatta koko järjestelmää uudelleen.

---

Keskeiset opit

1. Harness engineering on uusi tieteenala, jossa suunnitellaan järjestelmiä, jotka tekevät AI-agenteista luotettavia — sisältäen rajoitteet, palautesilmukat, dokumentaation ja elinkaaren hallinnan.
2. Malli on hyödyke; valjaat ovat kilpailuetu — LangChain nousi Top 30:stä Top 5:een suorituskykytesteissä muuttamalla vain valjaita.
3. OpenAI rakensi yli miljoona riviä nollalla ihmiskoodilla — osoittaen, että harness engineering toimii tuotantomittakaavassa.
4. Kolme pilaria: Kontekstisuunnittelu, arkkitehtuuriset rajoitteet ja entropian hallinta.
5. Aloita yksinkertaisesti: Hyvä AGENTS.md ja pre-commit hookit ovat vaikuttavampia kuin monimutkainen väliohjelmisto.
6. Insinöörin rooli kehittyy — koodin kirjoittajasta ympäristöjen suunnittelijaksi, joissa AI kirjoittaa koodia.
7. Rakenna joustavia valjaita — ylisuunnittelu hajoaa, kun mallit paranevat; pidä järjestelmä muokattavana.

---

Liittyvät resurssit

• Agenttinen verkko selitettynä: AGENTS.md, MCP vs A2A — Protokollakerros, jonka päälle harness engineering rakentuu.
• Cursor Cloud Agents: Autonominen koodaus virtuaalikoneilla — Pilvipohjaiset agenttivaljaat käytännössä.
• Claude Code Remote Control: Terminal Handoff -opas — Agenttisessioiden hallinta etänä.
• Rakenna verkkosivusi NxCodella — AI-pohjaista verkkokehitystä monen tarjoajan valjasarkkitehtuurilla.