ชีตสรุป

ชีตสรุป harness ของ agent: องค์ประกอบ ไฟล์ ปัญหา และเช็กลิสต์เริ่มต้น

อัปเดต: · Skillaria.Top

Harness ของ agent ประกอบด้วยระบบย่อยห้าอย่าง ได้แก่ คำสั่ง เครื่องมือ สภาพแวดล้อม สถานะ และวงป้อนกลับ ชุดไฟล์ขั้นต่ำประกอบด้วย AGENTS.md ฉบับย่อที่เป็นตัวกำหนดเส้นทาง สคริปต์ตรวจสอบ (make check, verify.sh) ไฟล์ความคืบหน้า และรายการฟีเจอร์พร้อมสถานะ สถานะความพร้อมถูกตั้งโดยสคริปต์ ไม่ใช่โดย agent

ห้าระบบย่อยของ harness

ระบบย่อยคืออะไรสิ่งประดิษฐ์อาการเมื่อพัง
คำสั่งagent ต้องรู้อะไรเกี่ยวกับโปรเจกต์AGENTS.md / CLAUDE.md, skills, docs/, ADRฝ่าฝืนแบบแผนที่รู้กันอยู่แล้ว
เครื่องมือagent ทำอะไรได้บ้างshell, เทสต์, linter, เบราว์เซอร์, MCP server«อยากทำแต่ทำไม่ได้»
สภาพแวดล้อมagent ทำงานที่ไหนไฟล์ล็อก, Docker/devcontainer, git worktree, sandbox, init.shเซสชันเริ่มด้วยการซ่อมสภาพแวดล้อม
สถานะอะไรคงอยู่ข้ามการรีสตาร์ตPROGRESS.md, DECISIONS.md, feature_list.json, commitเซสชันใหม่ไม่รู้ว่าค้างอยู่ที่ไหน
วงป้อนกลับagent รู้ว่าตัวเองผิดได้อย่างไรmake check, E2E, hooks, arch-check, ผู้ประเมิน«เสร็จแล้ว» แต่ใช้งานไม่ได้

ลำดับการนำไปใช้ตั้งแต่ต้น: วงป้อนกลับ → คำสั่ง → สถานะ → สภาพแวดล้อม → เครื่องมือ

ไฟล์ของ harness

ไฟล์วัตถุประสงค์กฎ
AGENTS.md / CLAUDE.mdจุดเริ่มต้น: โปรเจกต์คืออะไร เปิดอย่างไร ตรวจสอบอย่างไรตัวกำหนดเส้นทางสั้น (ประมาณ 80 บรรทัด) ลิงก์ไปเอกสารพร้อมเงื่อนไข «อ่านเมื่อไร»
docs/*.mdรายละเอียดแยกตามหัวข้ออ่านเมื่อจำเป็น ไม่อ่านทั้งหมด
.claude/skills/*/SKILL.mdขั้นตอนที่ทำซ้ำ (deploy, review)โหลดเมื่องานตรงกับคำอธิบาย
PROGRESS.mdสถานะ สิ่งที่ทำ ปัญหาขวางทาง ขั้นตอนถัดไปอัปเดตเมื่อจบทุกเซสชัน
DECISIONS.mdการตัดสินใจ เหตุผล ตัวเลือกที่ถูกปฏิเสธบันทึกเส้นทาง ไม่ใช่แค่ข้อสรุป
feature_list.jsonฟีเจอร์: behavior, verification, stateactive เพียงหนึ่งรายการ (WIP=1)
scripts/verify.shตรวจสอบฟีเจอร์และเปลี่ยนเป็น passingเป็นตัวเดียวที่ตั้ง passing พร้อม SHA ของ commit
scripts/arch-check.shขอบเขตสถาปัตยกรรมรหัสออก 1 + WHY และ FIX ในผลลัพธ์
scripts/init.shตรวจสภาพแวดล้อมก่อนเริ่มงานสภาพแวดล้อม git สะอาด make check เขียว ฟีเจอร์ active
sprint contractข้อตกลงสำหรับฟีเจอร์ก่อนเขียนโค้ดในขอบเขต / นอกขอบเขต / คำถามที่ยังเปิดอยู่
.claude/settings.jsonสิทธิ์และ hooks ของ Claude Codeการตรวจสอบผูกกับเหตุการณ์ ไม่อยู่ในความจำของ agent

โครงร่าง AGENTS.md

# โปรเจกต์: backend การชำระเงิน (FastAPI, PostgreSQL)

## เริ่มต้น
docker compose up -d && ./scripts/init.sh

## การตรวจสอบ
make check   # lint, ชนิดข้อมูล, unit, arch-check
make e2e     # สถานการณ์ปลายทางถึงปลายทาง

