Wat je zult leren

Deze gids behandelt Harness Engineering van basisprincipes tot praktische implementatie. Je zult begrijpen wat het is, waarom OpenAI hun grootste interne project hierop heeft ingezet, de specifieke architecturale patronen die het laten werken, en hoe je deze principes kunt toepassen op je eigen AI agent workflows — of je nu Codex, Claude Code, OpenCode of een ander agent-systeem gebruikt.

Harness Engineering: De volledige gids voor AI agent-ontwikkeling in 2026

Als 2025 het jaar was waarin AI agents bewezen dat ze code konden schrijven, dan is 2026 het jaar waarin we leerden dat de agent niet het moeilijke deel is — de harness is dat.

Het Codex-team van OpenAI publiceerde in februari 2026 een baanbrekende blogpost waarin werd beschreven hoe ze een productie-applicatie bouwden met ongeveer één miljoen regels code, waarvan nul regels door menselijke handen waren geschreven. Het geheim was niet een beter model of een slimmere prompt. Het was het systeem dat ze rond de agent bouwden — de harness. Bron

Deze gids analyseert elk principe, patroon en praktische techniek van dat experiment en de bredere Harness Engineering-beweging die daaruit is voortgekomen.

Deel 1: Wat is Harness Engineering?

De definitie

Harness Engineering is de discipline van het ontwerpen van de gehele omgeving — scaffolding, feedback loops, documentatie, architecturale beperkingen en machine-leesbare artefacten — die AI coding agents in staat stelt om betrouwbaar en kwalitatief hoogstaand werk op schaal te leveren met minimale menselijke tussenkomst.

De term "harness" komt van de tuigage van een paard: teugels, zadel, bit — de complete set uitrusting om een krachtig maar onvoorspelbaar dier in de juiste richting te sturen. Een ongecontroleerd paard is gevaarlijk. Een paard in een harnas (harness) bouwde beschavingen. Hetzelfde geldt voor AI agents. Bron

Waarom het nu is ontstaan

De verschuiving van Prompt Engineering naar Harness Engineering weerspiegelt een rijping van het AI-ontwikkelingslandschap:

Bron

Het belangrijkste inzicht dat deze transitie dreef: agents werden capabel genoeg zodat de bottleneck verschoof van modelkwaliteit naar omgevingskwaliteit. Een state-of-the-art model dat werkt in een slecht gestructureerde repository levert slechtere resultaten op dan een middelmatig model dat werkt in een goed uitgeruste harness-omgeving.

Deel 2: Het OpenAI Codex experiment

De schaal

In een intern experiment van vijf maanden bouwden en lanceerden technici van OpenAI een bèta-product met ongeveer één miljoen regels code. De repository omvat applicatielogica, infrastructuur, tooling, documentatie en interne hulpprogramma's voor ontwikkelaars. Er was geen vooraf bestaande, door mensen geschreven code om het systeem te verankeren. Bron

Het team

Het project begon met slechts drie technici die Codex aanstuurden. Gedurende de periode van vijf maanden werden ongeveer 1.500 pull requests geopend en samengevoegd. Naarmate het team groeide naar zeven technici, nam de doorvoer toe — een contra-intuïtief resultaat dat suggereerde dat de harness zelf de primaire productiviteitsvermenigvuldiger was, niet individuele vaardigheid.

OpenAI schat dat ze het systeem hebben gebouwd in ongeveer een tiende van de tijd die het zou hebben gekost om de code met de hand te schrijven. Bron

De initiële scaffold

Het project begon met Codex CLI die de initiële scaffold genereerde met behulp van GPT-5, geleid door een kleine set bestaande templates:

• Repository-structuur en directory-conventies
• CI/CD-configuratie
• Code-formattering en linting-regels
• Instellingen voor de package manager
• Applicatie-framework boilerplate

Vanuit dit zaadje groeide al het andere door agent-gestuurde ontwikkeling.

Het vrijdag-probleem

