AI முகவருக்கு பணிகளை எப்படிக் கொடுப்பது: ஒரு நேரத்தில் ஒரு அம்சம், அம்சப் பட்டியல், தயார் நிலை அளவுகோல்கள்

முகவர் ஏன் எல்லாவற்றையும் ஒரே நேரத்தில் எடுக்கிறது

நீங்கள் முகவரிடம் பதிவு அம்சத்தைக் கேட்கிறீர்கள். சில மணி நேரங்களில் diff-இல் பன்னிரண்டு கோப்புகள் மாறியிருக்கும், எண்ணூறு புதிய வரிகள்: பயனர் மாதிரி, மின்னஞ்சல் சரிபார்ப்பு, இணைக்கப்பட்ட மின்னஞ்சல் சேவை, கடவுச்சொல் hashing, மறுசீரமைக்கப்பட்ட middleware, நகர்த்தப்பட்ட சோதனைகள். இவை எல்லாம் இறுக்கமாகப் பின்னிப் பிணைந்திருக்கும், எந்த ஒரு காட்சியும் முழுமையாகச் செல்லாது. அடுத்த அமர்வு இந்தக் குறியீட்டைத் திறந்து எங்கிருந்து தொடங்குவது என்று புரியாமல் நிற்கும்.

இது «மோசமான மாதிரி» பிரச்சினை அல்ல. மனிதருக்கு «இன்றைக்குப் போதும்» என்ற உணர்வும் சாதாரணச் சோர்வும் இருக்கின்றன — அவையே வேலையின் அளவைத் தாமாகக் கட்டுப்படுத்துகின்றன. முகவருக்கு அவை இரண்டும் இல்லை. «அதனுடன் பிழை கையாளுதலையும் சரிசெய்கிறேன்» என்று சேர்ப்பது அதற்கு சில டஜன் token-கள் மட்டுமே, ஆனால் திட்டத்துக்கான விலை உண்மையானது: கவனம் சிதறுகிறது, சார்புகள் அதிகரிக்கின்றன, முடிந்த வேலை எதுவும் இல்லை.

ஒரு எளிய கணக்கும் உள்ளது. C என்பது பயனுள்ள சூழல் கொள்ளளவு, k என்பது முகவர் ஒரே நேரத்தில் வைத்திருக்கும் பணிகளின் எண்ணிக்கை என்று வைத்துக்கொள்ளுங்கள். ஒவ்வொரு பணிக்கும் ஏறத்தாழ C/k அளவு பகுத்தறிவு வளம் கிடைக்கிறது. அந்த மதிப்பு ஒரு பணியை முடிக்கத் தேவையானதற்குக் கீழே குறைந்தால், எந்தப் பணியும் முடிவதில்லை. எனவே முகவருக்குப் பணியை எப்படிக் கொடுப்பது என்ற கேள்விக்கான சரியான பதில் prompt-இன் வார்த்தைகளில் தொடங்குவதில்லை, ஒரு கட்டுப்பாட்டில் தொடங்குகிறது: வேலையில் ஒரு பணி மட்டுமே.

ஒரு அம்ச விதி (WIP=1)

WIP என்பது work in progress, அதாவது வேலையில் உள்ள பணிகளின் எண்ணிக்கை. முகவருக்கு அது ஒன்றாக வைக்கப்படுகிறது: எந்த நேரத்திலும் ஒரே ஒரு அம்சம் செயலில் இருக்கும், அடுத்தது அதன் தற்போதைய அம்சம் சரிபார்ப்பில் தேறிய பின்னரே தொடங்கும். இந்த விதி திட்டக் கோப்பில் எழுதப்படுகிறது (AGENTS.md அல்லது CLAUDE.md), முகவர் ஒவ்வொரு அமர்வின்போதும் அதைப் பார்க்க:

## Правила работы
- В любой момент времени в состоянии `active` находится РОВНО ОДНА фича.
- Следующую фичу начинать только после того, как текущая перешла в `passing`.
- Запрещено «заодно» рефакторить, переименовывать, реорганизовывать каталоги
  и чинить несвязанные баги. Нашли проблему — запишите в `BACKLOG.md` и идите дальше.
- Изменения вне скоупа активной фичи считаются нарушением, даже если они полезны.

கடைசிப் புள்ளி தோன்றுவதை விட முக்கியமானது. முகவர் தனது «வழியில்» மாற்றங்களை உண்மையாகவே பயனுள்ளவை என்று நம்புகிறது, பெரும்பாலும் அவை பயனுள்ளவையாகவும் இருக்கும். ஆனால் நோக்கத்துக்கு வெளியே உள்ள பயனுள்ள திருத்தமும் இரண்டு பணிகளை ஒரே diff-இல் கலக்கிறது, அவற்றைத் தனித்தனியாகத் திரும்பப் பெறவோ சரிபார்க்கவோ முடியாது.