## Definition of Done
- make check และ make e2e — รหัส 0
- ฟีเจอร์ถูกตั้งเป็น passing โดย scripts/verify.sh
- อัปเดต PROGRESS.md แล้ว

## MUST
- คิวรี DB ผ่าน repository เท่านั้น
- ความลับมาจากตัวแปรสภาพแวดล้อมเท่านั้น

## เอกสาร
- docs/payments.md — เมื่องานเกี่ยวกับการชำระเงินและการคืนเงิน
- docs/migrations.md — เมื่อมีการเปลี่ยน schema ของ DB

สถานะของฟีเจอร์

สถานะความหมายใครเปลี่ยน
pendingรอคิวผู้วางแผน
activeกำลังทำ (มีได้เพียงหนึ่ง)agent เมื่อเริ่ม
passingผ่านการตรวจสอบเฉพาะ verify.sh
blockedต้องการการตัดสินใจจากคนagent พร้อมเหตุผล

ระดับการตรวจสอบ

ระดับเนื้อหาเมื่อไร
1Lint, ชนิดข้อมูลทุกครั้ง
2Unit และ integration testsทุกครั้ง
3E2Eการเปลี่ยนแปลงกระทบมากกว่าหนึ่งชั้น และก่อนพูดว่า «เสร็จ»
4arch-checkมีการ import ข้ามชั้นใหม่

สิทธิ์ในการพูดว่า «เสร็จ» มีได้หลังจากระดับสูงสุดเท่านั้น ยูนิตเทสต์ที่เขียวไม่ได้หมายถึงความพร้อม

การทำให้กฎบังคับใช้ได้

ระดับเครื่องมือต้นทุน
Guard แบบ grepสคริปต์ค้นหารูปแบบและพิมพ์ข้อความ WHY/FIXไม่กี่นาที
กฎ linterimport-linter (Python), dependency-cruiser, eslint-plugin-boundaries (JS/TS)หนึ่งชั่วโมง
เทสต์สถาปัตยกรรมเทสต์ใน CI ที่ล้มเมื่อละเมิดชั้นมากกว่า แต่มองเห็นได้ใน make check
 
#!/usr/bin/env bash
fail=0
if grep -rn "from app.db" app/services/; then
  echo "WHY: service ไม่เข้าถึง DB โดยตรง"
  echo "FIX: ใช้ repository จาก app/repositories/"
  fail=1
fi
exit $fail

ปัญหาที่พบบ่อยและวิธีแก้

ปัญหาระบบย่อยวิธีแก้
กฎใน CLAUDE.md ไม่ถูกปฏิบัติตามคำสั่งย่อไฟล์ เปลี่ยนกฎเป็นการตรวจสอบหรือ hook
agent รันเทสต์ไม่ได้เครื่องมืออนุญาตคำสั่ง ติดตั้ง dependencies ในอิมเมจ
พฤติกรรมต่างกันในแต่ละเครื่องสภาพแวดล้อมไฟล์ล็อก Docker/devcontainer เวอร์ชัน runtime ที่ตรึงไว้
ความจำเสื่อมระหว่างเซสชันสถานะPROGRESS.md บันทึกการส่งต่อเซสชัน อ่านตอนเริ่ม
เริ่มสามฟีเจอร์ ไม่มีอันไหนเสร็จสถานะWIP=1 ใน feature_list.json
«เสร็จ» แต่ใช้งานไม่ได้วงป้อนกลับDoD, E2E, verify.sh, ผู้ประเมินอิสระ
เทสต์เขียวแต่ฟีเจอร์พังวงป้อนกลับE2E ด้วยฐานข้อมูลและการตั้งค่าจริง
agent คัดลอกรูปแบบที่ไม่ดีวงป้อนกลับarch-check ตั้งแต่ต้น
ไม่รู้ว่า agent ทำอะไรไปบ้างสถานะcommit เล็ก รายงานใน PROGRESS.md, DECISIONS.md
agent ทำสภาพแวดล้อมพังข้ามคืนสภาพแวดล้อมsandbox, git worktree, จุดตรวจ, ย้อนกลับผ่าน init.sh
ความคิดเห็นเดิมปรากฏในรีวิวสองครั้งharness โดยรวมเปลี่ยนเป็นการตรวจสอบใน make check และตัดข้อความออกจากคำสั่ง

บทบาทสำหรับงานที่ยาว

บทบาททำไม่ทำ
ผู้วางแผนฟีเจอร์พร้อมเกณฑ์การยอมรับไม่เขียนโค้ด
ผู้สร้างโค้ดลงมือทำหนึ่งฟีเจอร์ รันเทสต์ไม่ตัดสินว่าเสร็จหรือยัง
ผู้ประเมินตัดสินตาม rubric พร้อมอ้างอิงไฟล์ บรรทัด logไม่เห็นเหตุผลของผู้สร้างโค้ด
การรวมโค้ดcommit เมื่อ review == passเป็นโค้ด ไม่ใช่ agent

