ทำงานกับ AI coding agent ยาวๆ โดยไม่หลงทาง: ระบบ handoff ที่ resume ได้

TL;DR — AI coding agent จำอะไรข้าม session ไม่ได้ (context เต็มก็ลืม). ทางแก้ไม่ใช่ context ยาวขึ้น แต่คือ ย้าย state ออกจากหัว agent ไปไว้ในไฟล์ที่ commit ลง git — แบ่งเป็น 3 ชั้น (PLAN คงที่ / PROGRESS สถานะ / HANDOFF วิธี resume) + memory ส่วนตัว + git เป็น source of truth. ผลคือเปิด session ใหม่เมื่อไรก็ “resume” ต่อได้ ไม่ต้องเล่าใหม่

🌐 บทความนี้ vendor-neutral — หลักการใช้ได้กับ AI coding agent ทุกตัว (Cursor, GitHub Copilot, OpenAI Codex, Google Antigravity, Claude Code, ฯลฯ). ส่วนที่เจาะจงเครื่องมือจะมีป้าย 🔷 Claude Code กำกับ และ 🌐 จะมี ตัวอย่างไฟล์จริงของเครื่องมืออื่น ให้เอาไปทำตามได้เลย

ปัญหา: agent ลืมทุกอย่างเมื่อ context เต็ม

ลองนึกภาพงานจริง — โปรเจกต์ 7 เฟส ทำหลายวัน หลาย session. AI agent เก่งมากภายใน หนึ่ง บทสนทนา แต่พอ:

• context window เต็ม → โดนสรุป/ตัดทิ้ง
• คุณปิดแล้วเปิด session ใหม่วันรุ่งขึ้น
• เครื่องคนละเครื่อง / เพื่อนร่วมทีมมาต่อ

…agent ก็ เริ่มจากศูนย์. มันไม่รู้ว่าทำถึงไหน ตัดสินใจอะไรไปแล้ว เฟสต่อไปคืออะไร. ถ้าคุณ แก้ด้วยการ “เล่าใหม่ทุกครั้ง” = เสียเวลา + เล่าไม่ครบ + agent เดาผิด

แก่นปัญหา: memory ในหัว agent เป็นของชั่วคราวและเป็นส่วนตัวต่อ session. อย่าฝากอนาคตของ โปรเจกต์ไว้กับมัน

แนวคิด: state ต้องอยู่ “นอกหัว” agent

หลักการเดียวที่ทุกอย่างต่อยอดมา:

ย้าย state ของโปรเจกต์ออกจากบทสนทนา ไปไว้ในไฟล์ที่ commit ลง git

ไฟล์เดินทางไปกับ repo — ทุก session, ทุกเครื่อง, ทุกคน, ทุกเครื่องมือ อ่านได้เหมือนกัน. agent แค่ต้อง “อ่านไฟล์แล้ว resume” ไม่ใช่ “จำให้ได้”

แต่ถ้ายัดทุกอย่างลงไฟล์เดียวมันจะรก + อัปเดตยาก. เลยแบ่งตาม จังหวะที่มันเปลี่ยน

3 ชั้นเอกสาร (แต่ละชั้นมีงานเดียว)

ไฟล์	ตอบคำถาม	เปลี่ยนบ่อยแค่ไหน
PLAN (แผนที่อนุมัติแล้ว)	“จะสร้างอะไร ลำดับไหน ตัดสินใจอะไรไปแล้ว”	แทบไม่เปลี่ยน (เปลี่ยน = ตัดสินใจใหม่)
PROGRESS	”ตอนนี้อยู่ตรงไหน เฟสไหนเสร็จ gate ผ่านไหม ทำอะไรต่อ”	ทุกขอบเฟส
HANDOFF	”จะ resume ยังไง — คำสั่ง, ขั้นตอนถัดไปแบบเป๊ะ, กับดักที่เจอมาแล้ว”	ทุกขอบเฟส

แยกกันเพราะ คนละ cadence: PLAN เขียนครั้งเดียวอ่านหลายรอบ, PROGRESS/HANDOFF ขยับทุกเฟส. ยัดรวมกัน = เปิดมาแล้วไม่รู้ว่าอะไร current อะไรคือแผนเดิม

