Kaj se boste naučili

Ta vodnik obravnava Harness engineering od osnovnih principov do praktične implementacije. Razumeli boste, kaj je to, zakaj je OpenAI nanj stavil svoj največji interni projekt, specifične arhitekturne vzorce, ki omogočajo njegovo delovanje, in kako te principe uporabiti v lastnih delovnih tokovih AI agentov — ne glede na to, ali uporabljate Codex, Claude Code, OpenCode ali kateri koli drug sistem agentov.

Harness Engineering: Popoln vodnik za razvoj AI agentov v letu 2026

Če je bilo leto 2025 leto, ko so AI agenti dokazali, da znajo pisati kodo, je leto 2026 leto, ko smo se naučili, da agent ni težak del — težko delo je vpetje (harness).

Ekipa OpenAI Codex je februarja 2026 objavila prelomno objavo na blogu, v kateri so opisali, kako so zgradili produkcijsko aplikacijo z približno 1 milijon vrsticami kode, pri čemer človeške roke niso napisale niti ene vrstice. Skrivnost ni bila v boljšem modelu ali pametnejšem pozivu. Bil je sistem, ki so ga zgradili okoli agenta — vpetje (harness). Vir

Ta vodnik razčlenjuje vsak princip, vzorec in praktično tehniko iz tega eksperimenta ter širšega gibanja Harness engineering, ki se je pojavilo okoli njega.

1. del: Kaj je Harness Engineering?

Definicija

Harness engineering je disciplina načrtovanja celotnega okolja — ogrodja, povratnih zank, dokumentacije, arhitekturnih omejitev in strojno berljivih artefaktov — ki AI agentom za kodiranje omogoča zanesljivo in visoko kakovostno delo v velikem obsegu z minimalnim človeškim posredovanjem.

Izraz "harness" (vpetje) izvira iz konjske opreme: vajeti, sedlo, žvale — celoten nabor opreme za usmerjanje močne, a nepredvidljive živali v pravo smer. Nenadzorovan konj je nevaren. Vprežen konj je zgradil civilizacije. Enako velja za AI agente. Vir

Zakaj se je pojavil zdaj

Premik od Prompt engineering k Harness engineering odraža dozorevanje pokrajine razvoja AI:

Vir

Ključno spoznanje, ki je spodbudilo ta prehod: agenti so postali dovolj sposobni, da se je ozko grlo premaknilo s kakovosti modela na kakovost okolja. Vrhunski model, ki deluje v slabo strukturiranem repozitoriju, daje slabše rezultate kot povprečen model, ki deluje v dobro vpetem okolju.

2. del: Eksperiment OpenAI Codex

Obseg

V petmesečnem internem eksperimentu so inženirji OpenAI zgradili in poslali beta izdelek, ki vsebuje približno 1 milijon vrstic kode. Repozitorij obsega aplikacijsko logiko, infrastrukturo, orodja, dokumentacijo in interne razvojne pripomočke. Za sidranje sistema ni bilo nobene predhodno obstoječe kode, ki bi jo napisal človek. Vir

Ekipa

Projekt se je začel z le tremi inženirji, ki so upravljali Codex. V petmesečnem obdobju je bilo odprtih in združenih približno 1.500 pull requests. Ko se je ekipa povečala na sedem inženirjev, se je prepustnost povečala — kar je protisloven rezultat, ki je nakazal, da je bilo vpetje samo po sebi primarni multiplikator produktivnosti, ne pa posamezne veščine.

OpenAI ocenjuje, da so sistem zgradili v približno 1/10 časa, ki bi bil potreben za ročno pisanje kode. Vir

Začetno ogrodje (Scaffold)

Projekt se je začel s Codex CLI, ki je generiral začetno ogrodje z uporabo GPT-5, voden z majhnim naborom obstoječih predlog:

• Struktura repozitorija in konvencije o imenikih
• CI/CD konfiguracija
• Pravila za formatiranje kode in linting
• Nastavitev upravljalnika paketov
• Osnova aplikacijskega ogrodja

Iz tega semena je vse ostalo zraslo z razvojem, ki so ga vodili agenti.

Problem petka

