Sinabi ng agent na tapos na, pero hindi gumagana ang feature: bakit ito nangyayari at paano suriin ang trabaho ng AI agent

Bakit ito nangyayari

Pamilyar ang sitwasyong ito sa sinumang nagtrabaho sa agent: sinabi ng agent na «tapos na», pero hindi gumagana ang feature. Hindi ito sinasadyang pagsisinungaling. Iniuulat nito ang mga bagay na nagawa nitong suriin, at tapat nitong pinaniniwalaang sapat na iyon. Ang agwat sa pagitan ng pahayag at realidad ay katangian ng mismong pattern na «ang gumagawa ang sumusuri sa sariling gawa», hindi depekto ng isang partikular na modelo.

May tatlong dahilan. Una, may tendensiyang sobrang tiwala ang mga modelo: mas mataas ang kumpiyansa ng sagot kaysa sa katumpakan nito. Ikalawa, sinusuri ng agent ang sarili nitong gawa sa parehong context kung saan ito ginawa: nakumbinsi na nito ang sarili na tama ang solusyon, at hindi nagbabago ang context kapag sinabing «maging mas objective ka». Ikatlo, at ang pinakapraktikal, limitado ang access ng agent sa verification: mabilis maging berde ang unit test, pero walang nagpapatakbo ng end-to-end na senaryo.

Kronolohiya ng tipikal na maling «tapos na»

Inatasan ang agent na i-reset ang password. Binago nito ang schema ng database, nagdagdag ng endpoint, ikinabit ang template ng email, at pinatakbo ang unit test. Lahat ay berde. Lumitaw sa chat ang tiwalang «Tapos na».

Ang totoong nangyari:

• Pumalya ang migration sa gitna at iniwan ang schema sa hindi pare-parehong estado.
• Umiiral ang template ng email, pero hindi naka-configure ang serbisyo ng email (SMTP) sa kapaligiran, kaya hindi naipapadala ang email.
• Hindi kailanman napatakbo ang senaryong «pinindot ng user ang link → nagpasok ng bagong password → nag-log in».

Walang unit test na makakahuli sa mga problemang ito: naka-mock ang database, naka-mock ang pagpapadala ng email, at walang end-to-end na pagsubok na naganap.

Bakit hindi nagpapatunay na gumagana ang feature ang berdeng test

Sinusuri ng unit test ang isang module nang hiwalay: pinapalitan ng mock ang mga dependency at pinuputol ang mundo sa labas. Nagbibigay ito ng bilis at katumpakan, pero may sistematikong bulag na bahagi. Hindi ito bug ng mga test kundi disenyo nila. Ang berdeng unit test ay nagpapatunay lang na gumagana nang hiwalay ang bawat detalye, hindi na magkakasama ang mga ito.

May apat na uri ng depekto na hindi nakikita ng unit test sa prinsipyo:

Magkakapatong ang mga antas ng verification: anumang nahuhuli ng unit test ay nahuhuli rin ng integration test, at anumang nahuhuli ng integration test ay nahuhuli rin ng end-to-end (E2E) na pagtakbo. Mas marami ang nakikita ng bawat susunod na antas, nang mahigpit. Kaya ang karapatang magsabing «tapos na» ay dapat nasa pinakamataas na antas lamang.

Sukatin ang problema: verification gap

Bago ayusin, bilangin muna. Kumuha ng huling 10 gawaing natapos ng agent. Para sa bawat isa, sagutin ang dalawang tanong: sinabi ba ng agent na «tapos na», at kinumpirma ba ito ng independiyenteng pagsusuri (sinubukan mo mismo ang senaryo, o berde ang E2E test). Ang proporsyon ng hindi nagtutugma ay ang iyong verification gap.

Kapaki-pakinabang ang numerong ito sa dalawang dahilan. Ipinapakita nito ang laki ng problema nang hindi nagtatalo kung «parang gumagana naman». At nagsisilbi itong baseline: pagkatapos ng bawat pagbabago sa proseso, kalkulahin ulit sa katulad na set ng gawain at tingnan kung gumanda.

Tunay na pagsusuri: tatlong layer ng validation