Vroeg in het experiment ontdekte het team een kritiek probleem: ze besteedden elke vrijdag — 20% van hun technische tijd — aan het opruimen van wat ze "AI slop" noemden. Dit omvatte inconsistente patronen, gedupliceerde logica, verkeerd benoemde variabelen en architecturale afwijkingen.

Dat was niet schaalbaar. De oplossing was om hun standaarden in de harness zelf te coderen, zodat de agents vanaf het begin schonere output zouden produceren, en om geautomatiseerde opruimsystemen te bouwen voor de resterende afwijkingen.

Deel 3: De vijf kernprincipes

Principe 1: Repository-First kennis

Vanuit het perspectief van de agent bestaat alles wat hij niet in-context kan openen tijdens het draaien effectief niet. Kennis die leeft in Google Docs, chat-threads, Slack-berichten of in de hoofden van mensen is onzichtbaar voor het systeem.

Dit betekent dat alle kennis moet leven als repository-lokale, geversioneerde artefacten:

• Code — het primaire artefact
• Markdown-documentatie — architectuurbeslissingen, conventies, onboarding-handleidingen
• Schemas — API-contracten, database-schemas, type-definities
• Uitvoerbare plannen — stapsgewijze taakverdelingen die de agent kan volgen
• Configuratie — linter-regels, CI-pipelines, formattingsstandaarden

Het team leerde dat ze in de loop van de tijd steeds meer context naar de repo moesten pushen. Elke keer dat een agent een fout maakte omdat hij context miste, was de oplossing niet een betere prompt — het was het toevoegen van die context aan de repository. Bron

Praktische implementatie:

# 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

Principe 2: Golden Principles

Golden Principles zijn uitgesproken, mechanische regels die direct in de repository zijn gecodeerd en de codebase leesbaar en consistent houden voor toekomstige agent-sessies. Het zijn geen vrijblijvende richtlijnen — het zijn afgedwongen beperkingen.

Voorbeelden uit het OpenAI-experiment:

1. Geef de voorkeur aan gedeelde utility-packages boven zelfgeschreven helpers — centraliseert invarianten zodat wanneer gedrag moet veranderen, dit op één plek gebeurt
2. Sondeer data niet op een YOLO-manier — valideer grenzen of vertrouw op getypeerde SDKs zodat agents niet per ongeluk voortbouwen op geraden datastructuren
3. Eén concept, één bestand — elk bestand moet een enkel concept vertegenwoordigen, waardoor het voor agents gemakkelijker wordt om de juiste locatie te vinden en aan te passen
4. Expliciet boven impliciet — vermijd magisch gedrag waarvoor een agent informele kennis nodig zou hebben om het te begrijpen

Bron

Deze principes zijn niet alleen documentatie. Ze worden afgedwongen door:

• Linter-regels — aangepaste linters (die zelf door Codex zijn gegenereerd) die overtredingen markeren
• Structurele tests — tests die architecturale naleving valideren
• CI-gates — pull requests die Golden Principles schenden, worden automatisch geweigerd

Principe 3: Gelaagde architectuur met mechanische handhaving

Elk zakelijk domein in het OpenAI-project is onderverdeeld in een vaste set lagen met strikt gevalideerde afhankelijkheidsrichtingen:

Types → Config → Repo → Service → Runtime → UI

Afhankelijkheden stromen slechts in één richting. Een UI-component kan afhankelijk zijn van Runtime en Service, maar een Service mag nooit importeren uit UI. Een Repo kan afhankelijk zijn van Config en Types, maar nooit van Service. Bron

Deze beperkingen worden mechanisch afgedwongen:

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

De structurele tests valideren de naleving en voorkomen schendingen van modulaire gelaagdheid. Dit is geen suggestie — het wordt afgedwongen door CI. Elke pull request, of deze nu door een mens of een agent is gemaakt, moet deze tests doorstaan.

Principe 4: Geautomatiseerde garbage collection

Zelfs met Golden Principles en structurele handhaving wijkt door agents gegenereerde code in de loop van de tijd af. Het OpenAI-team loste dit op door geautomatiseerde garbage collection te implementeren — terugkerende achtergrondtaken die:

1. Scannen op afwijkingen van Golden Principles in de gehele codebase
2. Kwaliteitscijfers bijwerken voor elke module op basis van nalevingsscores
3. Gerichte refactoring pull requests openen die specifieke categorieën van afwijkingen herstellen

Dit verving de handmatige "vrijdag-opruiming" door een systeem dat continu draait. De garbage collector zelf wordt aangedreven door Codex-agents, waardoor een zelfonderhoudende lus ontstaat. Bron

# .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

Principe 5: Uitvoerbare plannen

Voordat agents code schrijven, schrijven ze plannen. Deze plannen zijn geen informele notities — het zijn gestructureerde, uitvoerbare documenten die het volgende specificeren:

• Doelstelling: Wat de taak bereikt
• Te wijzigen bestanden: Expliciete lijst van bestanden die de agent zal aanraken
• Afhankelijkheden: Andere taken of modules waarvan dit werk afhankelijk is
• Acceptatiecriteria: Hoe te verifiëren dat het werk voltooid is
• Beperkingen: Architecturale regels die niet mogen worden geschonden

# 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

Plannen leven in de repository als markdown-bestanden, zijn onderhevig aan versiebeheer en kunnen voor uitvoering worden beoordeeld — wat mensen een controlepunt geeft tussen intentie en implementatie.

Deel 4: De Codex agent loop

Begrijpen hoe de Codex agent loop werkt binnen een harness is essentieel voor effectieve Harness Engineering.

De loop-architectuur

OpenAI publiceerde een gedetailleerde analyse van de Codex agent loop in hun begeleidende blogpost "Unrolling the Codex agent loop." Bron De loop volgt deze cyclus:

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

Elke iteratie:

1. Context lezen: De agent leest relevante bestanden, documentatie, schemas en het taakplan uit de repository
2. Plannen: Op basis van de context bepaalt de agent welke wijzigingen hij moet aanbrengen
3. Uitvoeren: De agent schrijft of wijzigt code
4. Valideren: De harness voert tests, linters en structurele controles uit op de wijzigingen
5. Commit of Retry: Als de validatie slaagt, commit de agent. Als het mislukt, leest de agent de foutmelding en probeert het opnieuw.

De rol van de harness is om stappen 1 en 4 zo informatierijk mogelijk te maken. Hoe meer context de agent leest, hoe beter zijn plan. Hoe specifieker de validatiefeedback, hoe sneller hij convergeert naar een werkende oplossing.

De App Server harness

In hun post "Unlocking the Codex harness: how we built the App Server," beschrijft OpenAI de concrete infrastructuur die de agent loop aandrijft. Bron De App Server biedt:

• Sandbox-omgevingen voor elke agent-taak
• Geconfigureerde toegang tot tools (bestandssysteem, terminal, browser)
• Automatische context-injectie vanuit repository-artefacten
• Streaming validatiefeedback zodat agents testfouten in real-time kunnen zien

Deel 5: Harness Engineering toepassen op je team

Aan de slag: De Minimum Viable Harness

Je hoeft niet de volledige infrastructuur van OpenAI te kopiëren om te profiteren van Harness Engineering. Begin met deze fundamentele elementen:

Stap 1: Maak een ARCHITECTURE.md

Documenteer de architecturale regels van je project in een machine-leesbaar formaat in de root van je repository. Voeg toe:

• Modulegrenzen en toegestane afhankelijkheden
• Naamgevingsconventies
• Regels voor bestandsorganisatie
• Testvereisten

Dit enkele bestand verbetert de kwaliteit van de agent-output aanzienlijk omdat agents het lezen voordat ze wijzigingen aanbrengen.

Stap 2: Voeg structurele tests toe

Schrijf tests die je architecturale regels valideren. Deze tests controleren geen zakelijke logica — ze controleren of de code correct is georganiseerd:

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

Stap 3: Configureer CI-validatie

Zorg ervoor dat je CI-pipeline structurele tests, linters en type-controles uitvoert bij elke pull request — inclusief die gemaakt door agents. De agent moet dezelfde validatie-output zien als een menselijke ontwikkelaar.