Zgodaj v eksperimentu je ekipa odkrila kritično težavo: vsak petek — 20% svojega inženirskega časa — so porabili za čiščenje tistega, kar so poimenovali "AI slop" (AI navlaka). To je vključevalo neskladne vzorce, podvojeno logiko, napačno poimenovane spremenljivke in arhitekturni odmik.

To ni bilo razširljivo. Rešitev je bila, da so svoje standarde zakodirali v samo vpetje, tako da bi agenti že od začetka proizvajali čistejše izhode, in zgradili avtomatizirane sisteme za čiščenje preostalega odmika.

3. del: Pet ključnih principov

Princip 1: Znanje na prvem mestu v repozitoriju

Z vidika agenta vse, do česar ne more dostopati v kontekstu med delovanjem, dejansko ne obstaja. Znanje, ki živi v Google Docs, nitih klepetov, sporočilih Slack ali v glavah ljudi, je za sistem nevidno.

To pomeni, da mora vse znanje živeti kot lokalni, različicirani artefakti repozitorija:

• Koda — primarni artefakt
• Markdown dokumentacija — arhitekturne odločitve, konvencije, vodniki za uvajanje
• Sheme — API pogodbe, sheme baze podatkov, definicije tipov
• Izvedljivi načrti — razčlenitev nalog korak za korakom, ki jim agent lahko sledi
• Konfiguracija — linter pravila, CI cevovodi, standardi formatiranja

Ekipa se je naučila, da morajo sčasoma v repozitorij potisniti vedno več konteksta. Vsakič, ko je agent naredil napako, ker mu je manjkal kontekst, rešitev ni bila v boljšem pozivu — bila je v dodajanju tega konteksta v repozitorij. Vir

Praktična implementacija:

# ARCHITECTURE.md (lives in repo root)

## Dependency Rules
- UI components may import from Service layer but never from Repo layer
- Service layer may not import from Runtime layer
- All cross-domain communication goes through typed event bus

## Naming Conventions
- React components: PascalCase, suffixed with purpose (UserListPage, UserCard)
- Services: camelCase, suffixed with Service (userService, authService)
- Types: PascalCase, prefixed with domain (UserProfile, OrderItem)

## Testing Requirements
- All Service functions require unit tests
- All API endpoints require integration tests
- Coverage threshold: 80% per package

Princip 2: Zlata pravila

Zlata pravila so mnenjska, mehanska pravila, zakodirana neposredno v repozitorij, ki ohranjajo kodo čitljivo in skladno za prihodnje zagone agentov. To niso le smernice — so uveljavljene omejitve.

Primeri iz eksperimenta OpenAI:

1. Prednost imajo deljeni paketi pripomočkov pred ročno izdelanimi pomočniki — centralizira invariante, tako da se ob spremembi vedenja to spremeni na enem mestu.
2. Ne preiskuj podatkov v YOLO slogu — validiraj meje ali se zanašaj na tipizirane SDK, da agenti ne morejo po nesreči graditi na ugibanih oblikah podatkov.
3. En koncept, ena datoteka — vsaka datoteka mora predstavljati en sam koncept, kar agentom olajša iskanje in spreminjanje pravega mesta.
4. Eksplicitno namesto implicitnega — izogibajte se čarobnemu vedenju, za razumevanje katerega bi agent potreboval lokalno znanje ekipe.

Vir

Ta pravila niso le dokumentacija. Uveljavljajo jih:

• Linter pravila — linterji po meri (ki jih generira Codex), ki označujejo kršitve.
• Strukturni testi — testi, ki preverjajo skladnost z arhitekturo.
• CI vrata — pull requests, ki kršijo zlata pravila, so samodejno zavrnjeni.

Princip 3: Večplastna arhitektura z mehanskim uveljavljanjem

Vsaka poslovna domena v projektu OpenAI je razdeljena na fiksen nabor plasti s strogo preverjenimi smermi odvisnosti:

Types → Config → Repo → Service → Runtime → UI

Odvisnosti tečejo le v eno smer. UI komponenta je lahko odvisna od Runtime in Service, vendar Service nikoli ne sme uvažati iz UI. Repo je lahko odvoren od Config in Types, nikoli pa od Service. Vir

