You wake up to five critical bug reports on a Monday morning. Your review monitoring tool has done its job. It caught ev

Unamka na ripoti tano za hitilafu (bug) muhimu asubuhi ya Jumatatu. Zana yako ya kufuatilia imefanya kazi yake. Imekamata kila ripoti ya hitilafu, kila maoni ya nyota moja yenye hasira, kila "app inaganda ninapobofya save." Unajua sawia ni nini kilichoharibika. Kinachokukosa ni wapi pa kutafuta.

Huo ndio ulikuwa ukuta niliokutana nao baada ya kujenga mfumo (pipeline) wangu wa kwanza. Ulikuwa unafuatilia maoni ya programu na logi za hitilafu zinazoingia bila shida, ukipanga kila sehemu ya maoni katika makundi yaliyopangwa vizuri: hitilafu, hitilafu za kusimamisha programu (crashes), au maombi ya vipengele vipya. Dashibodi ilionekana kuwa sawa. Lakini mchakato halisi wa kutatua hitilafu (debugging) haukuwa sawa.

Kujua kuwa hitilafu ipo ni hatua ndogo tu ya safari ndefu. Bado ilibidi nifungue IDE, nitafute kwa kutumia grep kwenye moduli, nilinganishe stack traces na msingi wa kodi (codebase) wa sasa, na kuunda upya njia ya hitilafu kichwani mwangu. Wakati tiketi zinapojikusanya na kahawa bado ikiwa ya moto, utafiti huo wa kizamani wa kutafuta kwa mikono unatumia muda ambao huna. Nilihitaji mfumo huo ufanye zaidi ya kuashiria matatizo tu. Nilihitaji uweze kuyachunguza.

Hivyo, niliujenga upya mfumo huo kwa lengo moja: kuchukua ripoti ghafi ya hitilafu na kutoa utambuzi uliothibitishwa. Sio aya ya mawazo ya LLM. Bali ni matokeo yaliyopangwa yanayotaja faili, kuonyesha mstari, kukadiria hatari, na kupendekeza suluhisho. Hivi ndivyo ilivyofanyika.

Kwa Nini Muundo ni Bora Kuliko Logi ya Mazungumzo

Nilitengeneza wakala wa uchunguzi (investigating agent) kwa kutumia PydanticAI. Sababu ilikuwa rahisi. Unapomwomba modeli ya lugha (language model) afikirie kuhusu kodi, matokeo yake ya kawaida ni mtiririko wa maandishi ya kirafiki. Hiyo inaweza kumsaidia msomaji binadamu, lakini haina manufaa kwa skrini (script) inayofuata. Nilihitaji mkataba unaoweza kusomwa na mashine.

Wakala huyo hurudisha modeli ya data iliyothibitishwa yenye nyanja (fields) nne mahususi: chanzo cha tatizo (root cause), faili zilizoathiriwa, mabadiliko yanayopendekezwa, na tathmini ya ugumu na hatari. Ikiwa modeli itakosa nyanja au itabuni njia ya faili (filepath) isiyopo, uhalali (validation) hushindwa na mimi ninaweza kuigundua mara moja. Umakini huo huufanya mfumo kuwa wa kuaminika.

Ili kufanya kazi halisi ya upelelezi, wakala huyo anapewa zana nne za kusoma tu (read-only) na hakuna kingine. Anaweza kutafuta kodi kupitia grep, kusoma masafa mahususi ya mistari kutoka kwenye faili, kuorodhesha maudhui ya diziti, na kupata alama kama madarasa (classes) au kazi (functions). "Kusoma tu" ndiyo sehemu muhimu. Sikutaka wakala mwenye uwezo wa kuandika (write access) azurure kwenye sehemu yangu ya kodi (repository) saa nane za usiku. Kwanza elewa, kisha hariri.

Ramani ya Repo: Muktadha Kabla ya Zana

Toleo la kwanza la wakala lilikuwa sahihi lakini lilikuwa na gharama kubwa sana. Lilikuwa linatumia tokeni nyingi kama mtalii anayetembea kwa kuzunguka-zunguka. Modeli ingekuwa inaita list-dir, kisha grep, kisha kusoma faili, kisha list-dir tena, ikijaribu kuunda picha ya muundo wa mradi hatua kwa hatua kwa kutumia tokeni nyingi.

Suluhisho lilikuwa ni kutengeneza ramani fupi ya repo kabla hata wakala hajajanza. Ramani hii ni muhtasari uliopunguzwa wa repo: faili muhimu, kazi au madarasa yake makuu, na jinsi moduli kuu zinavyoungana. Ilinganishe na kumkabidhi wakala GPS badala ya kumuomba agundue barabara kwa majaribio na makosa.

