วิธีเขียนรายงานบั๊กที่ดี (สำหรับ AI หรือนักพัฒนา)

รายงานบั๊กที่ดีทำให้คนอื่น ทั้งนักพัฒนาหรือ AI สามารถเห็นปัญหาเดียวกับที่คุณเห็นได้ โดยไม่ต้องถามคุณเพิ่มเติม มันต้องมีหัวข้อที่เจาะจง ขั้นตอนที่แน่นอนในการทำให้เกิดซ้ำ สิ่งที่คุณคาดหวัง สิ่งที่เกิดขึ้นจริง ข้อความ error ที่คัดลอกคำต่อคำ และที่มาของปัญหา: หน้าไหน เบราว์เซอร์ อุปกรณ์ และผู้ใช้ รวมถึงหนึ่งบั๊กต่อหนึ่งรายงาน พร้อมภาพหน้าจอหากช่วยได้

บั๊กส่วนใหญ่ใช้เวลาทำความเข้าใจนานกว่าการแก้ไข รายงานที่ชัดเจนจะตัดส่วนการทำความเข้าใจออกไป สิ่งนี้สำคัญยิ่งขึ้นกับเครื่องมือ AI: AI ไม่สามารถถามคำถามต่อเนื่องเกี่ยวกับความหมายของ “หน้าชำระเงินแปลก ๆ” จึงต้องเดา และการเดาที่ผิดอาจทำให้สิ่งอื่นพังไปด้วย

เทมเพลต

คัดลอกนี้และกรอกข้อมูล:

หัวข้อ: [อะไรผิดพลาด ที่ไหน] เช่น “ฟอร์มการจองปฏิเสธเวลาหลัง 18:00”

ขั้นตอนในการทำให้เกิดซ้ำ:
1. ...
2. ...
3. ...

ที่คาดหวัง: [ควรเกิดอะไรขึ้น]
ที่เกิดขึ้นจริง: [เกิดอะไรขึ้นแทน]

ข้อความ error: [ข้อความที่แน่นอน ถ้ามี]
ที่ไหน: [หน้า/URL เบราว์เซอร์ อุปกรณ์ เข้าสู่ระบบด้วยผู้ใช้คนไหน]
ความถี่: [ทุกครั้ง / บางครั้ง / ครั้งเดียว]
ภาพหน้าจอหรือวิดีโอบันทึก: [แนบ]

ส่วนที่เหลือของคู่มืออธิบายแต่ละส่วน

ขั้นที่ 1: ทำให้มันเกิดซ้ำก่อน

ก่อนเขียน ให้ลองทำให้บั๊กเกิดขึ้นอีกครั้ง คุณจะรู้ว่าขั้นตอนไหนสำคัญ และมันเกิดขึ้นทุกครั้งหรือไม่

• เริ่มจากสถานะที่สะอาด: รีเฟรช หรือออกจากระบบแล้วเข้าใหม่
• จดทุกการคลิกและทุกสิ่งที่คุณพิมพ์
• ลองหาเส้นทางที่สั้นที่สุดที่ทำให้มันเกิด
• ลองเบราว์เซอร์หรือบัญชีอื่น หากเกิดขึ้นเฉพาะผู้ใช้คนเดียว นั่นคือเบาะแสสำคัญ

ดูเพิ่มเติมที่ วิธีดีบั๊กแอปที่สร้างด้วย AI

ขั้นที่ 2: เขียนหัวข้อให้เจาะจง

หัวข้อควรบอกว่าอะไรผิดและผิดตรงไหน เพื่อให้ผู้ที่กวาดตาดูรายการสามารถรู้ได้ว่าเป็นบั๊กไหน

ขั้นที่ 3: ลิสต์ขั้นตอนที่แน่นอน

ใส่หมายเลขกำกับ และตรงไปตรงมา: หน้าไหน ปุ่มไหน และคุณพิมพ์อะไร

1. เข้าสู่ระบบในฐานะลูกค้า (บัญชีทดสอบ: customer@example.com)
2. เพิ่ม “Starter kit” ลงในตะกร้า
3. ใส่โค้ดส่วนลด WELCOME10 แล้วคลิก Apply
4. คลิก Checkout

