Ano ang harness engineering: gawing kapaki-pakinabang na kasangkapan ang AI agent

Harness engineering sa simpleng salita

Ang harness engineering ay disiplina ng inhinyeriya tungkol sa kung paano bubuuin ang kapaligirang nakapalibot sa isang language model upang maisagawa nito nang maaasahan ang totoong trabaho. Ang salitang harness ay nangangahulugang «pang-gabay na kagamitan» o «tali». Malakas ang modelo, pero sa sarili nito, hindi nito alam kung saan pupunta, anong kasangkapan ang gagamitin, o kailan hihinto. Ang harness ang nagdidirekta sa lakas na iyon.

Ang pinakamaikling pagkakabuo nito ay ganito:

Agent = Model + Harness

Ang model ay ang mga weight, ang kakayahang mangatwiran, at ang pagsulat ng teksto o code. Ang harness naman ay ang lahat ng iba pa: mga system instruction at mga file tulad ng CLAUDE.md o AGENTS.md, hanay ng mga kasangkapan (shell, pag-edit ng file, MCP server), sandbox kung saan nagpapatakbo ng command ang agent, mga file ng estado na nananatili sa pagitan ng mga session, at mga test, linter, at hook na nagsasabi sa agent kapag may pagkakamali. Kapag inalis ang harness, ang matitira ay isang chat na marunong lang sumagot ng teksto.

Bakit minsan «senior» at minsan «junior» ang agent

Pamilyar ba? Sa isang repository, gumagana ang agent na parang bihasang developer. Sa ibang repository, nawawala ito, nakakalimutan ang mga desisyon kahapon, at nagsasabing «tapos na» kahit hindi gumagana ang feature. Ang unang reaksyon ay lumipat sa mas bagong modelo. Kadalasan hindi ito nakakatulong, dahil iisa pa rin ang modelo. Ang pagkakaiba ay nasa kapaligiran.

Dito nagsisimula ang unang pagbabago ng pag-iisip sa harness engineering: hindi sira ang agent. Ang nasira ay ang nakapalibot dito. Hindi makakapagpatakbo ng test ang agent kung walang access dito. Hindi nito maaalala ang sinubukan na kung walang nakasulat na tala. Hindi nito malalaman na sira ang feature kung walang check na magsasabi nito. Hindi ito «ugali» ng modelo kundi depekto sa disenyo, at maaaring ayusin nang sistematiko.

Mga karaniwang sintomas ng masamang harness

• Nagsisimula ang bawat bagong session sa pag-aayos ng kapaligiran: maling dependency, hindi bumubukas ang database, kulang ang environment variable.
• Inuulit ng agent ang mga solusyong tinanggihan na, dahil hindi nito naalala ang nakaraang session.
• Nakasulat ang panuntunan sa mga tagubilin, pero binabalewala pa rin ito ng agent.
• «Berde ang lahat ng test» pero sira pa rin ang feature, dahil maling bagay ang sinusuri ng test.
• Tatlong gawain ang sinasimulan ng agent nang sabay at wala ni isa ang natatapos.

Ano ang laman ng harness: limang bahagi

Karaniwang pagkakamali ang paniwalang isang file lang na prompt ang harness. Sa totoo, limang mekanismo ito, at bawat isa ay pumapalya sa sariling paraan.

Mga tagubilin

Sinasagot ng mga tagubilin ang tanong na «makikita ba ng agent ang tamang panuntunan». Ang mabuting entry file ay mapa, hindi textbook: maikling talaan ng nilalaman na may mga command sa pagsusuri at mahigpit na limitasyon, habang nasa hiwalay na dokumento ang mga detalye na binubuksan ng agent kapag kailangan. Ang mabubuting tagubilin ay nagtatakda ng mga invariant («lahat ng SQL query ay parameterized»), hindi nagdidikta ng implementasyon linya-por-linya.

Mga kasangkapan

Masusuri lang ng agent ang mga bagay na naaabot nito. Kung hindi nito mapatakbo ang linter, walang saysay ang panuntunang «patakbuhin ang linter bago mag-commit». Ikinakabit ang mga kasangkapan sa pamamagitan ng mga built-in na kakayahan ng agent (pagbabasa at pag-edit ng file, pagpapatakbo ng command) at sa pamamagitan ng MCP, ang protocol na nagbibigay sa agent ng access sa database, browser, at task tracker.

