Harness engineering ni nini: jinsi ya kufanya wakala wa AI kuwa zana ya kazi halisi

Harness engineering kwa lugha rahisi

Harness engineering ni nidhamu ya uhandisi inayofundisha jinsi ya kujenga mazingira yanayozunguka modeli ya lugha ili iweze kufanya kazi halisi kwa uaminifu. Neno harness linamaanisha «kamba ya kuongoza» au «vifaa vya kuunganisha»: modeli ina nguvu, lakini yenyewe haijui inakwenda wapi, itumie nini, wala lini isimame. Harness ndiyo inayoelekeza nguvu hiyo.

Kauli fupi kabisa ni hii:

Wakala = Modeli + Harness

Modeli ni uzito wa mtandao wa neva na uwezo wa kufikiri na kuandika maandishi au msimbo. Harness ni kila kitu kingine: maelekezo ya mfumo na faili kama CLAUDE.md au AGENTS.md, seti ya zana (shell, kuhariri faili, seva za MCP), sandbox ambamo wakala huendesha amri, faili za hali kati ya vikao, pamoja na majaribio, linter na hooks zinazomwambia wakala kuhusu makosa. Ukiondoa harness, kinachobaki ni mazungumzo yanayoweza tu kujibu kwa maandishi.

Kwa nini wakala wakati mwingine ni «mkubwa», wakati mwingine «mdogo»

Picha inayojulikana: katika hazina moja wakala anafanya kazi kama msanidi mwenye uzoefu, katika nyingine anachanganyikiwa, anasahau maamuzi ya jana na anaripoti «imekamilika» kwa kipengele ambacho hakifanyi kazi. Mwitikio wa kwanza mara nyingi ni kubadilisha modeli kwa toleo jipya zaidi. Kwa kawaida hii haisaidii, kwa sababu modeli ni ile ile katika visa vyote viwili. Tofauti iko kwenye mazingira.

Hapa ndipo mabadiliko makuu ya kufikiri ya harness engineering yanapoanzia: wakala hajavunjika — kilichovunjika ni kile kinachomzunguka. Wakala hawezi kuendesha majaribio ikiwa hana ufikiaji wake. Hatakumbuka alichojaribu ikiwa hakuna mahali ambapo kimeandikwa. Hatajua kipengele kimevunjika ikiwa hakuna ukaguzi unaomwambia. Hii si «tabia» ya modeli, bali kasoro ya muundo, na kasoro za aina hii zinaweza kurekebishwa kwa utaratibu.

Dalili za harness mbovu

• Kila kikao kipya kinaanza kwa kurekebisha mazingira: utegemezi usio sahihi, hifadhidata haiwashi, vigezo havipo.
• Wakala anarudia suluhisho lililokwisha kukataliwa, kwa sababu hakumbuki kikao kilichopita.
• Kanuni imeandikwa wazi kwenye maelekezo, lakini wakala bado anaipuuza.
• «Majaribio ni ya kijani», lakini kipengele kimevunjika, kwa sababu majaribio yalikagua jambo lisilo sahihi.
• Wakala anachukua kazi tatu kwa wakati mmoja na hamalizi hata moja.

Harness inajumuisha nini: vipengele vitano

Kosa la kawaida ni kudhani harness ni faili moja tu ya maelekezo. Kwa kweli kuna mifumo mitano, na kila moja huvunjika kwa namna yake.

Maelekezo

Maelekezo yanajibu swali «je, wakala atapata kanuni sahihi?». Faili nzuri ya kuingilia ni kama ramani, si kitabu: orodha fupi yenye amri za uthibitishaji na mipaka mikali, huku maelezo yakiwa kwenye nyaraka tofauti ambazo wakala hufungua inapohitajika. Maelekezo mazuri huweka kanuni zisizobadilika («maswali yote ya SQL yana vigezo»), badala ya kuamuru utekelezaji mstari kwa mstari.

Zana

Wakala anaweza kuthibitisha tu kile anachoweza kukifikia. Ikiwa hawezi kuendesha linter, kanuni ya «endesha linter kabla ya commit» haitasaidia. Zana huunganishwa kupitia uwezo wa wakala wenyewe (kusoma na kuhariri faili, kuendesha amri) na kupitia MCP, itifaki inayompa wakala ufikiaji wa hifadhidata, browser na vifuatiliaji vya kazi.

