Co se naučíte

Tento průvodce pokrývá harness engineering od základních principů až po praktickou implementaci. Pochopíte, co to je, proč na něj OpenAI vsadila svůj největší interní projekt, konkrétní architektonické vzory, díky kterým funguje, a jak tyto principy aplikovat na vaše vlastní pracovní postupy s AI agenty – ať už používáte Codex, Claude Code, Windsurf nebo jakýkoli jiný agentní systém.

Harness Engineering: Kompletní průvodce pro vývoj AI agentů v roce 2026

Pokud byl rok 2025 rokem, kdy AI agenti dokázali, že umí psát kód, rok 2026 je rokem, kdy jsme se naučili, že agent není ta těžká část – tou je harness.

Tým Codex v OpenAI publikoval v únoru 2026 přelomový příspěvek na blogu popisující, jak vybudovali produkční aplikaci obsahující zhruba 1 000 000 řádků kódu, kde 0 řádků nebylo napsáno lidskou rukou. Tajemstvím nebyl lepší model nebo chytřejší prompt. Byl to systém, který postavili kolem agenta – harness. Zdroj

Tento průvodce rozebírá každý princip, vzor a praktickou techniku z tohoto experimentu a širšího hnutí harness engineering, které se kolem něj objevilo.

Část 1: Co je Harness Engineering?

Definice

Harness engineering je disciplína navrhování celého prostředí – scaffolding, zpětnovazební smyčky, dokumentace, architektonická omezení a strojově čitelné artefakty – které umožňuje AI coding agentům odvádět spolehlivou a kvalitní práci ve velkém měřítku s minimálním zásahem člověka.

Termín "harness" pochází z koňského postroje: otěže, sedlo, udidlo – kompletní sada vybavení pro usměrňování silného, ale nepředvídatelného zvířete správným směrem. Nekontrolovaný kůň je nebezpečný. Osedlaný kůň vybudoval civilizace. Totéž platí pro AI agenty. Zdroj

Proč se objevil právě teď

Posun od prompt engineering k harness engineering odráží dozrávání prostředí vývoje AI:

Zdroj

Klíčový poznatek, který tento přechod vyvolal: agenti se stali dostatečně schopnými, takže se úzké hrdlo přesunulo z kvality modelu na kvalitu prostředí. Špičkový model pracující v nepovedeně strukturovaném repozitáři produkuje horší výsledky než průměrný model pracující v dobře nastaveném prostředí (harness).

Část 2: Experiment OpenAI Codex

Měřítko

V 5měsíčním interním experimentu inženýři OpenAI vyvinuli a vydali beta produkt obsahující zhruba 1 000 000 řádků kódu. Repozitář zahrnuje aplikační logiku, infrastrukturu, nástroje, dokumentaci a interní vývojářské utility. Neexistoval žádný předem existující lidmi psaný kód, o který by se systém mohl opřít. Zdroj

Tým

Projekt začal s pouhými 3 inženýry, kteří řídili Codex. Během období 5 měsíců bylo otevřeno a sloučeno přibližně 1 500 pull requests. Jak se tým rozrostl na 7 inženýrů, propustnost se zvýšila – což byl kontraintuitivní výsledek, který naznačoval, že samotný harness byl primárním multiplikátorem produktivity, nikoli individuální dovednosti.

OpenAI odhaduje, že systém postavili přibližně za 1/10 času, který by byl zapotřebí k ručnímu napsání kódu. Zdroj

Počáteční Scaffold

Projekt začal tím, že Codex CLI vygeneroval počáteční scaffold pomocí GPT-5, vedený malou sadou existujících šablon:

• Struktura repozitáře a konvence adresářů
• Konfigurace CI/CD
• Formátování kódu a pravidla pro linting
• Nastavení správce balíčků
• Boilerplate aplikačního frameworku

Z tohoto základu vyrostlo vše ostatní prostřednictvím vývoje řízeného agenty.

Páteční problém

Na začátku experimentu tým objevil kritický problém: každý pátek – 20% svého inženýrského času – trávili úklidem toho, co nazývali "AI slop". To zahrnovalo nekonzistentní vzory, duplikovanou logiku, nesprávně pojmenované proměnné a architektonický drift.

