ข้อเสนอเรื่องโครงสร้างไฟล์นี้ใช้เป็นแนวทางจัดระเบียบได้ แต่มี 3 เรื่องที่ไม่ควรเหมารวม: ไม่ใช่การทดสอบทุกชนิดจะย้ายออกจากแพ็กเกจธุรกิจได้โดยไม่มีข้อยกเว้น, สเปกไม่ใช่บทสรุปรวมของ ADR ทั้งหมด และการพักแผนไว้ก็ไม่เท่ากับการปิดงานหรือจัดเก็บเป็นงานที่เสร็จแล้ว

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

1. รวมการทดสอบไว้ในโฟลเดอร์กลาง แต่เผื่อข้อยกเว้นตามภาษา

ให้การทดสอบอยู่ในโฟลเดอร์กลางเป็นแนวทางหลัก แต่อย่ากำหนดว่าทุกโปรเจกต์ต้องไม่มีไฟล์ทดสอบอยู่ข้างโค้ดโดยเด็ดขาด

• Python: แนะนำให้รวมไว้ที่ tests/ และตรวจสอบการ import, การค้นหาชุดทดสอบ, fixtures และ CI หลังย้าย ปัจจุบัน CI ของรีโปนี้ใช้เส้นทางทดสอบแบบรวมศูนย์อยู่แล้ว
• Go: การทดสอบแบบ white-box ที่ต้องเข้าถึงสมาชิกซึ่งไม่ได้ export ควรอยู่ในแพ็กเกจเดียวกับโค้ดที่ทดสอบ ส่วนการทดสอบแบบ black-box การทดสอบข้ามคอมโพเนนต์ และ end-to-end ควรรวมไว้ที่ส่วนกลางเมื่อเหมาะสม เครื่องมือ Go คอมไพล์ไฟล์ทดสอบแยกตามแพ็กเกจ และรองรับทั้งการทดสอบในแพ็กเกจเดียวกันกับแพ็กเกจทดสอบภายนอก 1416
• อย่าสับสนระหว่างข้อจำกัดการ import ของแพ็กเกจ internal กับการเข้าถึงสมาชิกที่ไม่ได้ export ข้อจำกัดของ internal ขึ้นกับตำแหน่งไดเรกทอรีบรรพบุรุษ ไม่ได้แปลว่าต้องอยู่ไดเรกทอรีเดียวกันจึงจะ import ได้ 1016

ดังนั้น ไม่ควรใช้เงื่อนไขว่า “ย้ายการทดสอบ Go ทั้งหมดออกจากโฟลเดอร์ธุรกิจ โดยยังคงการทดสอบแบบ white-box และการห่อหุ้มโค้ดไว้เหมือนเดิม” เป็นเกณฑ์ผ่านโดยอัตโนมัติ อย่า export สถานะภายในหรือทำสำเนา logic ของธุรกิจ เพียงเพื่อให้โครงสร้างโฟลเดอร์ดูเรียบร้อย

สิ่งที่ควรลดคือไฟล์ย่อยที่ไม่มีคุณค่าและการตรวจซ้ำซ้อน ไม่ใช่ไฟล์ทดสอบแยกที่มีเหตุผล การทดสอบ regression ที่ต้องใช้ซ้ำควรอยู่ในการควบคุมเวอร์ชัน ส่วน probe ที่ใช้ครั้งเดียวจึงค่อยเก็บในพื้นที่ชั่วคราว

2. แยกสเปก, ADR และกฎระดับโปรเจกต์ออกจากกัน

แนวคิดโดยรวมใกล้เคียงแล้ว แต่ไม่ควรนิยาม specs/ ว่าเป็น “การสกัดกฎทั่วไปจาก ADR ทั้งหมด” แนะนำให้แบ่งหน้าที่ดังนี้