BACKLOG.md: «வழியில்» கண்டதை எங்கே வைப்பது

«வழியில் சரிசெய்» என்ற உந்துதலை வெறுமனே தடை செய்ய முடியாது — அதற்கு ஒரு முறையான வழி தேவை. அந்த வழி BACKLOG.md கோப்பு: முகவர் கண்ட சிக்கலை ஒன்று அல்லது இரண்டு வரிகளில் அங்கே எழுதிவிட்டு தற்போதைய அம்சத்துக்குத் திரும்புகிறது. தகவல் தொலைந்துவிடாது, நோக்கம் விரிவடையாது. backlog இல்லாவிட்டால் ஒரு அம்ச விதியை முகவர் விரைவிலேயே தவிர்க்கத் தொடங்கும், ஏனெனில் «பிழையை மௌனமாக விட்டுவிடுவது» அதற்கு விதியை மீறுவதை விட மோசமாகத் தோன்றும்.

# BACKLOG.md
- [ ] middleware/errors.py: разный формат ошибок в /auth и /orders
- [ ] tests/: фикстуры пользователя дублируются в трёх файлах
- [ ] нужна ли верификация e-mail при регистрации? — спросить

தயார் நிலை அளவுகோல்கள்: «தயார்» என்பது ஒரு கட்டளை

பிரச்சினையின் இரண்டாம் பாதி — பணி முடிந்ததா என்பதை முகவரே தீர்மானிக்கிறது. «குறியீடு நன்றாகத் தெரிகிறது», «செயல்பாடு இருக்கிறது», «தொகுப்புப் பிழைகள் இல்லை» — இவை எல்லாம் உணர்வுகள், உண்மைகள் அல்ல. முகவருக்கான பணியின் தயார் நிலை அளவுகோல் ஒரு இயக்கக்கூடிய கட்டளையாக இருக்க வேண்டும், அதன் முடிவு தெளிவாக: தேறியது அல்லது தேறவில்லை.

F01: регистрация пользователя
verification: pytest tests/e2e/test_auth.py::test_register_flow
state: active

பலவீனமான அளவுகோலுக்கும் வலிமையான அளவுகோலுக்கும் உள்ள வேறுபாடு எடுத்துக்காட்டுகளில் தெளிவாகத் தெரிகிறது:

நல்ல சரிபார்ப்புக் கட்டளை நிர்ணயிக்கக்கூடியது (ஒரே குறியீட்டுக்கு ஒரே முடிவு), மனிதர் தலையீடு இல்லாமல் ஓடுகிறது, மற்றும் நடத்தையை வெளியிலிருந்து சரிபார்க்கிறது — பயனரோ API வாடிக்கையாளரோ அதைப் பார்ப்பது போல. அத்தகைய கட்டளையை எழுத முடியவில்லை என்றால், பணி தெளிவற்ற முறையில் வடிவமைக்கப்பட்டுள்ளது என்பதற்கான அறிகுறி.

பிரித்தல்: ஓர் அம்சம் எவ்வளவு பெரியதாக இருக்க வேண்டும்

«ஒரே நேரத்தில் ஒரு அம்சம்» என்ற விதிக்குப் பிறகு கேட்கப்படும் அடுத்த கேள்வி: அம்சம் என்றால் எதைச் சொல்வது. மிகப் பெரிய பணி ஒரே அமர்வில் முடியாது, மிகச் சிறியது ஓட்டம், சூழல் மற்றும் சரிபார்ப்புச் செலவுகளில் மூழ்கிவிடும்.

• மிக அகலம்: «shopping cart-ஐ நடைமுறைப்படுத்து». இது ஒரு வார வேலை, டஜன் கணக்கான காட்சிகள்.
• சரியான அளவு: «பயனர் ஒரு பொருளை cart-இல் சேர்த்து அதை அங்கே பார்க்க முடியும்». ஒரு கவனிக்கக்கூடிய நடத்தை, ஒரு சரிபார்ப்புக் காட்சி.
• மிகக் குறுகல்: «CartItem மாதிரியில் quantity புலத்தை உருவாக்கு». இது செயல்படுத்தும் படி, நடத்தை அல்ல; அதைத் தனியாகச் சரிபார்ப்பதில் அர்த்தமில்லை.