Mazingira

Mazingira ndipo wakala anapoendesha amri. Yanapaswa kuwaka kwa amri moja, kuwa sawa kila kikao, na kupunguza madhara ya kosa: sandbox isiyo na ufikiaji wa uzalishaji, tawi au nakala tofauti ya kazi, na uwezo wa kurudisha kila kitu katika hali yake ya awali ndani ya dakika moja.

Hali

Modeli haina kumbukumbu kati ya vikao: kila kisichoandikwa kwenye hazina hupotea pamoja na dirisha la muktadha. Kwa hiyo lengo, yaliyokamilika, maamuzi yaliyofanywa, njia zisizofaa na hatua inayofuata lazima viishi kwenye faili. Jaribio ni rahisi: fungua kikao kipya, mwambie wakala «endelea» — kisha uone kama anaanza kazi moja kwa moja au anauliza la kufanya.

Maoni

Mzunguko wa maoni ndicho kipengele muhimu zaidi. Bila hicho, wakala ndiye hakimu pekee wa kazi yake mwenyewe na anahitimisha kwa dhati kwamba kazi imekamilika. Majaribio, ukaguzi wa aina, linter, hook inayoendeshwa baada ya kila mabadiliko, na hali ya E2E kwenye kivinjari — yote hayo humrudishia wakala ishara nyekundu wakati kosa bado ni rahisi kurekebisha.

Harness ni mzunguko, si orodha

Vipengele vitano hufanya kazi kama mzunguko funge. Modeli hupokea maelekezo, hutenda kupitia zana ndani ya mazingira, hufanya mabadiliko kwenye hazina, na uthibitishaji huangalia matokeo. Matokeo nyekundu hurudishwa kwa modeli kwa marekebisho, matokeo ya kijani huhifadhiwa kwenye hali. Hali nayo husasisha maelekezo kwa kikao kinachofuata.

maelekezo → modeli → zana → mazingira → mabadiliko
                ↑                              ↓
                └──── nyekundu ── uthibitishaji ┘
                                     ↓ kijani
                                 hali → (kikao kinachofuata)

Ukiondoa mshale wowote, mzunguko unakatika mahali hapo. Bila uthibitishaji, wakala hajui kuhusu kosa lake. Bila hali, kikao kinachofuata kinaanza kuchimba historia badala ya kufanya kazi. Kwa hiyo kuwekeza kwenye kipengele kimoja hakuzibi pengo la kingine: faili ya AGENTS.md ya kurasa tano haiwezi kuchukua nafasi ya majaribio yasiyopo.

Harness engineering inatofautianaje na prompt na context engineering

Dhana hizi zimo ndani ya nyingine, si washindani.

Prompt engineering ni sehemu ya kipengele cha maelekezo. Context engineering inagusa maelekezo na hali: wakala anaona nini kwa wakati wowote. Harness engineering inaongeza vitu ambavyo haviingii kwenye dirisha la muktadha kabisa: ufikiaji, sandbox, majaribio, hooks na mchakato wa kazi. Prompt nzuri haitasaidia ikiwa wakala hawezi kimwili kuendesha majaribio.

Kwa nini harness inahitajika: hesabu ya kazi ndefu

Kwa mtazamo wa kawaida, modeli inayofanya hatua 95% kwa usahihi inaonekana karibu kamilifu. Lakini kazi ya wakala ina hatua nyingi, na makosa hujilimbikiza. Ikiwa hatua ni huru kutoka kwa nyingine, uwezekano wa kuzipitia zote bila kosa ni zao la uwezekano wa kila hatua:

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

Katika hatua ya kumi, karibu 60% ya majaribio hufika bila kosa hata moja, na katika hatua ya hamsini chini ya moja kati ya kumi. Kuboresha modeli hadi 97% ni ghali na haiko mikononi mwako kikamilifu. Lakini kukamata kosa katika hatua ilipotokea na kumrudishia wakala ndicho kazi ya harness. Mzunguko wa maoni hubadilisha mnyororo wa «kosa moja huvuta kosa jingine» kuwa mnyororo wa hatua fupi zinazoweza kurekebishwa.