ชั้น	ตอบคำถามว่า	ที่มาของเนื้อหา
วิธีทำงานระดับส่วนกลาง	ควรวิเคราะห์ ตรวจสอบ และส่งมอบงานอย่างไร	ผู้ดูแลวิธีการทำงานกำหนด
จุดเริ่มต้นของโปรเจกต์ AGENTS.md	ทำงานในโปรเจกต์นี้อย่างไร	ข้อจำกัดที่ยืนยันแล้วและทางเข้าสู่ขั้นตอนต่าง ๆ
สเปกของโปรเจกต์ specs/	พฤติกรรมและสัญญาปัจจุบันที่ต้องทำตามคืออะไร	ความต้องการของผู้ใช้ การตัดสินใจที่ยอมรับแล้ว และการแก้ไขที่ได้รับอนุมัติ
บันทึกการตัดสินใจ docs/adr/	เหตุใดจึงเลือกแนวทางนี้	การแลกเปลี่ยนเชิงสถาปัตยกรรมและทางเลือกที่พิจารณา

เอกสารทางการของ Cline ยืนยันว่ามีกลไกกฎถาวรสำหรับเก็บคำสั่งที่ใช้ข้ามเซสชัน 4 แต่ข้อมูลในรอบนี้ไม่ได้ยืนยันว่า Cline จะเขียนไฟล์บางประเภทลงในโฟลเดอร์สเปกโดยอัตโนมัติ จึงควรถือเรื่องดังกล่าวเป็นข้อตกลงของโปรเจกต์ ไม่ใช่ความสามารถที่ Cline รับรอง

เนื้อหาของโปรเจกต์ไม่จำเป็นต้องเขียนเองทั้งหมด และไม่จำเป็นต้องรอให้เกิดปัญหาหรือข้อจำกัดระหว่างทำงานก่อนจึงค่อยสร้างสเปก:

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

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

3. ย้าย ADR ไปไว้ที่ docs/adr/ ได้ โดยไม่เปลี่ยนวิธีรับรอง

การกำหนด docs/adr/ เป็นตำแหน่งเริ่มต้นสำหรับการตัดสินใจใหม่ทำได้ แต่ควรระบุว่าเป็นข้อตกลงด้านการตั้งชื่อและจัดเก็บของโปรเจกต์ ไม่จำเป็นต้องอ้างว่าเป็นมาตรฐานเดียวที่ทุกโปรเจกต์ต้องใช้

คงแนวปฏิบัติเดิมไว้ดังนี้:

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

การย้ายยังต้องอัปเดตการอ้างอิงจริง เส้นทางการทำงาน และข้อจำกัดสิทธิ์ที่เกี่ยวข้อง ไม่ใช่แค่ย้ายไฟล์อย่างเดียว

4. แผนงานเก็บแบบแบนได้ แต่ต้องแยก “พัก” ออกจาก “เสร็จ”

รูปแบบ plans/ ที่วางไฟล์ไว้ในโฟลเดอร์เดียวกันใช้ได้ ไม่จำเป็นต้องสร้างโฟลเดอร์ย่อยเพื่อรองรับแผนเก่าจำนวนน้อย อาจใช้ชื่อไฟล์ตัวอย่างต่อไปนี้:

การใช้งาน	ชื่อไฟล์ตัวอย่าง	ความหมาย
แผนที่กำลังทำ	pending_implementation_plan.md	จุดเริ่มต้นหลักสำหรับแผนที่กำลังดำเนินการ
บันทึกแผนหลังเสร็จ	plan-20261022-example-id.md	งานเสร็จและได้รับอนุญาตให้จัดเก็บแล้ว
แผนที่พักไว้แต่ยังไม่เสร็จ	plan-20261022-example-id-frozen.md	เก็บงานค้างไว้ แต่ไม่ถือเป็นแผนที่กำลังทำโดยปริยาย

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

สิ่งสำคัญคือต้องแยกสถานะให้ชัด:

