เขียนคำอธิบายงานให้ agent

อธิบายการเปลี่ยนแปลงที่ผู้ตรวจทานประเมินได้

“เพิ่มการ export ข้อมูลลูกค้า” ยังเว้นการตัดสินใจหลายข้อ ใคร export ระเบียนได้ รวมระเบียนและ field ใดบ้าง เมื่อคำขอล้มเหลวจะเกิดอะไร Agent อาจเติมช่องว่างเหล่านี้ด้วยตัวเลือกที่ดูสมเหตุสมผล แต่ตัวเลือกนั้นยังอาจผิดสำหรับธุรกิจ

เริ่มจากผู้ใช้และปัญหา แล้วอธิบายพฤติกรรมที่ต้องการ รวมหลักฐานที่จะแสดงว่าผลลัพธ์ยอมรับได้หรือไม่

คำอธิบายงานควรลดความไม่แน่นอนโดยไม่ล็อกการออกแบบภายในทุกข้อ ระบุขอบเขตข้อมูลที่จำเป็น ให้การพัฒนาใช้รูปแบบที่มีใน repository เว้นแต่มีเหตุผลให้เปลี่ยน

ใช้ตัวอย่างที่เจาะจง

คำอธิบายงานต่อไปนี้สำหรับแอปพลิเคชันช่วยเหลือลูกค้าสมมติ เป็นตัวอย่างเพื่อการเรียนรู้ ไม่ใช่ specification สำหรับ production ที่ครบถ้วน

ผลลัพธ์: ผู้จัดการทีมช่วยเหลือลูกค้าดาวน์โหลดรายชื่อลูกค้าได้
ผู้ดำเนินการ: ผู้จัดการในองค์กรปัจจุบัน
ข้อมูล: เฉพาะลูกค้าที่ใช้งานอยู่ในองค์กรนั้น
Field: Customer ID ชื่อบริษัท และสถานะบัญชี
รูปแบบ: UTF-8 CSV ที่มีแถว header
คำขอที่ถูกปฏิเสธ: ส่งกลับข้อผิดพลาดการตรวจสอบสิทธิ์ที่ใช้อยู่
ผลลัพธ์ว่าง: ส่งกลับ CSV ที่ถูกต้องและมีเฉพาะ header
ขอบเขต: ใช้ route สำหรับ export และรูปแบบ audit ที่มีอยู่
สิ่งที่ไม่รวม: ไม่มี role ใหม่ dependency ใหม่ หรือ deployment
หลักฐาน: Test สำหรับคำขอที่อนุญาต ถูกปฏิเสธ ได้ผลลัพธ์ว่าง และข้ามองค์กร

คำอธิบายงานนี้ระบุพฤติกรรมที่มีประโยชน์และข้อจำกัด อีกทั้งเผยคำถามเพิ่มเติม ควรจำกัดขนาด export หรือไม่ Field อาจมีสูตร spreadsheet ได้หรือไม่ ใครเข้าถึงบันทึก audit ได้ หาคำตอบให้คำถามที่มีผลสำคัญก่อนพัฒนา อย่าถือว่าตัวอย่างนี้เป็น checklist ที่ใช้ได้กับทุกกรณี

แยกข้อกำหนดออกจากสมมติฐาน

ข้อกำหนดระบุพฤติกรรมที่การเปลี่ยนแปลงต้องทำได้ สมมติฐานคือข้อเท็จจริงที่ยังไม่ได้ตรวจสอบ แยกสองอย่างนี้ไว้

ตัวอย่างเช่น “ใช้รูปแบบ audit ที่มีอยู่” สันนิษฐานว่ามีรูปแบบที่เหมาะสมแล้ว ขอให้ agent หาให้พบ หาก repository ไม่มี Agent ควรรายงานสิ่งที่ต้องพึ่งพาซึ่งยังขาด ก่อนคิดระบบ audit ใหม่ขึ้นเอง

ข้อจำกัดอาจขัดกับผลลัพธ์ได้ด้วย Route เดิมอาจออกแบบให้ส่งกลับข้อมูลทุกองค์กร Agent ควรแสดงข้อขัดแย้งและเสนอการแก้ไขที่มีขอบเขต ไม่ควรลบขอบเขตข้อมูลโดยไม่แจ้ง หรือขยายงานเป็นการเขียนสถาปัตยกรรมใหม่

ให้งานเสร็จหมายถึงมีหลักฐานด้วย

ขอสรุปการส่งมอบที่อธิบายพฤติกรรมสุดท้าย ขอบเขตที่เปลี่ยน และการตรวจสอบที่ทำแล้ว ให้ระบุคำสั่งและผลลัพธ์จริงในจุดที่สำคัญ แยกการตรวจสอบที่ผ่านออกจากการตรวจสอบที่รันไม่ได้

Pull request ควรรักษาเหตุผลของการเปลี่ยนแปลงไว้ ผู้ดูแลในภายหลังอาจเห็นโค้ดโดยไม่มีบทสนทนาเดิม ให้บริบทเพียงพอที่จะอธิบายว่าทำไม export ไม่รวม field บางตัว และบังคับใช้สิทธิ์เข้าถึงอย่างไร

แนวทางการเขียนคำอธิบายการเปลี่ยนแปลงของ Google เป็นข้อมูลอ้างอิงที่มีประโยชน์สำหรับบันทึกนี้ คำอธิบายควรบอกว่าเปลี่ยนอะไรและเพื่ออะไร หลังแก้ตามการตรวจทาน ให้ปรับบันทึกให้ตรงกับสิ่งที่พัฒนาจริงในตอนสุดท้าย

ให้รายละเอียดเหมาะกับขนาดงาน

การแก้ข้อความเล็กน้อยใช้คำอธิบายงานสั้น ๆ ได้ การ export ข้อมูลต้องมีรายละเอียดมากกว่า เพราะความผิดพลาดอาจเปิดเผยข้อมูล ขั้นตอนชำระเงินใหม่ต้องวิเคราะห์และตรวจทานมากขึ้นอีก

อย่าวัดคุณภาพคำอธิบายงานจากความยาว ถามว่าผู้ตรวจทานที่มีความสามารถจะแยกผลลัพธ์ถูกออกจากผลลัพธ์ผิดได้หรือไม่ หากวิธีพัฒนาสองแบบที่ดูสมเหตุสมผลให้พฤติกรรมสำคัญต่างกัน ให้ระบุพฤติกรรมนั้นให้ชัดก่อน