Ce vei învăța

Acest ghid acoperă harness engineering de la principii fundamentale până la implementarea practică. Vei înțelege ce este, de ce OpenAI și-a pariat cel mai mare proiect intern pe acesta, modelele arhitecturale specifice care îl fac să funcționeze și cum să aplici aceste principii propriilor fluxuri de lucru pentru agenți AI — indiferent dacă folosești Codex, Claude Code, OpenCode sau orice alt sistem de agenți.

Harness Engineering: Ghidul complet pentru dezvoltarea agenților AI în 2026

Dacă 2025 a fost anul în care agenții AI au demonstrat că pot scrie cod, 2026 este anul în care am învățat că agentul nu este partea dificilă — harness-ul este.

Echipa Codex de la OpenAI a publicat o postare de referință pe blog în Februarie 2026, descriind cum au construit o aplicație de producție conținând aproximativ un milion de linii de cod, unde zero linii au fost scrise de mâini umane. Secretul nu a fost un model mai bun sau un prompt mai inteligent. A fost sistemul pe care l-au construit în jurul agentului — harness-ul. Sursă

Acest ghid detaliază fiecare principiu, model și tehnică practică din acel experiment și din mișcarea mai amplă de harness engineering care a apărut în jurul acestuia.

Partea 1: Ce este Harness Engineering?

Definiția

Harness engineering este disciplina proiectării întregului mediu — schele (scaffolding), bucle de feedback, documentație, constrângeri arhitecturale și artefacte care pot fi citite de mașină — care permite agenților de coding AI să realizeze o muncă fiabilă și de înaltă calitate la scară largă, cu intervenție umană minimă.

Termenul „harness” (ham) provine de la harnașamentul cailor: frâu, șa, zăbală — setul complet de echipamente pentru a direcționa un animal puternic, dar imprevizibil, în direcția corectă. Un cal necontrolat este periculos. Un cal înhămat a construit civilizații. Același lucru este valabil și pentru agenții AI. Sursă

De ce a apărut acum

Trecerea de la prompt engineering la harness engineering reflectă o maturizare a peisajului dezvoltării AI:

Sursă

Perspectiva cheie care a condus această tranziție: agenții au devenit suficient de capabili încât blocajul s-a mutat de la calitatea modelului la calitatea mediului. Un model de ultimă generație care operează într-un repository slab structurat produce rezultate mai slabe decât un model mediocrul care operează într-un mediu bine echipat cu un harness.

Partea 2: Experimentul OpenAI Codex

Scara

Într-un experiment intern de cinci luni, inginerii OpenAI au construit și lansat un produs beta conținând aproximativ un milion de linii de cod. Repository-ul cuprinde logica aplicației, infrastructura, tooling, documentația și utilitarele interne pentru dezvoltatori. Nu a existat cod preexistent scris de oameni pentru a ancora sistemul. Sursă

Echipa

Proiectul a început cu doar trei ingineri care coordonau Codex. Pe parcursul perioadei de cinci luni, aproximativ 1.500 de pull requests au fost deschise și îmbinate. Pe măsură ce echipa a crescut la șapte ingineri, productivitatea a crescut — un rezultat contraintuitiv care a sugerat că harness-ul în sine a fost principalul multiplicator de productivitate, nu abilitatea individuală.

OpenAI estimează că au construit sistemul în aproximativ o zecime din timpul care ar fi fost necesar pentru a scrie codul manual. Sursă

Schela inițială

Proiectul a început cu Codex CLI generând schela (scaffold) inițială folosind GPT-5, ghidat de un set mic de șabloane existente:

• Structura repository-ului și convențiile de directoare
• Configurația CI/CD
• Regulile de formatare a codului și linting
• Configurarea managerului de pachete
• Boilerplate-ul framework-ului aplicației

Din această sămânță, tot restul a crescut prin dezvoltare condusă de agenți.

Problema de vineri