• จัดเก็บว่าเสร็จแล้ว: เกณฑ์รับงานที่จำเป็นผ่านครบ และได้รับอนุญาตให้จัดเก็บ
• พักไว้โดยยังไม่เสร็จ: นำออกจากจุดเริ่มต้นของงานที่กำลังทำ แต่ห้ามระบุว่าเสร็จ และห้ามเปลี่ยนข้อเสนอที่ยังไม่ผ่านการตรวจให้กลายเป็นข้อเท็จจริง
• ยกเลิกอย่างชัดเจน: ระบุว่าไม่ดำเนินการต่อและบอกผลกระทบ ไม่ใช้คำว่า “พักชั่วคราว” แทนการยกเลิก หากต้องการสถานะยกเลิกอย่างเป็นทางการ ควรแก้ข้อตกลงแยกต่างหาก

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

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

5. เชื่อมโยงโค้ดกับการทดสอบแบบหลายต่อหลาย

ไม่ควรกำหนดว่าหนึ่งไฟล์โค้ดต้องมีไฟล์ทดสอบคู่กันหนึ่งไฟล์พอดี เพราะการทดสอบหนึ่งชุดอาจครอบคลุมหลายคอมโพเนนต์ และคอมโพเนนต์เดียวอาจต้องมีทั้ง unit test, property test และ integration regression

แนวทางเริ่มต้นที่แนะนำ:

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

ไฟล์แผนผังควรเก็บเท่าที่จำเป็น เช่น รหัสโมดูลหรือสัญญา ขอบเขตซอร์ส ขอบเขตการทดสอบ และคำสั่งตรวจสอบ ไม่ต้องคัดลอกโครงสร้างโฟลเดอร์ทั้งหมดหรือบันทึกสถานะว่าการทดสอบผ่านไว้ซ้ำอีกชุด

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

6. รวมร่างชั่วคราวไว้ได้ แต่อย่าใช้ตำแหน่งไฟล์ตัดสินความน่าเชื่อถือ

เห็นด้วยกับการรวมร่างชั่วคราว สคริปต์ใช้ครั้งเดียว และรายงานสำรวจไว้ที่ .scratch/ แต่ควรปรับแนวคิดที่ว่า “ข้อมูลในนี้ไม่ใช่ข้อมูลชั้นต้น” และ “ลบทั้งหมดได้เสมอ” ให้เป็นกฎที่มีเงื่อนไข

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

สำหรับรายงานเก่าหรือแผนภาพสถาปัตยกรรมใน docs/ ควรแยกเป็น “เอกสารที่ใช้อยู่”, “ข้อมูลประวัติศาสตร์ที่ตั้งใจเก็บ” และ “ข้อมูลที่ยังต้องตรวจสอบ” แทนการมองว่าทุกอย่างเก่าแล้วเป็นขยะ:

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

การเก็บไฟล์ไว้ไม่เท่ากับต้องโหลดมาอ่านทุกครั้ง ควรรักษาประวัติที่จำเป็นและลดข้อมูลรบกวนด้วยการอ่านเฉพาะส่วนที่เกี่ยวข้องกับงาน พร้อมระบุสถานะความเป็นปัจจุบัน แทนการลบหลักฐานทิ้ง

สรุป

แนวทางนี้นำไปใช้ได้ หากยึดขอบเขตหลัก 4 ข้อ: รวมการทดสอบเป็นค่าเริ่มต้นแต่เผื่อข้อยกเว้นตามภาษา, ใช้สเปกบันทึกข้อตกลงปัจจุบันแทนการสรุป ADR ทั้งหมด, แยกแผนที่พักไว้ออกจากงานที่เสร็จ และอย่าลบหลักฐานจำเป็นเพียงเพราะเก็บอยู่ในพื้นที่ชั่วคราว

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

รอบนี้เป็นการวิเคราะห์ในเซสชันเท่านั้น ยังไม่มีการแก้ไข ย้าย พัก หรือลบไฟล์ใด ๆ

