Uwazi wa wakala wa AI (observability): jinsi ya kujua wakala alifanya nini na nini cha kurekodi

Uwazi wa wakala wa AI ni nini

Uwazi wa wakala wa AI ni uwezo wa kujibu maswali matatu kwa kutumia vizalia (artifacts), si kumbukumbu wala maneno ya wakala: amefanya nini, kwa nini amefanya hivyo na kinathibitishwa na nini, na kama matokeo ni sahihi. Ikiwa baada ya dakika ishirini za kazi wakala anasema «imekamilika, lakini majaribio mawili yanaanguka, labda kwa sababu ya muda», na akiulizwa «ni njia zipi zimeguswa» anajibu «nipe nione msimbo» — hakuna uwazi. Wakala si mjinga: amekosa tu cha kuonyesha.

Tatizo ni la kimfumo. Wakala yuleyule ndani ya wiki moja anaweza kusema mara kumi kwa uaminifu «imekamilika», na kila mara neno hilo litamaanisha kitu tofauti: mahali pengine majaribio yote yamekimbizwa, mahali pengine moja tu, mahali pengine hakuna. Kadiri mradi unavyoishi, kila kikao kipya kinakuwa ghali zaidi kwa sababu huanza kwa kuchimba.

Tabaka mbili: utekelezaji na mchakato

Uwazi mara nyingi unachanganywa na kumbukumbu (logs), lakini kumbukumbu ni nusu tu.

Utekelezaji pekee: unaona kilichoanguka, lakini hujui walitaka nini. Mchakato pekee: unaelewa walichotaka, lakini hauoni kwa nini hakikufaulu. Unahitaji zote mbili.

Kwa nini wakala hawezi kulifanya hili mwenyewe

Kumwambia wakala «rekodi vizuri zaidi» hakufanyi kazi kwa sababu tatu.

• Hajui asichokijua. Wakala hatarekodi ishara ambayo hajui kwamba ni muhimu.
• Muundo unabadilika. Katika kikao kimoja anaandika kwa kina, katika kingine kwa mstari mmoja. Haiwezekani kulinganisha vikao au kuhesabu jumla.
• Mchakato hauwezi kufungwa kwa kumbukumbu. Jibu la «kwa nini hivi» linaishi kwenye nyaraka zilizoandikwa kabla ya kazi, si kwenye matokeo ya amri.

Kwa hiyo uwazi unajengwa ndani ya harness — mazingira ya wakala: violezo, hooks, skripti, muundo wa ripoti wa lazima.

Nini cha kurekodi: seti ya chini

Jarida zuri si nakala ya kila kitu, bali seti ya ukweli ambao kwao unaweza kurejesha mwenendo wa kazi na kuhesabu takwimu.

• Vitambulisho: kitambulisho cha kikao, cha kazi au kipengele, modeli ya wakala.
• Vitendo vyenye madhara ya nje: amri zilizoendeshwa, faili zilizobadilishwa. Kusoma faili kwa kawaida hakuhitaji kuandikwa.
• Matokeo ya ukaguzi: amri ya ukaguzi, msimbo wa kurudi, majaribio mangapi yamepita na mangapi yameanguka.
• Majaribio tena (retries): ilichukua majaribio mangapi kwa hatua, na yalitofautianaje.
• Matumizi: tokeni na muda, ikiwa zana inavitoa.
• Matokeo ya mwisho: kazi imekubaliwa, imekataliwa au imeachwa, na kwa nini.

Usirekodi: siri, tokeni za ufikiaji, data binafsi kutoka kwenye matokeo ya amri. Jarida linaweza kuishia kwenye ufikiaji wa pamoja au kurudi kwenye muktadha wa modeli.

Jarida la vitendo kupitia hooks za Claude Code

