วิธีมอบหมายงานให้ AI agent: ทีละหนึ่งฟีเจอร์ รายการฟีเจอร์ และเกณฑ์ว่าเสร็จแล้ว

ทำไม agent ถึงทำทุกอย่างพร้อมกัน

คุณขอให้ agent ทำระบบสมัครสมาชิก ผ่านไปสองชั่วโมง diff มีไฟล์ที่เปลี่ยนสิบสองไฟล์และโค้ดใหม่แปดร้อยบรรทัด ทั้งโมเดลผู้ใช้ การยืนยันอีเมล การเชื่อมบริการส่งอีเมล การแฮชรหัสผ่าน middleware ที่ถูกรีแฟกเตอร์ และเทสต์ที่ย้ายที่ ทุกอย่างเชื่อมโยงกันแน่นและไม่มีสถานการณ์ใดผ่านครบทั้งเส้นทาง เซสชันถัดไปเปิดโค้ดนี้ขึ้นมาแล้วไม่รู้ว่าจะเริ่มจากตรงไหน

สาเหตุไม่ได้มาจาก "โมเดลที่ไม่ดี" มนุษย์มีความรู้สึกว่า "พอแล้วสำหรับวันนี้" และมีความเหนื่อยล้าตามธรรมชาติ ซึ่งจำกัดขอบเขตของงานให้เอง agent ไม่มีทั้งสองอย่าง การเขียนต่อท้ายว่า "และแก้การจัดการข้อผิดพลาดด้วยเลย" ใช้โทเคนเพียงไม่กี่สิบ แต่ราคาที่โปรเจกต์ต้องจ่ายนั้นจริง: ความสนใจกระจาย ความเชื่อมโยงเพิ่มขึ้น และงานก็ไม่เสร็จสักอย่าง

มีคณิตศาสตร์ง่าย ๆ ให้ดู ให้ C เป็นความจุของบริบทที่มีประโยชน์ และ k เป็นจำนวนงานที่ agent ถืออยู่พร้อมกัน แต่ละงานจะได้ทรัพยากรการให้เหตุผลประมาณ C/k เมื่อค่านี้ต่ำกว่าที่ต้องใช้ในการทำงานหนึ่งงานให้จบ ก็จะไม่มีงานใดจบเลย ดังนั้นคำตอบของคำถามว่า "จะมอบหมายงานให้ AI agent อย่างไร" จึงไม่ได้เริ่มจากการเขียน prompt แต่เริ่มจากข้อจำกัด: มีงานเดียวที่กำลังทำ

กฎหนึ่งฟีเจอร์ (WIP=1)

WIP คือ work in progress หรือจำนวนงานที่กำลังทำอยู่ สำหรับ agent กำหนดให้เท่ากับหนึ่ง: ณ เวลาใดก็ตามมีฟีเจอร์ที่ active เพียงหนึ่งเดียว และฟีเจอร์ถัดไปจะเริ่มได้ก็ต่อเมื่อฟีเจอร์ปัจจุบันผ่านการตรวจแล้วเท่านั้น กฎนี้ควรเขียนไว้ในไฟล์คำสั่งของโปรเจกต์ (AGENTS.md หรือ CLAUDE.md) เพื่อให้ agent เห็นในทุกเซสชัน:

## กฎการทำงาน
- ณ เวลาใดก็ตาม มีฟีเจอร์ที่อยู่ในสถานะ `active` เพียง 1 รายการเท่านั้น
- เริ่มฟีเจอร์ถัดไปได้ก็ต่อเมื่อฟีเจอร์ปัจจุบันเปลี่ยนเป็น `passing` แล้ว
- ห้าม "ทำไปพร้อมกัน" เช่น รีแฟกเตอร์ เปลี่ยนชื่อ จัดโครงสร้างโฟลเดอร์ใหม่
  หรือแก้บั๊กที่ไม่เกี่ยวข้อง พบปัญหาให้บันทึกลง `BACKLOG.md` แล้วทำต่อ
- การเปลี่ยนแปลงนอกขอบเขตของฟีเจอร์ที่ active ถือเป็นการละเมิดกฎ แม้จะมีประโยชน์ก็ตาม

ข้อสุดท้ายสำคัญกว่าที่คิด agent มักเชื่อจริงใจว่าการแก้ "ไปพร้อมกัน" นั้นมีประโยชน์ และบ่อยครั้งก็จริง แต่การแก้นอกขอบเขตยังคงผสมสองงานเข้าด้วยกันในดิฟฟ์เดียว ทำให้ไม่สามารถย้อนกลับหรือตรวจสอบแยกกันได้อีกต่อไป

BACKLOG.md: จะเก็บ "ทำไปพร้อมกัน" ไว้ที่ไหน