Te omejitve se uveljavljajo mehansko:

// structural-test.ts — enforces dependency boundaries
import { analyzeImports } from './tools/import-analyzer';

describe('Dependency Layer Enforcement', () => {
  it('Service layer must not import from Runtime', () => {
    const violations = analyzeImports({
      sourceLayer: 'service',
      forbiddenLayers: ['runtime', 'ui'],
    });
    expect(violations).toEqual([]);
  });

  it('Repo layer must not import from Service', () => {
    const violations = analyzeImports({
      sourceLayer: 'repo',
      forbiddenLayers: ['service', 'runtime', 'ui'],
    });
    expect(violations).toEqual([]);
  });
});

Strukturni testi potrjujejo skladnost in preprečujejo kršitve modularnega plastenja. To ni predlog — to uveljavlja CI. Vsak pull request, ne glede na to, ali ga je ustvaril človek ali agent, mora opraviti te teste.

Princip 4: Avtomatizirano čiščenje kode (Garbage Collection)

Tudi z zlatimi pravili in strukturnim uveljavljanjem koda, ki jo generirajo agenti, sčasoma odstopa. Ekipa OpenAI je to rešila z implementacijo avtomatiziranega čiščenja kode (garbage collection) — ponavljajočimi se opravili v ozadju, ki:

1. Skenirajo odstopanja od zlatih pravil v celotni kodi.
2. Posodabljajo ocene kakovosti za vsak modul na podlagi rezultatov skladnosti.
3. Odpirajo ciljne refaktoring pull requests, ki odpravljajo specifične kategorije odstopanj.

To je nadomestilo ročno "petkovo čiščenje" s sistemom, ki deluje neprekinjeno. Sam Garbage collector poganjajo agenti Codex, kar ustvarja samooskrbno zanko. Vir

# .github/workflows/garbage-collection.yml
name: Codebase Garbage Collection
on:
  schedule:
    - cron: '0 2 * * *'  # Run nightly at 2 AM

jobs:
  gc-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run golden principle scanner
        run: npx codex-gc scan --principles ./GOLDEN_PRINCIPLES.md
      - name: Generate refactoring PRs
        run: npx codex-gc fix --auto-pr --max-prs 5

Princip 5: Izvedljivi načrti

Preden agenti napišejo kodo, napišejo načrte. Ti načrti niso neformalni zapiski — so strukturirani, izvedljivi dokumenti, ki določajo:

• Cilj: Kaj naloga doseže.
• Datoteke za spremembo: Ekspliciten seznam datotek, ki se jih bo agent dotaknil.
• Odvisnosti: Druge naloge ali moduli, od katerih je to delo odvisno.
• Kriteriji sprejemljivosti: Kako preveriti, ali je delo končano.
• Omejitve: Arhitekturna pravila, ki ne smejo biti kršena.

# Plan: Add user notification preferences

## Objective
Allow users to configure which notification channels (email, SMS, push) they
receive alerts on, with per-category granularity.

## Files to Modify
- src/types/user.ts — Add NotificationPreferences type
- src/repo/userRepo.ts — Add getPreferences/setPreferences methods
- src/service/notificationService.ts — Filter notifications by preferences
- src/ui/pages/SettingsPage.tsx — Add preferences UI section

## Constraints
- Must follow Types → Repo → Service → UI dependency flow
- NotificationPreferences type must be shared, not duplicated
- All new methods require unit tests

## Acceptance Criteria
- [ ] User can toggle email/SMS/push per notification category
- [ ] Preferences persist across sessions
- [ ] Toggling a channel off stops notifications on that channel within 30s

Načrti živijo v repozitoriju kot datoteke markdown, so pod nadzorom različic in jih je mogoče pregledati pred izvedbo — kar ljudem omogoča nadzorno točko med namero in implementacijo.

4. del: Zanka agenta Codex

Razumevanje, kako zanka agenta Codex deluje znotraj vpetja, je ključno za učinkovit Harness engineering.

Arhitektura zanke

OpenAI je objavil podrobno razčlenitev zanke agenta Codex v spremljajoči objavi na blogu "Unrolling the Codex agent loop." Vir Zanka sledi temu ciklu:

