Harness-inseneeria: Täielik juhend süsteemide ehitamiseks, mis panevad tehisintellekti agendid päriselt tööle

Märts 2026 — Kui 2025 oli aasta, mil AI-agendid tõestasid, et suudavad koodi kirjutada, siis 2026 on aasta, mil õppisime, et agent ei ole keeruline osa — harness (rakmed) on.

OpenAI Codexi meeskond ehitas just tootmisrakenduse, millel on üle 1 miljoni koodirea, kusjuures inimese käsi ei kirjutanud ühtegi rida. Insenerid ei kirjutanud koodi. Nad disainisid süsteemi, mis võimaldas AI-l koodi usaldusväärselt kirjutada. Seda süsteemi — piiranguid, tagasisideahelaid, dokumentatsiooni, lintereid ja elutsükli haldust — nimetab tööstus nüüd harnessiks.

Harness-inseneeria on uus distsipliin nende süsteemide projekteerimiseks. Ja see muudab tarkvarainseneriks olemise tähendust.

---

Mis on harness-inseneeria?

Hobuse metafoor

Mõiste "harness" (rakmed) pärineb hobusevarustusest — ohjad, sadul, suulised — täielik varustus võimsa, kuid ettearvamatu looma õiges suunas suunamiseks. Metafoor on teadlik:

• Hobune on AI-mudel — võimas, kiire, kuid ta ei tea ise, kuhu minna.
• Harness (rakmed) on infrastruktuur — piirangud, piirded, tagasisideahelad, mis suunavad mudeli võimsust produktiivselt.
• Ratsanik on iniminsener — annab suuna, mitte ei jookse ise.

Ilma harnessita on AI-agent nagu täisvereline hobune lagedal väljal. Kiire, muljetavaldav ja täiesti kasutu millegi saavutamiseks.

Formaalne definitsioon

Harness-inseneeria on süsteemide projekteerimine ja rakendamine, mis:

1. Piiravad (Constrain), mida AI-agent saab teha (arhitektuurilised piirid, sõltuvusreeglid).
2. Informeerivad (Inform) agenti sellest, mida ta peaks tegema (konteksti-inseneeria, dokumentatsioon).
3. Verifitseerivad (Verify), et agent tegi seda õigesti (testimine, lintimine, CI valideerimine).
4. Parandavad (Correct) agenti, kui asjad lähevad valesti (tagasisideahelad, iseparandusmehhanismid).

Martin Fowler kirjeldab seda kui "tööriistu ja tavasid, mida saame kasutada AI-agentide vaos hoidmiseks" — kuid see on enamat kui lihtsalt ohutus. Hea harness muudab agendid võimekamaks, mitte ainult kontrollitumaks.

---

Miks on harness-inseneeria praegu oluline?

Mudel on kaup. Harness on vallikraav.

Siin on ebamugav tõde, millega AI-tööstus silmitsi seisab: alusmudel loeb vähem kui süsteem selle ümber.

LangChain tõestas seda lõplikult. Nende koodiagent tõusis Terminal Bench 2.0-s 52,8%-lt 66,5%-le — hüpates esikolmekümnest esiviisikusse —, muutmata mudeli juures midagi. Nad muutsid ainult harnessi:

Muudatus	Mida nad tegid	Mõju
Iseverifitseerimise ahel	Lisati täitmise-eelne kontrollnimekirja vahetarkvara	Veid tuvastati enne esitamist
Konteksti-inseneeria	Kaardistati kataloogistruktuurid käivitamisel	Agent mõistis koodibaasi algusest peale
Tsükli tuvastamine	Jälgiti korduvaid failimuudatusi	Ennetati "surmasilmuseid"
Arutluskäigu võileib	Kõrge arutlus planeerimiseks/verifitseerimiseks, keskmine rakendamiseks	Parem kvaliteet ajaeelarve piires

Sama mudel. Erinev harness. Oluliselt paremad tulemused.

OpenAI 1 miljoni koodirea tõenduspunkt

