บทที่ 5 — Pull request, การรีวิว และเอกสารที่ต้องอัปเดตด้วย

บทที่แล้วเราเปิด PR เป็นแล้ว บทนี้ว่ากันว่า อะไรควรอยู่ใน PR และ ทำไม repo นี้ถึงบังคับให้อัปเดตเอกสารไปพร้อมโค้ด

PR ที่ดีมีขนาดเล็ก

PR ที่แก้ 40 ไฟล์ใน 6 เรื่อง คนรีวิวจะอ่านไม่ไหวแล้วกด approve มั่ว ๆ — เท่ากับไม่มีการรีวิวเลย

ในโปรเจกต์นี้เราแบ่งงาน mockup ทั้งเว็บ (~45 หน้า) ออกเป็น 6 PR ตามหัวข้อ: ระบบดีไซน์ → แคตตาล็อกสินค้า → หน้าข้อมูล+ล็อกอิน → ตะกร้า+ชำระเงิน → บัญชีลูกค้า → หลังบ้าน แต่ละอันรีวิวจบได้ในครั้งเดียว

หลักคิด: ถ้าอธิบาย PR ของตัวเองด้วยประโยคเดียวไม่ได้ แปลว่าควรซอย

โครงคำอธิบาย PR

## ทำอะไร
เพิ่มตัวกรองสินค้าตามแบรนด์ในหน้าแคตตาล็อก

## ทำไม
ลูกค้าที่รู้ยี่ห้ออะไหล่อยู่แล้วต้องเลื่อนหาเองทั้งหน้า (ตามสเปกหัวข้อ 7)

## ทดสอบยังไง
- typecheck / lint / build ผ่าน
- ลองกรอง KURO Aero แล้วได้ 3 รายการถูกต้อง
- เช็คหน้าจอมือถือ 390px ไม่มีล้นขอบ

ยาวแค่นี้พอ ไม่ต้องเขียนเรียงความ

กฎ: แก้ของใหญ่ ต้องอัปเดตเอกสารและเทสต์ใน PR เดียวกัน

AGENTS.md เขียนไว้ชัด — ถ้า PR แตะ API, โครงสร้างฐานข้อมูล, หรือ flow หลักของธุรกิจ ต้องมีสิ่งนี้อยู่ใน PR เดียวกัน:

1. เอกสารที่เกี่ยวข้อง ใน docs/ ที่อัปเดตแล้ว
2. เทสต์ ที่ครอบพฤติกรรมใหม่ (ไม่ใช่แค่ทางที่ถูก แต่ทางที่ผิดด้วย)

เหตุผลง่ายมาก: ถ้าแยกไปทำทีหลัง มันจะไม่ถูกทำ แล้วอีกสามเดือนเอกสารก็จะโกหก ซึ่งแย่กว่าไม่มีเอกสารเลย

ADR — บันทึกว่า "ทำไมถึงเลือกแบบนี้"

บางการตัดสินใจย้อนกลับยาก เช่น เลือกใช้ library ตัวไหน หรือออกแบบระบบ auth ยังไง ถ้าไม่จดไว้ อีกครึ่งปีจะมีคนมาถามว่า "ทำไมไม่ใช้ X" แล้วไม่มีใครตอบได้

ADR (Architecture Decision Record) คือบันทึกสั้น ๆ หนึ่งไฟล์ต่อหนึ่งการตัดสินใจ อยู่ใน docs/decisions/ เขียนตามแม่แบบ 0000-template.md:

• Context — เจอปัญหาอะไร มีข้อจำกัดอะไร
• Decision — ตัดสินใจทำอะไร
• Alternatives considered — พิจารณาทางอื่นอะไรบ้าง ทำไมไม่เอา
• Consequences — ได้อะไร เสียอะไร
• Revisit when — เงื่อนไขที่ควรกลับมาทบทวน

ตัวอย่างจริงใน repo นี้มี 2 ฉบับ:

เมื่อไหร่ต้องเขียน ADR: เมื่อการตัดสินใจนั้น ย้อนยาก, ทำให้คนอ่านในอนาคตงง, หรือ กระทบทั้งระบบ — งานปกติอย่างเพิ่มฟีเจอร์หรือแก้บั๊กตามแพทเทิร์นเดิม ไม่ต้องเขียน

รีวิวงานคนอื่นยังไง

ถ้าถูกขอให้รีวิว ดู 4 อย่างนี้ก็ครอบคลุมแล้ว:

1. มันทำในสิ่งที่บอกไว้จริงไหม — อ่านคำอธิบาย PR แล้วดูโค้ดว่าตรงกัน
2. มีอะไรที่จะพังเงียบ ๆ ไหม — ค่าที่เป็น null ได้, กรณีข้อมูลว่าง, ผู้ใช้กดรัว ๆ
3. มันเข้ากับของเดิมไหม — ใช้ component/แพทเทิร์นที่มีอยู่ หรือสร้างของซ้ำซ้อนขึ้นมาใหม่
4. CI เขียวหรือยัง — ถ้าแดงอยู่ ยังไม่ต้องรีวิว บอกเจ้าของ PR ให้แก้ก่อน

เวลาคอมเมนต์ ให้ชี้ที่โค้ดไม่ใช่ที่คน: "ตรงนี้ถ้า variants เป็น array ว่างจะ error ไหม" ดีกว่า "เขียนไม่รอบคอบ"

ลองทำเอง: เปิด PR เก่าของ repo นี้สัก 2 อัน (เช่น PR #7 เรื่องตะกร้า และ PR #12 เรื่อง auto-deploy) แล้วอ่านดูว่า เขาอธิบายอะไรบ้าง, แตะไฟล์กี่ไฟล์, มีเอกสารอัปเดตมาด้วยไหม — แล้วลองเขียนคำอธิบาย PR ในสไตล์เดียวกันสำหรับงานชิ้นแรกของคุณ

เอกสารสำคัญของ repo นี้ (รู้ไว้ว่าอะไรอยู่ตรงไหน)

นิสัยที่ควรติด: ก่อนเริ่มงานใหม่ เปิด docs/implementation-plan.md ดูก่อนว่างานที่จะทำอยู่ในเฟสไหน และมีข้อสมมติอะไรบันทึกไว้แล้วบ้าง

บทหน้า: ระบบ 5 ชั้นที่ทำให้ AI ทำงานถูกทางโดยไม่ต้องคุมทุกฝีก้าว