Jinsi ya kumpa wakala wa AI kazi: kipengele kimoja kwa wakati, orodha ya vipengele na vigezo vya kukamilika

Kwa nini wakala hujaribu kufanya kila kitu kwa mara moja

Unamwomba wakala atengeneze usajili. Baada ya saa mbili, tofauti (diff) ina faili kumi na mbili zilizobadilishwa na mistari mia nane mipya: modeli ya mtumiaji, uthibitishaji wa barua pepe, huduma ya barua iliyounganishwa, usimbaji wa nywila, middleware iliyopangwa upya na majaribio yaliyohamishwa. Kila kitu kimeunganishwa kwa nguvu, na hakuna hata mfumo mmoja unaofanya kazi kikamilifu. Kikao kijacho kinafungua msimbo huu na hakielewi pa kuanzia.

Chanzo si "modeli mbaya". Binadamu ana hisia ya "inatosha kwa leo" na uchovu wa kawaida, ambavyo vyenyewe vinaweka mipaka ya kazi. Wakala hana hata moja kati ya hivi. Kuongeza "na pia nitarekebisha usimamizi wa makosa" kunamgharimu tokeni chache tu, lakini gharama kwa mradi ni halisi: umakini unatawanyika, utegemezi unaongezeka, na hakuna kilichokamilika.

Pia kuna hesabu rahisi. Acha C iwe uwezo muhimu wa muktadha, na k idadi ya kazi ambazo wakala anazishikilia kwa wakati mmoja. Kila kazi inapata takriban C/k ya rasilimali ya kufikiri. Thamani hii ikishuka chini ya inayohitajika kumaliza kazi moja, hakuna kazi inayokamilika. Kwa hiyo jibu sahihi kuhusu jinsi ya kumpa wakala wa AI kazi halianzi na maneno ya prompt, bali na kizuizi: kazi moja tu kwenye kazi.

Kanuni ya kipengele kimoja (WIP=1)

WIP ni work in progress, yaani idadi ya kazi zinazoendelea. Kwa wakala huiweka sawa na moja: wakati wowote kipengele kimoja tu kiko hai, na kinachofuata huanza tu baada ya cha sasa kupita ukaguzi. Kanuni hii imeandikwa kwenye faili la maagizo la mradi (AGENTS.md au CLAUDE.md) ili wakala aione katika kila kikao:

## Sheria za kazi
- Wakati wowote, hali `active` inashikwa na KIPENGELE KIMOJA TU.
- Kipengele kinachofuata kianze tu baada ya cha sasa kuhamia `passing`.
- Ni marufuku "kwa pamoja" kurekebisha muundo, kubadilisha majina, kupanga upya
  saraka, au kurekebisha hitilafu zisizohusiana. Ukiona tatizo, liandike
  kwenye `BACKLOG.md` kisha endelea.
- Mabadiliko nje ya wigo wa kipengele kilicho hai ni ukiukaji, hata kama ni ya manufaa.

Kipengele cha mwisho ni muhimu kuliko kinavyoonekana. Wakala huamini kwa dhati kwamba "mambo ya ziada" yake ni muhimu, na mara nyingi ni kweli. Lakini marekebisho ya manufaa nje ya wigo bado yanachanganya kazi mbili katika tofauti moja, na haiwezekani tena kuyarudisha nyuma au kuyakagua kando.

BACKLOG.md: "mambo ya ziada" yanaenda wapi

Msukumo wa "nirekebishe pia" hauwezi kukatazwa tu; unahitaji njia halali ya kutokea. Njia hiyo ni faili BACKLOG.md: wakala anaandika tatizo lililoonekana kwa mistari moja au miwili kisha anarudi kwenye kipengele cha sasa. Taarifa haipotei, na wigo hauongezeki. Bila backlog, sheria ya kipengele kimoja itakwepwa mapema au baadaye, kwa sababu wakala anaona "kunyamaza kuhusu hitilafu" kuwa baya zaidi kuliko ukiukaji.

# BACKLOG.md
- [ ] middleware/errors.py: muundo tofauti wa makosa katika /auth na /orders
- [ ] tests/: fixtures za mtumiaji zinarudiwa kwenye faili tatu
- [ ] je, uthibitishaji wa barua pepe unahitajika wakati wa usajili? — kuuliza

Vigezo vya kukamilika: "imekamilika" ni amri