ข้อเสนอเรื่องโครงสร้างไฟล์นี้ใช้เป็นแนวทางจัดระเบียบได้ แต่มี 3 เรื่องที่ไม่ควรเหมารวม: ไม่ใช่การทดสอบทุกชนิดจะย้ายออกจากแพ็กเกจธุรกิจได้โดยไม่มีข้อยกเว้น, สเปกไม่ใช่บทสรุปรวมของ ADR ทั้งหมด และการพักแผนไว้ก็ไม่เท่ากับการปิดงานหรือจัดเก็บเป็นงานที่เสร็จแล้ว

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

1. รวมการทดสอบไว้ในโฟลเดอร์กลาง แต่เผื่อข้อยกเว้นตามภาษา

ให้การทดสอบอยู่ในโฟลเดอร์กลางเป็นแนวทางหลัก แต่อย่ากำหนดว่าทุกโปรเจกต์ต้องไม่มีไฟล์ทดสอบอยู่ข้างโค้ดโดยเด็ดขาด

• Python: แนะนำให้รวมไว้ที่ tests/ และตรวจสอบการ import, การค้นหาชุดทดสอบ, fixtures และ CI หลังย้าย ปัจจุบัน CI ของรีโปนี้ใช้เส้นทางทดสอบแบบรวมศูนย์อยู่แล้ว
• Go: การทดสอบแบบ white-box ที่ต้องเข้าถึงสมาชิกซึ่งไม่ได้ export ควรอยู่ในแพ็กเกจเดียวกับโค้ดที่ทดสอบ ส่วนการทดสอบแบบ black-box การทดสอบข้ามคอมโพเนนต์ และ end-to-end ควรรวมไว้ที่ส่วนกลางเมื่อเหมาะสม เครื่องมือ Go คอมไพล์ไฟล์ทดสอบแยกตามแพ็กเกจ และรองรับทั้งการทดสอบในแพ็กเกจเดียวกันกับแพ็กเกจทดสอบภายนอก 1416
• อย่าสับสนระหว่างข้อจำกัดการ import ของแพ็กเกจ internal กับการเข้าถึงสมาชิกที่ไม่ได้ export ข้อจำกัดของ internal ขึ้นกับตำแหน่งไดเรกทอรีบรรพบุรุษ ไม่ได้แปลว่าต้องอยู่ไดเรกทอรีเดียวกันจึงจะ import ได้ 1016

ดังนั้น ไม่ควรใช้เงื่อนไขว่า “ย้ายการทดสอบ Go ทั้งหมดออกจากโฟลเดอร์ธุรกิจ โดยยังคงการทดสอบแบบ white-box และการห่อหุ้มโค้ดไว้เหมือนเดิม” เป็นเกณฑ์ผ่านโดยอัตโนมัติ อย่า export สถานะภายในหรือทำสำเนา logic ของธุรกิจ เพียงเพื่อให้โครงสร้างโฟลเดอร์ดูเรียบร้อย

สิ่งที่ควรลดคือไฟล์ย่อยที่ไม่มีคุณค่าและการตรวจซ้ำซ้อน ไม่ใช่ไฟล์ทดสอบแยกที่มีเหตุผล การทดสอบ regression ที่ต้องใช้ซ้ำควรอยู่ในการควบคุมเวอร์ชัน ส่วน probe ที่ใช้ครั้งเดียวจึงค่อยเก็บในพื้นที่ชั่วคราว

2. แยกสเปก, ADR และกฎระดับโปรเจกต์ออกจากกัน

แนวคิดโดยรวมใกล้เคียงแล้ว แต่ไม่ควรนิยาม specs/ ว่าเป็น “การสกัดกฎทั่วไปจาก ADR ทั้งหมด” แนะนำให้แบ่งหน้าที่ดังนี้