La începutul experimentului, echipa a descoperit o problemă critică: petreceau fiecare zi de vineri — 20% din timpul lor de inginerie — curățând ceea ce ei au numit „slop AI”. Aceasta includea tipare inconsistente, logică duplicată, variabile denumite greșit și derivă arhitecturală.

Acest lucru nu era scalabil. Soluția a fost codificarea standardelor lor chiar în harness, astfel încât agenții să producă output-uri mai curate de la început, și construirea unor sisteme automate de curățare pentru deriva reziduală.

Partea 3: Cele cinci principii de bază

Principiul 1: Cunoștințe centrate pe Repository

Din perspectiva agentului, orice nu poate accesa în context în timp ce rulează, practic nu există. Cunoștințele care trăiesc în Google Docs, fire de discuție, mesaje Slack sau în mintea oamenilor sunt invizibile pentru sistem.

Acest lucru înseamnă că toate cunoștințele trebuie să trăiască ca artefacte locale în repository, versionate:

• Cod — artefactul principal
• Documentație Markdown — decizii de arhitectură, convenții, ghiduri de integrare
• Scheme — contracte API, scheme de baze de date, definiții de tipuri
• Planuri executabile — defalcări pas cu pas ale sarcinilor pe care agentul le poate urma
• Configurare — reguli linter, pipeline-uri CI, standarde de formatare

Echipa a învățat că trebuie să introducă tot mai mult context în repo de-a lungul timpului. De fiecare dată când un agent făcea o greșeală pentru că îi lipsea contextul, soluția nu era un prompt mai bun — ci adăugarea acelui context în repository. Sursă

Implementare practică:

# 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

Principiul 2: Principii de Aur (Golden Principles)

Principiile de aur sunt reguli de opinie, mecanice, codificate direct în repository, care mențin baza de cod lizibilă și consistentă pentru viitoarele rulări ale agenților. Ele nu sunt linii directoare aspiraționale — sunt constrângeri impuse.

Exemple din experimentul OpenAI:

1. Preferă pachetele de utilitare partajate în locul helper-elor create manual — centralizează invarianții astfel încât, atunci când comportamentul trebuie să se schimbe, să se schimbe într-un singur loc
2. Nu sonda datele în stil YOLO — validează limitele sau bazează-te pe SDK-uri tipizate, astfel încât agenții să nu poată construi accidental pe forme de date ghicite
3. Un concept, un fișier — fiecare fișier ar trebui să reprezinte un singur concept, facilitând găsirea și modificarea locației corecte de către agenți
4. Explicit în loc de implicit — evită comportamentele magice pentru care un agent ar avea nevoie de cunoștințe tribale pentru a le înțelege

Sursă

Aceste principii nu sunt doar documentație. Ele sunt impuse de:

• Reguli Linter — lintere personalizate (ele însele generate de Codex) care semnalează încălcările
• Teste structurale — teste care validează conformitatea arhitecturală
• Porți CI — pull requests care încalcă principiile de aur sunt respinse automat

Principiul 3: Arhitectură stratificată cu impunere mecanică

Fiecare domeniu de business din proiectul OpenAI este împărțit într-un set fix de straturi cu direcții de dependență strict validate:

Types → Config → Repo → Service → Runtime → UI

Dependențele curg într-o singură direcție. Un component UI poate depinde de Runtime și Service, dar un Service nu poate importa niciodată din UI. Un Repo poate depinde de Config și Types, dar niciodată de Service. Sursă

Aceste constrângeri sunt impuse mecanic:

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

Testele structurale validează conformitatea și previn încălcările stratificării modulare. Aceasta nu este o sugestie — este impusă de CI. Fiecare pull request, fie că este creat de un om sau de un agent, trebuie să treacă aceste teste.

Principiul 4: Colectarea automată a gunoiului (Garbage Collection)

Chiar și cu principii de aur și impunere structurală, codul generat de agenți deviază în timp. Echipa OpenAI a rezolvat acest lucru prin implementarea colectării automate a gunoiului — sarcini de fundal recurente care:

1. Scanează abaterile de la principiile de aur în întreaga bază de cod
2. Actualizează notele de calitate pentru fiecare modul pe baza scorurilor de conformitate
3. Deschid pull requests de refactorizare țintite care repară categorii specifice de derivă

Acest lucru a înlocuit „curățenia de vineri” manuală cu un sistem care rulează continuu. Colectorul de gunoi în sine este alimentat de agenți Codex, creând o buclă de auto-întreținere. Sursă

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

Principiul 5: Planuri executabile

Înainte ca agenții să scrie cod, ei scriu planuri. Aceste planuri nu sunt note informale — sunt documente structurate, executabile, care specifică:

• Obiectiv: Ce realizează sarcina
• Fișiere de modificat: Listă explicită de fișiere pe care agentul le va atinge
• Dependențe: Alte sarcini sau module de care depinde această lucrare
• Criterii de acceptare: Cum se verifică faptul că lucrarea este finalizată
• Constrângeri: Reguli arhitecturale care nu trebuie încălcate

# 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

Planurile trăiesc în repository ca fișiere markdown, sunt controlate prin versiuni și pot fi revizuite înainte de execuție — oferind oamenilor un punct de control între intenție și implementare.

Partea 4: Bucla Agentului Codex

Înțelegerea modului în care operează bucla agentului Codex în cadrul unui harness este esențială pentru un harness engineering eficient.

Arhitectura Buclei

OpenAI a publicat o defalcare detaliată a buclei agentului Codex în postarea lor însoțitoare „Unrolling the Codex agent loop”. Sursă Bucla urmează acest ciclu:

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

Fiecare iterație:

1. Citire Context: Agentul citește fișierele relevante, documentația, schemele și planul sarcinii din repository
2. Planificare: Pe baza contextului, agentul determină ce modificări să facă
3. Execuție: Agentul scrie sau modifică codul
4. Validare: Harness-ul rulează teste, lintere și verificări structurale asupra modificărilor
5. Commit sau Reîncercare: Dacă validarea trece, agentul face commit. Dacă eșuează, agentul citește mesajul de eroare și încearcă din nou.

Rolul harness-ului este de a face pașii 1 și 4 cât mai bogați în informații posibil. Cu cât agentul citește mai mult context, cu atât planul său este mai bun. Cu cât feedback-ul de validare este mai specific, cu atât converge mai repede către o soluție funcțională.

App Server Harness

În postarea lor „Unlocking the Codex harness: how we built the App Server”, OpenAI descrie infrastructura concretă care alimentează bucla agentului. Sursă App Server oferă:

• Medii de execuție izolate (sandboxed) pentru fiecare sarcină a agentului
• Acces la instrumente pre-configurate (sistem de fișiere, terminal, browser)
• Injectare automată de context din artefactele repository-ului
• Feedback de validare prin streaming, astfel încât agenții să poată vedea eșecurile testelor în timp real

Partea 5: Aplicarea Harness Engineering în echipa ta

Începerea: Harness-ul Minim Viabil

Nu trebuie să replici întreaga infrastructură OpenAI pentru a beneficia de harness engineering. Începe cu aceste elemente fundamentale:

Pasul 1: Creează un ARCHITECTURE.md

Documentează regulile arhitecturale ale proiectului tău într-un format care poate fi citit de mașină în rădăcina repository-ului tău. Include:

• Limitele modulelor și dependențele permise
• Convenții de denumire
• Reguli de organizare a fișierelor
• Cerințe de testare

Acest singur fișier îmbunătățește dramatic calitatea output-ului agentului, deoarece agenții îl citesc înainte de a face modificări.

Pasul 2: Adaugă teste structurale

Scrie teste care validează regulile arhitecturale. Aceste teste nu verifică logica de business — ele verifică dacă codul este organizat corect:

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

Pasul 3: Configurează validarea CI

Asigură-te că pipeline-ul tău CI rulează teste structurale, lintere și verificări de tipuri la fiecare pull request — inclusiv la cele create de agenți. Agentul ar trebui să vadă același output de validare pe care l-ar vedea un dezvoltator uman.

