ผมทำงานข้าม 3 repos ด้วย Claude Code ยังไงไม่ให้พัง

ผม build product คนเดียว 3 repos พร้อมกัน — frontend (Next.js), backend (NestJS), smart contracts (Solidity)

ทุก repo เปิด Claude Code คนละ terminal ทำงานพร้อมกัน

ฟังดูเหมือนจะพังทุกวัน แต่ไม่เคยพังสักครั้ง

นี่คือวิธีที่ผมจัดการ

---

ปัญหาจริงของ multi-repo + AI

ปกติเปิด Claude Code ใน repo เดียว มันทำงานดี เพราะมันเห็นแค่ code ใน repo นั้น

แต่พอ build product จริงๆ ที่มีหลาย repo — frontend เรียก API ที่ backend define, backend เรียก contract ที่ Solidity define — AI ไม่เห็นภาพรวม

terminal ที่ 1 แก้ API response shape
terminal ที่ 2 ยังใช้ shape เดิม
ผลคือ frontend พัง ทั้งที่ไม่ได้แตะ

---

วิธีแก้: CLAUDE.md เป็น constitution ของแต่ละ repo

ทุก repo มี CLAUDE.md ของตัวเอง บอก AI ว่า:

• repo นี้ทำอะไร
• boundary อยู่ตรงไหน
• ห้ามแตะอะไร
• data contract กับ repo อื่นเป็นยังไง

ตัวอย่าง CLAUDE.md ของ frontend:

คุณอยู่ใน frontend repo (Next.js)
API contract อยู่ใน /docs/api-contract.md
ห้ามเปลี่ยน API shape เอง — ถ้า contract ไม่ match ให้ถามก่อน
ห้าม assume backend behavior ที่ไม่มีใน contract

AI ใน frontend repo จะไม่เดา backend behavior เพราะ CLAUDE.md กั้นขอบเขตไว้แล้ว

---

Shared contract file คือ single source of truth

ปัญหาใหญ่สุดของ multi-repo คือ AI ทุก terminal เห็นแค่ repo ตัวเอง

ผมแก้ด้วย shared contract — file ที่ define API shape, types, error codes ไว้ที่เดียว ทุก repo อ้างอิงจากที่เดียวกัน

เปลี่ยน contract ที่เดียว → ทุก repo รู้ว่าอะไรเปลี่ยน

ไม่มี "frontend ใช้ field เก่าที่ backend ลบไปแล้ว" อีกต่อไป

---

Spec-driven development — เขียน spec ก่อน code

ผมไม่เคยบอก AI ว่า "สร้าง feature X ให้หน่อย" แล้วปล่อยให้มันคิดเอง

ทุกครั้งที่จะ build อะไรข้าม repo ผมเขียน spec ก่อน — markdown file ที่บอกว่า:

• input/output เป็นยังไง
• API endpoint ชื่ออะไร รับ-ส่ง type อะไร
• error cases มีอะไรบ้าง
• ใครทำส่วนไหน (frontend/backend/contract)

แล้วค่อยสั่ง AI แต่ละ terminal ว่า "implement ตาม spec นี้"

AI ที่มี spec ชัดจะไม่คิดเอง ไม่เดา ไม่แถม เพราะมันรู้ว่าคำตอบอยู่ใน spec แล้ว

---

Handoff protocol — ส่งงานข้าม terminal

พอ backend เขียน API เสร็จ ผมไม่ได้เปิด frontend แล้วอธิบายใหม่ทั้งหมด

ผมให้ backend terminal สรุปสิ่งที่ทำเป็น handoff note — markdown สั้นๆ ที่บอก:

• endpoint อะไรพร้อมแล้ว
• response shape เป็นยังไง
• มีอะไรที่ยังไม่เสร็จ

แล้วเอา handoff note นี้ไปวางใน frontend repo ก่อนสั่ง AI ทำงานต่อ