To nebylo škálovatelné. Řešením bylo zakódovat jejich standardy přímo do harnessu, aby agenti od začátku produkovali čistší výstup, a vybudovat automatizované systémy pro čištění zbytkového driftu.

Část 3: Pět hlavních principů

Princip 1: Znalosti prioritně v repozitáři (Repository-First Knowledge)

Z pohledu agenta cokoli, k čemu nemá přístup v kontextu během běhu, efektivně neexistuje. Znalosti, které žijí v Google Docs, chatovacích vláknech, zprávách na Slacku nebo v hlavách lidí, jsou pro systém neviditelné.

To znamená, že veškeré znalosti musí žít jako lokální, verzované artefakty v repozitáři:

• Kód – primární artefakt
• Markdown dokumentace – architektonická rozhodnutí, konvence, příručky pro onboarding
• Schémata – API kontrakty, databázová schémata, definice typů
• Spustitelné plány – krok za krokem rozepsané úkoly, které může agent sledovat
• Konfigurace – pravidla linteru, CI pipelines, standardy formátování

Tým se naučil, že musí do repozitáře postupem času tlačit stále více kontextu. Pokaždé, když agent udělal chybu, protože mu chyběl kontext, nápravou nebyl lepší prompt – bylo to přidání tohoto kontextu do repozitáře. Zdroj

Praktická implementace:

# 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: Zlaté principy (Golden Principles)

Zlaté principy jsou názorově vyhraněná, mechanická pravidla zakódovaná přímo do repozitáře, která udržují codebase čitelnou a konzistentní pro budoucí běhy agentů. Nejsou to jen aspirativní pokyny – jsou to vynucovaná omezení.

Příklady z experimentu OpenAI:

1. Preferujte sdílené utility balíčky před ručně psanými pomocníky – centralizuje invarianty, takže když je potřeba změnit chování, změní se na jednom místě.
2. Nepropátrávejte data stylem YOLO – validujte hranice nebo spoléhejte na typovaná SDK, aby agenti nemohli omylem stavět na odhadovaných tvarech dat.
3. Jeden koncept, jeden soubor – každý soubor by měl reprezentovat jeden koncept, což agentům usnadňuje hledání a úpravu správného místa.
4. Explicitní nad implicitním – vyhněte se magickému chování, k jehož pochopení by agent potřeboval kmenové znalosti.

Zdroj

Tyto principy nejsou jen dokumentací. Jsou vynucovány pomocí:

• Linter pravidel – vlastní lintery (samy generované pomocí Codex), které označují porušení pravidel.
• Strukturálních testů – testy, které validují soulad s architekturou.
• CI gates – pull requests, které porušují zlaté principy, jsou automaticky zamítnuty.

Princip 3: Vrstvená architektura s mechanickým vymáháním

Každá byznys doména v projektu OpenAI je rozdělena do pevné sady vrstev s přísně validovanými směry závislostí:

Types → Config → Repo → Service → Runtime → UI

Závislosti proudí pouze jedním směrem. UI komponenta může záviset na Runtime a Service, ale Service nesmí nikdy importovat z UI. Repo může záviset na Config a Types, ale nikdy na Service. Zdroj

Tato omezení jsou vymáhána mechanicky:

// 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([]);
  });
});

Strukturální testy validují shodu a zabraňují porušení modulárního vrstvení. Nejedná se o doporučení – je to vynucováno CI. Každý pull request, ať už vytvořený člověkem nebo agentem, musí těmito testy projít.

Princip 4: Automatizovaný Garbage Collection

I se zlatými principy a strukturálním vymáháním kód generovaný agenty v průběhu času driftuje. Tým OpenAI to vyřešil implementací automatizovaného garbage collection – opakujících se úloh na pozadí, které:

1. Skenují odchylky od zlatých principů v celé codebase.
2. Aktualizují hodnocení kvality pro každý modul na základě skóre shody.
3. Otevírají cílené refaktoringové pull requests, které opravují specifické kategorie driftu.

To nahradilo manuální "páteční úklid" systémem, který běží nepřetržitě. Samotný garbage collector je poháněn agenty Codex, což vytváří smyčku s vlastní údržbou. Zdroj

# .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: Spustitelné plány