Mfano: wakala yule yule katika hazina mbili

Kazi: kuongeza punguzo kwa msimbo wa promo kwenye backend ya malipo ya FastAPI.

Bila harness

Wakala anasoma faili chache, anaandika kazi ya kuhesabu punguzo na jaribio la kitengo linalokagua kazi hiyo peke yake. Jaribio ni la kijani, wakala anaandika «imekamilika». Hakujua kwamba hesabu ya jumla ya bei inafanyika kwenye moduli nyingine, na hakuweza kuendesha hifadhidata wala mchakato mzima wa checkout. Siku moja baadaye inagunduliwa kwamba punguzo haliingii kwenye kikapu.

Ukiwa na harness

Kwenye mzizi wa mradi kuna AGENTS.md ya mistari michache kadhaa: jinsi ya kuwasha mazingira, amri gani za uthibitishaji ni lazima, na mfumo wa malipo umeelezwa wapi. Mazingira yanawaka kwa docker compose up -d. Kwenye hazina kuna faili la mpango lenye kigezo cha ukamilifu: «mchakato wa E2E wa checkout wenye msimbo wa promo unapita». Baada ya kila mabadiliko, hook huendesha linter na ukaguzi wa aina; kabla ya kumaliza, wakala lazima aendeshe jaribio la E2E.

# AGENTS.md (sehemu)
## Uthibitishaji — ni lazima kabla ya neno «imekamilika»
make lint        # ruff + mypy
make test        # pytest, vipimo vya kitengo na ujumuishaji
make e2e         # mchakato wa checkout

## MUST
- Fedha zinahesabiwa kwa senti (int), kamwe float
- Maswali yote ya SQL yana vigezo
- Usibadilishe migrations zilizotumika kwenye uzalishaji

Modeli ni ile ile. Lakini sasa wakala anapata moduli ya jumla ya bei kupitia ramani ya mradi, jaribio la E2E linashindwa kwenye jaribio la kwanza, wakala anaona kwamba punguzo halikufika kwenye kikapu, analirekebisha, na anaripoti tu baada ya matokeo ya kijani. Tofauti ya matokeo ni ya harness kikamilifu.

Uanze wapi

1. Andika jinsi wakala anavyokagua kazi yake: amri moja hadi tatu anazopaswa kuziendesha. Maoni ndiyo yanayotoa matokeo makubwa zaidi, kwa hiyo anza hapa.
2. Fanya mazingira yaweze kurudiwa: yanawaka kwa amri moja, na kuna njia ya haraka ya kurudi kwenye hali ya awali.
3. Tengeneza faili la hali: lengo, yaliyokamilika, maamuzi na njia zisizofaa, na hatua inayofuata.
4. Punguza maelekezo kuwa ramani: amri za uthibitishaji, mipaka mikali, na viungo vya nyaraka za kina.
5. Weka kumbukumbu ya kushindwa kwa wakala: kwa kila kushindwa andika kipengele kilichoruhusu kutokea. Kumbukumbu hii inaonyesha nini kirekebishwe kinachofuata.

Zoezi muhimu ni kupima kila moja ya vipengele vitano kwa kipimo cha 1 hadi 5, kutumia nusu saa kwenye dhaifu zaidi, na kuendesha seti ile ile ya kazi tano za kawaida kabla na baada. Kwa njia hii maboresho ya harness yanapimika, si «yanaonekana kuwa bora» tu.

Hitimisho

Harness engineering si kuhusu modeli, bali kuhusu kila kitu kinachoizunguka: maelekezo, zana, mazingira, hali na mzunguko wa maoni. Uaminifu wa wakala unaamuliwa na kiungo dhaifu zaidi cha mzunguko huu, kwa hiyo kubadilisha modeli mara chache hutatua kutokuwa imara, lakini jaribio moja au faili moja la mpango mara nyingi hutatua. Vipengele vyote vitano na jinsi ya kujenga harness nzima vinafundishwa kwa vitendo katika kozi ya harness engineering.