அளவுக்கான எளிய சோதனை: ஒரு அம்சம் = ஒரு முகவர் அமர்வு = ஒரு அர்த்தமுள்ள commit = ஒரு முழுமையான (E2E) காட்சி. அம்சம் ஒரு அமர்வில் அடங்கவில்லை என்றால், மேலும் பிரிக்கவும். அதற்குத் தனிக் காட்சியை எழுத முடியவில்லை என்றால், அது மிகச் சிறியது — அருகிலுள்ள அம்சத்துடன் இணைக்கவும்.

«cart» பணியின் பிரிப்பு எடுத்துக்காட்டு

அகலமான தேவை ஒவ்வொன்றும் ஒரே நடத்தையும் தனக்கென ஒரு சரிபார்ப்புக் கட்டளையும் கொண்ட அணு அலகுகளாகப் பிரிக்கப்படுகிறது:

1. பொருளை cart-இல் சேர்த்து பட்டியலில் அதைக் காண்பது.
2. பொருளின் எண்ணிக்கையை மாற்றுவது — தொகை மீண்டும் கணக்கிடப்படுகிறது.
3. cart-இலிருந்து பொருளை நீக்குவது.
4. விருந்தினர் cart கணக்கில் நுழைந்த பின்னும் சேமிக்கப்படுகிறது.
5. இருப்பில் இல்லாத பொருளைச் சேர்க்க முடியாது — தெளிவான பிழை.

இறுதிச் சோதனை: எந்த அலகும் «வழியில்» மற்றொன்றைத் தொட வேண்டிய தேவையில்லை. புள்ளி 4-க்கு புள்ளி 1-ஐ மீண்டும் எழுத வேண்டியிருந்தால், வரிசை அல்லது எல்லைகள் தவறாக தேர்வு செய்யப்பட்டுள்ளன.

அம்சப் பட்டியல்: feature_list.json

ஒரு அம்ச விதி ஓர் அமர்வுக்குள் ஒழுங்கை வைக்கிறது. ஆனால் அமர்வுகளுக்கு இடையே எது முடிந்தது என்பதை யார் நினைவில் வைப்பது? அரட்டையில் «auth-உம் catalog-உம் முடிந்தன, cart ஏறத்தாழ தயார், ஆனால் சில பிழைகள் உள்ளன» என்று எழுதியிருப்பது புதிய அமர்வுக்கு எதையும் தருவதில்லை: «ஏறத்தாழ» என்றால் என்ன, எந்தச் சோதனைகள் தேறின, payment-ஐ எது தடுக்கிறது என்பது தெரியாது. ஒவ்வொரு புதிய அமர்வும் அதே காரை ஓட்டும் புதிய ஓட்டுநர் போன்றது: குறிப்புகள் முந்தையவரின் தலையில் மட்டும் இருந்தால், புதியவருக்கு எதுவும் தெரியாது.

எனவே நிலை வெளியே, இயந்திரம் படிக்கக்கூடிய கோப்பில் வைக்கப்படுகிறது. பாடத்தில் அது .agent/feature_list.json:

[
  {
    "id": "F01",
    "behavior": "Пользователь регистрируется по e-mail и паролю и сразу входит",
    "verification": "pytest tests/e2e/test_auth.py::test_register_flow",
    "state": "passing",
    "evidence": "a3f9c12: 1 passed in 2.31s"
  },
  {
    "id": "F02",
    "behavior": "Пользователь добавляет товар в корзину и видит его в списке",
    "verification": "pytest tests/e2e/test_cart.py::test_add_item -q",
    "state": "active"
  },
  {
    "id": "F03",
    "behavior": "Оплата заказа картой",
    "verification": "pytest tests/e2e/test_payment.py -q",
    "state": "blocked",
    "blocker": "нет тестовых ключей платёжного шлюза"
  }
]

ஒவ்வொரு பதிவுக்கும் மூன்று கட்டாயப் புலங்கள் உள்ளன: வெளியிலிருந்து கவனிக்கக்கூடிய நடத்தையின் விளக்கம், இயக்கக்கூடிய சரிபார்ப்புக் கட்டளை (மனிதர் இல்லாமல்), மற்றும் நிலை. நான்காவதாக விருப்பப் புலம் evidence: commit hash மற்றும் சரிபார்ப்பின் வெளியீடு, passing நிலை உண்மையில் வந்தது என்பதற்கான ஆதாரம்.

