เรียนรู้การกำหนดขอบเขตงานด้วย Claude Code เพื่อเปลี่ยนคำขอฟีเจอร์ที่รกให้เป็นเกณฑ์การยอมรับที่ทดสอบได้ แผน UI/API ขั้นพื้นฐาน และคอมมิตเล็ก ๆ

GET /items/{id} คืนค่าสถานะที่ต้องการเพื่อเรนเดอร์หน้าจอ\n- POST /items/{id}/update รับเฉพาะสิ่งที่ผู้ใช้เปลี่ยนและคืนค่าสถานะที่อัปเดต\n\nเขียนอินพุตและเอาต์พุตเป็นวัตถุธรรมดา ไม่ใช่ย่อหน้ารายละเอียด รวมฟิลด์ที่จำเป็น vs ตัวเลือก และสิ่งที่จะเกิดขึ้นเมื่อพบข้อผิดพลาดทั่วไป (ไม่พบ, ตรวจสอบล้มเหลว)\n\nทำการตรวจสอบสิทธิ์อย่างรวดเร็วก่อนแตะฐานข้อมูล ตัดสินใจว่าใครอ่านได้และใครเขียนได้ และเขียนกฎเป็นประโยคเดียว (ตัวอย่าง: “ผู้ใช้ที่ลงชื่อเข้าใช้ทุกคนอ่านได้ ผู้ดูแลระบบเท่านั้นที่เขียนได้”) การข้ามขั้นตอนนี้มักนำไปสู่การทำงานซ้ำ\n\nสุดท้าย ตัดสินใจว่าสิ่งใดต้องเก็บและสิ่งใดคำนวณ กฎง่าย ๆ: เก็บข้อเท็จจริง คำนวณมุมมอง\n\n## ใช้ Claude Code เพื่อผลิตงานที่กำหนดขอบเขต\n\nClaude Code ทำงานได้ดีที่สุดเมื่อคุณให้เป้าหมายชัดเจนและขอบเขตแคบ ๆ เริ่มโดยวางคำขอที่รกและข้อจำกัด (เส้นตาย ผู้ใช้ที่ได้รับผลกระทบ กฎข้อมูล) แล้วขอเอาต์พุตที่กำหนดขอบเขตซึ่งรวม:\n\n1. สรุปขอบเขตเป็นภาษาธรรมชาติและเช็คลิสต์เกณฑ์การยอมรับสั้น ๆ\n2. ลำดับคอมมิตขนาดเล็ก (ตั้งเป้า 3–7) แต่ละคอมมิตมีผลลัพธ์ชัดเจน\n3. ไฟล์หรือโฟลเดอร์ที่น่าจะถูกแก้ต่อคอมมิต และสิ่งที่เปลี่ยนภายใน\n4. แผนการทดสอบสั้นต่อคอมมิต (เส้นทางที่สำเร็จและกรณีขอบหนึ่งอย่าง)\n5. บันทึกสิ่งที่ไม่รวมในขอบเขต\n\nหลังจากได้รับคำตอบ อ่านเหมือนผู้ตรวจ หากคุณเห็นวลีอย่าง “ปรับปรุงประสิทธิภาพ” หรือ “ทำให้สะอาดขึ้น” ให้ขอคำที่วัดได้\n\n### ตัวอย่างสั้น ๆ (ตัวอย่างของสิ่งที่ “ดี” เท่าที่ควรจะเป็น)\n\nคำขอ: “เพิ่มวิธีพักสมัครสมาชิก”\n\nเวอร์ชันที่กำหนดขอบเขตอาจระบุว่า: “ผู้ใช้สามารถพักได้ 1–3 เดือน; วันที่เรียกเก็บเงินถัดไปอัปเดต; ผู้ดูแลเห็นสถานะพัก” และสิ่งที่ไม่รวม: “ไม่มีการเปลี่ยน prorate”\n\nจากนั้นแผนคอมมิตจะเป็นแบบปฏิบัติ: คอมมิตหนึ่งสำหรับโครงสร้าง DB และ API, คอมมิตหนึ่งสำหรับคอนโทรล UI, คอมมิตหนึ่งสำหรับการตรวจสอบและสถานะข้อผิดพลาด, คอมมิตหนึ่งสำหรับการทดสอบ end-to-end\n\n## แยกงานเป็นคอมมิตเล็ก ๆ ที่รีวิวได้\n\nการเปลี่ยนแปลงใหญ่ซ่อนบั๊ก คอมมิตเล็กทำให้การรีวิวเร็วขึ้น ทำให้การย้อนกลับปลอดภัย และช่วยให้สังเกตเมื่อหลุดจากเกณฑ์การยอมรับ\n\nกฎที่มีประโยชน์: แต่ละคอมมิตควรปลดล็อกพฤติกรรมใหม่หนึ่งอย่าง และรวมวิธีพิสูจน์สั้น ๆ ว่ามันทำงาน\n\nลำดับทั่วไปมีลักษณะดังนี้:\n\n- โมเดลข้อมูลหรือตัวมิเกรต (ถ้าจำเป็น) พร้อมเทสต์\n- พฤติกรรม API และการตรวจสอบ\n- เชื่อม UI กับสถานะว่างและข้อผิดพลาด\n- บันทึกหรือการวิเคราะห์เฉพาะที่ต้องการ แล้วค่อยแต่งเล็กน้อย\n\nทำให้แต่ละคอมมิตมีจุดประสงค์ หลีกเลี่ยงการรีแฟกเตอร์ “ขณะนี้ฉันอยู่ที่นี่” เก็บแอปให้ทำงานแบบ end-to-end แม้ UI จะพื้นฐาน อย่ารวมมิเกรชัน พฤติกรรม และ UI เป็นคอมมิตเดียวเว้นแต่มีเหตุผลชัดเจน\n\n## การเดินผ่าน: “ส่งออกรายงาน”\n\nผู้มีส่วนได้ส่วนเสียพูดว่า: “เพิ่มการส่งออกรายงานได้ไหม?” มันซ่อนตัวเลือกมากมาย: รายงานแบบไหน รูปแบบอะไร ใครส่งออกได้ และส่งอย่างไร\n\nถามเฉพาะคำถามที่เปลี่ยนการออกแบบ:\n\n- ประเภทรายงานใดอยู่ในขอบเขตสำหรับ v1?\n- รูปแบบใดที่ต้องการสำหรับ v1 (CSV, PDF)?\n- ใครส่งออกได้ (admins, บทบาทเฉพาะ)?\n- เป็นดาวน์โหลดตรงหรือส่งทางอีเมล?\n- ข้อจำกัดอะไรบ้าง (ช่วงวันที่สูงสุด, จำนวนแถวสูงสุด, เวลาหมดเวลา)?\n\nสมมติคำตอบว่า: “Sales Summary, CSV เท่านั้น, บทบาทผู้จัดการ, ดาวน์โหลดตรง, สูงสุด 90 วัน” ตอนนี้เกณฑ์ยอมรับ v1 ชัดเจน: ผู้จัดการคลิก Export บนหน้า Sales Summary; CSV ตรงกับคอลัมน์บนตาราง; การส่งออกเคารพตัวกรองปัจจุบัน; การส่งออกมากกว่า 90 วันจะแสดงข้อผิดพลาดชัดเจน; การดาวน์โหลดเสร็จภายใน 30 วินาทีสำหรับสูงสุด 50k แถว\n\nแผน UI ขั้นพื้นฐาน: ปุ่ม Export ใกล้การกระทำของตาราง, สถานะกำลังโหลดขณะสร้างไฟล์, และข้อความข้อผิดพลาดที่บอกวิธีแก้ (เช่น “เลือก 90 วันหรือน้อยกว่า”)\n\nแผน API ขั้นพื้นฐาน: endpoint เดียวที่รับตัวกรองและคืน CSV เป็นไฟล์ตอบกลับ โดยใช้คิวรีเดียวกับตารางและบังคับกฎ 90 วันฝั่งเซิร์ฟเวอร์\n\nแล้วส่งของในคอมมิตแคบ ๆ: ก่อนอื่น endpoint สำหรับเส้นทางที่สำเร็จคงที่ จากนั้นเชื่อม UI แล้วตรวจสอบและข้อความแสดงแก่ผู้ใช้ สุดท้ายทดสอบและเอกสาร\n\n## ข้อผิดพลาดทั่วไปในการกำหนดขอบเขต (และวิธีเลี่ยง)\n\n### ความต้องการแอบแฝงแทรกตัวเข้ามา\n\nคำขออย่าง “เพิ่มบทบาททีม” มักแอบกฎเกี่ยวกับการเชิญ แก้ไข และเกิดอะไรขึ้นกับผู้ใช้เดิม ถ้าคุณกำลังเดาให้เขียนสมมติฐานนั้นลงไปแล้วเปลี่ยนเป็นคำถามหรือกฎชัดเจน\n\n### การขัดเกลาด้าน UI ปะปนกับพฤติกรรมหลัก\n\nทีมเสียเวลาหลายวันเมื่อหนึ่งงานรวมทั้ง “ทำให้ทำงานได้” และ “ทำให้สวย” ไว้ด้วยกัน ให้โฟกัสครั้งแรกที่พฤติกรรมและข้อมูล แยกสไตลิง แอนิเมชัน และช่องว่างเป็นงานถัดไป เว้นแต่จำเป็นต้องใช้ฟีเจอร์\n\n### พยายามแก้ทุกกรณีขอบใน v1\n\nกรณีขอบสำคัญ แต่ไม่จำเป็นต้องจัดการทั้งหมดในทันที แก้เท่าที่จะทำให้ความเชื่อมั่นไม่พัง (double submits, การแก้ไขขัดแย้ง) และเลื่อนที่เหลือพร้อมบันทึกชัดเจน\n\n### สถานะข้อผิดพลาดและสิทธิ์ถูกเลื่อนไปเป็น "ทีหลัง"\n\nถ้าไม่เขียนไว้ คุณจะพลาดมัน รวมอย่างน้อยหนึ่งเส้นทางไม่สำเร็จและกฎสิทธิ์หนึ่งข้อในเกณฑ์การยอมรับ\n\n### เกณฑ์ที่คุณตรวจสอบไม่ได้\n\nหลีกเลี่ยงคำว่า “เร็ว” หรือ “น่าใช้งาน” เว้นแต่จะแนบตัวเลขหรือการตรวจสอบที่ชัดเจน แทนที่ด้วยสิ่งที่พิสูจน์ได้ในการรีวิวเริ่มจากเขียนผลลัพธ์เป็นประโยคเดียวว่าเมื่อเสร็จแล้วผู้ใช้จะทำอะไรได้ แล้วเพิ่ม 3–7 เกณฑ์การยอมรับ ที่ผู้ทดสอบสามารถตรวจสอบได้\n\nถ้าคุณอธิบายพฤติกรรม “ถูกต้อง” ไม่ได้โดยไม่ต้องถกเถียง งานนั้นยังคลุมเครืออยู่
ใช้รูปแบบสั้น ๆ นี้:\n\n- ในฐานะ [ผู้ใช้]\n- ฉันต้องการ [การกระทำ]\n- เพื่อที่ฉันจะได้ [เป้าหมาย]\n\nแล้วเพิ่มตัวอย่างพฤติกรรมที่คาดหวังอย่างหนึ่ง ถ้าให้ตัวอย่างไม่ได้ ให้ย้อนไปจำเหตุการณ์ครั้งล่าสุดที่ปัญหาเกิดขึ้นแล้วเขียนสิ่งที่ผู้ใช้คลิกและคาดหวังจะเห็น
เขียนรายการสั้น ๆ ของ "เกณฑ์เสร็จ" ก่อน (เช็คลิสต์ที่ต้องผ่าน) แล้วแยกรายการ "สิ่งที่อยากได้"\n\nกฎมาตรฐาน: ถ้าไม่จำเป็นเพื่อพิสูจน์ว่าฟีเจอร์ทำงานแบบ end-to-end ให้ใส่ไว้ใน "สิ่งที่อยากได้"
ถามคำถามสั้น ๆ ที่เปลี่ยนขอบเขต:\n\n- ใครใช้ได้บ้าง (ระดับและบทบาท)?\n- กำหนดส่งเมื่อไร และเวอร์ชันที่ยอมรับได้ขั้นต่ำคืออะไร?\n- ตัวอย่างพฤติกรรมที่คาดหวังคืออะไร?\n- เกิดอะไรขึ้นในสถานะว่าง ข้อผิดพลาด และการเชื่อมต่อช้า?\n- เราจะยืนยันได้อย่างไรว่ามันทำงาน (เกณฑ์หรือเมตริก)?\n\nคำถามเหล่านี้จะยัดการตัดสินใจที่หายไปออกมาข้างนอก
มองข้ามไม่ได้: รวมกรณีที่ทำให้ความเชื่อมั่นพังไว้ใน v1:\n\n- สถานะว่าง\n- ข้อผิดพลาดการตรวจสอบข้อมูล\n- สิทธิ์ถูกปฏิเสธ\n- ความล้มเหลวของเครือข่าย/API\n- พฤติกรรม “ยกเลิก/ย้อนกลับ” ถ้ามี\n\nอย่างอื่นสามารถเลื่อนออกไปโดยระบุไว้เป็นสิ่งที่ไม่รวมในขอบเขต
ใช้ ประโยคที่ทดสอบได้ ที่ใครก็ทำตามได้โดยไม่ต้องเดา:\n\n- Given สถานะเริ่มต้น\n- When ผู้ใช้ทำ X\n- Then เกิด Y\n\nรวมอย่างน้อยหนึ่งกรณีล้มเหลวและหนึ่งกฎเรื่องสิทธิ์ หากเกณฑ์ใดทดสอบไม่ได้ ให้เขียนใหม่จนกว่าจะทดสอบได้
ระบุหน้าจอที่เปลี่ยนและการเปลี่ยนที่มองเห็นได้เป็นอย่างแรก\n\nและรายการสถานะ UI ที่ต้องมี:\n\n- กำลังโหลด\n- ว่าง\n- ข้อผิดพลาด (และมีปุ่มลองใหม่หรือไม่)\n- สำเร็จ (toast/ข้อความ/รายการอัปเดต)\n\nรวมข้อความใน UI (ปุ่ม ข้อความช่วย เหตุผลข้อผิดพลาด) ให้อยู่ในขอบเขต แม้จะเป็นสำเนาชั่วคราวก็ตาม
รักษาสัญญา API ให้เล็ก: มักพอด้วย หนึ่งการอ่าน และ หนึ่งการเขียน สำหรับ v1\n\nกำหนด:\n\n- อินพุต/เอาต์พุตเป็นวัตถุเรียบ (ฟิลด์ที่ต้องการ vs ตัวเลือก)\n- ข้อผิดพลาดทั่วไป (ไม่พบ, ตรวจสอบล้มเหลว)\n- กฎการยืนยันสิทธิ์เป็นหนึ่งประโยค (ใครอ่าน/เขียนได้)\n\nบันทึกข้อเท็จจริง; คำนวนมุมมองเมื่อเป็นไปได้
ขอผลลัพธ์ที่บรรจุกล่อง:\n\n- สรุปขอบเขต + เช็คลิสต์เกณฑ์\n- 3–7 คอมมิต แต่ละคอมมิตปลดล็อกพฤติกรรมหนึ่งอย่าง\n- ไฟล์ที่จะถูกแก้โดยคร่าวต่อคอมมิต\n- แผนการทดสอบสั้น ๆ (เส้นทางปกติ + ขอบกรณีหนึ่ง)\n- รายการสิ่งที่ไม่รวมในขอบเขต\n\nแล้วขอให้ปรับคำที่คลุมเครือให้เป็นพฤติกรรมที่วัดได้
ลำดับมาตรฐาน:\n\n- การเปลี่ยนโมเดลข้อมูล/มิเกรชัน (ถ้าต้องการ) + เทสต์\n- พฤติกรรม API + การตรวจสอบ\n- การเชื่อม UI กับสถานะว่าง/ข้อผิดพลาด\n- งานแต่งเติมเล็กน้อยถ้าจำเป็น\n\nกติกา: คอมมิตหนึ่งชิ้น = พฤติกรรมใหม่ที่ผู้ใช้เห็นได้หนึ่งอย่าง + วิธีพิสูจน์สั้น ๆ อย่ารวมการรีแฟกเตอร์ใหญ่ ๆ เข้าไปในคอมมิตของฟีเจอร์