AI ใน frontend ไม่ต้องเดาว่า backend ทำอะไรมา มันอ่าน handoff note แล้วทำงานต่อได้เลย

เหมือน pitstop ใน F1 — ช่างทุกคนรู้ก่อนรถเข้าแล้วว่าต้องทำอะไร เพราะมี plan ชัด ไม่ต้องถามกันตอนรถจอด

---

R0/R1/R2 — จัดระดับความเสี่ยงให้ AI

ไม่ใช่ทุก action ที่ AI ควรทำได้เลย ผมแบ่งเป็น 3 ระดับใน CLAUDE.md:

• R0 (ย้อนไม่ได้) → หยุด ถามก่อน เช่น deploy contract, ลบ table, push to main
• R1 (ย้อนได้แต่เหนื่อย) → ทำได้ แต่ต้องบอก เช่น เปลี่ยน API contract, migration
• R2 (ย้อนง่าย) → ทำเลย เช่น แก้ UI, เปลี่ยน config, fix bug

contract repo ส่วนใหญ่เป็น R0 — เพราะ deploy contract ผิดแล้วย้อนไม่ได้
frontend ส่วนใหญ่เป็น R2 — เพราะ revert ง่าย

AI แต่ละ terminal รู้ระดับความเสี่ยงของ repo ตัวเอง ไม่ต้องมานั่ง approve ทุก action

---

Scope guard — ไม่ให้ AI ทำเกินที่สั่ง

เขียน rule ตรงๆ ใน CLAUDE.md: ถ้าเริ่มทำเกินที่สั่ง ให้หยุดแล้วถาม

สั่ง "แก้ bug ที่ API response" แต่ AI เริ่ม refactor ทั้ง service layer → AI ต้องหยุดเอง

สำคัญมากกับ multi-repo เพราะ AI ที่ทำเกินใน repo นึง อาจส่งผลกระทบ repo อื่นโดยไม่รู้ตัว

---

สรุป: ทำไมมันไม่พัง

❌ multi-repo แบบไม่มีโครงสร้าง:

• AI แต่ละ terminal ไม่รู้จัก repo อื่น
• เปลี่ยน API shape แล้วอีก repo ไม่รู้
• สั่ง "สร้าง feature" แล้วปล่อยให้ AI เดาเอง
• ส่งงานข้าม terminal แล้วต้องอธิบายใหม่ทุกครั้ง

✅ multi-repo + architecture:

• CLAUDE.md เป็น constitution ของแต่ละ repo
• shared contract เป็น single source of truth
• spec-driven — เขียน spec ก่อน ให้ AI implement ตาม
• handoff note — ส่งงานข้าม terminal โดยไม่เสีย context
• R0/R1/R2 บอก AI ว่าอะไรทำได้ อะไรต้องถาม
• scope guard ป้องกัน AI ทำเกิน

ทั้งหมดนี้ไม่ใช้ tool พิเศษ ไม่มี plugin แค่ markdown files ที่วางไว้ถูกที่

---

ถ้าจะเริ่มใช้:

1. เขียน CLAUDE.md ให้ทุก repo — บอกขอบเขต, ห้าม, data contract
2. สร้าง shared contract file — types, API shape, error codes ที่เดียว
3. เขียน spec ก่อน code — ให้ AI implement ตาม ไม่ใช่คิดเอง
4. ใช้ handoff note ส่งงานข้าม terminal — สรุปสิ่งที่ทำ + สิ่งที่ยังไม่เสร็จ
5. กำหนด R0/R1/R2 ตาม repo — contract repo = R0 heavy, frontend = R2 heavy
6. เพิ่ม scope guard — ให้ AI ตรวจจับตัวเองว่าทำเกินหรือยัง

เขียนโค้ดคนเดียว 3 repos ไม่ใช่ปัญหา
ปัญหาคือปล่อยให้ AI แต่ละ terminal คิดเอง