ตัวแทนการเข้ารหัสชอบบันทึกการตัดสินใจ

บทความต่อไปนี้เดิมปรากฏเมื่อ บล็อกของดันแคน เดวิดสัน และกำลังเผยแพร่ซ้ำที่นี่โดยได้รับอนุญาตจากผู้เขียน

บันทึกการตัดสินใจช่วยให้ตัวแทนการเขียนโค้ดมีบริบทของโครงการที่คงทน ตราบใดที่พวกเขาไม่ได้เปลี่ยนทุกการตัดสินใจให้กลายเป็นบันทึกของศาล

บันทึกการตัดสินใจทางสถาปัตยกรรม (ADR) ช่วยให้ทีมงานมนุษย์สร้างกฎเกณฑ์และขับเคลื่อนบริบทในโครงการซอฟต์แวร์ พวกเขารวบรวมตัวเลือกการออกแบบที่มีความหมาย บริบท และเหตุผลที่อยู่เบื้องหลัง เช่นเดียวกับเครื่องมือหลายอย่างที่ออกแบบมาสำหรับทีมซอฟต์แวร์มนุษย์ ADR ยังทำงานได้ดีกับตัวแทนการเขียนโค้ดอีกด้วย

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

เมื่อการตัดสินใจเข้าสู่หน้าต่างบริบทของตัวแทน ตัวแทนสามารถปฏิบัติตามการตัดสินใจนั้นได้เคร่งครัดมากกว่าที่มนุษย์จะทำ ในงานของฉันเอง ฉันเคยเห็นเจ้าหน้าที่ต่อสู้ฟันฝ่าฟันและตอกตะปูเพื่อบังคับใช้การตัดสินใจที่ได้รับการยอมรับแม้ว่าจะล้าสมัยไปแล้วก็ตาม ในกรณีหนึ่ง เอเจนต์จะรักษาสิ่งที่เป็นนามธรรมของการจัดเก็บข้อมูลที่ล้าสมัยไว้ในทรัพยากรใหม่ เนื่องจาก ADR ยังคงอธิบายว่าเป็นสิ่งที่จำเป็น แทนที่จะทำเครื่องหมายความไม่เข้ากันนั้น กลับเพิ่มเลเยอร์อื่นเพื่อให้ข้อกำหนดใหม่เข้ากันได้กับทางเทคนิคกับการตัดสินใจเก่า

วิธีแก้ปัญหาแรกคือการให้สิทธิ์แก่ตัวแทนอย่างชัดเจนในการตั้งคำถามต่อการตัดสินใจที่ไม่เหมาะอีกต่อไป และคอยสังเกตสัญญาณที่แสดงว่าพวกเขากำลังปรับเปลี่ยนมากเกินไป แต่นี่จะช่วยแก้ปัญหาได้เพียงครึ่งเดียวเท่านั้น เมื่อตัวแทนได้รับเชิญให้อัปเดตการตัดสินใจ มีแนวโน้มที่สองเกิดขึ้น: การรักษาการพิจารณา การชี้แจงแต่ละครั้งกลายเป็นการเปลี่ยนแปลงที่อธิบายการดำรงอยู่ของมันเองโดยสูญเสียความชัดเจน รายละเอียดการใช้งานเล็กๆ น้อยๆ กลายเป็นกฎเกณฑ์ และการอ้างอิงโยงจะได้รับการปฏิรูปและการให้เหตุผลของตนเอง ผลลัพธ์ที่ได้คือร้อยแก้วที่มีการฟ้องร้องดำเนินคดีมากเกินไปซึ่งมนุษย์อ่านยาก

ADR จะต้องเป็นสิ่งที่มนุษย์สามารถอ่านได้อย่างแน่นอน โดยเฉพาะอย่างยิ่งเมื่อเราพึ่งพาตัวแทนในการสร้างโค้ดเพิ่มมากขึ้นเรื่อยๆ เพื่อตอบโต้สิ่งนี้ ฉันจึงแสดงความชัดเจนในโครงการของฉัน AGENTS.md ไฟล์เกี่ยวกับวิธีการใช้และรักษา ADR ของตัวแทน นี่เป็นข้อความที่ตัดตอนมาจากข้อหนึ่ง:

Architectural Decision Records (ADRs) are stored as Markdown files in the
docs/decisions directory. Treat accepted ADRs as binding. Proposed ADRs
are non-binding context. Superseded ADRs are historical context and do
not govern current work. If a given task conflicts with an accepted ADR,
stop and discuss whether the task or ADR should change and propose the
change that you think should be made. Propose new ADRs or updates to
existing ones when a change introduces or revises a durable product or
architectural decision.

Keep ADRs succinct. Each ADR carries only its current text; Git history
is its changelog, so do not add or maintain amendment logs in ADR
headers. When substantively changing an accepted ADR, add or update a
single Updated: date line after Date:—its presence signals that history
exists and Git has the details. A superseded ADR records a Superseded-On:
date instead of Updated: , matching the Supersedes: line on the ADR that
replaced it. State each rule once in the ADR that owns it and cross-reference
it from other ADRs instead of restating it.

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

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