Preberi kontekst → Načrtuj → Izvedi → Validiraj → Commit-aj (ali Ponovi)

Vsaka iteracija:

1. Preberi kontekst: Agent prebere ustrezne datoteke, dokumentacijo, sheme in načrt nalog iz repozitorija.
2. Načrtuj: Na podlagi konteksta agent določi, katere spremembe bo izvedel.
3. Izvedi: Agent napiše ali spremeni kodo.
4. Validiraj: Vpetje zažene teste, linterje in strukturne preglede sprememb.
5. Commit-aj ali Ponovi: Če validacija uspe, agent opravi commit. Če ne uspe, agent prebere izpis napake in poskusi znova.

Vloga vpetja je, da naredi koraka 1 in 4 čim bolj informacijsko bogata. Več konteksta kot agent prebere, boljši je njegov načrt. Bolj ko so povratne informacije validacije specifične, hitreje pride do delujoče rešitve.

Vpetje strežnika aplikacij (App Server Harness)

V objavi "Unlocking the Codex harness: how we built the App Server" OpenAI opisuje konkretno infrastrukturo, ki poganja zanko agenta. Vir App Server zagotavlja:

• Peskovniška okolja za izvajanje za vsako nalogo agenta.
• Vnaprej konfiguriran dostop do orodij (datotečni sistem, terminal, brskalnik).
• Samodejno vbrizgavanje konteksta iz artefaktov repozitorija.
• Pretočne povratne informacije o validaciji, tako da agenti lahko vidijo neuspele teste v realnem času.

5. del: Uporaba Harness Engineering v vaši ekipi

Prvi koraki: Minimalno vzdržno vpetje (MVH)

Za koristi od Harness engineering vam ni treba replicirati celotne infrastrukture OpenAI. Začnite s temi temeljnimi elementi:

1. korak: Ustvarite ARCHITECTURE.md

Dokumentirajte arhitekturna pravila svojega projekta v strojno berljivi obliki v korenu repozitorija. Vključite:

• Meje modulov in dovoljene odvisnosti
• Konvencije o poimenovanju
• Pravila za organizacijo datotek
• Zahteve za testiranje

Ta ena sama datoteka dramatično izboljša kakovost izhoda agentov, saj jo agenti preberejo pred izvajanjem sprememb.

2. korak: Dodajte strukturne teste

Napišite teste, ki preverjajo vaša arhitekturna pravila. Ti testi ne preverjajo poslovne logike — preverjajo, ali je koda pravilno organizirana:

// No service file should import from a UI module
test('service layer isolation', () => {
  const serviceFiles = glob('src/services/**/*.ts');
  for (const file of serviceFiles) {
    const imports = extractImports(file);
    const uiImports = imports.filter(i => i.startsWith('../ui/'));
    expect(uiImports).toHaveLength(0);
  }
});

3. korak: Konfigurirajte CI validacijo

Zagotovite, da vaš CI cevovod zažene strukturne teste, linterje in preglede tipov ob vsakem pull requestu — vključno s tistimi, ki jih ustvarijo agenti. Agent mora videti enak izpis validacije kot človeški razvijalec.

4. korak: Napišite načrte nalog pred izvedbo agenta

Preden od agenta zahtevate implementacijo funkcije, napišite dokument s strukturiranim načrtom, ki določa datoteke za spremembo, omejitve, ki jih je treba upoštevati, in kriterije sprejemljivosti. Te načrte shranite v svoj repozitorij.

5. korak: Nastavite avtomatizirano čiščenje

Implementirajte tedensko ali nočno CI opravilo, ki skenira kodo za odstopanja od vaših dokumentiranih standardov in ustvari ciljne refaktoring PR-je.

Izbira vašega sistema agentov

Principi Harness engineering veljajo ne glede na to, katerega agenta uporabljate:

Vpetje živi v vašem repozitoriju, ne v vašem agentu. To pomeni, da lahko zamenjate agente, ne da bi izgubili naložbo v vpetje.

Razširitev z enega agenta na več

