Paano magbigay ng gawain sa AI agent: isang feature sa bawat pagkakataon, listahan ng feature, at pamantayan ng pagkatapos

Bakit sinusubukan ng agent na gawin ang lahat nang sabay

Hiniling mo sa agent na gumawa ng registration. Makalipas ang ilang oras, may labindalawang file na nabago sa diff at walong daang bagong linya: modelo ng user, beripikasyon ng e-mail, nakakabit na serbisyo ng mail, hashing ng password, muling isinaayos na middleware, at inilipat na mga test. Magkakaugnay ang lahat, at wala ni isang senaryo ang buong gumagana. Binubuksan ng susunod na session ang code na ito at hindi alam kung saan magsisimula.

Hindi ang "masamang modelo" ang sanhi. May pakiramdam ang tao ng "sapat na para sa araw na ito" at karaniwang pagod, na kusang naglilimita sa saklaw ng trabaho. Wala ng alinman sa dalawa ang agent. Ang pagdagdag ng "at aayusin ko na rin ang error handling" ay nagkakahalaga sa kanya ng ilang dosenang token, pero ang halaga sa proyekto ay totoo: nagkakalat ang atensiyon, tumataas ang pagkakaugnay ng mga bahagi, at walang natapos.

May simpleng aritmetika rin dito. Ipagpalagay na ang C ay ang kapaki-pakinabang na kapasidad ng context, at ang k ay ang bilang ng gawaing sabay na hawak ng agent. Sa bawat gawain ay humigit-kumulang C/k ang laang pangangatwiran. Kapag bumaba ito sa kinakailangan para matapos ang isang gawain, wala ni isa ang natatapos. Kaya ang tamang sagot sa tanong na paano magbigay ng gawain sa AI agent ay hindi nagsisimula sa pagbubuo ng prompt, kundi sa limitasyon: isang gawain lamang ang nasa progreso.

Ang patakarang isang feature (WIP=1)

Ang WIP ay work in progress, ang bilang ng gawaing nasa progreso. Itinatakda ito sa isa para sa agent: sa anumang sandali, isang feature lamang ang aktibo, at ang susunod ay magsisimula lamang kapag nakapasa na sa pagsusuri ang kasalukuyan. Isinusulat ang patakarang ito sa file ng mga tagubilin ng proyekto (AGENTS.md o CLAUDE.md) para makita ito ng agent sa bawat session:

## Mga tuntunin sa trabaho
- Sa anumang oras, ISANG feature lamang ang nasa estadong `active`.
- Simulan ang susunod na feature lamang kapag ang kasalukuyan ay lumipat na sa `passing`.
- Bawal ang "kasabay na" pag-refactor, pagpapalit ng pangalan, muling pag-aayos ng mga direktoryo,
  at pag-aayos ng hindi kaugnay na bug. Kung may nakitang problema, itala sa `BACKLOG.md` at magpatuloy.
- Ang mga pagbabagong labas sa saklaw ng aktibong feature ayituturing na paglabag, kahit kapaki-pakinabang ang mga ito.

Mas mahalaga ang huling punto kaysa sa tingin. Taos-pusong iniisip ng agent na kapaki-pakinabang ang kanyang mga "kasabay" na pagbabago, at kadalasan ay tama nga siya. Pero ang pagbabagong labas sa saklaw ay naghahalo pa rin ng dalawang gawain sa iisang diff, at hindi na sila maibabalik o masusuri nang hiwalay.

BACKLOG.md: saan ilalagay ang "kasabay"

Hindi sapat na ipagbawal ang impulse na "ayusin na rin habang nandito." Kailangan nito ng lehitimong labasan. Ang labasang iyon ay ang file na BACKLOG.md: itinatala ng agent doon ang nakitang problema sa isa o dalawang linya at bumabalik sa kasalukuyang feature. Hindi nawawala ang impormasyon at hindi lumalaki ang saklaw. Kung walang backlog, maaga o huli ay lalampasan ng agent ang patakaran ng isang feature, dahil mas masama para sa kanya ang "tahimik na iwan ang bug" kaysa sa paglabag.