Katika Claude Code jarida ni rahisi kuliendesha kwa hooks — amri zinazoanzishwa na zana yenyewe, si na modeli, kwa hiyo zinafanya kazi kila wakati. Hook inapokea JSON yenye maelezo ya tukio, ikiwemo kitambulisho cha kikao, jina la zana na vigezo vyake. Mfano wa usanidi kwenye .claude/settings.json unaoongeza mstari kwenye jarida baada ya kila wito wa Bash, Edit au Write:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash|Edit|Write",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/log-action.sh" }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# .claude/hooks/log-action.sh — mstari mmoja wa JSON kwa kila kitendo
mkdir -p .agent/logs
jq -c '{ts: (now | todate), session: .session_id, tool: .tool_name,
        cmd: .tool_input.command, file: .tool_input.file_path}' \
  >> .agent/logs/actions.jsonl || true

Muundo wa JSONL (rekodi moja ya JSON kwa mstari) ni rahisi kuchuja kwa jq na kupakia kwenye mfumo wowote wa uchambuzi. Zaidi ya hayo, Claude Code yenyewe huhifadhi historia kamili ya vikao ndani ya nchi kwenye saraka ~/.claude/projects/ — unaweza kuifungua ukitaka kuona fikra na matokeo kamili, lakini kwa takwimu jarida lako fupi ni rahisi zaidi.

Trace: trace moja kwa kikao, span moja kwa kazi

Wakala wanapokuwa wengi au wanafanya kazi kwa ratiba, majarida ya maandishi hayatoshi: unahitaji mikusanyiko. Hapa zana za kawaida za distributed tracing na kiwango cha OpenTelemetry zinafaa.

• Trace — kikao kimoja cha wakala.
• Span — kazi moja ndani ya kikao.
• Span zilizowekwa ndani ya nyingine — hatua za uthibitisho: build, majaribio, e2e.

Sifa za chini kwa kila span: kitambulisho cha kipengele na kikao, modeli, matokeo ya ukaguzi, tokeni, idadi ya majaribio tena. Data kama hii inasomwa kwenye Jaeger, Grafana Tempo, Honeycomb, na inajibu maswali ambayo kikao kimoja hakiyaonyeshi: aina gani ya kazi inahitaji majaribio tena mara nyingi, wakala anatumia tokeni nyingi wapi, na baada ya mabadiliko gani ya harness kiwango cha kazi zilizokubaliwa kiliporomoka. Claude Code ina usafirishaji uliojengwa ndani wa vipimo na matukio kupitia OpenTelemetry — unawashwa kwa vigezo vya mazingira, maelezo yako kwenye nyaraka za zana.

Commits kama jarida

Jarida rahisi na la kuaminika zaidi tayari unalo — ni git. Inahitaji tu kusomeka.

1. Commit moja — kazi moja. Hapo git log inalingana na orodha ya kilichofanyika, na kurudisha kazi nyuma ni git revert moja.
2. Kwenye ujumbe — kilichobadilishwa na kilivyothibitishwa. Si «fix», bali «kilichobadilishwa, kwa nini, kimethibitishwa kwa amri gani».
3. Commit baada ya ukaguzi wa kijani pekee. Hapo kila nukta ya historia ni hali inayofanya kazi, na git bisect inampata mhalifu.

fix(payments): kuzungusha punguzo hadi senti

Punguzo lilihesabiwa kwa float, kwa kiasi 999.99 senti ilipotea.
Hesabu nimeihamishia kwa int kwa senti.
Imethibitishwa: make test (142 passed), make e2e checkout — sawa.
Nje ya upeo: kuzungusha kwenye ripoti, kimeandikwa BACKLOG.md.

Ripoti ya wakala: ushahidi badala ya hisia

Ujumbe wa mwisho wa wakala pia ni kizalia cha uwazi, ikiwa una muundo usiobadilika. Andika kiolezo kwenye AGENTS.md au CLAUDE.md:

## Ripoti mwishoni mwa kazi
- Kilichofanyika: orodha ya mabadiliko (faili — maudhui)
- Jinsi kilivyothibitishwa: amri halisi na matokeo yake
- Kisichothibitishwa na kwa nini
- Mikengeuko kutoka kwenye makubaliano ya kazi
- Maswali wazi kwa binadamu

