Kumbukumbu ya wakala wa AI kati ya vikao: faili la maendeleo, daftari la maamuzi, git na script ya kuanza

Kwa nini wakala hakumbuki chochote

Modeli haihifadhi hali kati ya uendeshaji. Kila kitu ambacho wakala "anajua" kuhusu kazi yako kiko kwenye dirisha la muktadha la kikao cha sasa: faili alizosoma, matokeo ya amri, mazungumzo nawe. Kikao kikifungwa au muktadha ukijaa, kikao kipya kinaanza kutoka mwanzo na kinaona tu kilichoandikwa diskini.

Mfano unaofaa: mhandisi mwenye kipaji anayefika kazini kila asubuhi akiwa amefutiwa kumbukumbu kabisa. Ataelewa msimbo haraka, lakini hatakumbuka ni chaguo gani la usanifu lilichaguliwa jana, kwa nini mengine yalikataliwa, na majaribio yako katika hali gani. Bila maandishi, atatumia dakika kumi na tano hadi ishirini kuchunguza, na kuna uwezekano mkubwa wa kurudia kile ulichokwisha kukikataa kwa makusudi.

Kwa hiyo kumbukumbu ya wakala wa AI si sifa ya modeli, bali sehemu ya harness: seti ya faili na sheria unazozibuni mwenyewe. Habari njema ni kwamba hauhitaji hifadhidata za vekta wala huduma maalum. Faili chache za Markdown, git na nidhamu zinatosha.

Kwa nini dirisha kubwa la muktadha halitatui tatizo

Inaonekana kwamba ni bora kusubiri modeli yenye dirisha kubwa zaidi. Lakini kazi ngumu itajaza dirisha lolote: wakala anasoma msingi wa msimbo, anakusanya historia ya maamuzi, anapokea matokeo marefu ya majaribio, na anashikilia mazungumzo yote. Mahitaji yanakua pamoja na dirisha. Hili ni tatizo la usanifu, si la ukubwa.

Pia kuna athari ya pili. Karibu na mpaka wa dirisha, modeli nyingi huanza kuharakisha kumaliza: zinaruka ukaguzi au kuchagua suluhisho rahisi badala ya sahihi. Anthropic inaeleza uchunguzi huu kwa modeli zake, na ukubwa wa athari hutofautiana kati ya modeli. Kikao kirefu kwenye ukomo wa muktadha si hatari ya kupoteza taarifa tu, bali pia hatari ya kuharibu ubora wa kazi.

Kubana muktadha: nini kinahifadhiwa na nini kinapotea

Kubana (compaction) ni kufinya sehemu ya awali ya mazungumzo kuwa muhtasari mfupi ili kupata nafasi ndani ya kikao kile kile. Katika Claude Code hili hufanywa na amri /compact, na pia hutokea kiotomatiki muktadha unapokaribia ukomo. Amri /clear, kinyume chake, inafuta historia na kuanza mazungumzo upya.

Tatizo la kubana ni kwamba muhtasari kwa kawaida huhifadhi "nini" na kupoteza "kwa nini". Msimbo uliokamilika unabaki kwenye faili, lakini hoja — kwa nini chaguo B lilichaguliwa, kwa nini maktaba haikutumika, kwa nini uboreshaji uliruka kwa makusudi — zinabanwa hadi maneno machache au zinatoweka. Hatua inayofuata ya wakala "inaboresha" uamuzi uliokusudiwa kwa sababu haoni tena sababu zake.

Kanuni ya vitendo bila vipimo tata: kazi ikichukua takriban 60% ya dirisha, acha kuandika msimbo na uandae makabidhiano ya kazi. Ikiwa muktadha umetumika 40% na mwisho wa kazi uko karibu, kubana kunatosha.

Vizalia vinne vinavyounda kumbukumbu ya wakala

Badala ya kutegemea kumbukumbu ya modeli, weka daftari la safari. Lina sehemu nne, na kila moja ina jukumu lake.

1. PROGRESS.md — tuko wapi sasa.
2. DECISIONS.md — kwa nini imefanywa hivi na si vinginevyo.
3. Commit za git — vituo vya ukaguzi vya hali bila gharama.
4. Itifaki ya kubadilishana zamu katika AGENTS.md — la kufanya mwanzoni na mwishoni mwa zamu.

PROGRESS.md: faili la maendeleo

Linajibu swali moja: mradi uko katika hali gani sasa hivi. Wakala anaisoma kwanza mwanzoni mwa kikao na kuisasisha mwisho kabla ya kuondoka. Faili ni fupi, linaandikwa upya badala ya kuongezwa bila mwisho: historia inaishi kwenye git.

# PROGRESS.md

## Lengo la sasa
Utafutaji wa katalogi ya bidhaa (kipengele search-01)

## Hali
- HEAD: 4f2a9c1
- make check: kijani, majaribio 142/142
- Imekamilika: faharasa kwenye PostgreSQL (tsvector), endpoint GET /search
- Imethibitishwa: majaribio ya kitengo + ombi la mkono la curl kwa maswali 3