ส่วนที่คนมองข้ามคือ HANDOFF “sharp edges” — ลิสต์กับดักที่เจอมาแล้ว (เช่น migration ต้องทำ ท่านี้, cache ต้อง invalidate ตรงไหน, build OOM เพราะ RAM). อันนี้คือส่วนที่มีค่าที่สุด เพราะกันไม่ให้ session หน้าไปเหยียบกับระเบิดเดิมซ้ำ

ตัวอย่างจริง: 3 ไฟล์หน้าตายังไง (และโยงกัน)

PROGRESS.md — สถานะล่าสุด (เขียน fact ถาวร, ปล่อย git คุม merge):

# PROGRESS
**You are here:** P2 เสร็จ gate เขียว · ถ้ายังไม่ merge → merge แล้วเริ่ม P3 บน branch ใหม่

- [x] P1 — auth flow
- [x] P2 — token refresh · gate เขียว
- [ ] P3 — sessions   ← ต่อไป

HANDOFF.md — วิธี resume (ชี้ไป PROGRESS + เก็บกับดัก):

# HANDOFF
> อ่าน PROGRESS.md ก่อน แล้วค่อยไฟล์นี้

## Resume — ทำอะไรต่อ
1. P2 gate เขียว → ถ้ายังไม่ merge ขออนุมัติ merge → main ก่อน
2. เริ่ม P3 บน branch `feature/p3-sessions` (แตกจาก main)

## Sharp edges (กับดักที่เจอแล้ว)
- migrate ด้วย `make migrate` เท่านั้น (prisma ตรงๆ พังกับ liquibase)
- แก้ role/session แล้ว **ต้อง invalidate cache ที่ revoke** ด้วย

CLAUDE.md / AGENTS.md — สั่ง agent ให้ผูกทุกอย่างเข้าด้วยกัน:

# Project rules
- เริ่มทุก session: อ่าน HANDOFF.md → PROGRESS.md ก่อนลงมือ
- 1 เฟส = 1 branch · ห้าม commit ตรง main · ขออนุมัติก่อน merge
- จบเฟส: รัน gate → อัปเดต PROGRESS + HANDOFF → แล้วค่อยขอ merge

เห็นไหมว่ามัน โยงกันเป็นเส้นเดียว: CLAUDE.md/AGENTS.md สั่งให้อ่าน HANDOFF → HANDOFF ชี้ไป PROGRESS → PROGRESS บอกเฟสถัดไป. agent เปิด session ใหม่ก็เดินตามเส้นนี้ resume เองได้