Předtím, než agenti píší kód, píší plány. Tyto plány nejsou neformální poznámky – jsou to strukturované, spustitelné dokumenty, které specifikují:

• Cíl (Objective): Čeho úkol dosahuje.
• Soubory k úpravě: Explicitní seznam souborů, kterých se agent dotkne.
• Závislosti: Jiné úkoly nebo moduly, na kterých tato práce závisí.
• Akceptační kritéria: Jak ověřit, že je práce hotová.
• Omezení (Constraints): Architektonická pravidla, která nesmí být poruš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

Plány žijí v repozitáři jako markdown soubory, jsou verzovány a mohou být před provedením zkontrolovány – což lidem dává kontrolní bod mezi záměrem a implementací.

Část 4: Codex Agent Loop

Pochopení toho, jak Codex agent loop funguje v rámci harnessu, je nezbytné pro efektivní harness engineering.

Architektura smyčky (Loop Architecture)

OpenAI zveřejnila podrobný rozbor Codex agent loop ve svém doprovodném příspěvku na blogu „Unrolling the Codex agent loop“. Zdroj Smyčka sleduje tento cyklus:

Read Context → Plan → Execute → Validate → Commit (or Retry)

Každá iterace:

1. Read Context (Čtení kontextu): Agent čte relevantní soubory, dokumentaci, schémata a plán úkolů z repozitáře.
2. Plan (Plánování): Na základě kontextu agent určí, jaké změny provede.
3. Execute (Provedení): Agent píše nebo upravuje kód.
4. Validate (Validace): Harness spustí testy, lintery a strukturální kontroly proti provedeným změnám.
5. Commit or Retry (Potvrzení nebo opakování): Pokud validace projde, agent provede commit. Pokud selže, agent si přečte chybový výstup a zkusí to znovu.

Roli harnessu je učinit kroky 1 a 4 co nejbohatšími na informace. Čím více kontextu agent přečte, tím lepší je jeho plán. Čím specifičtější je zpětná vazba z validace, tím rychleji dospěje k funkčnímu řešení.

App Server Harness

Ve svém příspěvku „Unlocking the Codex harness: how we built the App Server“ OpenAI popisuje konkrétní infrastrukturu, která pohání agent loop. Zdroj App Server poskytuje:

• Sandboxovaná prostředí pro spouštění pro každý úkol agenta.
• Předkonfigurovaný přístup k nástrojům (souborový systém, terminál, prohlížeč).
• Automatické vkládání kontextu z artefaktů repozitáře.
• Streamovanou zpětnou vazbu z validace, aby agenti viděli selhání testů v reálném čase.

Část 5: Aplikace Harness Engineering ve vašem týmu

Jak začít: Minimální životaschopný Harness (MVH)

Nemusíte replikovat celou infrastrukturu OpenAI, abyste mohli těžit z harness engineering. Začněte s těmito základními prvky:

Krok 1: Vytvořte ARCHITECTURE.md

Zdokumentujte architektonická pravidla svého projektu v strojově čitelném formátu v kořenovém adresáři repozitáře. Zahrňte:

• Hranice modulů a povolené závislosti.
• Konvence pojmenování.
• Pravidla organizace souborů.
• Požadavky na testování.

Tento jediný soubor dramaticky zlepšuje kvalitu výstupu agentů, protože si ho agenti přečtou před provedením změn.

Krok 2: Přidejte strukturální testy

Napište testy, které validují vaše architektonická pravidla. Tyto testy nekontrolují byznys logiku – kontrolují, zda je kód správně organizován:

// 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);
  }
});

Krok 3: Konfigurace validace CI

Zajistěte, aby vaše CI pipeline spouštěla strukturální testy, lintery a typové kontroly při každém pull requestu – včetně těch vytvořených agenty. Agent by měl vidět stejný výstup validace, jaký by viděl lidský vývojář.

Krok 4: Pište plány úkolů před spuštěním agenta

Předtím, než požádáte agenta o implementaci funkce, napište strukturovaný dokument plánu, který specifikuje soubory k úpravě, omezení, která je třeba dodržet, a akceptační kritéria. Tyto plány ukládejte do repozitáře.

Krok 5: Nastavte automatizovaný úklid