Ukiwa na ramani hiyo kwenye dirisha lake la muktadha (context window), wakala huyo hapotezi muda kutafuta kama src/utils/parser.ts ipo. Tayari anajua mazingira. Huenda moja kwa moja kwenye eneo la tukio ambapo moshi unanyanyuka. Mabadiliko hayo moja yalipunguza kabisa hatua ya kuzurura.

Funeli ya Zana: Kulazimisha Hitimisho

Hata kukiwa na ramani, wakala alikuwa anaweza kusita. Angepata faili inayotiliwa shaka, kisha ajitilie shaka mwenyewe, kisha atafute tena, kisha asome faili nyingine, akijikuta kwenye mzunguko usioisha wa "nijaribu mara moja tu zaidi." Nilihitaji njia ya kulazimisha kasi.

Nilitekeleza funeli ya zana ya awamu tatu inayozuia kile ambacho wakala anaweza kufanya anapoendelea.

Awamu ya kwanza ni uchunguzi. Wakala ana ufikiaji kamili wa zana zote nne. Anaweza kutafuta, kupitia, na kusoma chochote anachohitaji ili kurudia hitilafu katika uelewa wake.

Awamu ya pili ni uchunguzi wa kina (deep-dive). Mara tu wakala anapobaini maeneo yenye hitilafu, anapoteza zana za ugunduzi. Anaweza kusoma faili tu. Hakuna tena grep, hakuna tena kuorodhesha diziti. Katika hatua hii lazima asome kodi ambayo tayari ameshaipata na kujenga mfululizo wa ushahidi.

Awamu ya tatu ni kutoa matokeo. Zana zote zimefungwa. Wakala hawezi tena kuulizia msingi wa kodi. Lazima aketi chini na kuandika ripoti. Hii inazuia mzunguko usioisha wa "acha nikague kitu kingine kimoja."

Funeli hiyo ilipunguza wastani wa idadi ya wito wa zana (tool calls) kutoka zaidi ya arobaini kwa kila uchambuzi hadi takriban kumi. Wakala akawa na kasi zaidi, gharama nafuu, na kwa kushangaza, kuwa na ujasiri zaidi kwa sababu ilimlazimu kutoa hitimisho.

Kuifanya Backend Iweze Kubadilishwa Kirahisi

Sikutaka kuifunga mifumo hiyo kwa mtoa huduma mmoja wa modeli. Ninatumia injini tofauti kulingana na kazi. Wakati mwingine Claude Code, wakati mwingine Grok Build, au chochote ambacho ni cha bei rahisi zaidi kwa wakati huo. Ili kuifanya mantiki ya msingi isitegemee mtoa huduma maalum, nimegawanya kazi katika hatua mbili.

Hatua ya kwanza ni uchunguzi. Wakala wa uandishi wa kodi, ambao anaweza kuwa modeli yoyote yenye uwezo, husoma ramani ya repo, hutumia zana, na kutoa ripoti ghafi ya markdown. Hii ndiyo sehemu ya gharama kubwa ya kufikiri.

Hatua ya pili ni uundaji wa muundo. LLM ya bei rahisi na ya haraka huchukua markdown hiyo na kuifanyia uundaji upya katika muundo mkali wa Pydantic. Hatua hii haihitaji uwezo mkubwa wa kufikiri. Ni uchukuaji na uundaji wa muundo tu, hivyo huendeshwa kwenye vifaa vyepesi vya kompyuta.

Kwa sababu mpaka ni wazi, ninaweza kubadilisha backend bila kugusa mantiki ya uhakiki. Ripoti ya markdown hufanya kazi kama kiunganishi cha ulimwengu wote kati ya ubongo wa uchunguzi na matokeo yaliyoundwa ambayo ninayotumia.

Kilichofanya Kazi Hasa

Mpangilio huu umebadilisha jinsi ninavyoshughulikia matatizo yanayoingia. Tabaka la uainishaji bado hutenganisha hitilafu (bugs) kutoka kwa maombi ya vipengele vipya, lakini sasa tabaka la uchambuzi huanza kazi mara moja baada ya hapo. Wakati ninapofungua edita yangu, tayari nina njia ya faili, mfululizo wa mistari, na mabadiliko yanayopendekezwa yanayonisubiri. Bado ninapitia kila kitu kwa mkono. Hii ni msaada, siyo uendeshaji wa kiotomatiki. Lakini ukusanyaji wa muktadha ambao ulikuwa