Wakala amesema «imekamilika», lakini kipengele hakifanyi kazi: kwa nini hutokea na jinsi ya kukagua kazi ya wakala wa AI

Kwa nini hili hutokea

Hali hii inajulikana kwa kila anayefanya kazi na mawakala: wakala ameandika «imekamilika», lakini kipengele hakifanyi kazi. Hasemi uongo kwa makusudi. Anaripoti alichoweza kukikagua na anaamini hilo linatosha. Pengo kati ya maneno na uhalisia ni sifa ya mpangilio wa «mtekelezaji anajitathmini mwenyewe», si kasoro ya modeli fulani.

Sababu tatu zinaelezea hili. Kwanza, modeli huelekea kujiamini kupita kiasi: kiwango cha uhakika wa jibu ni kikubwa kuliko usahihi wake. Pili, wakala anatathmini kazi yake katika muktadha ule ule aliotumia kuifanya: tayari amejishawishi kwamba suluhisho ni sahihi, na ombi la «kagua kwa lengo zaidi» halibadilishi muktadha huo. Tatu, na hii ndiyo ya vitendo zaidi: wakala anapata ukaguzi wa sehemu tu. Majaribio ya kitengo hukimbia haraka na kuwa kijani, lakini hali ya mwisho-hadi-mwisho haikuwahi kuendeshwa na yeyote.

Historia ya «imekamilika» iliyokosewa

Wakala alipewa kazi ya kuweka upya nywila. Alibadilisha schema ya database, aliongeza endpoint, aliunganisha kiolezo cha barua pepe, akaendesha majaribio ya kitengo — yote ni ya kijani. Kwenye mazungumzo likaja sentensi yenye kujiamini: «Imekamilika».

Kilichotokea kwa kweli:

• migration ilishindwa katikati na kuacha schema katika hali isiyolingana;
• kiolezo cha barua pepe kipo, lakini huduma ya barua (SMTP) haijasanidiwa kwenye mazingira — barua haitumwi;
• hali ya «mtumiaji anabofya kiungo → anaweka nywila mpya → anaingia» haikuwahi kuendeshwa.

Majaribio ya kitengo hayakuweza kukamata hata moja ya matatizo haya: database ilikuwa imeigwa (mock), utumaji wa barua uliigwa, na hakukuwa na mtiririko mzima wa kuendesha.

Kwa nini majaribio ya kijani hayathibitishi kwamba kipengele kinafanya kazi

Jaribio la kitengo hukagua moduli moja kwa pekee: utegemezi umeigwa, dunia ya nje imezimwa. Hii huleta kasi na usahihi, lakini pia upofu wa kimfumo. Upofu huo si kasoro ya majaribio, ni sehemu ya muundo wake. Vitengo vya kijani vinathibitisha tu kwamba kila sehemu inafanya kazi yenyewe, si kwamba sehemu hizo zinafanya kazi pamoja.

Aina nne za kasoro jaribio la kitengo haliwezi kuziona kimsingi:

Ngazi za ukaguzi zimo ndani ya nyingine: kila kinachokamatwa na kitengo pia hukamatwa na jaribio la ujumuishaji, na kila kinachokamatwa na ujumuishaji pia hukamatwa na mtiririko wa mwisho-hadi-mwisho (E2E). Kila ngazi inayofuata inaona zaidi. Kwa hiyo haki ya kusema «imekamilika» inapaswa kuwa ya ngazi ya juu kabisa tu.

Kupima tatizo: verification gap

Kabla ya kurekebisha, pima. Chukua kazi 10 za mwisho ambazo wakala alizifunga. Kwa kila moja jibu maswali mawili: je wakala alisema «imekamilika», na je ukaguzi huru ulithibitisha hilo (wewe mwenyewe ulipitia hali, au jaribio la E2E ni la kijani). Uwiano wa kutolingana ni verification gap yako.

Namba hii ina manufaa kwa sababu mbili. Inaonyesha ukubwa wa tatizo bila mjadala wa «ndiyo, kwa kawaida inafanya kazi». Na inatoa msingi: baada ya kila mabadiliko ya mchakato, hesabu tena kwenye seti inayofanana ya kazi na uone kama kuna maboresho.

Ukaguzi halisi: tabaka tatu za uthibitishaji

Mfano mzuri ni kituo cha ukarabati wa magari. Gari linapita vituo vitatu, na hakuna kituo kinachoruhusiwa kuruka.