Pasul 4: Scrie planuri de sarcini înainte de execuția agentului

Înainte de a cere unui agent să implementeze o funcționalitate, scrie un document de plan structurat care specifică fișierele de modificat, constrângerile de urmat și criteriile de acceptare. Stochează aceste planuri în repository.

Pasul 5: Configurează curățarea automată

Implementează un job CI săptămânal sau nocturn care scanează baza de cod pentru abateri de la standardele documentate și creează PR-uri de refactorizare concentrate.

Alegerea sistemului de agenți

Principiile de harness engineering se aplică indiferent de agentul pe care îl folosești:

Harness-ul trăiește în repository-ul tău, nu în agentul tău. Acest lucru înseamnă că poți schimba agenții fără a pierde investiția în harness.

Scalarea de la un agent la mai mulți

Experimentul OpenAI a demonstrat că harness engineering permite execuția paralelă a agenților. Deoarece harness-ul impune limite arhitecturale, mai mulți agenți pot lucra simultan pe părți diferite ale bazei de cod fără a crea conflicte.

Cerințe cheie pentru execuția paralelă a agenților:

1. Proprietate clară asupra modulelor — fiecare agent lucrează într-o limită definită
2. Interfețe tipizate între module — agenții pot scrie cod pentru interfețe fără a cunoaște detaliile de implementare
3. Prevenirea conflictelor de merge — sarcinile sunt dimensionate pentru a minimiza suprapunerea fișierelor
4. Validare centralizată — toți agenții trimit către același pipeline CI

Partea 6: Greșeli comune și anti-modele

Anti-model 1: Tratarea agentului ca fiind harness-ul

Agentul nu este harness-ul. Harness-ul este mediul în care operează agentul. A cere unui model mai inteligent să compenseze un repository prost structurat este abordarea greșită. Repară mediul, nu prompt-ul.

Anti-model 2: Documentația în locul greșit

Dacă deciziile tale arhitecturale trăiesc în Confluence, Notion sau Google Docs, agenții nu le pot vedea. Soluția este simplă, dar necesită disciplină: mută toată documentația relevantă pentru dezvoltare în repository.

Anti-model 3: Curățare manuală în loc de impunere automată

Dacă petreci timp semnificativ curățând codul generat de agenți, ai nevoie de o impunere mai bună, nu de mai multe sesiuni de curățare. Fiecare sarcină de curățare recurentă ar trebui să devină fie o regulă linter, un test structural sau un job de refactorizare automată.

Anti-model 4: Supra-constrângerea

Un harness prea rigid împiedică agenții să găsească soluții creative. Scopul este de a constrânge arhitectura, nu implementarea. Spune agenților ce module pot modifica și ce dependențe sunt permise, dar lasă-i pe ei să decidă cum să implementeze logica în acele limite.

Anti-model 5: Ignorarea feedback-ului agentului

Atunci când un agent eșuează în mod repetat la anumite sarcini, eșecul indică de obicei o lacună în harness, nu o limitare a agentului. Urmărește tiparele de eșec și folosește-le pentru a-ți îmbunătăți documentația, testele structurale sau constrângerile arhitecturale.

Partea 7: Viitorul Harness Engineering

Perspectiva lui Martin Fowler

Martin Fowler a publicat o analiză a harness engineering pe blogul său, menționând că acesta reprezintă o schimbare fundamentală în modul în care operează echipele de software. Disciplina împrumută din decenii de bune practici de inginerie software — integrare continuă, înregistrări ale deciziilor de arhitectură, injecție de dependență — dar le reutilizează pentru o lume condusă de agenți. Sursă

Framework-ul HumanLayer

Echipa de la HumanLayer și-a publicat analiza numind harness engineering o „problemă de abilitate” (skill issue) — susținând că capacitatea de a proiecta harness-uri eficiente va deveni principalul diferențiator între echipele de inginerie performante și cele care se confruntă cu dificultăți. Sursă