OpenAI eksperiment on seni kõige veenvam tõend:

• 5 kuud arendust.
• 1 miljon+ koodirida lõpptootes.
• Null käsitsi kirjutatud rida — iga rea lõid Codexi agendid.
• Ehitatud umbes 1/10 ajaga, mis oleks kulunud inimestel.
• Tootel on sisesed igapäevased kasutajad ja välised alfatestijad.
• See tarnitakse, juurutatakse, see läheb katki ja parandatakse — kõik agentide poolt harnessi sees.

Inseneride töö? Harnessi projekteerimine. Kavatsuse täpsustamine. Tagasiside andmine. Mitte koodi kirjutamine.

---

Harness-inseneeria kolm sammast

OpenAI raamistik jagab harness-inseneeria kolme põhikategooriasse:

1. Konteksti-inseneeria

Konteksti-inseneeria eesmärk on tagada, et agendil oleks õigel ajal õige teave.

Staatiline kontekst:

• Repositooriumi-lokaalne dokumentatsioon (arhitektuuri spetsifikatsioonid, API lepingud, stiilijuhised).
• AGENTS.md või CLAUDE.md failid, mis kodeerivad projektispetsiifilised reeglid.
• Ristviidatud disainidokumendid, mida valideerivad linterid.

Dünaamiline kontekst:

• Seireandmed (logid, meetrikad, jäljed), mis on agentidele kättesaadavad.
• Kataloogistruktuuri kaardistamine agendi käivitamisel.
• CI/CD torustiku olek ja testitulemused.

Kriitiline reegel: Agendi vaatenurgast ei ole olemas midagi, millele tal pole kontekstis juurdepääsu. Teadmised Google Docsis, Slacki vestlustes või inimeste peades on süsteemile nähtamatud. Repositoorium peab olema ainus tõeallikas.

2. Arhitektuurilised piirangud

Siin lahkneb harness-inseneeria kõige teravamalt traditsioonilisest AI-viipamisest. Selle asemel, et öelda agendile "kirjuta head koodi", te jõustate mehaaniliselt, milline hea kood välja näeb.

Sõltuvuste kihilisus:

Tüübid → Konfiguratsioon → Repositoorium → Teenus → Käitusaeg → UI

Iga kiht saab importida ainult endast vasakul asuvatest kihtidest. See ei ole soovitus — seda jõustavad struktuuritestid ja CI valideerimine.

Piirangute jõustamise tööriistad:

• Deterministlikud linterid — Kohandatud reeglid, mis märgistavad rikkumised automaatselt.
• LLM-põhised audiitorid — Agendid, kes vaatavad läbi teiste agentide koodi arhitektuurilise vastavuse osas.
• Struktuuritestid — Nagu ArchUnit, kuid AI-genereeritud koodi jaoks.
• Pre-commit konksud — Automaatsed kontrollid enne koodi salvestamist.

Miks piirangud väljundit parandavad: Paradoksaalselt muudab lahendusruumi piiramine agendid produktiivsemaks, mitte vähem. Kui agent võib genereerida mida iganes, raiskab ta tokeneid tupikteede uurimisele. Kui harness määratleb selged piirid, koondub agent kiiremini õigete lahendusteni.

3. Entroopia haldus ("Prügikoristus")

See on kõige vähem hinnatud komponent. Aja jooksul koguvad AI-genereeritud koodibaasid entroopiat — dokumentatsioon triivib tegelikkusest eemale, nimekonventsioonid lahknevad, koguneb surnud koodi.

Harness-inseneeria lahendab selle perioodiliste puhastusagentidega:

• Dokumentatsiooni konsistentsi agendid — Kontrollivad, kas dokumendid vastavad praegusele koodile.
• Piirangute rikkumise skannerid — Leiavad koodi, mis pääses varasematest kontrollidest läbi.
• Mustrite jõustamise agendid — Tuvastavad ja parandavad kõrvalekaldeid kehtestatud mustritest.
• Sõltuvuste audiitorid — Jälgivad ja lahendavad ring- või mittevajalikke sõltuvusi.