“ลองชำระเงินด้วยโค้ด” ละเว้นรายละเอียดที่มักสำคัญ: ผู้ใช้คนไหน สินค้าอะไร โค้ดอะไร และโค้ดถูกนำไปใช้ก่อนหรือไม่

ขั้นที่ 4: ที่คาดหวัง กับที่เกิดขึ้นจริง

นี่คือแกนหลักของรายงาน ให้บอกทั้งสองอย่าง เพราะความแตกต่างระหว่างสองอย่างนั้นคือบั๊ก

• ที่คาดหวัง: หน้าชำระเงินเปิดขึ้นพร้อมส่วนลด 10% ที่แสดงในยอดรวม
• ที่เกิดขึ้นจริง: ปุ่มแสดงสปินเนอร์อยู่หนึ่งวินาที แล้วไม่มีอะไรเกิดขึ้น เมื่อไม่มีโค้ดส่วนลด การชำระเงินทำงานได้

หากไม่มี “ที่คาดหวัง” ผู้อ่านอาจไม่รู้ว่าพฤติกรรมนั้นผิด หากไม่มี “ที่เกิดขึ้นจริง” พวกเขาไม่รู้ว่าควรมองหาอะไร

ขั้นที่ 5: คัดลอก error อย่างแม่นยำ

ข้อความ error คือเส้นทางที่เร็วที่สุดสู่สาเหตุ คัดลอกเป็นข้อความคำต่อคำ อย่าเรียบเรียงใหม่

ที่หาได้:

• บนหน้าจอ: ข้อความใดก็ตามที่แอปแสดง
• Console ของเบราว์เซอร์: เปิดเครื่องมือสำหรับนักพัฒนา (F12 หรือคลิกขวา → Inspect) แล้วดูแท็บ Console สำหรับบรรทัดสีแดง
• แท็บ Network: ในเครื่องมือสำหรับนักพัฒนา หา request ที่ล้มเหลว แล้วจด URL และ status code (เช่น POST /api/checkout → 500)
• server log หากคุณเข้าถึงได้

บรรทัดอย่าง TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48 มักชี้ตรงไปยังปัญหาได้เลย

ขั้นที่ 6: เพิ่มบริบท

• ที่ไหน: URL ของหน้า สภาพแวดล้อม (preview, staging หรือ live)
• ใคร: ผู้ใช้หรือบทบาทไหน เช่น แอดมิน สมาชิก หรือยังไม่ได้เข้าสู่ระบบ
• อุปกรณ์และเบราว์เซอร์: “Safari บน iPhone” กับ “Chrome บน Windows” อาจสำคัญ
• ข้อมูล: อะไรที่ผิดปกติเกี่ยวกับระเบียน เช่น ข้อความยาวมาก อักขระพิเศษ หรือจำนวนรายการจำนวนมาก
• เริ่มเมื่อไร: “หลังการเปลี่ยนแปลงโค้ดส่วนลดเมื่อวาน” มีค่ามาก
• ความถี่: ทุกครั้ง หรือหนึ่งในสิบครั้ง

ขั้นที่ 7: แสดงให้เห็น

ภาพหน้าจอที่วงปัญหาไว้ หรือวิดีโอบันทึกหน้าจอสั้น ๆ จะขจัดความคลุมเครือ โดยเฉพาะบั๊กเรื่องเลย์เอาต์ หากเครื่องมือ AI ของคุณรับรูปภาพได้ ให้แนบมา ตัดส่วนที่เป็นความลับออก รวมถึง key และข้อมูลของคนอื่น

การเขียนรายงานบั๊กให้เครื่องมือสร้างแอป AI

โครงสร้างเดียวกันนี้ใช้เป็น prompt ได้ โดยเพิ่มสองอย่าง:

• บอกสิ่งที่ห้ามเปลี่ยน เพื่อไม่ให้การแก้ไขทำให้เกิดปัญหาใหม่
• ขอให้ตรวจสอบการแก้ไข ไม่ใช่แค่เขียนมัน