ஏன் Markdown பட்டியல் அல்ல, JSON? அதை முகவர் மட்டுமல்ல, ஸ்கிரிப்டுகளும் படிக்கின்றன: திட்டமிடுபவர் not_started நிலையில் அடுத்த அம்சத்தைத் தேர்ந்தெடுக்கிறார், சரிபார்ப்பான் சரிபார்ப்புக் கட்டளையை எடுக்கிறார், அமர்வு அறிக்கை தானாகத் தொகுக்கப்படுகிறது, நிலைகளின் பங்கீடு திட்டத்தின் ஆரோக்கிய அளவீடுகளைத் தருகிறது. அம்சப் பட்டியல் harness-இன் முதுகெலும்பு, நினைவூட்டல் குறிப்பு அல்ல.

நான்கு நிலைகளும் அனுமதிக்கப்பட்ட மாற்றங்களும்

இவை தவிர வேறு மாற்றங்கள் இல்லை. குறிப்பாக சரிபார்ப்பைத் தவிர்த்து passing-க்குச் செல்ல வழியில்லை, «ஏறத்தாழ தயார்» என்ற நிலையும் இல்லை.

passing வாயில்: முகவர் கோரலாம், ஆனால் அறிவிக்க முடியாது

இந்த அமைப்பின் மையக் விதி: முகவர் state புலத்தைக் கைமுறையாகத் திருத்துவதில்லை. அது சரிபார்ப்பை இயக்கலாம், ஆனால் முடிவை தானே அறிவிக்க முடியாது — அதை ஸ்கிரிப்டே செய்கிறது. «முகவர் அறிக்கை அளித்தது» மற்றும் «ஸ்கிரிப்ட் உறுதிப்படுத்தியது» என்பதற்கிடையிலான வேறுபாடு உரைக்கும் உண்மைக்கும் உள்ள வேறுபாடு. இந்த விதியையும் அறிவுறுத்தல் கோப்பில் எழுதுகிறார்கள்:

## Правила списка фич
- Файл: `.agent/feature_list.json`. Это единственный источник истины по скоупу.
- Ровно одна фича в состоянии `active`.
- Ты НЕ редактируешь поле `state` вручную. Его меняет `scripts/verify.sh`.
- Чтобы перевести фичу в `passing`, запусти `./scripts/verify.sh F02` и добейся кода 0.
- Если фича заблокирована — переведи в `blocked` и обязательно укажи `blocker`.
- Новые фичи добавляются только в `not_started` и только с командой верификации.

ஸ்கிரிப்ட் இரண்டு நிலைகளில் சரிபார்க்கிறது: முதலில் திட்டம் முழுவதுமாக ஓடுகிறது (அம்சம் மற்றவற்றை உடைக்கக்கூடாது), பின்னர் குறிப்பிட்ட அம்சத்தின் கட்டளை. உள்ளூரில் வெற்றி, ஆனால் பொதுவான பின்னடைவு இருந்தால், அது வெற்றியாகக் கருதப்படாது.

#!/usr/bin/env bash
# Единственный компонент, имеющий право ставить 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: нет команды верификации для $FID"; exit 2
fi

echo "== global check =="
make check || { echo "FAIL: общая проверка красная, $FID не может быть passing"; exit 1; }

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

«state-ஐத் திருத்தாதே» என்ற விதி உரையில் இன்னும் ஒரு கோரிக்கை மட்டுமே. அதை ஒரு கட்டுப்பாடாக மாற்ற, எழுதுவதை இயந்திரத்தனமாகத் தடுக்கலாம்: evidence-ஐ commit வரலாற்றுடன் ஒப்பிடும் CI சரிபார்ப்பால், அல்லது உங்கள் கருவியில் முகவரின் அணுக்க உரிமைகளின் கட்டுப்பாட்டால். கொள்கை harness முழுவதும் ஒன்றே: முக்கியமான விதி இயந்திரத்தனமான ஆதரவுடன் வலுப்பெறுகிறது.

முகவர் பணிகளை முடிக்கிறதா என்பதை எப்படி அளப்பது

கவர்ச்சிகரமான அளவீடு — அமர்வின் குறியீட்டு அளவு. நடைமுறையில் அது எதிர்மாறாக வேலை செய்கிறது: பெரிய diff பெரும்பாலும் முகவர் பல திசைகளில் சிதறியதைக் குறிக்கிறது. passing நிலையிலுள்ள அம்சங்களை எண்ணுங்கள், வரிகளை அல்ல.

பாடத்திலிருந்து ஒரு வசதியான அளவீடு — VCR (Verified Completion Rate): சரிபார்க்கப்பட்ட பணிகளின் எண்ணிக்கையை, செயல்படுத்தப்பட்ட பணிகளின் எண்ணிக்கையால் வகுப்பது. விதி எளியது: VCR ஒன்றை விடக் குறைவாக இருக்கும் வரை புதிய பணிகளைச் செயல்படுத்தக்கூடாது. இது harness முகவருக்குச் செலுத்தும் பின்னழுத்தம், மேலும் முடியாத வேலையை உணர்வுக்குப் பதிலாக ஒரு எண்ணாகக் காணக்கூடியதாக்கும் வழி.