Kapaligiran

Ang kapaligiran ang lugar kung saan tumatakbo ang mga command ng agent. Dapat itong bumukas sa iisang command, pareho sa bawat session, at dapat nitong limitahan ang pinsala kapag may pagkakamali: sandbox na walang access sa production, hiwalay na branch o working copy, at kakayahang ibalik ang lahat sa dating kalagayan sa loob ng isang minuto.

Estado

Walang memorya ang modelo sa pagitan ng mga session. Ang lahat ng hindi naitala sa repository ay nawawala kasabay ng context window. Kaya ang layunin, ang mga nagawa na, mga desisyon, mga dead end, at ang susunod na hakbang ay dapat nakatira sa mga file. Simple ang pagsubok: buksan ang bagong session, sabihin sa agent na «ituloy mo», at tingnan kung magsisimula ito nang maayos o magtatanong kung ano ang gagawin.

Feedback

Ang feedback loop ang pinakamahalagang bahagi. Kung wala ito, ang agent ang sarili lang nitong hukom at tapat nitong iisipin na tapos na ang gawain. Ang mga test, type check, linter, hook na tumatakbo pagkatapos ng bawat pagbabago, at E2E na senaryo sa browser ay nagbabalik ng pulang senyales sa agent habang mura pa ang pag-aayos.

Ang harness ay isang saradong loop, hindi isang listahan

Gumagana ang limang bahagi bilang saradong loop. Tumatanggap ang modelo ng mga tagubilin, kumikilos sa pamamagitan ng mga kasangkapan sa kapaligiran, gumagawa ng pagbabago sa repository, at sinusuri ng verification ang resulta. Ang pulang sagot ay ibinabalik sa modelo para ayusin, ang berdeng sagot ay nire-record sa estado. Ina-update naman ng estado ang mga tagubilin para sa susunod na session.

mga tagubilin → modelo → kasangkapan → kapaligiran → pagbabago
                ↑                              ↓
                └──── pula ── verification ────┘
                                     ↓ berde
                                 estado → (susunod na session)

Kapag inalis ang alinmang arrow, babagsak ang loop sa puntong iyon. Kung walang verification, hindi malalaman ng agent na nagkamali ito. Kung walang estado, ang susunod na session ay gugugol ng oras sa paghahanap ng nangyari sa halip na magtrabaho. Kaya hindi nababayaran ng pamumuhunan sa isang bahagi ang butas sa iba: ang limang-pahinang AGENTS.md ay hindi mapapalitan ang nawawalang test.

Paano naiiba ang harness engineering sa prompt engineering at context engineering

Magkakasama ang mga konseptong ito, hindi nagkakalaban.

Bahagi ng subsystem ng mga tagubilin ang prompt engineering. Sakop ng context engineering ang mga tagubilin at estado: kung ano ang nakikita ng agent sa bawat sandali. Dinadagdagan naman ng harness engineering ang mga bagay na hindi kasya sa context window: access, sandbox, test, hook, at proseso ng trabaho. Hindi makakatulong ang maayos na prompt kung talagang hindi makapagpatakbo ng test ang agent.

Bakit kailangan ang harness: matematika ng mahahabang gawain

Sa unang tingin, parang halos perpekto na ang modelong tama sa 95% ng hakbang. Pero maraming hakbang ang gawain ng agent, at nag-iipon ang mga pagkakamali. Kung independyente ang bawat hakbang, ang tsansang makadaan sa lahat nang walang pagkakamali ay ang produkto ng mga tsansa:

0.95 ^ 10 ≈ 0.60
0.95 ^ 20 ≈ 0.36
0.95 ^ 50 ≈ 0.08