Eksperiment OpenAI je pokazal, da Harness engineering omogoča vzporedno izvajanje agentov. Ker vpetje uveljavlja arhitekturne meje, lahko več agentov hkrati dela na različnih delih kode, ne da bi prišlo do sporov.

Ključne zahteve za vzporedno izvajanje agentov:

1. Jasno lastništvo modulov — vsak agent dela znotraj definiranih meja.
2. Tipizirani vmesniki med moduli — agenti lahko kodirajo glede na vmesnike, ne da bi poznali podrobnosti implementacije.
3. Preprečevanje sporov pri združevanju — naloge so omejene tako, da se zmanjša prekrivanje datotek.
4. Centralizirana validacija — vsi agenti oddajo dela v isti CI cevovod.

6. del: Pogoste pasti in proti-vzorci

Proti-vzorec 1: Obravnavanje agenta kot vpetja

Agent ni vpetje. Vpetje je okolje, v katerem agent deluje. Iskanje pametnejšega modela za kompenzacijo slabo strukturiranega repozitorija je napačen pristop. Popravite okolje, ne poziva.

Proti-vzorec 2: Dokumentacija na napačnem mestu

Če vaše arhitekturne odločitve živijo v Confluence, Notion ali Google Docs, jih agenti ne vidijo. Rešitev je preprosta, a zahteva disciplino: vso dokumentacijo, pomembno za razvoj, premaknite v repozitorij.

Proti-vzorec 3: Ročno čiščenje namesto avtomatiziranega uveljavljanja

Če porabite veliko časa za čiščenje kode, ki jo generirajo agenti, potrebujete boljše uveljavljanje, ne več sej čiščenja. Vsako ponavljajoče se opravilo čiščenja mora postati linter pravilo, strukturni test ali avtomatizirano opravilo refaktoringa.

Proti-vzorec 4: Preveliko omejevanje

Vpetje, ki je preveč togo, agentom preprečuje iskanje kreativnih rešitev. Cilj je omejiti arhitekturo, ne implementacije. Agentom povejte, katere module lahko spreminjajo in katere odvisnosti so dovoljene, vendar jim pustite, da se sami odločijo, kako bodo implementirali logiko znotraj teh meja.

Proti-vzorec 5: Ignoriranje povratnih informacij agenta

Ko agent večkrat spodleti pri določenih nalogah, neuspeh običajno kaže na vrzel v vpetju, ne na omejitev agenta. Spremljajte vzorce napak in jih uporabite za izboljšanje dokumentacije, strukturnih testov ali arhitekturnih omejitev.

7. del: Prihodnost Harness Engineering

Vidik Martina Fowlerja

Martin Fowler je na svojem blogu objavil analizo Harness engineering in opozoril, da predstavlja temeljni premik v načinu delovanja programskih ekip. Disciplina si izposoja desetletja najboljših praks programskega inženiringa — continuous integration, zapise o arhitekturnih odločitvah, dependency injection — vendar jih preoblikuje za svet, ki ga vodijo agenti. Vir

Okvir HumanLayer

Ekipa pri HumanLayer je objavila svojo analizo, v kateri so Harness engineering označili za "težavo v veščinah" (skill issue) — trdijo, da bo sposobnost načrtovanja učinkovitih vpetij postala primarna razlika med visoko zmogljivimi in težavnimi inženirskimi ekipami. Vir

Kaj to pomeni za razvijalce

Harness engineering ne nadomešča razvijalskih veščin — temveč jih preusmerja. Namesto pisanja kode starejši inženirji načrtujejo sisteme, ki agentom omogočajo dobro pisanje kode. Veščine, ki štejejo, se premikajo od implementacije k arhitekturi, od kodiranja k sistemskemu načrtovanju, od pisanja testov k načrtovanju okvirjev za testiranje.

Za ekipe, ki gradijo aplikacije, platforme, kot je ZBuild, že vključujejo principe Harness engineering v svoje delovne tokove graditeljev aplikacij. Namesto da bi od razvijalcev zahtevali načrtovanje lastnih vpetij iz nič, ZBuild ponuja vnaprej konfigurirane arhitekturne vzorce, upravljanje odvisnosti in sisteme validacije, ki vodijo AI agente k visoko kakovostnemu izhodu — kar razvijalcem omogoča, da se osredotočijo na produktne odločitve namesto na infrastrukturo.