Kanuni kuu: kila dai linarejelea ushahidi — faili na mstari, matokeo ya jaribio, ingizo la jarida. «Inaonekana sawa» na «nadhani ni sawa» si ripoti. Kipengele cha «kisichothibitishwa» ni cha thamani sana: kinaonyesha waziwazi mipaka ya uhakika.

Makubaliano kabla ya msimbo na kigezo baada yake

Tabaka la mchakato linaanza kabla ya kazi. Makubaliano mafupi ya kazi (sprint contract) yanaeleza upeo, vigezo vya kukubali, sehemu ya «nje ya upeo», na maswali wazi ambayo binadamu anayaamua. Sehemu ya «nje ya upeo» inazuia nusu ya mabishano kuhusu matokeo.

Baada ya kazi, matokeo yanatathminiwa kwa kigezo, si kwa hisia. Vinginevyo wakaguzi wawili wenye uzoefu watatoa hukumu tofauti, na tathmini inageuka bahati nasibu.

Kila kipimo kinakadiriwa A/B/C/D, na alama isiyo na marejeo si halali. Kanuni rahisi ya uamuzi: D moja au C mbili — kukataa kwa orodha ya kinachopaswa kurekebishwa. Kigezo hiki hiki kinaweza kutumiwa na wakala mwingine anayekagua.

Jinsi ya kuchambua alichofanya wakala katika kikao

Ikiwa ripoti haipo au huna imani nayo, pitia vizalia kwa mpangilio huu.

1. Hali ya mti wa faili: git status — kilicho bila commit, kama kuna faili takataka.
2. Historia: git log --stat tangu mwanzo wa kikao — commits na faili gani.
3. Ukubwa wa mabadiliko: git diff --stat main...HEAD, kisha diff kamili ya faili muhimu.
4. Jarida la vitendo: ni amri zipi ziliendeshwa na ukaguzi ulirudisha nini.
5. Uthibitisho upya: endesha build na majaribio mwenyewe. Amini matokeo ya amri, si muhtasari wa maneno.

# amri ambazo wakala aliendesha katika kikao cha mwisho
jq -r 'select(.tool=="Bash") | .cmd' .agent/logs/actions.jsonl | tail -n 30
# faili gani zilibadilishwa mara nyingi zaidi
jq -r '.file // empty' .agent/logs/actions.jsonl | sort | uniq -c | sort -rn | head

Makosa ya kawaida

• Kurekodi kila kitu. Gigabaiti za nakala hazisomwi na mtu. Rekodi vitendo vyenye madhara ya nje na matokeo ya ukaguzi.
• Muundo huru. Ikiwa wakala ndiye anayeamua muundo wa jarida, hakutakuwa na takwimu. Harness ndiyo inayoamua muundo.
• Kuamini ripoti bila matokeo ya amri. «Majaribio ni ya kijani» bila matokeo ni maoni tu.
• Majaribio tena bila kipimo. Bila sababu ya kushindwa, wakala anarekebisha sehemu za kubahatisha. Dai kwanza utambuzi wenye marejeo ya jarida, kisha marekebisho.
• «Tutasafisha baadaye». Faili za utatuzi na mabadiliko ambayo hayajawekwa commit yanachanganya kikao kijacho: hakiwezi kutofautisha cha muda na cha makusudi.

Hitimisho

Uwazi wa wakala wa AI unajengwa kwa tabaka mbili: utekelezaji (jarida la vitendo kupitia hooks, traces, commits zenye maelezo ya ukaguzi) na mchakato (makubaliano ya kazi kabla ya msimbo, kigezo na ripoti yenye ushahidi). Hapo neno «imekamilika» linamaanisha kitu kile kile katika kila kikao, na kuchambua kazi ya wakala kunachukua dakika. Mada hii tunaifundisha kwa vitendo katika kozi ya harness engineering, kwenye mradi wa kweli wa backend ya malipo.