เข้าสู่ระบบในฐานะลูกค้า มี “Starter kit” ในตะกร้า และใช้โค้ด WELCOME10 แล้ว เมื่อคลิก Checkout ไม่มีอะไรเกิดขึ้น ที่คาดหวัง: หน้าชำระเงินเปิดขึ้นพร้อมส่วนลด 10% ของยอดรวม ที่เกิดขึ้นจริง: สปินเนอร์สั้น ๆ แล้วไม่มีอะไร แท็บ network แสดงว่า POST /api/checkout ตอบ 500 การชำระเงินโดยไม่มีโค้ดทำงานได้ ค้นหาสาเหตุและแก้ไขโดยไม่เปลี่ยนวิธีคำนวณราคาสำหรับออเดอร์ที่ไม่มีโค้ด จากนั้นตรวจการชำระเงินด้วยโค้ดเปอร์เซ็นต์ โค้ดจำนวนเงินคงที่ และไม่มีโค้ด

หากคุณไม่แน่ใจเรื่องสาเหตุ ให้ขอการวินิจฉัยก่อน:

ยังไม่ต้องเปลี่ยนโค้ด จากรายงานนี้ สาเหตุที่เป็นไปได้มีอะไรบ้าง และอะไรจะยืนยันแต่ละสาเหตุได้

ข้อผิดพลาดที่พบบ่อย

• “มันพัง” ไม่มีขั้นตอน ไม่มีผลที่คาดหวัง ไม่มีอะไรให้ลงมือ
• หลายบั๊กในรายงานเดียว บางอันได้รับการแก้ไข อีกอันหายไป
• ถอดความ error “undefined อะไรสักอย่าง” ซ่อนส่วนที่มีประโยชน์
• ลืมระบุผู้ใช้หรือบทบาท บั๊กหลายตัวกระทบเฉพาะแอดมิน หรือเฉพาะผู้ใช้ใหม่
• บรรยายเฉพาะการแก้ไขที่คุณต้องการ (“เพิ่มการตรวจสอบ null”) แทนที่จะบรรยายปัญหา
• แชร์ความลับ ในภาพหน้าจอหรือ log ที่วางมา

รายการตรวจสอบ

• ฉันทำให้บั๊กเกิดซ้ำและหาขั้นตอนที่สั้นที่สุดได้แล้ว
• หัวข้อบอกว่าอะไรผิดและที่ไหน
• ขั้นตอนมีหมายเลขและตรงไปตรงมา
• ระบุทั้งที่คาดหวังและที่เกิดขึ้นจริง
• คัดลอก error อย่างแม่นยำ พร้อม request ที่ล้มเหลวและ status code
• มีหน้า สภาพแวดล้อม ผู้ใช้ อุปกรณ์ และเบราว์เซอร์
• ฉันบอกความถี่และเวลาที่เริ่มเกิด
• แนบภาพหน้าจอหรือวิดีโอแล้ว โดยลบข้อมูลส่วนตัวออก
• หนึ่งบั๊กต่อหนึ่งรายงาน

การรายงานบั๊กให้ agent ของ Mythex

ในโปรเจกต์ Mythex รายงานคือ prompt เอง มีฟีเจอร์บางอย่างที่ช่วยได้:

• แนบภาพหน้าจอ ของ preview หรือหน้าจอ error ได้สูงสุด 5 ไฟล์ต่อข้อความ
• /fix ทำให้ agent โฟกัสกับการแก้บั๊ก และโหมด Plan ให้มันตรวจสอบก่อนแก้ไข
• /test ให้ agent ทำซ้ำขั้นตอนต่าง ๆ ใน preview เองและรายงานสิ่งที่มันเห็น
• Revert to this point ยกเลิกการแก้ไขที่ทำให้สิ่งต่าง ๆ แย่ลง

หน้า การดีบั๊กด้วย prompt ในเอกสารใช้โครงสร้างขั้นตอน / ที่คาดหวัง / ที่เกิดขึ้นจริงแบบเดียวกัน สำหรับลูปการแก้ไขและตรวจสอบรอบ ๆ มัน ดู วิธีทำซ้ำกับแอปที่สร้างด้วย AI

คำถาม