Implementujte týdenní nebo noční CI úlohu, která skenuje vaši codebase na odchylky od zdokumentovaných standardů a vytváří zaměřené refaktoringové PR.

Výběr vašeho agentního systému

Principy harness engineering platí bez ohledu na to, kterého agenta používáte:

Harness žije ve vašem repozitáři, nikoli ve vašem agentovi. To znamená, že můžete měnit agenty, aniž byste přišli o investici do harnessu.

Škálování z jednoho agenta na mnoho

Experiment OpenAI ukázal, že harness engineering umožňuje paralelní spouštění agentů. Protože harness vynucuje architektonické hranice, může více agentů pracovat na různých částech codebase současně bez vytváření konfliktů.

Klíčové požadavky pro paralelní spouštění agentů:

1. Jasné vlastnictví modulů – každý agent pracuje v definované hranici.
2. Typovaná rozhraní mezi moduly – agenti mohou psát kód proti rozhraním, aniž by znali detaily implementace.
3. Prevence konfliktů při slučování – úkoly jsou vymezeny tak, aby se minimalizovalo překrývání souborů.
4. Centralizovaná validace – všichni agenti odesílají do stejné CI pipeline.

Část 6: Časté chyby a anti-vzory

Anti-vzor 1: Považování agenta za harness

Agent není harness. Harness je prostředí, ve kterém agent operuje. Žádat chytřejší model, aby kompenzoval špatně strukturovaný repozitář, je špatný přístup. Opravte prostředí, ne prompt.

Anti-vzor 2: Dokumentace na špatném místě

Pokud vaše architektonická rozhodnutí žijí v Confluence, Notion nebo Google Docs, agenti je nevidí. Náprava je jednoduchá, ale vyžaduje disciplínu: přesuňte veškerou dokumentaci relevantní pro vývoj do repozitáře.

Anti-vzor 3: Manuální úklid místo automatizovaného vymáhání

Pokud trávíte značné množství času čištěním kódu generovaného agenty, potřebujete lepší vymáhání, nikoli více úklidových sezení. Každý opakující se úkol úklidu by se měl stát buď pravidlem linteru, strukturálním testem, nebo automatizovanou refaktoringovou úlohou.

Anti-vzor 4: Nadměrné omezování

Harness, který je příliš rigidní, brání agentům v hledání kreativních řešení. Cílem je omezit architekturu, nikoli implementaci. Řekněte agentům, které moduly mohou upravovat a které závislosti jsou povoleny, ale nechte je rozhodnout, jak implementovat logiku uvnitř těchto hranic.

Anti-vzor 5: Ignorování zpětné vazby od agenta

Když agent opakovaně selhává u určitých úkolů, selhání obvykle ukazuje na mezeru v harnessu, nikoli na omezení agenta. Sledujte vzorce selhání a používejte je ke zlepšení dokumentace, strukturálních testů nebo architektonických omezení.

Část 7: Budoucnost Harness Engineering

Pohled Martina Fowlera

Martin Fowler publikoval analýzu harness engineering na svém blogu, kde poznamenal, že to představuje zásadní posun v tom, jak softwarové týmy fungují. Tato disciplína si vypůjčuje z desetiletí osvědčených postupů softwarového inženýrství – kontinuální integrace, záznamy o architektonických rozhodnutích (ADR), dependency injection – ale mění jejich účel pro svět řízený agenty. Zdroj

Rámec HumanLayer

Tým z HumanLayer zveřejnil svou analýzu, v níž označil harness engineering za „problém dovedností“ (skill issue) – argumentují tím, že schopnost navrhovat efektivní harnessy se stane primárním rozlišovacím znakem mezi vysoce výkonnými a strádajícími inženýrskými týmy. Zdroj

Co to znamená pro vývojáře

Harness engineering nenahrazuje dovednosti vývojáře – pouze je přesměrovává. Místo psaní kódu navrhují seniorní inženýři systémy, které umožňují agentům psát kód kvalitně. Dovednosti, na kterých záleží, se přesouvají od implementace k architektuře, od kódování k systémovému designu, od psaní testů k navrhování testovacích frameworků.