แค่ห้ามความอยาก "แก้ไปด้วยเลย" นั้นไม่พอ ต้องมีทางออกที่ถูกต้องให้มัน ทางออกนั้นคือไฟล์ BACKLOG.md agent บันทึกปัญหาที่พบลงไปหนึ่งถึงสองบรรทัดแล้วกลับไปทำฟีเจอร์ปัจจุบันต่อ ข้อมูลไม่สูญหาย และขอบเขตงานก็ไม่ขยาย หากไม่มี backlog กฎหนึ่งฟีเจอร์จะถูกหลบเลี่ยงในที่สุด เพราะการ "เงียบ ๆ ปล่อยบั๊กไว้" ดูเหมือนแย่กว่าการละเมิดกฎในสายตาของ agent

# BACKLOG.md
- [ ] middleware/errors.py: รูปแบบข้อผิดพลาดของ /auth และ /orders ไม่เหมือนกัน
- [ ] tests/: fixture ของผู้ใช้ถูกทำซ้ำในสามไฟล์
- [ ] ต้องยืนยันอีเมลตอนสมัครหรือไม่ ถามก่อน

เกณฑ์ว่าเสร็จแล้ว: "เสร็จ" ต้องเป็นคำสั่ง

ปัญหาอีกครึ่งหนึ่งคือ agent ตัดสินเองว่างานเสร็จแล้ว "โค้ดดูเรียบร้อย" "ฟังก์ชันมีอยู่" "ไม่มี compile error" ทั้งหมดนี้เป็นความรู้สึก ไม่ใช่ข้อเท็จจริง เกณฑ์ว่างานเสร็จสำหรับ agent ต้องเป็นคำสั่งที่รันได้และให้ผลชัดเจนว่าผ่านหรือไม่ผ่าน

F01: การสมัครสมาชิกของผู้ใช้
verification: pytest tests/e2e/test_auth.py::test_register_flow
state: active

ความต่างระหว่างเกณฑ์ที่อ่อนกับเกณฑ์ที่เข้มงวดเห็นได้ชัดจากตัวอย่าง:

คำสั่งตรวจสอบที่ดีต้องให้ผลแน่นอน (โค้ดเดิมให้ผลเดิมเสมอ) รันได้โดยไม่ต้องมีมนุษย์ และตรวจพฤติกรรมจากภายนอก เหมือนที่ผู้ใช้หรือผู้เรียก API จะเห็น หากเขียนคำสั่งแบบนี้ไม่ได้ นั่นคือสัญญาณว่างานถูกกำหนดไว้ไม่ชัดเจน

การแตกงาน: ฟีเจอร์ควรมีขนาดเท่าไร

คำถามที่พบบ่อยที่สุดหลังจาก "หนึ่งฟีเจอร์ต่อครั้ง" คือ อะไรนับเป็นฟีเจอร์ งานที่กว้างเกินไปจะไม่จบในเซสชันเดียว ส่วนงานที่แคบเกินไปจะจมอยู่กับค่าใช้จ่ายของการเริ่มงาน บริบท และการตรวจสอบ

• กว้างเกินไป: "ทำตะกร้าสินค้า" นี่คืองานหนึ่งสัปดาห์และมีสถานการณ์เป็นสิบ
• พอดี: "ผู้ใช้เพิ่มสินค้าลงตะกร้าและเห็นสินค้านั้นในรายการได้" มีพฤติกรรมที่สังเกตได้หนึ่งอย่าง และมีสถานการณ์ตรวจหนึ่งอย่าง
• แคบเกินไป: "สร้างฟิลด์ quantity ในโมเดล CartItem" นี่คือขั้นตอนของการพัฒนา ไม่ใช่พฤติกรรม การตรวจแยกต่างหากไม่มีความหมาย

วิธีตรวจขนาดแบบง่าย: หนึ่งฟีเจอร์ = หนึ่งเซสชันของ agent = หนึ่ง commit ที่มีความหมาย = หนึ่งสถานการณ์ end-to-end (E2E) ถ้าฟีเจอร์ไม่พอดีกับเซสชันเดียว ให้แตกต่อ ถ้าเขียนสถานการณ์ตรวจแยกไม่ได้ แสดงว่าเล็กเกินไป ให้รวมเข้ากับฟีเจอร์ข้างเคียง

ตัวอย่างการแตกงาน "ตะกร้าสินค้า"

ความต้องการที่กว้างถูกแบ่งเป็นหน่วยย่อยที่ไม่ซ้ำกัน แต่ละหน่วยมีพฤติกรรมเดียวและคำสั่งตรวจของตัวเอง:

1. เพิ่มสินค้าลงตะกร้าและเห็นสินค้านั้นในรายการ
2. เปลี่ยนจำนวนสินค้า ยอดรวมต้องคำนวณใหม่
3. ลบสินค้าออกจากตะกร้า
4. ตะกร้าของผู้เยี่ยมชม (guest) ยังคงอยู่หลังจากเข้าสู่ระบบ
5. เพิ่มสินค้าที่หมดสต็อกไม่ได้ และต้องมีข้อความผิดพลาดที่เข้าใจได้