Sa ikasampung hakbang, humigit-kumulang 60% lang ng mga takbo ang walang pagkakamali, at sa ikalimampung hakbang, wala pang isa sa sampu. Ang pagpapabuti ng modelo hanggang 97% ay mahal at wala sa iyong kontrol. Pero ang pagkahuli ng pagkakamali sa mismong hakbang kung saan ito nangyari, at ang pagbabalik nito sa agent, ay trabaho ng harness. Ginagawang maliliit at naaayos na hakbang ng feedback loop ang kadena kung saan «humihila ang isang pagkakamali ng susunod».

Halimbawa: parehong agent sa dalawang repository

Gawain: magdagdag ng discount sa pamamagitan ng promo code sa payment backend na gumagamit ng FastAPI.

Walang harness

Nagbabasa ang agent ng ilang file, nagsusulat ng function para kalkulahin ang discount at unit test na sumusubok sa function na iyon nang hiwalay. Berde ang test, kaya sinabi ng agent na «tapos na». Hindi nito alam na ang pagkalkula ng huling kabuuan ay nasa ibang module, at hindi nito napatakbo ang buong checkout flow dahil hindi nito maitayo ang database. Kinabukasan, nadiskubre na hindi nailalapat ang discount sa cart.

May harness

May AGENTS.md sa root na ilang dosenang linya: paano itayo ang kapaligiran, aling mga command sa pagsusuri ang sapilitan, at kung saan nakasulat ang arkitektura ng payment. Bumubukas ang kapaligiran sa docker compose up -d. Mayroong plan file sa repository na may pamantayan ng pagtatapos: «pumapasa ang E2E test ng checkout na may promo code». Pagkatapos ng bawat pagbabago, tumatakbo ang hook ng linter at type check, at bago magtapos, dapat patakbuhin ng agent ang E2E test.

# AGENTS.md (bahagi)
## Verification — sapilitan bago sabihing «tapos na»
make lint        # ruff + mypy
make test        # pytest, unit at integration
make e2e         # senaryo ng checkout

## MUST
- Ang pera ay kinakalkula sa sentimo (int), hindi kailanman sa float
- Lahat ng SQL query ay parameterized
- Huwag galawin ang migration na naipatupad na sa production

Pareho pa rin ang modelo. Pero ngayon, natatagpuan ng agent ang module ng kabuuan sa pamamagitan ng mapa ng proyekto, pumapalya ang E2E test sa unang takbo, nakikita ng agent na hindi umabot sa cart ang discount, inaayos ito, at nag-uulat lang pagkatapos maging berde ang takbo. Ang pagkakaiba sa resulta ay buong utang sa harness.

Saan magsisimula

1. Ilarawan kung paano sinusuri ng agent ang sariling trabaho: isa hanggang tatlong command na dapat nitong patakbuhin. Pinakamalaki ang epekto ng feedback, kaya doon magsimula.
2. Gawing mauulit ang kapaligiran: bumukas sa isang command, at may mabilisang paraan para bumalik.
3. Gumawa ng state file: layunin, mga nagawa na, mga desisyon at dead end, at ang susunod na hakbang.
4. Paikliin ang mga tagubilin sa mapa: mga command sa verification, mahigpit na limitasyon, at mga link sa detalyadong dokumento.
5. Magtala ng failure log ng agent: sa bawat pagkakamali, isulat kung aling bahagi ng harness ang nagpahintulot dito. Ituturo ng log kung ano ang aayusin susunod.

Kapaki-pakinabang na gawain ang bawat isa sa limang bahagi bigyan ng marka mula 1 hanggang 5, gugulin ang kalahating oras sa pinakamahina, at patakbuhin ang parehong limang tipikal na gawain bago at pagkatapos. Sa ganitong paraan, nasusukat ang mga pagpapabuti sa harness at hindi lang «ramdam».

Buod

Ang harness engineering ay trabaho hindi sa modelo kundi sa lahat ng nakapaligid dito: mga tagubilin, kasangkapan, kapaligiran, estado, at feedback loop. Ang pagiging maaasahan ng agent ay tinutukoy ng pinakamahinang bahagi ng loop na ito, kaya bihirang gumaling ang kawalang-tatag sa pagpalit ng modelo, pero madalas gumaling sa dagdag na test o plan file. Ang limang bahagi at ang buong pagbuo ng harness ay tinatalakay nang praktikal sa kursong harness engineering.