Need agendid töötavad graafiku alusel — kord päevas, kord nädalas või teatud sündmuste peale —, hoides koodibaasi tervena nii inimretsensentide kui ka tulevaste AI-agentide jaoks.

---

Harness-inseneeria praktikas: Kuidas meeskonnad seda tegelikult teevad

OpenAI lähenemine: Null inimkoodi

OpenAI meeskonna struktuur harness-inseneeria jaoks:

Roll	Traditsiooniline	Harness-inseneeria
Koodi kirjutamine	Põhitöö	Mitte kunagi
Arhitektuuri disain	Osa tööst	Põhitöö
Dokumentatsiooni kirjutamine	Järelemõte	Kriitiline infrastruktuur
PR-ide ülevaatus	Koodi ülevaatus	Agendi väljundi + harnessi tõhususe ülevaatus
Silumine (Debugging)	Koodi lugemine	Agendi käitumismustrite analüüsimine
Testimine	Testide kirjutamine	Testimisstrateegiate disainimine, mida agendid täidavad

Stripe'i lähenemine: "Käsilased" mastaabis

Stripe'i sisesed koodiagendid, mida nimetatakse Minions (käsilased), loovad nüüd üle 1000 liidetud pull request'i nädalas:

1. Arendaja postitab ülesande Slacki.
2. Minion kirjutab koodi.
3. Minion läbib CI.
4. Minion avab PR-i.
5. Inimene vaatab üle ja liidab (merge).

Sammude 1 ja 5 vahel puudub arendaja sekkumine. Harness tegeleb kõige muuga — testide täitmine, CI valideerimine, stiilile vastavus ja dokumentatsiooni uuendused.

LangChaini lähenemine: Vahetarkvara-keskne

LangChain struktureerib oma harnessi koostatavate vahetarkvara kihtidena:

Agendi päring
  → LocalContextMiddleware (kaardistab koodibaasi)
  → LoopDetectionMiddleware (ennetab kordusi)
  → ReasoningSandwichMiddleware (optimeerib arvutust)
  → PreCompletionChecklistMiddleware (jõustab verifitseerimist)
  → Agendi vastus

Iga vahetarkvara kiht lisab konkreetse võimekuse ilma agendi põhiloogikat muutmata. See modulaarne lähenemine muudab harnessi testitavaks ja arendatavaks.

---

Oma esimese harnessi ehitamine: Praktiline raamistik

Tase 1: Põhiline harness (üksikarendaja)

Kui kasutate Claude Code'i, Cursorit või Codexit individuaalsete projektide jaoks:

Mida seadistada:

• CLAUDE.md või .cursorrules fail projekti konventsioonidega.
• Pre-commit konksud lintimiseks ja vormindamiseks.
• Testide kogumik, mida agent saab iseseisvaks verifitseerimiseks käivitada.
• Selge kataloogistruktuur koos ühtse nimepanekuga.

Seadistamise aeg: 1-2 tundi Mõju: Ennetab kõige tavalisemaid agendi vigu.

Tase 2: Meeskonna harness (väike meeskond)

3-10 arendajaga meeskondadele, kes jagavad koodibaasi:

Lisa tasemele 1:

• AGENTS.md meeskonnaüleste konventsioonidega.
• CI poolt jõustatud arhitektuurilised piirangud.
• Jagatud viibamallid (prompt templates) tavaliste ülesannete jaoks.
• Dokumentatsioon-kui-kood, mida valideerivad linterid.
• Koodi ülevaatuse kontrollnimekirjad spetsiaalselt agendi loodud PR-ide jaoks.

Seadistamise aeg: 1-2 päeva Mõju: Järjepidev agendi käitumine kogu meeskonnas.

Tase 3: Tootmisharness (inseneriorganisatsioon)

Organisatsioonidele, kus töötab kümneid samaaegseid agente:

Lisa tasemele 2:

• Kohandatud vahetarkvara kihid (tsükli tuvastamine, arutluskäigu optimeerimine).
• Seire integratsioon (agendid loevad logisid ja meetrikat).
• Entroopia halduse agendid graafiku alusel.
• Harnessi versioonimine ja A/B testimine.
• Agendi jõudluse jälgimise töölauad.
• Eskaleerimispoliitikad juhuks, kui agendid jäävad hätta.

Seadistamise aeg: 1-2 nädalat Mõju: Agendid tegutsevad autonoomsete panustajatena.

---

Tavalised harness-inseneeria vead

1. Kontrollvoo üle-inseneerimine

"Kui teete kontrollvoo liiga keeruliseks, lõhub järgmine mudeliuuendus teie süsteemi."

Mudelid arenevad kiiresti. Võimekused, mis 2024. aastal nõudsid keerulisi torustikke, lahendatakse nüüd ühe kontekstiakna viibaga. Ehitage oma harness eemaldatavana (rippable) — peaksite saama "targa" loogika eemaldada, kui mudel muutub piisavalt targaks, et seda mitte vajada.

2. Harnessi kohtlemine staatilisena

Harness peab koos mudeliga arenema. Kui uus mudeliversioon parandab arutlusvõimet, võib teie arutluskäigu optimeerimise vahetarkvara muutuda vastutöötavaks. Vaadake üle ja uuendage harnessi komponente iga suurema mudeliuuendusega.

3. Dokumentatsioonikihi ignoreerimine

Kõige mõjuvam harnessi täiustus on sageli lihtsaim: parem dokumentatsioon. Kui teie AGENTS.md on segane, on ka agendi väljund segane. Investeerige täpsesse, masinloetavasse dokumentatsiooni, mis on agendi jaoks absoluutne tõde.

4. Tagasisideahela puudumine

Ilma tagasisideta harness on puur, mitte juhend. Agent peab teadma, millal ta õnnestub ja millal ebaõnnestub. Ehitage sisse:

• Iseverifitseerimise sammud enne ülesande lõpetamist.
• Testide täitmine agendi töövoo osana.
• Meetrikad agendi edukuse määra kohta ülesande tüübi järgi.

5. Ainult inimestele mõeldud dokumentatsioon

Kui teie arhitektuurilised otsused elavad inimeste peades või Confluence'i lehtedel, millele agent ligi ei pääse, on harnessis tühimik. Kõik, mida agent vajab, peab olema repositooriumis.

---

Harness-inseneeria vs. seotud mõisted

Mõiste	Ulatus	Fookus
Prompt-inseneeria	Üksik interaktsioon	Tõhusate viipade koostamine
Konteksti-inseneeria	Mudeli kontekstiaken	Millist teavet mudel näeb
Harness-inseneeria	Kogu agendi süsteem	Keskkond, piirangud, tagasiside, elutsükkel
Agendi-inseneeria	Agendi arhitektuur	Agendi sisemine disain ja marsruutimine
Platvormi-inseneeria	Infrastruktuur	Juurutamine, skaleerimine, operatsioonid

Harness-inseneeria sisaldab konteksti-inseneeriat ja ammutab prompt-inseneeriast, kuid see toimib kõrgemal tasemel — see räägib terviklikust süsteemist, mis muudab agendid usaldusväärseks, mitte ainult ühe interaktsiooni sisenditest.

---

Mida see tähendab tarkvarainseneride jaoks

Töö on muutumas

Harness-inseneeria kujutab endast tõelist evolutsiooni selles, mida tarkvarainsenerid teevad:

Enne	Pärast
Koodi kirjutamine	Keskkondade disainimine, kus AI kirjutab koodi
Koodi silumine	Agendi käitumise silumine
Koodi ülevaatus	Agendi väljundi + harnessi tõhususe ülevaatus
Testide kirjutamine	Testimisstrateegiate disainimine
Dokumentide haldamine	Dokumentatsiooni ehitamine masinloetava infrastruktuurina