🔷 Claude Code = CLAUDE.md · 🌐 Codex/Antigravity = AGENTS.md · Copilot = .github/copilot-instructions.md · Cursor = .cursor/rules/*.mdc — เนื้อหาเหมือนกัน แค่ เปลี่ยนชื่อไฟล์ตามเครื่องมือ

memory ส่วนตัว vs ไฟล์ใน repo

เครื่องมือหลายตัวมี “memory” ส่วนตัวของ agent ด้วย. เส้นแบ่งง่ายๆ:

• ข้อเท็จจริงที่ทั้งทีมต้องรู้ → ไฟล์ใน repo (เดินทางผ่าน git)
• “เราชอบทำงานแบบไหน” / rule / preference ส่วนตัว → memory ของ agent

🔷 Claude Code: ไฟล์ในเรพคือ CLAUDE.md (instructions ต่อโปรเจกต์) + PROGRESS.md/ HANDOFF.md. memory เป็นไฟล์ส่วนตัวที่ auto-recall ข้าม session. ระวัง: memory ผูกกับ path ของโฟลเดอร์ — เปิดใน git worktree/subfolder จะได้ memory คนละกอง เลยของสำคัญต้องอยู่ในเรพ (อ่านเรื่อง memory ผูก path เต็มๆ)

🌐 ทั่วไป: ไฟล์ instructions ต่อโปรเจกต์มีทุกเครื่องมือ แค่คนละชื่อ — GitHub Copilot .github/copilot-instructions.md · Codex AGENTS.md · Antigravity AGENTS.md · Cursor .cursor/rules/*.mdc (เดิม .cursorrules). ส่วน memory ส่วนตัว: บางเครื่องมือมี (เช่น Cursor “Memories”) บางตัวพึ่งไฟล์เป็นหลัก (Copilot/Codex) — แต่ไม่ว่าจะมีหรือไม่ durable knowledge ก็ ควรอยู่ในไฟล์ในเรพ เพราะ memory ของเครื่องมือเป็น local ไม่เดินทางผ่าน git (เช็ค docs รุ่นล่าสุดอีกที)

จังหวะอัปเดต (what updates when)

ถ้าไม่มีกติกาว่าอัปเดตเมื่อไร ไฟล์จะเก่าทันที. กติกาที่ใช้ได้จริง:

1. ระหว่างทำงาน — commit เล็กๆ บ่อยๆ (git history เล่าเรื่องละเอียดอยู่แล้ว)
2. ขอบเฟส — อัปเดต PROGRESS (ติ๊ก checkbox, ผล gate) + HANDOFF (สถานะ + ขั้นตอนถัดไป + sharp edges ใหม่) แล้วค่อยขอ merge
3. เจอกับดัก — เพิ่มลง HANDOFF sharp edges ทันที
4. rule/preference ใหม่ — เซฟลง memory

🔷 Claude Code: ทำให้เป็น slash command ได้ — /phase-done (รัน gate → อัปเดต trackers → โชว์ diff → ขออนุมัติ merge) และ /resume (อ่าน HANDOFF → สรุป → รอ go-ahead). พิมพ์คำสั่งเดียว แทนที่จะจำ ritual เอง (วิธี codify ritual ซ้ำๆ ให้เป็น command/skill)

🌐 ทั่วไป: ถ้าเครื่องมือมี prompt/command files — GitHub Copilot .github/prompts/*.prompt.md · Cursor reusable rules/prompts — ก็เก็บ ritual resume/phase-done เป็นไฟล์แบบนั้น. ถ้าไม่มี (เช่น Codex/Antigravity) เก็บ ritual เป็น checklist ใน AGENTS.md แล้วสั่ง agent ว่า “ทำ phase-done ritual” — ได้ผลเหมือนกัน

resume ยังไงให้ agent ไม่หลง

เปิด session ใหม่ → ให้ agent:

1. อ่าน HANDOFF แล้ว PROGRESS → รู้ว่าอยู่เฟสไหน ทำอะไรต่อ
2. cross-check กับ git จริง (git log --oneline -5 main, git branch, git status) — อย่าเชื่อ ข้อความในเอกสารเรื่อง “merge รึยัง/อยู่ branch ไหน” เพราะเอกสารอาจ lag
3. สรุปสถานะ + ขั้นตอนถัดไป แล้ว หยุดรอคุณยืนยัน (ไม่ลุยเอง)

ข้อ 2 สำคัญกว่าที่คิด (ดูหัวข้อถัดไป)

บทเรียน 1: git เป็น source of truth — เอกสารพูดแค่ “fact ถาวร”

กับดักคลาสสิก: เขียนสถานะ ชั่วคราว ลงไฟล์ ถาวร. เช่นตอนจบเฟสเขียนว่า ”⏸ รออนุมัติ merge, ยังอยู่ branch feature/x” แล้ว commit. พอ merge จริง ข้อความนั้นก็ ค้าง/ผิดทันที — เพราะ commit ที่เขียน “รออนุมัติ” มันถูกรวมเข้า merge ไปแล้ว และไม่มีใครกลับมาแก้

ทางแก้: ให้เอกสารพูดแค่ fact ถาวร (“เฟส 4 เสร็จ, gate เขียว”) ส่วน “merge รึยัง / อยู่ branch ไหน” ปล่อยให้ git ตอบ. เขียน next-step แบบ self-reconciling: “ถ้ายังไม่ merge → ขออนุมัติ → merge → main แล้วเริ่มเฟสถัดไป”. คำพูดแบบนี้ จริงทั้งก่อนและหลัง merge → ไม่มีวันค้าง

กฎทอง: git เป็นเจ้าของ “merged รึยัง / branch ไหน” · เอกสารเป็นเจ้าของ “เฟสไหนเสร็จ + ทำ อะไรต่อ” — อย่าให้เอกสารไปแย่งพูดเรื่องที่ git ตอบดีกว่า

บทเรียน 2: เฟสใหม่ต้องขึ้น branch ใหม่เสมอ

จุดที่พังง่ายที่สุดคือ resume ตอน “เฟสเสร็จแต่ยังไม่ merge”. ถ้า agent เผลอเริ่มงานเฟสถัดไป บน branch เฟสเดิม = สองเฟสพันกัน merge ไม่ออก. เพราะงั้น ritual resume ต้องบังคับ:

ถ้าเฟสล่าสุดเสร็จแต่ยังไม่ merge → merge เข้า main ก่อน แล้วเริ่มเฟสถัดไปบน branch ใหม่ที่ แตกจาก main — ห้ามต่อบน branch เฟสเดิม ห้าม commit ตรง main

การให้ agent cross-check git ตอน resume (บทเรียน 1) ทำให้มันเห็นเองว่า “ยังไม่ merge นะ อยู่ branch เฟสเดิม” แล้วทำตามลำดับถูก

เริ่มใช้ยังไง (สรุปเป็น checklist)

1. หลังตกลงแผน → เขียน PLAN (คงที่)
2. สร้าง PROGRESS (checklist เฟส + gate table) และ HANDOFF (resume guide + sharp edges)
3. ทำงานทีละเฟสบน branch ของตัวเอง, commit เล็กๆ บ่อยๆ
4. ขอบเฟส: รัน gate → อัปเดต PROGRESS/HANDOFF (เขียน fact ถาวร ปล่อย git คุม merge status) → ขอ อนุมัติ merge
5. เปิด session ใหม่: agent อ่าน HANDOFF+PROGRESS → cross-check git → สรุป → รอคุณ

🔷 Claude Code: ทำเป็น starter kit ได้ — skeleton ของ CLAUDE.md/PROGRESS.md/HANDOFF.md

• /resume /phase-done แล้ว copy เข้าโปรเจกต์ใหม่ทุกอัน

อัปเดตจากการใช้จริง: พอทำหลายโปรเจกต์ starter kit วิวัฒน์เป็น 2 อย่าง — (1) รวม tracker ทั้งหมดไว้โฟลเดอร์เดียว (เช่น project-handoff/) แทนวางหลวมที่ root: หา/เคลียร์/ls ดูงาน active ได้ในที่เดียว (2) ตัว kit กลายเป็น slash command (/bootstrap-…, /migrate-…) ที่ agent รันเองได้ทั้ง flow — ไม่ต้อง copy มือแล้ว · แนวคิดเดียวกับตอน codify workflow เป็น command

🌐 ทั่วไป: 3 ไฟล์ markdown + git = พอแล้ว ไม่ต้องมีเครื่องมือพิเศษ. วาง PLAN/PROGRESS/HANDOFF ในเรพ แล้วชี้ให้ agent อ่านผ่านไฟล์ instructions ของมัน (.github/copilot-instructions.md, AGENTS.md, .cursor/rules/… แล้วแต่เครื่องมือ) — Codex/Copilot/Cursor/Antigravity ใช้ระบบนี้ได้หมด

สรุป

AI coding agent เก่งใน “หนึ่งบทสนทนา” แต่ ลืมข้าม session. อย่าสู้ด้วยการจำให้มากขึ้น — ย้าย state ไปไว้ในไฟล์ที่ git คุม:

1. 3 ชั้น: PLAN (คงที่) / PROGRESS (สถานะ) / HANDOFF (วิธี resume + sharp edges)
2. git = source of truth — เอกสารพูด fact ถาวร, ปล่อย git คุม merge/branch status
3. resume = อ่านเอกสาร + cross-check git + หยุดรอ · เฟสใหม่ = branch ใหม่เสมอ
4. durable knowledge อยู่ใน repo files ไม่ใช่ memory ส่วนตัว

ทำครั้งเดียวเป็น template → ทุกโปรเจกต์ (และทุกคนในทีม) resume งานกับ agent ต่อได้ ไม่มีหลงทาง 🚀