# BACKLOG.md
- [ ] middleware/errors.py: magkaibang format ng error sa /auth at /orders
- [ ] tests/: dinoble ang user fixtures sa tatlong file
- [ ] kailangan ba ang beripikasyon ng e-mail sa registration? — itanong

Pamantayan ng pagkatapos: ang "tapos" ay isang utos

Ang ikalawang bahagi ng problema: ang agent mismo ang nagpapasya na tapos na ang gawain. Ang "mukhang maayos ang code," "umiiral ang function," "walang compile error" ay pawang pakiramdam at hindi katotohanan. Ang pamantayan ng pagkatapos para sa agent ay dapat isang utos na maisasagawa, na may malinaw na resulta: pumasa o hindi.

F01: registration ng user
verification: pytest tests/e2e/test_auth.py::test_register_flow
state: active

Malinaw ang pagkakaiba ng mahinang pamantayan at mahigpit na pamantayan sa mga halimbawa:

Ang mahusay na utos ng pagsusuri ay deterministiko (parehong resulta sa parehong code), tumatakbo nang walang taong sangkot, at sinusuri ang gawi mula sa labas, gaya ng makikita ng user o ng kliyente ng API. Kung hindi mo ito maisulat, senyales iyon na malabo ang pagkakabuo ng gawain.

Paghahati: gaano kalaki dapat ang isang feature

Ang pinakakaraniwang tanong pagkatapos ng "isang feature sa isang pagkakataon" ay kung ano ang ituturing na feature. Ang masyadong malawak na gawain ay hindi matatapos sa isang session, at ang masyadong makitid ay nalulunod sa gastos ng pagsisimula, context, at pagsusuri.

• Masyadong malawak: "ipatupad ang cart." Isang linggong trabaho at sampung senaryo.
• Tama lang: "maaaring magdagdag ang user ng produkto sa cart at makita ito roon." Isang nakikitang gawi, isang senaryo ng pagsusuri.
• Masyadong makitid: "gumawa ng field na quantity sa modelong CartItem." Hakbang ito ng implementasyon, hindi gawi; walang saysay na suriin ito nang mag-isa.

Praktikal na pagsusuri ng laki: isang feature = isang session ng agent = isang makabuluhang commit = isang end-to-end (E2E) na senaryo. Kung hindi kasya ang feature sa isang session, hatiin pa. Kung hindi ka makasulat ng hiwalay na senaryo para dito, masyado itong maliit; pagsamahin sa katabing feature.

Halimbawa ng paghahati ng gawaing "cart"

Nahahati ang malawak na kinakailangan sa mga atomic na yunit, at bawat isa ay may iisang gawi at sariling utos ng pagsusuri:

1. Magdagdag ng produkto sa cart at makita ito sa listahan.
2. Baguhin ang dami ng produkto, at muling kalkulahin ang kabuuan.
3. Alisin ang produkto sa cart.
4. Manatili ang cart ng bisita pagkatapos mag-login sa account.
5. Hindi maaaring magdagdag ng produktong wala sa stock; malinaw na mensahe ng error.

Huling pagsusuri ng paghahati: walang yunit na nangangailangan ng "kasabay" na pagbago sa iba. Kung kailangang baguhin ang punto 1 para maipatupad ang punto 4, hindi maayos ang pagkakasunod o mga hangganan.

Listahan ng feature: feature_list.json

Pinananatili ng patakaran ng isang feature ang ayos sa loob ng session. Pero sino ang nakakaalala sa pagitan ng mga session kung ano na ang tapos? Ang tala sa chat na "tapos na ang auth at catalog, halos tapos na ang cart, pero may mga bug" ay walang silbi sa bagong session: ano ang ibig sabihin ng "halos," aling mga test ang pumasa, ano ang humaharang sa bayad? Hindi alam. Ang bawat bagong session ay parang bagong drayber ng parehong sasakyan: kung nanatili lamang sa ulo ng dating drayber ang mga tala, wala siyang alam.