See ei tähenda, et insenerid muutuvad vähem tehniliseks. Pigem nõuab harness-inseneeria sügavamat arhitektuurilist mõtlemist — te projekteerite süsteeme, mis peavad töötama ilma teie pideva sekkumiseta.

Oskused, mis loevad

Põhinedes sellel, mida oleme näinud AI-põhiseid tooteid ehitades NxCode'is:

1. Süsteemne mõtlemine — Arusaamine, kuidas piirangud, tagasisideahelad ja dokumentatsioon omavahel suhtlevad.
2. Arhitektuuri disain — Piiride määratlemine, mis on jõustatavad ja produktiivsed.
3. Spetsifikatsioonide kirjutamine — Kavatsuse väljendamine piisavalt täpselt, et agendid saaksid seda täita.
4. Jälgitavus (Observability) — Seire ehitamine, mis paljastab agendi käitumismustrid.
5. Iteratsiooni kiirus — Harnessi konfiguratsioonide kiire testimine ja viimistlemine.

Meie kogemus: Mis praktikas toimib

Oleme ehitanud AI-põhiseid veebirakendusi, kasutades mitmeid agendi süsteeme (Claude Code, Codex, Cursor). Mustrid, mis on meie jaoks suurimat erinevust loonud:

• Repositooriumi-keskne dokumentatsioon: Iga arhitektuuriline otsus, nimekonventsioon ja juurutusprotsess on repos. Midagi ei ela Slackis ega Google Docsis.
• Inkrementaalne piirangute ehitamine: Alustage põhilisest lintimisest, lisage arhitektuurilised piirangud mustrite ilmnemisel, ärge püüdke alguses täiuslikku harnessi disainida.
• Agendipõhised ülevaatuse kontrollnimekirjad: AI-genereeritud koodil on teistsugused veatüübid kui inimkoodil. Meie ülevaatusprotsess arvestab tavaliste agendi mustritega (üle-abstraheerimine, mittevajalik veahaldus, dokumentatsiooni triiv).
• Mitme pakkuja harnessi disain: Meie harness töötab Claude'i, GPT ja Gemini mudelitega. Pakkujast sõltumatu disain tähendab, et saame mudeleid vahetada ilma kogu süsteemi uuesti üles ehitamata.

---

Peamised järeldused

1. Harness-inseneeria on uus distsipliin süsteemide projekteerimiseks, mis muudavad AI-agendid usaldusväärseks — piirangud, tagasisideahelad, dokumentatsioon ja elutsükli haldus.
2. Mudel on kaup; harness on vallikraav — LangChain hüppas edetabelites esikolmekümnest esiviisikusse, muutes ainult harnessi.
3. OpenAI ehitas 1M+ koodirida nulli inimkoodiga — tõestades, et harness-inseneeria töötab tootmismastaabis.
4. Kolm sammast: Konteksti-inseneeria, arhitektuurilised piirangud ja entroopia haldus.
5. Alusta lihtsalt: Hea AGENTS.md ja pre-commit konksud on mõjuvamad kui keeruline vahetarkvara.
6. Inseneri töö areneb — koodi kirjutamisest keskkondade disainimiseni, kus AI kirjutab koodi.
7. Ehita eemaldatavaid harnesse — üle-inseneerimine puruneb mudelite parandemisel; hoia see kohandatavana.

---

Seotud ressursid

• Agentne veeb selgitatud: AGENTS.md, MCP vs A2A — Protokollikiht, millele harness-inseneeria toetub.
• Cursor Cloud Agents: Autonoomne kodeerimine virtuaalmasinates — Pilvepõhised agendi harnessid praktikas.
• Claude Code kaugjuhtimine: Terminali üleandmise juhend — Agendi sessioonide haldamine eemalt.
• Ehita oma veebileht NxCode'iga — AI-põhine veebiarendus koos mitme pakkuja harnessi arhitektuuriga.