Nusu ya pili ya tatizo ni kwamba wakala mwenyewe anaamua kama kazi imekwisha. "Msimbo unaonekana sawa", "kazi ipo", "hakuna makosa ya kukusanya" — hayo ni hisia, si ukweli. Kigezo cha kukamilika kwa wakala kinapaswa kuwa amri inayoweza kuendeshwa yenye matokeo yasiyo na utata: imepita au haijapita.

F01: usajili wa mtumiaji
verification: pytest tests/e2e/test_auth.py::test_register_flow
state: active

Tofauti kati ya kigezo dhaifu na kigezo kikali inaonekana wazi kwenye mifano:

Amri nzuri ya ukaguzi ni thabiti (matokeo sawa kwa msimbo uleule), inaendeshwa bila binadamu, na inakagua tabia kutoka nje, kama mtumiaji au mteja wa API anavyoiona. Ikiwa haiwezekani kuandika amri kama hiyo, hiyo ni ishara kwamba kazi haijaelezwa vizuri.

Kugawanya kazi: kipengele kinapaswa kuwa na ukubwa gani

Swali linalofuata mara nyingi ni kipengele kinapimwa vipi. Kazi pana sana haitamaliziwa kikao kimoja, na kazi nyembamba sana inazama kwenye gharama za kuanzisha, muktadha na ukaguzi.

• Pana mno: "tekeleza kikapu". Hii ni wiki ya kazi na mandhari kadhaa.
• Inafaa: "mtumiaji anaweza kuongeza bidhaa kwenye kikapu na kuiona hapo". Tabia moja inayoonekana, mandhari moja ya ukaguzi.
• Nyembamba mno: "tengeneza sehemu ya quantity kwenye modeli ya CartItem". Hii ni hatua ya utekelezaji, si tabia; kuikagua peke yake hakuna maana.

Kipimo rahisi cha ukubwa: kipengele kimoja = kikao kimoja cha wakala = commit moja yenye maana = mandhari moja ya majaribio ya mwisho hadi mwisho (E2E). Ikiwa kipengele hakiingii kwenye kikao kimoja, kigawanye zaidi. Ikiwa haiwezekani kuandika mandhari yake yenyewe, kipengele ni kidogo mno; kiunganishe na kilicho jirani.

Mfano wa kugawanya kazi ya "kikapu"

Mahitaji mapana yanagawanywa kuwa vitengo visivyogawanyika, kila kimoja kikiwa na tabia moja na amri yake ya ukaguzi:

1. Kuongeza bidhaa kwenye kikapu na kuiona kwenye orodha.
2. Kubadilisha idadi ya bidhaa, jumla inahesabiwa upya.
3. Kuondoa bidhaa kutoka kwenye kikapu.
4. Kikapu cha mgeni kinahifadhiwa baada ya kuingia kwenye akaunti.
5. Haiwezekani kuongeza bidhaa isiyopatikana, na kuna hitilafu inayoeleweka.

Ukaguzi wa mwisho wa mgawanyo: hakuna kitengo kinachohitaji "kwa kupita njia" kugusa kingine. Ikiwa kwa kipengele cha 4 unahitaji kuandika upya cha 1, mpangilio au mipaka haikuchaguliwa vizuri.

Orodha ya vipengele: feature_list.json

Kanuni ya kipengele kimoja inaweka mpangilio ndani ya kikao. Lakini nani anakumbuka kati ya vikao kilichokamilika? Maandishi kwenye gumzo kama "auth na katalogi zimekamilika, kikapu karibu kimekamilika lakini kuna hitilafu" hayamsaidii kikao kipya: "karibu" inamaanisha nini, majaribio gani yamepita, nini kinazuia malipo, hakijulikani. Kila kikao kipya ni kama dereva mpya wa gari lilelile: kama maelezo yaliishi kichwani mwa aliyetangulia, mpya hajui chochote.

Kwa hiyo hali inatolewa nje, kwenye faili linaloweza kusomwa na mashine. Katika kozi hili ni .agent/feature_list.json:

[
  {
    "id": "F01",
    "behavior": "Mtumiaji anajisajili kwa barua pepe na nywila na kuingia mara moja",
    "verification": "pytest tests/e2e/test_auth.py::test_register_flow",
    "state": "passing",
    "evidence": "a3f9c12: 1 passed in 2.31s"
  },
  {
    "id": "F02",
    "behavior": "Mtumiaji anaongeza bidhaa kwenye kikapu na kuiona kwenye orodha",
    "verification": "pytest tests/e2e/test_cart.py::test_add_item -q",
    "state": "active"
  },
  {
    "id": "F03",
    "behavior": "Malipo ya agizo kwa kadi",
    "verification": "pytest tests/e2e/test_payment.py -q",
    "state": "blocked",
    "blocker": "hakuna funguo za majaribio za lango la malipo"
  }
]

Kila rekodi ina sehemu tatu za lazima: maelezo ya tabia (yanayoonekana kutoka nje), amri ya ukaguzi (inayoweza kuendeshwa bila binadamu), na hali. Sehemu ya nne ya hiari ni evidence: heshi ya commit na matokeo ya ukaguzi, uthibitisho kwamba mpito kwenda passing ulifanyika kweli.

Kwa nini JSON na si orodha ya Markdown? Inasomwa si tu na wakala, bali pia na hati: mpangaji anachagua kipengele kinachofuata kilicho kwenye not_started, kithibitishaji kinachukua amri ya ukaguzi, ripoti ya kikao inakusanywa kiotomatiki, na usambazaji wa hali unatoa vipimo vya afya ya mradi. Orodha ya vipengele ni uti wa mgongo wa harness, si kikumbusho tu.

Hali nne na mpito zinazoruhusiwa

Hakuna mipito mingine. Hasa, hakuna njia ya kwenda passing bila kupita ukaguzi, na hakuna hali ya "karibu imekamilika".

Lango la passing: wakala anaweza kuomba, lakini si kutangaza

Kanuni kuu ya mfumo mzima: wakala hahariri sehemu ya state kwa mkono. Anaweza kuendesha ukaguzi, lakini hawezi kutangaza matokeo mwenyewe; hilo hufanywa na hati. Tofauti kati ya "wakala ametoa ripoti" na "hati imethibitisha" ni tofauti kati ya maandishi na ukweli. Sheria hizi nazo zinaandikwa kwenye faili la maagizo:

## Sheria za orodha ya vipengele
- Faili: `.agent/feature_list.json`. Hili ndilo chanzo pekee cha ukweli kuhusu wigo.
- Kipengele kimoja tu kiwe katika hali `active`.
- Wewe HUHARIRI sehemu ya `state` kwa mkono. Inabadilishwa na `scripts/verify.sh`.
- Ili kuhamisha kipengele kwenda `passing`, endesha `./scripts/verify.sh F02` na upate msimbo 0.
- Kipengele kikizuiwa, kiweke `blocked` na lazima uandike `blocker`.
- Vipengele vipya huongezwa tu kwenye `not_started` na tu pamoja na amri ya uthibitishaji.

Hati yenyewe inakagua katika ngazi mbili: kwanza mzunguko wa jumla wa mradi (kipengele kisivunje mengine), kisha amri ya kipengele mahususi. Mafanikio ya ndani yakiambatana na kurudi nyuma kwa jumla, hayahesabiwi kuwa mafanikio.

#!/usr/bin/env bash
# Sehemu pekee yenye haki ya kuweka passing.
set -uo pipefail
FID="$1"
FILE=".agent/feature_list.json"

CMD=$(jq -r --arg id "$FID" '.[] | select(.id==$id) | .verification' "$FILE")
if [ -z "$CMD" ] || [ "$CMD" = "null" ]; then
  echo "FAIL: hakuna amri ya uthibitishaji kwa $FID"; exit 2
fi

echo "== ukaguzi wa jumla =="
make check || { echo "FAIL: ukaguzi wa jumla umevunjika, $FID haiwezi kuwa passing"; exit 1; }

echo "== ukaguzi wa kipengele: $CMD =="
if OUT=$(eval "$CMD" 2>&1); then
  SHA=$(git rev-parse --short HEAD)
  LAST=$(printf '%s\n' "$OUT" | tail -n 1)
  TMP=$(mktemp)
  jq --arg id "$FID" --arg ev "$SHA: $LAST" \
    'map(if .id==$id then .state="passing" | .evidence=$ev else . end)' \
    "$FILE" > "$TMP" && mv "$TMP" "$FILE"
  echo "PASS: $FID"
else
  printf '%s\n' "$OUT"
  echo "FAIL: $FID"; exit 1