Stap 4: Schrijf taakplannen vóór agent-uitvoering

Voordat je een agent vraagt om een functie te implementeren, schrijf je een gestructureerd plandocument dat de te wijzigen bestanden, de te volgen beperkingen en de acceptatiecriteria specificeert. Sla deze plannen op in je repository.

Stap 5: Zet geautomatiseerde opruiming op

Implementeer een wekelijkse of nachtelijke CI-job die je codebase scant op afwijkingen van je gedocumenteerde standaarden en gerichte refactoring PRs aanmaakt.

Je agent-systeem kiezen

Harness Engineering-principes zijn van toepassing ongeacht welke agent je gebruikt:

De harness leeft in je repository, niet in je agent. Dit betekent dat je van agent kunt wisselen zonder je investering in de harness te verliezen.

Opschalen van één agent naar vele

Het OpenAI-experiment toonde aan dat Harness Engineering parallelle agent-uitvoering mogelijk maakt. Omdat de harness architecturale grenzen afdwingt, kunnen meerdere agents tegelijkertijd aan verschillende delen van de codebase werken zonder conflicten te veroorzaken.

Belangrijkste vereisten voor parallelle agent-uitvoering:

1. Duidelijk module-eigenaarschap — elke agent werkt binnen een gedefinieerde grens
2. Getypeerde interfaces tussen modules — agents kunnen code schrijven tegen interfaces zonder implementatiedetails te kennen
3. Voorkomen van merge-conflicten — taken zijn zo afgebakend dat overlap in bestanden minimaal is
4. Gecentraliseerde validatie — alle agents dienen in bij dezelfde CI-pipeline

Deel 6: Veelvoorkomende valkuilen en anti-patronen

Anti-patroon 1: De agent behandelen als de harness

De agent is niet de harness. De harness is de omgeving waarin de agent werkt. Een slimmer model vragen om te compenseren voor een slecht gestructureerde repository is de verkeerde aanpak. Herstel de omgeving, niet de prompt.

Anti-patroon 2: Documentatie op de verkeerde plek

Als je architectuurbeslissingen in Confluence, Notion of Google Docs staan, kunnen agents ze niet zien. De oplossing is simpel maar vereist discipline: verplaats alle ontwikkelingsrelevante documentatie naar de repository.

Anti-patroon 3: Handmatige opruiming in plaats van geautomatiseerde handhaving

Als je veel tijd besteedt aan het opruimen van door agents gegenereerde code, heb je betere handhaving nodig, niet meer opruimsessies. Elke terugkerende opruimtaak moet een linter-regel, een structurele test of een geautomatiseerde refactoring-job worden.

Anti-patroon 4: Te veel beperkingen opleggen

Een harness die te rigide is, voorkomt dat agents creatieve oplossingen vinden. Het doel is om de architectuur te beperken, niet de implementatie. Vertel agents welke modules ze mogen wijzigen en welke afhankelijkheden zijn toegestaan, maar laat hen beslissen hoe de logica binnen die grenzen wordt geïmplementeerd.

Anti-patroon 5: Feedback van agents negeren

Wanneer een agent herhaaldelijk faalt bij bepaalde taken, duidt de fout meestal op een gat in de harness, niet op een beperking van de agent. Houd foutpatronen bij en gebruik ze om je documentatie, structurele tests of architecturale beperkingen te verbeteren.

Deel 7: De toekomst van Harness Engineering

Het perspectief van Martin Fowler

Martin Fowler publiceerde een analyse van Harness Engineering op zijn blog en merkte op dat het een fundamentele verschuiving vertegenwoordigt in de manier waarop softwareteams werken. De discipline leent van decennia aan best practices in software engineering — continuous integration, architecture decision records, dependency injection — maar hergebruikt ze voor een agent-gestuurde wereld. Bron

Het HumanLayer-framework

Het team van HumanLayer publiceerde hun analyse waarin ze Harness Engineering een "skill issue" noemen — ze stellen dat het vermogen om effectieve harnesses te ontwerpen de belangrijkste differentiator zal worden tussen hoogpresterende en worstelende technische teams. Bron