Kaya inilalabas ang estado sa isang machine-readable na file. Sa kurso, ito ay .agent/feature_list.json:

[
  {
    "id": "F01",
    "behavior": "Nagre-register ang user gamit ang e-mail at password at agad na nakakapasok",
    "verification": "pytest tests/e2e/test_auth.py::test_register_flow",
    "state": "passing",
    "evidence": "a3f9c12: 1 passed in 2.31s"
  },
  {
    "id": "F02",
    "behavior": "Nagdadagdag ang user ng produkto sa cart at nakikita ito sa listahan",
    "verification": "pytest tests/e2e/test_cart.py::test_add_item -q",
    "state": "active"
  },
  {
    "id": "F03",
    "behavior": "Pagbabayad ng order gamit ang card",
    "verification": "pytest tests/e2e/test_payment.py -q",
    "state": "blocked",
    "blocker": "walang test key ang payment gateway"
  }
]

Tatlong obligadong field ang bawat tala: paglalarawan ng gawi (nakikita mula sa labas), utos ng pagsusuri (maisasagawa nang walang tao), at estado. Opsyonal ang ikaapat na evidence: hash ng commit at output ng pagsusuri, patunay na tunay ang paglipat sa passing.

Bakit JSON at hindi listahan sa Markdown? Binabasa ito hindi lamang ng agent kundi pati ng mga script: pinipili ng scheduler ang susunod na feature sa not_started, kinukuha ng verifier ang utos ng pagsusuri, awtomatikong binubuo ang ulat ng session, at ang distribusyon ng mga estado ay nagbibigay ng sukatan ng kalusugan ng proyekto. Ang listahan ng feature ang gulugod ng harness, hindi lamang isang paalala.

Apat na estado at pinapayagang paglipat

Walang ibang paglipat. Lalo na, walang daan papuntang passing na nilalampasan ang pagsusuri, at walang estadong "halos tapos na."

Gate ng passing: maaaring humiling ang agent, pero hindi ito maaaring magdeklara

Ang sentrong tuntunin ng buong scheme: hindi mano-manong binabago ng agent ang field na state. Maaari niyang patakbuhin ang pagsusuri, pero hindi niya maaaring ideklara ang resulta. Ang script ang gumagawa nito. Ang pagkakaiba ng "nag-ulat ang agent" at "kinumpirma ng script" ay ang pagkakaiba ng teksto at katotohanan. Isinusulat din ang tuntuning ito sa file ng mga tagubilin:

## Mga tuntunin sa listahan ng feature
- File: `.agent/feature_list.json`. Ito lamang ang pinagmumulan ng katotohanan tungkol sa saklaw.
- Eksaktong isang feature lamang ang nasa estadong `active`.
- HINDI mo binabago nang mano-mano ang field na `state`. Binabago ito ng `scripts/verify.sh`.
- Para ilipat ang feature sa `passing`, patakbuhin ang `./scripts/verify.sh F02` at tiyaking code 0 ang resulta.
- Kung naka-block ang feature, ilipat sa `blocked` at tiyaking may `blocker`.
- Idinaragdag ang mga bagong feature lamang sa `not_started` at lamang kasama ang utos ng beripikasyon.

Sinusuri ng script mismo sa dalawang antas: una ang pangkalahatang takbo ng proyekto (hindi dapat masira ng feature ang iba), pagkatapos ang utos ng partikular na feature. Hindi itinuturing na tagumpay ang lokal na pagpasa kung may pangkalahatang regression.

#!/usr/bin/env bash
# Ang tanging bahagi na may karapatang magtakda ng 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: walang utos ng beripikasyon para sa $FID"; exit 2
fi

echo "== pangkalahatang tseke =="
make check || { echo "FAIL: pula ang pangkalahatang tseke, hindi maaaring passing ang $FID"; exit 1; }

echo "== tseke ng feature: $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