1. Uchunguzi (sekunde): sintaksia, aina, linter. Hukamata makosa ya kuandika na kasoro za wazi.
2. Benchi (dakika): majaribio ya kitengo na ujumuishaji, programu inaanza. Injini inafanya kazi, lakini gari bado halijaondoka.
3. Jaribio la barabarani: mtiririko wa mwisho-hadi-mwisho jinsi mtumiaji anavyouendesha — kupitia API, browser au CLI, na database na mipangilio halisi.

Kanuni ya mpangilio: usiende kwenye jaribio la barabarani wakati uchunguzi bado uko nyekundu, na usitoe gari bila kupita jaribio la barabarani. Jaribio la kitengo la kijani ni kituo cha pili kilichopitwa, si cha tatu.

Kila kitu kinaweza kukusanywa kwenye mlango mmoja:

# Makefile
check:
	ruff check .
	mypy app
	pytest tests/unit tests/integration

e2e:
	docker compose up -d db mailhog
	alembic upgrade head
	pytest tests/e2e

verify: check e2e

Hapa lengo la E2E huwasha database halisi na seva ya barua ya majaribio, hutumia migrations, na kuendesha mtiririko mzima. Migration iliyoshindwa au barua isiyosanidiwa vinaonekana mara moja, si kwa mteja.

Definition of Done katika AGENTS.md

Wakala hapaswi kuamua mwenyewe maana ya «imekamilika». Kigezo kinaandikwa kwenye faili la maelekezo, kwa namna inayoweza kuthibitishwa:

## Definition of Done
Kipengele kinachukuliwa kuwa kimekamilika tu wakati vyote hivi vimetimia:
1. make check imemaliza kwa msimbo 0
2. make e2e imemaliza kwa msimbo 0, mtiririko wa kipengele upo tests/e2e
3. Migrations zinatumika kwenye database tupu na zinaweza kurudishwa
4. Vigezo vipya vya mazingira vimeelezwa katika .env.example
5. PROGRESS.md inaandika kilichofanyika na jinsi kilivyothibitishwa

HAZIONYESHI kwamba kipengele kiko tayari:
- «msimbo umeandikwa na unaonekana sahihi»
- «majaribio ya kitengo yanapita»
- «kwangu inafanya kazi»

Orodha wazi ya kile kisichohesabiwa kuwa tayari inafanya kazi vizuri kuliko unavyodhani: wakala anaacha kusimama kwenye matokeo ya kwanza ya kijani.

Nani anayepaswa kutoa hali ya «passing»

Hatua inayofuata ni kuondoa kabisa hali ya utayari mikononi mwa wakala. Vipengele vinahifadhiwa kwenye orodha (kwa mfano feature_list.json) vikiwa na sehemu za «tabia», «amri ya uthibitishaji» na «hali». Skripti pekee ndiyo inaweza kupeleka kipengele kwenye passing: inaendesha make check ya jumla, kisha amri ya uthibitishaji ya kipengele hicho, na ikifanikiwa inaandika hali pamoja na commit hash kama ushahidi. Kisipopita, kipengele kinabaki active — hakuna «karibu imefaulu».

{
  "id": "F04",
  "behavior": "Mtumiaji anapokea barua pepe yenye kiungo na kubadilisha nywila",
  "verification": "pytest tests/e2e/test_password_reset.py",
  "state": "active"
}

Kuna mtego hapa: skripti inakagua tu kile kilichoandikwa kwenye sehemu ya verification. Ikiwa ukaguzi wa muundo ni sehemu ya Definition of Done lakini haupo kwenye amri ya kipengele, pengo litabaki halionekani. Kwa hiyo make check ya jumla lazima ijumuishe ukaguzi wote wa lazima, si majaribio tu.

Mkaguzi huru

Taarifa ya mtekelezaji mwenyewe kamwe si chanzo huru cha ukweli. Suluhisho ni la kimuundo: tenganisha majukumu.

• mpangaji hugawanya mahitaji kuwa vipengele vyenye vigezo vya kukubalika na haandiki msimbo;
• jenereta hutekeleza kipengele kimoja na kuendesha majaribio, lakini haamui kama kiko tayari;
• mkaguzi hutoa hukumu kwa kuangalia orodha ya vigezo.