Wat dit betekent voor ontwikkelaars

Harness Engineering vervangt de vaardigheden van de ontwikkelaar niet — het verlegt ze. In plaats van code te schrijven, ontwerpen senior engineers de systemen die agents in staat stellen om code goed te schrijven. De vaardigheden die ertoe doen verschuiven van implementatie naar architectuur, van coderen naar systeemontwerp, van het schrijven van tests naar het ontwerpen van testframeworks.

Voor teams die applicaties bouwen, integreren platforms zoals ZBuild al Harness Engineering-principes in hun workflows voor app-bouwers. In plaats van dat ontwikkelaars hun eigen harnesses vanaf nul moeten ontwerpen, biedt ZBuild vooraf geconfigureerde architecturale patronen, afhankelijkheidsbeheer en validatiesystemen die AI agents naar hoogwaardige output leiden — waardoor ontwikkelaars zich kunnen concentreren op productbeslissingen in plaats van op infrastructuur.

De drie horizons

Vooruitkijkend zal Harness Engineering waarschijnlijk evolueren via drie fasen:

1. Korte termijn (2026): Teams omarmen repository-first documentatie, structurele tests en Golden Principles. Agent-ondersteunde ontwikkeling wordt de standaardpraktijk voor projecten met een goede harness.

2. Middellange termijn (2027): Het genereren van de harness zelf wordt agent-gestuurd. Agents analyseren bestaande codebases en stellen harness-configuraties voor — linter-regels, structurele tests, afhankelijkheidsgrenzen — op basis van de patronen die ze waarnemen.

3. Lange termijn (2028+): Harnesses worden adaptief. In plaats van statische regels evolueren ze op basis van de resultaten van door agents gegenereerde code, waarbij beperkingen automatisch worden aangescherpt in gebieden waar agents vaak fouten maken en versoepeld waar ze consequent slagen.

Deel 8: Praktische checklist

Gebruik deze checklist om de volwassenheid van de Harness Engineering van je team te evalueren:

Basis (Begin hier)

• ARCHITECTURE.md bestaat in de root van de repository
• Code-formattering is geautomatiseerd (Prettier, Black, gofmt)
• Linting draait op elke pull request
• Type-checking wordt afgedwongen (TypeScript strict, mypy, etc.)

Gemiddeld

• Structurele tests valideren afhankelijkheidsgrenzen
• Golden Principles zijn gedocumenteerd en machine-afdwingbaar
• Taakplannen worden geschreven vóór agent-uitvoering
• Door agents gegenereerde PRs doorlopen dezelfde CI als menselijke PRs

Geavanceerd

• Geautomatiseerde garbage collection draait volgens een schema
• Meerdere agents kunnen parallel werken zonder conflicten
• Foutpatronen van agents worden bijgehouden en gebruikt om de harness te verbeteren
• De harness zelf is onderhevig aan versiebeheer en wordt beoordeeld als code

Expert

• Agents genereren delen van de harness (linter-regels, structurele tests)
• Kwaliteitscijfers worden automatisch toegewezen aan elke module
• Verbeteringen aan de harness zijn datagestuurd op basis van succespercentages van agents
• Het team levert per technicus per week meer code op dan vóór het adopteren van agents

Conclusie

Harness Engineering is geen hype. Het is de natuurlijke evolutie van software engineering in een tijdperk waarin AI agents capabel genoeg zijn om productiecode te schrijven, maar gestructureerde omgevingen nodig hebben om dit goed te doen. Het experiment van OpenAI met een miljoen regels bewees het concept op schaal, en de principes die zij formuleerden — repository-first kennis, Golden Principles, gelaagde architectuur, geautomatiseerde garbage collection en uitvoerbare plannen — zijn toepasbaar op teams van elke omvang.

De teams die Harness Engineering in 2026 onder de knie krijgen, zullen sneller leveren, een hogere codekwaliteit handhaven en effectiever schalen dan teams die AI agents behandelen als een veredelde autocomplete. De agent is het paard. De harness is wat het nuttig maakt.

Bronnen

• 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 — De nieuwe discipline — CodeNote