Ang tuntuning "huwag baguhin ang state" sa teksto ay isa pa ring kahilingan. Para maging limitasyon ito, maaaring isara mekanikal ang pagsulat sa file: sa pamamagitan ng tseke sa CI na nagtutugma ng evidence sa kasaysayan ng commit, o ng mga limitasyon sa karapatan ng agent sa iyong kagamitan. Iisa ang prinsipyo sa buong harness: ang mahalagang tuntunin ay sinusuportahan ng mekanismo.

Paano sukatin na tinatapos ng agent ang mga gawain

Nakakaakit na sukatan ang dami ng code kada session. Sa praktika, kabaligtaran ang nangyayari: ang malaking diff ay kadalasang nangangahulugang nagkalat ang agent sa maraming direksiyon. Bilangin ang mga feature sa estadong passing, hindi ang mga linya.

Isang kapaki-pakinabang na sukatan mula sa kurso ay ang VCR (Verified Completion Rate): ang bilang ng na-verify na gawain na hinati sa bilang ng na-activate. Simple ang tuntunin: habang mas mababa sa isa ang VCR, hindi maaaring mag-activate ng bagong gawain. Ito ang reverse pressure na ipinapataw ng harness sa agent, at paraan din para maging nakikitang bilang ang mga hindi tapos, sa halip na pakiramdam lamang.

Mga karaniwang pagkakamali sa pagbibigay ng gawain sa agent

• Gawaing walang utos ng pagsusuri. Ang "gumawa ng registration" nang walang senaryo: magpapasya ang agent kung saan titigil, at mali ang magiging desisyon niya.
• Maraming feature sa isang kahilingan. "Gawin ang cart at bayad": dalawang aktibong gawain, at wala sa mga ito ang matatapos.
• Estado na nasa chat lamang. Ang progreso na nakasulat sa usapan ay nawawala kasabay ng pagtatapos ng session. Dapat nasa file ito.
• Sariling ulat sa halip na pagsusuri. Ang "sinabi ng agent na pumasa ang mga test" ay hindi katumbas ng return code ng script.
• Walang backlog. Ipinagbabawal ang "kasabay," pero walang lugar na pagsusulatan ng nakita, kaya lalampasan ito ng agent.

Kapag hindi na sapat ang isang feature sa isang pagkakataon

Gumagana nang maayos ang iskemang "isang feature, isang session, isang pagsusuri" para sa iisang agent sa iisang siklo. Kapag dumami ang gawain at lumitaw ang mga independent na sangay, pinalalawak ito sa sistema ng ilang siklo: hiwalay na node ng pagpaplano, mga node ng implementasyon, node ng pagsusuri, at mga gilid sa pagitan nila, parallel man, kondisyonal, o may pagbabalik sa implementasyon kapag hindi pumasa ang pagsusuri. Pero sa bawat node ng implementasyon ay nalalapat pa rin ang parehong tuntunin: isang gawain, maisasagawang pamantayan ng pagkatapos, at estadong nasa labas ng ulo ng agent. Hindi binubura ng graph ang disiplina ng isang feature, kundi itinatayo ito sa ibabaw nito.

May mahalagang babala mula sa parehong pagsusuri: pinapaboran ng loop ang sukatang ibinigay dito. Kung mali ang pagkakapili ng pamantayan ng pagkatapos, halimbawa "sarado na ang ticket" sa halip na "nalutas na ang problema," matututo ang agent na tuparin ang pamantayan at hindi ang gawain. Kaya karapat-dapat ng higit na panahon ang pagbubuo ng gawi at utos ng pagsusuri kaysa sa inaakala.

Sa madaling sabi

Kung paano magbigay ng gawain sa AI agent sa maikling salita: isa-isa, may nakikitang gawi at maisasagawang utos ng pagsusuri, may backlog para sa lahat ng nakita sa daan, at may listahan ng feature sa file kung saan ang paglipat sa "tapos" ay ginagawa ng script, hindi ng agent. Ang preno ng agent ay itinatakda ng harness; hindi niya ito mismong bubuksan. Ang WIP=1, feature_list.json, at verify.sh ay tinatalakay nang may praktikal na halimbawa sa kurso ng harness engineering sa pamamagitan ng isang end-to-end na proyekto.