Ce înseamnă acest lucru pentru dezvoltatori

Harness engineering nu înlocuiește abilitatea dezvoltatorului — o redirecționează. În loc să scrie cod, inginerii seniori proiectează sistemele care permit agenților să scrie cod bine. Abilitățile care contează se mută de la implementare la arhitectură, de la coding la proiectarea sistemelor, de la scrierea testelor la proiectarea framework-urilor de testare.

Pentru echipele care construiesc aplicații, platforme precum ZBuild încorporează deja principiile de harness engineering în fluxurile lor de lucru de construire a aplicațiilor. În loc să ceară dezvoltatorilor să își proiecteze propriile harness-uri de la zero, ZBuild oferă modele arhitecturale pre-configurate, managementul dependențelor și sisteme de validare care ghidează agenții AI către rezultate de înaltă calitate — permițând dezvoltatorilor să se concentreze pe deciziile de produs, mai degrabă decât pe infrastructură.

Cele trei orizonturi

Privind înainte, harness engineering este probabil să evolueze prin trei faze:

1. Termen apropiat (2026): Echipele adoptă documentația centrată pe repository, testele structurale și principiile de aur. Dezvoltarea asistată de agenți devine o practică standard pentru proiectele bine echipate cu harness.

2. Termen mediu (2027): Generarea harness-ului în sine devine condusă de agenți. Agenții analizează bazele de cod existente și propun configurații de harness — reguli linter, teste structurale, limite de dependență — pe baza tiparelor pe care le observă.

3. Termen lung (2028+): Harness-urile devin adaptive. În loc de reguli statice, ele evoluează pe baza rezultatelor codului generat de agenți, înăsprind automat constrângerile în zonele în care agenții produc frecvent erori și relaxându-le acolo unde au succes în mod constant.

Partea 8: Listă de verificare practică

Folosește această listă de verificare pentru a evalua maturitatea de harness engineering a echipei tale:

Fundație (Începe aici)

• ARCHITECTURE.md există în rădăcina repository-ului
• Formatarea codului este automatizată (Prettier, Black, gofmt)
• Linting-ul rulează la fiecare pull request
• Verificarea tipurilor este impusă (TypeScript strict, mypy, etc.)

Intermediar

• Testele structurale validează limitele dependențelor
• Principiile de aur sunt documentate și pot fi impuse mecanic
• Planurile sarcinilor sunt scrise înainte de execuția agentului
• PR-urile generate de agenți trec prin același CI ca și PR-urile umane

Avansat

• Colectarea automată a gunoiului (garbage collection) rulează programat
• Mai mulți agenți pot lucra în paralel fără conflicte
• Tiparele de eșec ale agenților sunt urmărite și folosite pentru a îmbunătăți harness-ul
• Harness-ul în sine este controlat prin versiuni și revizuit ca și codul

Expert

• Agenții generează părți din harness (reguli linter, teste structurale)
• Notele de calitate sunt atribuite automat fiecărui modul
• Îmbunătățirile harness-ului sunt bazate pe date, conform ratelor de succes ale agenților
• Echipa livrează mai mult cod per inginer per săptămână decât înainte de adoptarea agenților

Concluzie

Harness engineering nu este o modă pasageră. Este evoluția naturală a ingineriei software într-o eră în care agenții AI sunt suficient de capabili să scrie cod de producție, dar au nevoie de medii structurate pentru a o face bine. Experimentul de un milion de linii al OpenAI a dovedit conceptul la scară largă, iar principiile pe care le-au articulat — cunoștințe centrate pe repository, principii de aur, arhitectură stratificată, colectarea automată a gunoiului și planuri executabile — sunt aplicabile echipelor de orice dimensiune.

Echipele care vor stăpâni harness engineering în 2026 vor livra mai rapid, vor menține o calitate mai ridicată a codului și vor scala mai eficient decât cele care tratează agenții AI ca pe un autocomplete glorificat. Agentul este calul. Harness-ul este ceea ce îl face util.

Surse

• 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