Mkaguzi hapaswi kuona hoja za jenereta, kwa sababu atarithi uhakika wake. Anapokea mahitaji, diff na matokeo ya kuendesha ukaguzi tu. Katika Claude Code hili ni rahisi kwa subagent, kwa sababu ana muktadha wake safi. Ni bora zaidi ikiwa mkaguzi ni modeli nyingine, kwa sababu ina sehemu tofauti za upofu. Tathmini ya aina «inaonekana sawa» haikubaliwi: kila hitimisho lazima lirejelee faili, mstari au kumbukumbu.

Ujumbe wa kosa ambao wakala anaweza kurekebisha mwenyewe

Ukaguzi una manufaa tu ikiwa matokeo yake yanaelekeza kwenye marekebisho. «Test failed» au AssertionError tupu haimwambii wakala chochote. Ujumbe mzuri unaeleza kilichovunjika, kwa nini kanuni ipo, na jinsi ya kurekebisha:

ERROR arch-check: app/services/refund.py inaingiza app/db/session.py
WHY: service hazigusi database moja kwa moja, zinapita kwenye repository tu
FIX: tumia RefundRepository kutoka app/repositories/refund.py

Muundo kama huu unageuza ukaguzi kutoka katazo kuwa dokezo: wakala anarekebisha ukiukaji bila wewe kuingilia.

Ukaguzi wa mkono: bado unahitajika wapi

Otomatiki haimwondoi binadamu, lakini inapunguza jukumu lake. Ukaguzi wa mkono unahitajika mahali ambapo vigezo ni vigumu kuweka rasmi: mwonekano wa kiolesura, maandishi, urahisi wa mtiririko. Ufanye kwa orodha ya vigezo vya kukubalika, si kwa «kubofya tu». Ukiandika maoni yale yale kwa wakala mara ya pili, hiyo ni ishara ya kuyageuza kuwa ukaguzi wa kiotomatiki: jaribio, kanuni ya linter, au grep-guard kwenye make check.

Jinsi E2E inavyobadilisha tabia ya wakala hata kabla ya kuendeshwa

Thamani ya jaribio la mwisho-hadi-mwisho si tu kwenye hitilafu zilizokamatwa. Ikiwa wakala anajua tangu mwanzo kwamba kazi yake itakaguliwa kwa mtiririko wa E2E, anaandika msimbo tofauti: anafikiria mkataba na moduli jirani, sio kazi yake peke yake, anashughulikia njia za makosa, na haivuki mipaka ya muundo kwa sababu ukiukaji utaonekana wakati wa kuendesha. Ukaguzi unafanya kazi kama kikwazo mwanzoni, si tu kichujio mwishoni.

Lakini kuna sharti: E2E ina maana wakati mfumo una mipaka iliyo wazi. Kwenye muundo wa spaghetti, jaribio la mwisho-hadi-mwisho linathibitisha tu kwamba spaghetti inafanya kazi, halionyeshi mahali nia ya muundo imevunjwa. Kwa hiyo tabaka na kanuni za utegemezi huwekwa kwanza, kisha mitiririko ya mwisho-hadi-mwisho inajengwa. Wakala hunakili kwa hiari mifumo iliyopo kwenye hazina, pamoja na ile mibaya, kwa hiyo vikwazo vinapaswa kuanzishwa tangu siku ya kwanza.

Makosa ya kawaida

• Kumwomba wakala «kagua kwa makini zaidi». Muktadha ni uleule, na tathmini itabaki imepanda juu.
• Kuchukulia kufunika kwa 100% kama dhamana. Kufunika kwa vitengo hakufuniki miunganisho.
• Kurekebisha muundo kabla kipengele hakijathibitishwa. Mpangilio ni mkali: usahihi → utendaji → mtindo.
• Kuiga (mock) katika E2E sehemu inayovunjika mara nyingi zaidi. Database, migrations na mipangilio lazima viendeshwe kwa kweli katika E2E; huduma za nje zinazolipiwa zinaweza kubadilishwa na seva ya majaribio.

Hitimisho

Wakala akiandika «imekamilika» wakati kipengele hakifanyi kazi, tatizo karibu kila mara liko kwenye mchakato wa ukaguzi, si kwenye modeli. Pima verification gap, weka Definition of Done katika AGENTS.md, fanya E2E kuwa ya lazima, mpe skripti hali ya ukamilifu, na ongeza mkaguzi huru. Mpangilio huu unafundishwa kwa kina na kwa vitendo katika kozi ya harness engineering.