## Vizuizi
- Hakuna data ya mofolojia kwa lugha ya Kazakh — tunasubiri uamuzi

## Hatua inayofuata
Ongeza paginesheni kwenye GET /search, kigezo: jaribio la ukurasa wa 2

Angalia sehemu nne ambazo zinatosha kwa makabidhiano: heshi ya commit, sehemu ya majaribio yanayopita, vizuizi na hatua inayofuata. Ikiwa kikao kipya hakiwezi kuendelea bila shaka kwa kutumia faili hili, basi kiolezo kinakosa sehemu.

DECISIONS.md: daftari la maamuzi

Hushikilia "kwa nini" hasa ambayo hupotea wakati wa kubana. Muundo wa rekodi: uamuzi, sababu, kilichokataliwa na kwa nini, vikwazo.

## 2026-03-14 — Akiba ya mipangilio ya mtumiaji kwenye Redis
- Uamuzi: Redis, TTL dakika 5, kufuta akiba kikamilifu wakati wa kuandika.
- Sababu: inasomwa kwenye kila ombi, na data ni ndogo sana.
- Kilichokataliwa: materialized view kwenye PostgreSQL — mabadiliko ni ya mara kwa mara,
  matengenezo hayalipi.
- Kikwazo: usihifadhi akiba ya mipangilio ya malipo.

Mstari wa thamani zaidi hapa ni "Kilichokataliwa". Ndio unaozuia kikao kijacho "kuboresha" uamuzi kurudi kwenye chaguo ambalo tayari lilijadiliwa na kutupwa. Tofauti na faili la maendeleo, daftari la maamuzi hujazwa tu: rekodi za zamani hazifutwi, zinawekwa alama kuwa zimebadilishwa na mpya.

Historia ya git kama vituo vya ukaguzi

Commit tayari ni picha zilizopangwa za hali ya kazi. Wakala anaweza kusoma git log na git diff na kurejesha kilichobadilika. Ili historia ifanye kazi kama kumbukumbu, ujumbe wa commit lazima ueleze lengo, si kurudia tofauti.

# vibaya
git commit -m "update search.py"

# vizuri
git commit -m "search: faharasa ya tsvector badala ya LIKE

LIKE '%q%' haitumii faharasa, kwa bidhaa 200k swali linachukua sekunde 1.8.
Paginesheni bado haijafanywa, angalia PROGRESS.md."

Commit ndogo na za mara kwa mara baada ya kila majaribio yanayopita pia hutoa sehemu ya kurudi nyuma. Kikao kikienda mrama, ni rahisi kurudi kwenye hali ya mwisho iliyothibitishwa kuliko kufumbua mabadiliko yaliyokaribia kukamilika.

Itifaki ya kubadilishana zamu katika AGENTS.md

Faili za hali hazina maana ikiwa wakala hajui kuzihusu. Kwa hiyo kwenye faili la maagizo la kuingia (AGENTS.md au CLAUDE.md) kunaandikwa itifaki fupi: la kufanya wakati wa kuingia na wakati wa kutoka.

## Kuingia zamu
1. Soma PROGRESS.md na DECISIONS.md.
2. Tafuta kazi hai kwenye .agent/feature_list.json.
3. Endesha make check — hakikisha hazina iko sawa.
4. Endelea na "Hatua inayofuata", bila kufungua upya yaliyoamuliwa.

## Kutoka zamuni
1. Endesha make check, fanya commit ya hali ya kijani.
2. Sasisha PROGRESS.md: HEAD, majaribio, vizuizi, hatua inayofuata.
3. Ongeza maamuzi mapya kwenye DECISIONS.md.
4. Usiache kazi ambayo haijakamilika kwenye working tree.

Ni vyema kuweka itifaki fupi: ni mistari michache kwenye faili la kuingia, si ukurasa mzima wa maelekezo.

Script ya kuanza: jinsi ya kuharakisha mwanzo wa kikao

Ili wakala asikusanye picha kwa mkono, mpe script moja inayokagua mazingira na kuonyesha hali. Script inapaswa kuwa idempotent — inaweza kuendeshwa mara nyingi bila madhara — na kumalizia kwa ujumbe wazi wa utayari.

#!/usr/bin/env bash
set -euo pipefail

echo "== 1. Mazingira =="
command -v uv >/dev/null || { echo "FAIL: uv haijawekwa"; exit 1; }
uv sync --frozen

echo "== 2. Hazina =="
if [ -n "$(git status --porcelain)" ]; then
  echo "WARN: working tree ni chafu"
else
  echo "OK: safi"
fi
echo "HEAD: $(git log -1 --oneline)"

echo "== 3. Ukaguzi =="
make check

echo "== 4. Hali =="
cat PROGRESS.md

echo "Tayari kufanya kazi"

Katika itifaki ya kuingia basi inatosha mstari mmoja: "endesha scripts/init.sh". Katika Claude Code uendeshaji huu unaweza kuwekwa kiotomatiki kwa hook ya kuanza kikao (tukio la SessionStart), lakini hata bila hook wakala ataendesha script kwa maagizo ya faili.