การตรวจสุดท้ายของการแตกงานคือ ไม่มีหน่วยใดต้องแก้หน่วยอื่น "ไปพร้อมกัน" ถ้าข้อ 4 ต้องเขียนข้อ 1 ใหม่ แปลว่าลำดับหรือขอบเขตถูกเลือกมาไม่ดี

รายการฟีเจอร์: feature_list.json

กฎหนึ่งฟีเจอร์รักษาลำดับภายในเซสชัน แต่ใครจะจำได้ว่าอะไรเสร็จแล้วข้ามเซสชัน? ข้อความในแชตอย่าง "ระบบยืนยันตัวตนและแคตตาล็อกเสร็จแล้ว ตะกร้าใกล้เสร็จแต่ยังมีบั๊ก" ไม่ช่วยอะไรเซสชันใหม่ "ใกล้เสร็จ" หมายถึงอะไร เทสต์ตัวไหนผ่านแล้ว อะไรขวางการชำระเงิน ไม่มีใครรู้ เซสชันใหม่ก็เหมือนคนขับรถคันเดิมที่มาคนใหม่ ถ้าโน้ตอยู่แค่ในหัวของคนก่อน คนใหม่ก็ไม่รู้อะไรเลย

ดังนั้นสถานะจึงต้องถูกนำออกมาไว้ในไฟล์ที่เครื่องอ่านได้ ในคอร์สนี้ใช้ .agent/feature_list.json:

[
  {
    "id": "F01",
    "behavior": "ผู้ใช้สมัครด้วยอีเมลและรหัสผ่านแล้วเข้าสู่ระบบทันที",
    "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": "ยังไม่มีคีย์ทดสอบของ payment gateway"
  }
]

แต่ละรายการมีสามฟิลด์ที่จำเป็น: คำอธิบายพฤติกรรม (ที่สังเกตได้จากภายนอก) คำสั่งตรวจสอบ (รันได้โดยไม่ต้องมีคน) และสถานะ ฟิลด์ที่สี่ซึ่งไม่บังคับคือ evidence ได้แก่ hash ของ commit และผลการตรวจ เป็นหลักฐานว่าการเปลี่ยนเป็น passing เกิดขึ้นจริง

ทำไมต้องเป็น JSON ไม่ใช่รายการ Markdown? เพราะไม่ได้มีแค่ agent ที่อ่าน แต่สคริปต์ก็อ่านด้วย: ตัวจัดตารางเลือกฟีเจอร์ถัดไปที่อยู่ในสถานะ not_started ตัวตรวจดึงคำสั่งตรวจสอบ รายงานของเซสชันถูกรวบรวมอัตโนมัติ และการกระจายของสถานะให้ตัวชี้วัดสุขภาพของโปรเจกต์ รายการฟีเจอร์คือกระดูกสันหลังของ harness ไม่ใช่แค่โน้ตช่วยจำ

สี่สถานะและการเปลี่ยนที่อนุญาต

ไม่มีการเปลี่ยนอื่น โดยเฉพาะไม่มีทางไปถึง passing โดยข้ามการตรวจ และไม่มีสถานะ "เกือบเสร็จ"

ประตู passing: agent ขอได้ แต่ประกาศเองไม่ได้

กฎหลักของระบบนี้คือ agent ไม่แก้ฟิลด์ state ด้วยมือ มันรันการตรวจได้ แต่ไม่สามารถประกาศผลเองได้ สคริปต์เป็นผู้ทำ ความต่างระหว่าง "agent รายงานว่าเสร็จ" กับ "สคริปต์ยืนยันแล้ว" คือความต่างระหว่างข้อความกับข้อเท็จจริง กฎเหล่านี้ก็ควรเขียนไว้ในไฟล์คำสั่งเช่นกัน:

## กฎของรายการฟีเจอร์
- ไฟล์: `.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 "== การตรวจทั้งโปรเจกต์ =="
make check || { echo "FAIL: การตรวจรวมไม่ผ่าน $FID เป็น passing ไม่ได้"; exit 1; }

echo "== การตรวจฟีเจอร์: $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" ที่เขียนเป็นข้อความยังเป็นเพียงคำขอ เพื่อให้กลายเป็นข้อจำกัดจริง ต้องปิดการเขียนไฟล์ด้วยกลไก เช่น การตรวจใน CI ที่เทียบ evidence กับประวัติ commit หรือกำหนดสิทธิ์ของ agent ในเครื่องมือที่ใช้ หลักการเดียวกันใช้ได้ทั่วทั้ง harness: กฎที่สำคัญต้องถูกหนุนด้วยกลไก

วัดอย่างไรว่า agent ทำงานจนจบ

ตัวชี้วัดที่น่าดึงดูดคือปริมาณโค้ดต่อเซสชัน แต่ในทางปฏิบัติมันให้ผลกลับกัน ดิฟฟ์ที่ใหญ่มักหมายถึง agent กระจายตัวไปหลายทิศทาง ให้นับฟีเจอร์ที่อยู่ในสถานะ passing ไม่ใช่นับจำนวนบรรทัด

ตัวชี้วัดที่ใช้ได้จากคอร์สคือ VCR (Verified Completion Rate) คือจำนวนงานที่ผ่านการตรวจแล้วหารด้วยจำนวนงานที่ถูกเปิดใช้งาน กฎคือ ตราบใดที่ VCR ยังน้อยกว่าหนึ่ง ห้ามเปิดงานใหม่ นี่คือแรงกดดันย้อนกลับที่ harness ใช้กับ agent และเป็นวิธีทำให้งานที่ยังไม่เสร็จปรากฏเป็นตัวเลข ไม่ใช่แค่ความรู้สึก

ข้อผิดพลาดที่พบบ่อยในการมอบหมายงานให้ agent

• งานที่ไม่มีคำสั่งตรวจ "ทำระบบสมัครสมาชิก" โดยไม่มีสถานการณ์ตรวจ agent จะตัดสินเองว่าควรหยุดตรงไหน และมักตัดสินผิด
• หลายฟีเจอร์ในคำขอเดียว "ทำตะกร้าและการชำระเงิน" คือสองงานที่ active พร้อมกัน และไม่มีงานใดถูกทำจนจบ
• สถานะอยู่แค่ในแชต ความคืบหน้าที่เขียนในบทสนทนาจะหายไปเมื่อเซสชันจบ มันต้องอยู่ในไฟล์
• รายงานตัวเองแทนการตรวจ "agent บอกว่าเทสต์ผ่าน" ไม่เหมือนกับรหัสผลลัพธ์ของสคริปต์
• ไม่มี backlog การห้าม "ทำไปพร้อมกัน" โดยไม่มีที่ให้บันทึกสิ่งที่พบ agent จะหลบเลี่ยงกฎ

เมื่อหนึ่งฟีเจอร์ต่อครั้งไม่พออีกต่อไป

รูปแบบ "หนึ่งฟีเจอร์ หนึ่งเซสชัน หนึ่งการตรวจ" ใช้ได้ดีกับ agent หนึ่งตัวในลูปเดียว เมื่องานมีจำนวนมากขึ้นและมีสายงานอิสระหลายสาย รูปแบบนี้จะขยายเป็นระบบของหลายลูป มีโหนดวางแผน โหนดลงมือทำ โหนดตรวจสอบ และเส้นเชื่อมระหว่างกันที่ทำงานขนานกัน มีเงื่อนไข และย้อนกลับไปลงมือทำใหม่หากการตรวจไม่ผ่าน แต่ในแต่ละโหนดลงมือทำยังคงใช้กฎเดิม: งานหนึ่งงาน เกณฑ์ว่าเสร็จที่รันได้ และสถานะที่อยู่นอกหัวของ agent กราฟไม่ได้ยกเลิกวินัยของหนึ่งฟีเจอร์ แต่สร้างต่อยอดขึ้นบนมัน

คำเตือนสำคัญจากการวิเคราะห์เดียวกันคือ ลูปจะปรับให้เหมาะกับตัวชี้วัดที่ได้รับจริง ๆ ถ้าเกณฑ์ว่าเสร็จถูกเลือกมาไม่ดี เช่น "ปิดตั๋วแล้ว" แทนที่จะเป็น "แก้ปัญหาแล้ว" agent จะเรียนรู้ที่จะทำให้เกณฑ์ผ่าน ไม่ใช่แก้งาน ดังนั้นการกำหนดพฤติกรรมและคำสั่งตรวจควรได้รับเวลามากกว่าที่คิด

สรุป

สรุปวิธีมอบหมายงานให้ AI agent: ทีละงาน โดยมีพฤติกรรมที่สังเกตได้และคำสั่งตรวจที่รันได้ มี backlog สำหรับทุกสิ่งที่พบระหว่างทาง และมีรายการฟีเจอร์ในไฟล์ โดยมีเพียงสคริปต์เท่านั้นที่เปลี่ยนสถานะเป็น "เสร็จ" ไม่ใช่ตัว agent เบรกของ agent ต้องถูกติดตั้งโดย harness เพราะ agent จะไม่ติดตั้งมันเอง กฎ WIP=1, feature_list.json และ verify.sh ถูกอธิบายและนำไปใช้จริงในคอร์สเกี่ยวกับ harness engineering ผ่านโปรเจกต์ตัวอย่างแบบครบวงจร