Madaling ihalintulad ito sa talyer ng sasakyan. Dumaraan ang kotse sa tatlong istasyon, at hindi maaaring laktawan ang alinman.

1. Diagnostics (ilang segundo): syntax, type, linter. Nahuhuli nito ang typo at mga magaspang na pagkakamali.
2. Test bench (ilang minuto): unit at integration test, nagsisimula ang application. Gumagana na ang makina, pero nakatigil pa rin ang kotse.
3. Test drive: end-to-end na senaryo gaya ng ginagawa ng user, sa pamamagitan ng API, browser, o CLI, may totoong database at configuration.

Panuntunan ng pag-usad: hindi puwedeng pumunta sa test drive habang may error pa sa diagnostics, at hindi puwedeng ipasa ang kotse nang hindi dumadaan sa test drive. Ang berdeng unit test ay ang ikalawang istasyong nalampasan na, hindi ang ikatlo.

Maaaring pagsama-samahin ang lahat sa iisang entry point:

# 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

Dito, binubuksan ng E2E ang totoong database at test mail server, ina-apply ang mga migration, at pinapatakbo ang buong senaryo. Lalabas kaagad ang migration na pumalya o ang mail na hindi naka-configure, hindi sa kliyente.

Definition of Done sa AGENTS.md

Hindi dapat ang agent ang magpasya kung ano ang «tapos na». Isinusulat ang pamantayan sa file ng tagubilin, at ginagawang masusuri:

## Definition of Done
Tapos ang feature kapag natupad ang LAHAT ng puntong ito:
1. Natapos ang make check nang may code 0
2. Natapos ang make e2e nang may code 0, at may senaryo ng feature sa tests/e2e
3. Naa-apply ang migration sa malinis na database at naibabalik
4. Nakadeskripsyon sa .env.example ang mga bagong environment variable
5. Nakatala sa PROGRESS.md kung ano ang nagawa at paano ito sinuri

HINDI palatandaan ng pagiging tapos ang:
- «nakasulat na ang code at mukhang tama»
- «pumapasa ang unit test»
- «gumagana sa lokal ko»

Mas epektibo kaysa sa inaakala ang tahasang listahan ng hindi itinuturing na tapos: hindi na humihinto ang agent sa unang berdeng takbo.

Sino ang may karapatang maglagay ng «passing»

Ang susunod na hakbang ay alisin nang buo ang status ng pagiging tapos sa kamay ng agent. Nakaimbak ang mga feature sa isang listahan (halimbawa feature_list.json) na may mga field na «behavior», «verification command», at «state». Ang script lang ang maaaring maglipat ng feature sa passing: pinapatakbo nito ang pangkalahatang make check, saka ang verification command ng partikular na feature, at kapag pumasa ay itinatala ang status kasama ang hash ng commit bilang patunay. Kung hindi pumasa, nananatiling active ang feature. Walang «malapit na».

{
  "id": "F04",
  "behavior": "Nakakatanggap ang user ng email na may link at napapalitan ang password",
  "verification": "pytest tests/e2e/test_password_reset.py",
  "state": "active"
}

May bitag dito: sinusuri lang ng script ang nakasulat sa field na verification. Kung ang architectural na pagsusuri ay bahagi ng Definition of Done pero wala sa command ng feature, mananatiling hindi nakikita ang butas. Kaya dapat sakupin ng pangkalahatang make check ang lahat ng mandatoryong pagsusuri, hindi lang ang mga test.

Independiyenteng tagasuri

Hindi kailanman independiyenteng pinagmumulan ng katotohanan ang sariling ulat ng gumagawa. Ang istrukturang solusyon ay paghiwalayin ang mga tungkulin:

• tagaplano ang naghahati ng requirement sa mga feature na may acceptance criteria at hindi nagsusulat ng code;
• tagagawa ang nagpapatupad ng isang feature at nagpapatakbo ng test, pero hindi nagpapasya kung tapos na;
• tagasuri ang nagbibigay ng hatol ayon sa checklist ng pamantayan.