Nini cha kuweka kwenye kumbukumbu ya wakala na nini kisiwekwe

Kosa kuu ni kugeuza kumbukumbu kuwa jaa la taka. Kila mstari ambao wakala anausoma mwanzoni unachukua nafasi kwenye muktadha, na mambo yasiyo muhimu yanafunika yale muhimu.

Tenganisha pia kwa muda wa maisha. Sheria za mradi hubadilika mara chache na zinahusu kazi zote — zina nafasi kwenye faili la maagizo la kuingia. Hali hubadilika kila kikao — ina nafasi kwenye faili la maendeleo. Zikichanganywa, faili la kuingia linakua haraka kwa maelezo yaliyopitwa na wakati.

Kikao cha kwanza: uanzishaji kama awamu tofauti

Kumbukumbu kati ya vikao haitasaidia ikiwa kikao cha kwanza kiliingia kwenye fujo. Picha ya kawaida: unaandika kwenye hazina tupu "ongeza utafutaji", na baada ya nusu saa inagundulika kwamba mfumo wa majaribio umewekwa vibaya na muundo wa migration si sahihi. Utafutaji umeonekana, lakini msingi ni mbovu.

Sababu ni kwamba utekelezaji na uanzishaji vinaboresha vitu tofauti: cha kwanza ni idadi ya vipengele vilivyokamilika katika kikao hiki, cha pili ni kasi na uaminifu wa kazi zote zinazofuata. Wakala huelekea kwenye matokeo yanayoonekana, yaani msimbo. Kwa hiyo uanzishaji unapaswa kutengwa kuwa kikao chake chenye kigezo cha kukamilika cha masharti manne.

• Kuanzishwa: make setup na make dev zinafanya kazi kutoka clone safi.
• Kukaguliwa: kuna make test na angalau jaribio moja halisi linalopita.
• Kuonekana kwa maendeleo: faili la hali lipo na linasomeka.
• Kuchukua kazi: kuna orodha ya kazi zenye vigezo vya kukubalika.

Ukianzisha miradi mipya mara kwa mara, tengeneza kiolezo cha hazina: Makefile, mfumo wa majaribio, mfupa wa AGENTS.md, folda ya .agent/, scripts/init.sh, linter na CI. Basi uanzishaji utabaki kwenye maalum ya mradi husika tu.

Jinsi ya kuthibitisha kwamba kumbukumbu inafanya kazi

Kipimo cha uaminifu zaidi ni muda kutoka mwanzo wa kikao kipya hadi mabadiliko ya kwanza yenye maana ya msimbo. Bila vizalia, kwa kawaida ni dakika kumi na tano hadi ishirini za uchunguzi; kwa makabidhiano mazuri ni dakika mbili au tatu. Pima mara moja kabla na baada, na utaona kama nidhamu hii inalipa.

Njia ya pili ni jaribio la kuanza baridi. Fungua kikao kipya, andika "endelea" na uulize maswali matano: lengo la sasa ni nini, majaribio yako katika hali gani, ni uamuzi gani uliochukuliwa kuhusu mada muhimu na kwa nini, nini kinazuia, na hatua inayofuata ni ipi. Ikiwa wakala anajibu yote matano kutoka kwenye faili, bila kubahatisha, kumbukumbu imejengwa vizuri. Kila jibu lisilo na uhakika ni sehemu inayokosekana kwenye kiolezo.

Makosa ya kawaida

• Faili la maendeleo linakua tu. Baada ya mwezi lina mistari mamia ya historia. Liandike upya kulingana na hali ya sasa; historia iko kwenye git.
• Hakuna mstari wa "kilichokataliwa". Daftari la maamuzi bila chaguzi zilizokataliwa haliwezi kuzuia mijadala ya kurudia.
• Wakala anasasisha hali "kwa jicho". Andika jinsi ilivyothibitishwa: amri na matokeo, si "kila kitu kinafanya kazi".
• Makabidhiano kwenye ukomo wa dirisha. Karibu na mpaka wa muktadha wakala tayari anaharakisha; anza handoff mapema, takriban kwa 60%.
• Working tree chafu wakati wa kutoka. Mabadiliko yaliyokaribia kukamilika bila commit yanachanganya kikao kijacho.

Kwa ufupi

Kumbukumbu ya wakala wa AI kati ya vikao inajengwa juu ya faili, si modeli: PROGRESS.md inahifadhi hali ya sasa, DECISIONS.md inahifadhi sababu na chaguzi zilizokataliwa, commit za git ni vituo vya ukaguzi vyenye maelezo ya lengo, na itifaki ya kubadilishana zamu katika AGENTS.md inalazimisha kusoma na kusasisha yote haya. Script ya kuanza inapunguza mwanzo hadi amri moja, na jaribio la kuanza baridi linaonyesha kama kumbukumbu inatosha. Daftari la safari la wakala na mkataba wa bootstrap vinafafanuliwa kwa vitendo katika kozi ya harness engineering.