முகவருக்குப் பணி கொடுப்பதில் பொதுவான தவறுகள்

• சரிபார்ப்புக் கட்டளை இல்லாத பணி. «பதிவைச் செய்» என்று காட்சி இல்லாமல் சொல்வது — எங்கே நிறுத்துவது என்பதை முகவர் தானே தீர்மானிக்கும், தவறாக.
• ஒரே கோரிக்கையில் பல அம்சங்கள். «cart-உம் payment-உம் செய்» — இரண்டு செயலில் பணிகள், எதுவும் முடியாது.
• நிலை அரட்டையில் மட்டும். அமர்வு முடிந்ததும் உரையாடலில் எழுதிய முன்னேற்றம் மறைகிறது. அது கோப்பில் வாழ வேண்டும்.
• சரிபார்ப்புக்குப் பதில் சுய அறிக்கை. «சோதனைகள் தேறின என்று முகவர் சொன்னது» — ஸ்கிரிப்ட்டின் திரும்பும் குறியீட்டுக்குச் சமமல்ல.
• backlog இல்லை. «வழியில்» என்பதற்குத் தடை இருந்தும் கண்டதை எழுத இடம் இல்லாவிட்டால், முகவர் அதைச் சுற்றிச் செல்லும்.

ஒரு அம்சம் ஒரு நேரத்தில் போதாதபோது

«ஒரு அம்சம் — ஓர் அமர்வு — ஒரு சரிபார்ப்பு» திட்டம் ஒரு சுழற்சியில் ஒரு முகவருக்கு நன்றாக வேலை செய்கிறது. பணிகள் அதிகமாகி சுயாதீனமான கிளைகள் தோன்றும்போது, அது பல சுழற்சிகளின் அமைப்பாக விரிவடைகிறது: தனி திட்டமிடல் கணு, செயல்படுத்தல் கணுக்கள், சரிபார்ப்புக் கணு, அவற்றுக்கிடையே இணை, நிபந்தனை, சரிபார்ப்புத் தோல்வியில் செயல்படுத்தலுக்குத் திரும்பும் விளிம்புகள். ஆனால் அங்கும் ஒவ்வொரு செயல்படுத்தல் கணுவும் அதே விதியின்படி வேலை செய்கிறது: ஒரு பணி, இயக்கக்கூடிய தயார் நிலை அளவுகோல், முகவரின் தலைக்கு வெளியே நிலை. வரைபடம் ஒரு அம்ச ஒழுங்கை ரத்து செய்யாது, அதன் மேலேயே கட்டப்படுகிறது.

அதே ஆய்வின் முக்கிய எச்சரிக்கை: சுழற்சி தனக்குக் கொடுக்கப்பட்ட அளவீட்டையே நேர்மையாக மேம்படுத்தும். தயார் நிலை அளவுகோல் தவறாகத் தேர்ந்தெடுக்கப்பட்டால் — உதாரணமாக «பணி மூடப்பட்டது» என்பதற்குப் பதில் «சிக்கல் தீர்ந்தது» — முகவர் பணியை அல்ல, அளவுகோலை நிறைவேற்றக் கற்றுக்கொள்ளும். எனவே நடத்தையின் விளக்கத்துக்கும் சரிபார்ப்புக் கட்டளைக்கும் அதிக நேரம் ஒதுக்குவது மதிப்புக்குரியது.

சுருக்கமாக

AI முகவருக்கு எப்படி பணி கொடுப்பது என்பதன் சுருக்கம்: ஒவ்வொன்றாக, கவனிக்கக்கூடிய நடத்தையுடனும் இயக்கக்கூடிய சரிபார்ப்புக் கட்டளையுடனும், வழியில் கண்டதற்கு backlog-உடனும், «தயார்» என்ற மாற்றத்தை முகவர் அல்ல ஸ்கிரிப்ட் செய்யும் அம்சப் பட்டியலுடனும். முகவரின் வேகத்தடையை harness வைக்கிறது — முகவர் தானே அதைச் செயல்படுத்தாது. WIP=1 விதி, feature_list.json மற்றும் verify.sh ஆகியவை ஒரு கூட்டு திட்ட எடுத்துக்காட்டில் பாடத்தில் நடைமுறையில் விளக்கப்பட்டுள்ளன.