Hindi dapat makita ng tagasuri ang pangangatwiran ng tagagawa, dahil mamanahin nito ang kumpiyansa ng tagagawa. Ang natatanggap lang nito ay requirement, diff, at resulta ng pagtakbo. Sa Claude Code, madaling gawin ito gamit ang subagent dahil may sarili itong malinis na context. Mas mainam pa kung ibang modelo ang tagasuri, dahil iba ang mga blind spot nito. Ipinagbabawal ang pagsusuring «mukhang ayos naman»: bawat konklusyon ay dapat tumukoy sa file, linya, o log.

Mga mensahe ng error na maaaring ayusin ng agent mismo

Kapaki-pakinabang lang ang pagsusuri kung ang output nito ay humahantong sa pag-aayos. Ang «Test failed» o isang hubad na AssertionError ay walang sinasabi sa agent. Ang mabuting mensahe ay nagsasabi kung ano ang nasira, bakit umiiral ang panuntunan, at paano ito ayusin:

ERROR arch-check: app/services/refund.py nag-import ng app/db/session.py
WHY: hindi direktang kumokonekta sa database ang mga service, sa pamamagitan lang ng repository
FIX: gamitin ang RefundRepository mula sa app/repositories/refund.py

Ginagawang mungkahi ng ganitong format ang pagsusuri mula sa pagbabawal. Inaayos ng agent ang paglabag nang hindi ka na kailangang makialam.

Manwal na pagsusuri: saan pa rin kailangan

Hindi inaalis ng automation ang tao, pero pinapaliit ang papel nito. Kailangan ang manwal na pagsusuri kung saan mahirap gawing pormal ang pamantayan: hitsura ng interface, mga teksto, at kaginhawahan ng senaryo. Gawin ito ayon sa checklist ng acceptance criteria, hindi basta «pag-click-click». Kung pangalawang beses mo nang isinulat sa agent ang parehong komento, senyales ito na gawing awtomatikong pagsusuri: test, panuntunan ng linter, o grep guard sa make check.

Binabago ng E2E ang kilos ng agent kahit bago pa tumakbo

Hindi lang nasa mga nahuling bug ang halaga ng end-to-end na test. Kapag alam ng agent nang maaga na susuriin ng E2E na senaryo ang gawa nito, iba ang isusulat nitong code: iisipin nito ang kontrata sa katabing bahagi, hindi lang ang sarili nitong function, hahawakan ang mga error path, at hindi lalabagin ang mga hangganan ng arkitektura dahil lalabas ang paglabag sa takbo. Gumagana ang pagsusuri bilang limitasyon sa pasukan, hindi lang bilang filter sa labasan.

May kondisyon: may saysay ang E2E kapag malinaw ang mga hangganan ng sistema. Sa arkitekturang «spaghetti», patutunayan lang ng end-to-end test na gumagana pa ang spaghetti, at hindi nito ipapakita kung saan nilabag ang disenyo. Kaya unahin ang mga layer at panuntunan ng dependency bago magtayo ng mga end-to-end na senaryo. Kumokopya ang mga agent sa mga umiiral na pattern ng repository, kasama ang masasama, kaya mas mabuting ilagay ang mga limitasyon mula sa unang araw.

Mga karaniwang pagkakamali

• Pag-utos sa agent na «suriing mabuti». Pareho pa rin ang context, mananatiling sobra ang pagtatasa.
• Pagtingin sa 100% coverage bilang garantiya. Hindi tinatakpan ng unit coverage ang mga punto ng koneksyon.
• Pag-refactor bago makumpirma ang feature. Mahigpit ang pagkakasunod: tama → performance → estilo.
• Pag-mock sa E2E ng mga bagay na pinakamadalas pumalya. Dapat tumakbo nang totoo ang database, migration, at configuration sa end-to-end na test; ang mga mamahaling external API ay maaaring palitan ng test server.

Buod

Kapag sinabi ng agent na «tapos na» pero hindi gumagana ang feature, halos palaging nasa proseso ng pagsusuri ang problema, hindi sa modelo. Sukatin ang verification gap, isulat ang Definition of Done sa AGENTS.md, gawing mandatoryo ang E2E, ibigay ang status ng pagiging tapos sa script, at magdagdag ng independiyenteng tagasuri. Ang disenyong ito ay tinatalakay nang praktikal sa kursong harness engineering.