Tri obzorja

V prihodnosti se bo Harness engineering verjetno razvijal skozi tri faze:

1. Kratkoročno (2026): Ekipe sprejmejo dokumentacijo v repozitoriju, strukturne teste in zlata pravila. Razvoj s pomočjo agentov postane standardna praksa za dobro vpete projekte.

2. Srednjeročno (2027): Samogeneriranje vpetja postane vodeno s strani agentov. Agenti analizirajo obstoječe kodo in predlagajo konfiguracije vpetja — linter pravila, strukturne teste, meje odvisnosti — na podlagi vzorcev, ki jih opazijo.

3. Dolgoročno (2028+): Vpetja postanejo prilagodljiva. Namesto statičnih pravil se razvijajo na podlagi rezultatov kode, ki jo generirajo agenti, in samodejno zaostrujejo omejitve na področjih, kjer agenti pogosto delajo napake, ter jih sproščajo tam, kjer so dosledno uspešni.

8. del: Praktični kontrolni seznam

Uporabite ta seznam za oceno zrelosti Harness engineering v vaši ekipi:

Temelji (Začnite tukaj)

• ARCHITECTURE.md obstaja v korenu repozitorija
• Formatiranje kode je avtomatizirano (Prettier, Black, gofmt)
• Linting se izvaja ob vsakem pull requestu
• Preverjanje tipov je obvezno (TypeScript strict, mypy, itd.)

Srednja stopnja

• Strukturni testi potrjujejo meje odvisnosti
• Zlata pravila so dokumentirana in strojno uveljavljiva
• Načrti nalog so napisani pred izvedbo agenta
• PR-ji, ki jih generirajo agenti, gredo skozi enak CI kot PR-ji, ki jih ustvarijo ljudje

Napredno

• Avtomatizirano čiščenje kode (garbage collection) se izvaja po urniku
• Več agentov lahko dela vzporedno brez sporov
• Vzorci napak agentov se spremljajo in uporabljajo za izboljšanje vpetja
• Vpetje samo je pod nadzorom različic in se pregleduje kot koda

Ekspert

• Agenti generirajo dele vpetja (linter pravila, strukturni testi)
• Ocene kakovosti se samodejno dodelijo vsakemu modulu
• Izboljšave vpetja temeljijo na podatkih o stopnji uspešnosti agentov
• Ekipa pošlje več kode na inženirja na teden kot pred uvedbo agentov

Zaključek

Harness engineering ni modna muha. Je naravna evolucija programskega inženiringa v dobi, ko so AI agenti dovolj sposobni za pisanje produkcijske kode, vendar potrebujejo strukturirana okolja, da to počnejo dobro. Eksperiment OpenAI z milijonom vrstic je dokazal koncept v velikem obsegu, principi, ki so jih izpostavili — znanje v repozitoriju, zlata pravila, večplastna arhitektura, avtomatizirano čiščenje in izvedljivi načrti — pa so uporabni za ekipe vseh velikosti.

Ekipe, ki bodo leta 2026 obvladale Harness engineering, bodo pošiljale kodo hitreje, ohranjale višjo kakovost kode in se učinkoviteje širile kot tiste, ki AI agente obravnavajo kot poveličan avtodopolnjevalnik (autocomplete). Agent je konj. Vpetje pa je tisto, kar ga naredi koristnega.

Viri

• Harness Engineering: Leveraging Codex in an Agent-First World — OpenAI
• Unlocking the Codex Harness: How We Built the App Server — OpenAI
• Unrolling the Codex Agent Loop — OpenAI
• OpenAI Introduces Harness Engineering — InfoQ
• Harness Engineering — Martin Fowler
• Skill Issue: Harness Engineering for Coding Agents — HumanLayer
• From Prompt Engineering to Harness Engineering — SoftmaxData
• How to Build an Agent Harness — Study Notes
• Harness Engineering — GTCode
• OpenAI Harness Engineering: Ship 1M Lines of Code — The Neuron
• How OpenAI Built 1M Lines of Code Using Only Agents — TonyLee
• Harness Engineering — The New Discipline — CodeNote