Pro týmy budující aplikace již platformy jako ZBuild začleňují principy harness engineering do svých workflow pro tvorbu aplikací. Místo toho, aby po vývojářích vyžadoval navrhování vlastních harnessů od nuly, poskytuje ZBuild předkonfigurované architektonické vzory, správu závislostí a validační systémy, které vedou AI agenty ke kvalitnímu výstupu – což vývojářům umožňuje soustředit se na produktová rozhodnutí spíše než na infrastrukturu.

Tři horizonty

Při pohledu do budoucna se harness engineering pravděpodobně vyvine ve třech fázích:

1. Krátkodobý horizont (2026): Týmy adoptují dokumentaci prioritně v repozitáři, strukturální testy a zlaté principy. Vývoj asistovaný agenty se stává standardní praxí pro projekty s dobrým harnessem.

2. Střednědobý horizont (2027): Samotné generování harnessu se stává řízeným agenty. Agenti analyzují existující codebase a navrhují konfigurace harnessu – pravidla linteru, strukturální testy, hranice závislostí – na základě vzorců, které pozorují.

3. Dlouhodobý horizont (2028+): Harnessy se stávají adaptivními. Místo statických pravidel se vyvíjejí na základě výsledků kódu generovaného agenty, přičemž automaticky zpřísňují omezení v oblastech, kde agenti často chybují, a uvolňují je tam, kde trvale uspívají.

Část 8: Praktický kontrolní seznam

Použijte tento kontrolní seznam k vyhodnocení vyspělosti harness engineering ve vašem týmu:

Základy (Začněte zde)

• ARCHITECTURE.md existuje v kořenovém adresáři repozitáře.
• Formátování kódu je automatizované (Prettier, Black, gofmt).
• Linting běží při každém pull requestu.
• Typová kontrola je vynucena (TypeScript strict, mypy, atd.).

Pokročilé

• Strukturální testy validují hranice závislostí.
• Zlaté principy jsou dokumentovány a strojově vynutitelné.
• Plány úkolů jsou psány před spuštěním agenta.
• PR generované agenty procházejí stejnou CI jako PR od lidí.

Expert

• Automatizovaný garbage collection běží podle plánu.
• Více agentů může pracovat paralelně bez konfliktů.
• Vzorce selhání agentů jsou sledovány a využívány ke zlepšení harnessu.
• Samotný harness je verzován a revidován jako kód.

Mistr

• Agenti generují části harnessu (pravidla linteru, strukturální testy).
• Hodnocení kvality jsou automaticky přiřazována každému modulu.
• Zlepšení harnessu jsou řízena daty na základě úspěšnosti agentů.
• Tým dodává více kódu na inženýra týdně než před adopcí agentů.

Závěr

Harness engineering není módní výstřelek. Je to přirozený vývoj softwarového inženýrství v éře, kdy AI agenti jsou schopni psát produkční kód, ale potřebují strukturovaná prostředí, aby to dělali dobře. Experiment OpenAI s 1 000 000 řádky kódu prokázal tento koncept v měřítku a principy, které formulovali – znalosti v repozitáři, zlaté principy, vrstvená architektura, automatizovaný garbage collection a spustitelné plány – jsou použitelné pro týmy jakékoli velikosti.

Týmy, které ovládnou harness engineering v roce 2026, budou dodávat kód rychleji, udržovat vyšší kvalitu kódu a škálovat efektivněji než ty, které považují AI agenty za pouhé vylepšené doplňování kódu. Agent je kůň. Harness je to, co ho činí užitečným.

Zdroje

• Harness Engineering: Využití Codexu ve světě zaměřeném na agenty — OpenAI
• Odemknutí Codex Harness: Jak jsme postavili App Server — OpenAI
• Rozbalení Codex Agent Loop — OpenAI
• OpenAI představuje Harness Engineering — InfoQ
• Harness Engineering — Martin Fowler
• Problém dovedností: Harness Engineering pro kódovací agenty — HumanLayer
• Od Prompt Engineering k Harness Engineering — SoftmaxData
• Jak postavit Agent Harness — Studijní poznámky
• Harness Engineering — GTCode
• OpenAI Harness Engineering: Dodání 1M řádků kódu — The Neuron
• Jak OpenAI vybudovala 1M řádků kódu pouze s agenty — TonyLee
• Harness Engineering — nová disciplína — CodeNote