ชั้น	ตอบคำถามว่า	ที่มาของเนื้อหา
วิธีทำงานระดับส่วนกลาง	ควรวิเคราะห์ ตรวจสอบ และส่งมอบงานอย่างไร	ผู้ดูแลวิธีการทำงานกำหนด
จุดเริ่มต้นของโปรเจกต์ AGENTS.md	ทำงานในโปรเจกต์นี้อย่างไร	ข้อจำกัดที่ยืนยันแล้วและทางเข้าสู่ขั้นตอนต่าง ๆ
สเปกของโปรเจกต์ specs/	พฤติกรรมและสัญญาปัจจุบันที่ต้องทำตามคืออะไร	ความต้องการของผู้ใช้ การตัดสินใจที่ยอมรับแล้ว และการแก้ไขที่ได้รับอนุมัติ
บันทึกการตัดสินใจ docs/adr/	เหตุใดจึงเลือกแนวทางนี้	การแลกเปลี่ยนเชิงสถาปัตยกรรมและทางเลือกที่พิจารณา

เอกสารทางการของ Cline ยืนยันว่ามีกลไกกฎถาวรสำหรับเก็บคำสั่งที่ใช้ข้ามเซสชัน 4 แต่ข้อมูลในรอบนี้ไม่ได้ยืนยันว่า Cline จะเขียนไฟล์บางประเภทลงในโฟลเดอร์สเปกโดยอัตโนมัติ จึงควรถือเรื่องดังกล่าวเป็นข้อตกลงของโปรเจกต์ ไม่ใช่ความสามารถที่ Cline รับรอง

เนื้อหาของโปรเจกต์ไม่จำเป็นต้องเขียนเองทั้งหมด และไม่จำเป็นต้องรอให้เกิดปัญหาหรือข้อจำกัดระหว่างทำงานก่อนจึงค่อยสร้างสเปก:

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

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

3. ย้าย ADR ไปไว้ที่ docs/adr/ ได้ โดยไม่เปลี่ยนวิธีรับรอง

การกำหนด docs/adr/ เป็นตำแหน่งเริ่มต้นสำหรับการตัดสินใจใหม่ทำได้ แต่ควรระบุว่าเป็นข้อตกลงด้านการตั้งชื่อและจัดเก็บของโปรเจกต์ ไม่จำเป็นต้องอ้างว่าเป็นมาตรฐานเดียวที่ทุกโปรเจกต์ต้องใช้

คงแนวปฏิบัติเดิมไว้ดังนี้:

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

การย้ายยังต้องอัปเดตการอ้างอิงจริง เส้นทางการทำงาน และข้อจำกัดสิทธิ์ที่เกี่ยวข้อง ไม่ใช่แค่ย้ายไฟล์อย่างเดียว

4. แผนงานเก็บแบบแบนได้ แต่ต้องแยก “พัก” ออกจาก “เสร็จ”

รูปแบบ plans/ ที่วางไฟล์ไว้ในโฟลเดอร์เดียวกันใช้ได้ ไม่จำเป็นต้องสร้างโฟลเดอร์ย่อยเพื่อรองรับแผนเก่าจำนวนน้อย อาจใช้ชื่อไฟล์ตัวอย่างต่อไปนี้:

การใช้งาน	ชื่อไฟล์ตัวอย่าง	ความหมาย
แผนที่กำลังทำ	pending_implementation_plan.md	จุดเริ่มต้นหลักสำหรับแผนที่กำลังดำเนินการ
บันทึกแผนหลังเสร็จ	plan-20261022-example-id.md	งานเสร็จและได้รับอนุญาตให้จัดเก็บแล้ว
แผนที่พักไว้แต่ยังไม่เสร็จ	plan-20261022-example-id-frozen.md	เก็บงานค้างไว้ แต่ไม่ถือเป็นแผนที่กำลังทำโดยปริยาย

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

สิ่งสำคัญคือต้องแยกสถานะให้ชัด:

• จัดเก็บว่าเสร็จแล้ว: เกณฑ์รับงานที่จำเป็นผ่านครบ และได้รับอนุญาตให้จัดเก็บ
• พักไว้โดยยังไม่เสร็จ: นำออกจากจุดเริ่มต้นของงานที่กำลังทำ แต่ห้ามระบุว่าเสร็จ และห้ามเปลี่ยนข้อเสนอที่ยังไม่ผ่านการตรวจให้กลายเป็นข้อเท็จจริง
• ยกเลิกอย่างชัดเจน: ระบุว่าไม่ดำเนินการต่อและบอกผลกระทบ ไม่ใช้คำว่า “พักชั่วคราว” แทนการยกเลิก หากต้องการสถานะยกเลิกอย่างเป็นทางการ ควรแก้ข้อตกลงแยกต่างหาก

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

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

5. เชื่อมโยงโค้ดกับการทดสอบแบบหลายต่อหลาย

ไม่ควรกำหนดว่าหนึ่งไฟล์โค้ดต้องมีไฟล์ทดสอบคู่กันหนึ่งไฟล์พอดี เพราะการทดสอบหนึ่งชุดอาจครอบคลุมหลายคอมโพเนนต์ และคอมโพเนนต์เดียวอาจต้องมีทั้ง unit test, property test และ integration regression

แนวทางเริ่มต้นที่แนะนำ:

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

ไฟล์แผนผังควรเก็บเท่าที่จำเป็น เช่น รหัสโมดูลหรือสัญญา ขอบเขตซอร์ส ขอบเขตการทดสอบ และคำสั่งตรวจสอบ ไม่ต้องคัดลอกโครงสร้างโฟลเดอร์ทั้งหมดหรือบันทึกสถานะว่าการทดสอบผ่านไว้ซ้ำอีกชุด

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

6. รวมร่างชั่วคราวไว้ได้ แต่อย่าใช้ตำแหน่งไฟล์ตัดสินความน่าเชื่อถือ

เห็นด้วยกับการรวมร่างชั่วคราว สคริปต์ใช้ครั้งเดียว และรายงานสำรวจไว้ที่ .scratch/ แต่ควรปรับแนวคิดที่ว่า “ข้อมูลในนี้ไม่ใช่ข้อมูลชั้นต้น” และ “ลบทั้งหมดได้เสมอ” ให้เป็นกฎที่มีเงื่อนไข

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

สำหรับรายงานเก่าหรือแผนภาพสถาปัตยกรรมใน docs/ ควรแยกเป็น “เอกสารที่ใช้อยู่”, “ข้อมูลประวัติศาสตร์ที่ตั้งใจเก็บ” และ “ข้อมูลที่ยังต้องตรวจสอบ” แทนการมองว่าทุกอย่างเก่าแล้วเป็นขยะ:

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

การเก็บไฟล์ไว้ไม่เท่ากับต้องโหลดมาอ่านทุกครั้ง ควรรักษาประวัติที่จำเป็นและลดข้อมูลรบกวนด้วยการอ่านเฉพาะส่วนที่เกี่ยวข้องกับงาน พร้อมระบุสถานะความเป็นปัจจุบัน แทนการลบหลักฐานทิ้ง

สรุป

แนวทางนี้นำไปใช้ได้ หากยึดขอบเขตหลัก 4 ข้อ: รวมการทดสอบเป็นค่าเริ่มต้นแต่เผื่อข้อยกเว้นตามภาษา, ใช้สเปกบันทึกข้อตกลงปัจจุบันแทนการสรุป ADR ทั้งหมด, แยกแผนที่พักไว้ออกจากงานที่เสร็จ และอย่าลบหลักฐานจำเป็นเพียงเพราะเก็บอยู่ในพื้นที่ชั่วคราว

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

รอบนี้เป็นการวิเคราะห์ในเซสชันเท่านั้น ยังไม่มีการแก้ไข ย้าย พัก หรือลบไฟล์ใด ๆ