fi

Sheria "usihariri state" iliyoandikwa kwenye maandishi bado ni ombi. Ili iwe kizuizi, uandishi kwenye faili unaweza kufungwa kiufundi: ukaguzi wa CI unaolinganisha evidence na historia ya commit, au vikwazo vya ruhusa za wakala kwenye zana yako. Kanuni ni ile ile inayopita katika harness nzima: sheria muhimu inaungwa mkono na utaratibu wa kiufundi.

Jinsi ya kupima kwamba wakala anamaliza kazi

Kipimo cha kuvutia ni kiasi cha msimbo kwa kikao. Kwa vitendo hufanya kazi kinyume: tofauti kubwa mara nyingi inamaanisha wakala amegawanyika kwenye mwelekeo kadhaa. Hesabu vipengele vilivyo katika hali passing, si mistari.

Kipimo kinachofaa kutoka kozini ni VCR (Verified Completion Rate): idadi ya kazi zilizothibitishwa, ikigawanywa kwa idadi ya kazi zilizoamilishwa. Kanuni ni rahisi: mradi VCR iko chini ya moja, kazi mpya haziwezi kuamilishwa. Hii ni shinikizo la nyuma ambalo harness linaweka kwa wakala, na pia njia ya kufanya kazi ambazo hazijakamilika ziwe nambari inayoonekana, si hisia tu.

Makosa ya kawaida katika kumpa wakala kazi

• Kazi bila amri ya ukaguzi. "Tengeneza usajili" bila mandhari — wakala ataamua mwenyewe pa kusimama, na ataamua vibaya.
• Vipengele vingi kwenye ombi moja. "Tengeneza kikapu na malipo" ni kazi mbili zilizo hai, na hakuna itakayomalizika.
• Hali iko kwenye gumzo tu. Maendeleo yaliyoandikwa kwenye mazungumzo hupotea mwishoni mwa kikao. Yanapaswa kuishi kwenye faili.
• Ripoti ya kibinafsi badala ya ukaguzi. "Wakala amesema majaribio yamepita" si sawa na msimbo wa kutoka wa hati.
• Hakuna backlog. Katazo la "mambo ya ziada" bila mahali pa kuandika yaliyoonekana linakwepwa na wakala.

Wakati kipengele kimoja kwa wakati hakitoshi tena

Mpango wa "kipengele kimoja — kikao kimoja — ukaguzi mmoja" unafanya kazi vizuri kwa wakala mmoja katika mzunguko mmoja. Kazi zinapokuwa nyingi na kuna matawi huru, mpango huo unapanuliwa kuwa mfumo wa mizunguko kadhaa: nodi ya mipango, nodi za utekelezaji, nodi ya ukaguzi, na mistari inayounganisha kati yake — sambamba, yenye masharti, na kurudi kwenye utekelezaji ukaguzi ukishindwa. Lakini hata hapo kila nodi ya utekelezaji inafanya kazi kwa kanuni ile ile: kazi moja, kigezo cha kukamilika kinachoweza kutekelezwa, na hali iliyo nje ya kichwa cha wakala. Grafu haifuti nidhamu ya kipengele kimoja, bali inajengwa juu yake.

Onyo muhimu kutoka kwenye uchambuzi huo huo: mzunguko unaboresha kwa uaminifu kipimo kilichopewa. Kigezo cha kukamilika kikichaguliwa vibaya — kwa mfano "tiketi imefungwa" badala ya "tatizo limetatuliwa" — wakala atajifunza kutimiza kigezo badala ya kazi yenyewe. Kwa hiyo kuandika tabia na amri ya ukaguzi kunastahili muda zaidi kuliko inavyoonekana.

Kwa ufupi

Kwa kifupi, jinsi ya kumpa wakala wa AI kazi: moja kwa wakati, na tabia inayoonekana na amri ya ukaguzi inayoweza kuendeshwa, backlog kwa kila kilichoonekana njiani, na orodha ya vipengele kwenye faili ambapo mpito kwenda "kimekamilika" unafanywa na hati, si wakala. Breki za wakala huwekwa na harness — yeye mwenyewe hataziwasha. Kanuni ya WIP=1, feature_list.json na verify.sh zinafafanuliwa kwa vitendo katika kozi ya harness engineering kwa kutumia mradi wa mfano wa mwanzo hadi mwisho.