งบประมาณสำหรับการทำงานอัตโนมัติ

  • เป้าหมาย — หนึ่งประโยค (เช่น ทำให้ทุกฟีเจอร์เป็น passing)
  • WIP=1 จำกัดเวลาและจำนวนครั้งต่อฟีเจอร์
  • ตัวชี้วัดเพิ่มขึ้นอย่างต่อเนื่อง การถดถอยให้ย้อนกลับทันที
  • migration โครงสร้างพื้นฐาน เงิน ให้ส่งต่อให้คน
  • หลังรีวิวล้มเหลวหลายครั้ง ให้เริ่มฟีเจอร์ใหม่ด้วยบริบทสะอาด

เช็กลิสต์ก่อนเริ่ม agent

  1. มี AGENTS.md: stack วิธีเริ่ม คำสั่งตรวจสอบ DoD
  2. make check ผ่านบน clone ที่สะอาด
  3. สภาพแวดล้อมทำซ้ำได้: ไฟล์ล็อก Docker หรือ devcontainer
  4. agent มีคำสั่งที่จำเป็น คำสั่งอันตรายถูกห้ามหรืออยู่ใน sandbox
  5. มี E2E อย่างน้อยสำหรับสถานการณ์หลัก
  6. มี PROGRESS.md และกฎให้อ่านเมื่อเริ่มเซสชัน
  7. ฟีเจอร์ในรายการมีสถานะ และมี active เพียงหนึ่งรายการ
  8. สถานะ passing ถูกตั้งโดยสคริปต์
  9. ข้อความการตรวจสอบมี WHY และ FIX
  10. งานมีเกณฑ์การยอมรับและขอบเขตที่ชัดเจน
  11. ระบุแล้วว่าอะไรต้องการการตัดสินใจจากคน
  12. วัด verification gap ก่อนการเปลี่ยนแปลง เพื่อให้มีค่าให้เปรียบเทียบ

ตัวชี้วัดของ harness

ตัวชี้วัดวิธีคำนวณ
Verification gapสัดส่วนของ «เสร็จ» ที่ไม่มีการยืนยันจากการตรวจสอบ บนงาน 10 ชิ้น
MTTRเวลาตั้งแต่พังจนกลับสู่สถานะทำงาน
Cold startเซสชันใหม่ตอบได้ไหมว่า «เราอยู่ที่ไหน ต่อไปทำอะไร» โดยไม่ต้องเดา
Ablationการลดลงเมื่อปิดระบบย่อยหนึ่งตัวบนชุดงานที่ตรึงไว้

สรุป

Harness เป็นวงปิดไม่ใช่ไฟล์เดียว ประกอบด้วยคำสั่ง เครื่องมือ สภาพแวดล้อม สถานะ และวงป้อนกลับ เริ่มจากการตรวจสอบ เก็บ AGENTS.md ให้สั้น มอบสถานะ «เสร็จ» ให้สคริปต์ และทบทวน harness เป็นประจำ ทั้งหมดนี้ถูกประกอบเข้าด้วยกันบนโปรเจกต์จริงในหลักสูตร harness engineering

คำถามที่พบบ่อย

AGENTS.md ต่างจาก CLAUDE.md อย่างไร?

ในแง่วัตถุประสงค์เหมือนกัน คือเป็นไฟล์คำสั่งสำหรับ agent CLAUDE.md ถูกอ่านโดย Claude Code ส่วน AGENTS.md เป็นรูปแบบกลางสำหรับ agent หลายตัว ใน CLAUDE.md สามารถอ้างถึง AGENTS.md ได้เลย

AGENTS.md ควรมีกี่บรรทัด?

ไม่มีขีดจำกัดตายตัว แต่ไฟล์หลักควรสั้น ประมาณหลักร้อยบรรทัดลงมาเหมือนสารบัญ รายละเอียดแยกไปเอกสารอื่น

โปรเจกต์เล็กจำเป็นต้องมี feature_list.json หรือไม่?

สำหรับการแก้ไขเล็กน้อยไม่จำเป็น จะคุ้มค่าเมื่อ agent ทำหลายฟีเจอร์ติดต่อกันหรือหลายเซสชัน

ควรเก็บความลับที่ agent ต้องเข้าถึงไว้ที่ไหน?

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

เรียนหัวข้อนี้ผ่านวิดีโอ

หัวข้อนี้สอนอย่างละเอียดพร้อมฝึกปฏิบัติในคอร์ส “Harness Engineering: инженерия надёжности AI-агентов”

ไปที่คอร์ส