อย่าใช้ `/init` สร้าง AGENTS.md อัตโนมัติ — มีแต่ทำให้ต้นทุนเพิ่มขึ้น 20%

ข้ออ้างสำคัญ

• หาก สร้างไฟล์คอนเท็กซ์ (AGENTS.md) สำหรับ AI coding agent แบบอัตโนมัติด้วยคำสั่ง /init ประสิทธิภาพของเอเจนต์จะกลับแย่ลง และต้นทุนเพิ่มขึ้น มากกว่า 20%
• ปัญหาหลักคือการให้ข้อมูลซ้ำกับสิ่งที่เอเจนต์ค้นพบได้ด้วยตัวเองอยู่แล้ว
• ใน AGENTS.md ควรใส่เฉพาะ ข้อมูลที่เอเจนต์ไม่มีทางรู้ได้จากการอ่านโค้ด เท่านั้น

ผลการวิจัย: AGENTS.md ช่วยหรือทำร้ายกันแน่

• Lulla et al. (ICSE JAWs 2026): การทดลองแบบ paired กับ GitHub PR 124 รายการ โดยเปลี่ยนแค่การมีหรือไม่มี AGENTS.md
  • เมื่อมี AGENTS.md เวลารันลดลง 28.64% และโทเคนเอาต์พุตลดลง 16.58%
  • ไฟล์ที่ใช้ในการวิจัยนี้เป็นไฟล์ที่นักพัฒนาดูแลจริง และมีความรู้เฉพาะของโปรเจ็กต์อยู่ภายใน
• งานวิจัยจาก ETH Zurich: ทดสอบเอเจนต์ 4 ตัวบน SWE-bench เป็นต้น โดย แยกไฟล์ที่ LLM สร้างอัตโนมัติออกจากไฟล์ที่นักพัฒนาเขียนเอง
  • คอนเท็กซ์ที่ LLM สร้างอัตโนมัติ: อัตราสำเร็จของงานลดลง 2~3% และต้นทุนเพิ่มขึ้น 20%+
    • ในสภาพแวดล้อมที่ลบเอกสารเดิมทั้งหมด เช่น README ออก ไฟล์ที่ LLM สร้างกลับช่วยเพิ่มประสิทธิภาพได้ 2.7%
  • ไฟล์ที่นักพัฒนาเขียนเอง: อัตราสำเร็จเพิ่มขึ้นราว 4% แต่ต้นทุนอาจเพิ่มได้สูงสุด 19%
• สรุป: ไม่ใช่ว่าเนื้อหาที่สร้างอัตโนมัติแย่ แต่ปัญหาอยู่ที่ความซ้ำซ้อน
  • เมื่อให้ข้อมูลเดียวกันซ้ำสองครั้ง จะเพิ่มแต่ noise และมีเพียง ความรู้ที่ค้นพบเองไม่ได้ ซึ่งนักพัฒนาเขียนไว้เท่านั้นที่ช่วยได้จริง

ทำไมการสร้างอัตโนมัติจึงเป็นโทษ

• AGENTS.md ที่สร้างอัตโนมัติส่วนใหญ่มี ข้อมูลที่เอเจนต์ค้นพบเองได้อยู่แล้ว
  • ภาพรวมของโค้ดเบส (100% ของเอาต์พุต Sonnet 4.5 และ 99% ของเอาต์พุต GPT-5.2 มีข้อมูลนี้)
  • โครงสร้างไดเรกทอรี, tech stack, คำอธิบายโมดูล
• การให้ข้อมูลที่รู้อยู่แล้วซ้ำอีกครั้งมีแต่ เปลืองโทเคน และไม่มีคุณค่า
• ผลของการยึดติด (anchoring effect): หากกล่าวถึงแพตเทิร์นแบบ legacy เอเจนต์จะยึดติดกับแพตเทิร์นนั้น แม้จะมีทางเลือกที่ดีกว่าก็ตาม
  • สอดคล้องกับงานวิจัย "Lost in the Middle" (Liu et al., 2024) — คอนเท็กซ์ที่ยาวเกินไปทำให้ความสนใจแตกกระจายและประสิทธิภาพลดลง

สิ่งที่ควรใส่ vs สิ่งที่ไม่ควรใส่ใน AGENTS.md

• ควรใส่ (ข้อมูลที่เอเจนต์ค้นพบเองไม่ได้)
  • การกำหนดเครื่องมือ: "ให้ใช้ uv สำหรับจัดการแพ็กเกจ"
  • กฎที่ไม่ชัดเจนโดยสัญชาตญาณ: "ต้องรันเทสต์ด้วย --no-cache เสมอ ไม่เช่นนั้น fixture จะเกิด false positive"
  • ข้อจำกัดของระบบ: "โมดูล auth ใช้ custom middleware อยู่ ห้ามรีแฟกเตอร์เป็น Express มาตรฐาน"
  • หากมีการระบุเครื่องมือไว้ในเอกสาร เอเจนต์จะใช้งานมัน 1.6~2.5 ครั้งต่อหนึ่งงาน แต่ถ้าไม่มีการระบุไว้จะลดลงเหลือ น้อยกว่า 0.05 ครั้ง
• ไม่ควรใส่ (สิ่งที่เอเจนต์ค้นพบเองได้)
  • โครงสร้างไดเรกทอรี, เลย์เอาต์ของ monorepo
  • ภาพรวมของ tech stack, แพตเทิร์นสถาปัตยกรรมมาตรฐาน

ข้อจำกัดเชิงโครงสร้างของไฟล์แบบสแตติก

• ต่อให้เขียน AGENTS.md ได้ดี ก็ยังมีจุดอ่อนพื้นฐานอยู่ — ไฟล์เป็นแบบสแตติก แต่งานเป็นแบบไดนามิก
• คำสั่งในไฟล์เดียวไม่สามารถแตกเงื่อนไขตามประเภทงานได้
  • แม้เป็นงานแก้เอกสาร ก็ยังอาจถูกสั่งให้ "รันเทสต์ทั้งหมดก่อน commit" ทำให้เสียทั้งโทเคนและเวลา
  • งานรีแฟกเตอร์ CSS อาจต้องโหลดคำเตือนเรื่อง DB migration และงานแก้ security ก็อาจพ่วง hint เรื่อง performance optimization มาด้วย
• ACE framework (ICLR 2026): แทนที่จะใช้ไฟล์สแตติก ใช้วิธี Agentic Context Engineering ที่ทำให้คอนเท็กซ์พัฒนาแบบไดนามิกผ่าน pipeline แบบ generator/reflector/curator ซึ่งให้ประสิทธิภาพสูงกว่าวิธีสแตติก 12.3%

โครงสร้างที่ดีกว่า ซึ่งยังไม่มีใครสร้าง

• หลายคนสรุปตรงกันอย่างอิสระเกี่ยวกับ AGENTS.md
  • โครงสร้างที่ถูกต้องไม่ใช่ไฟล์เดียว แต่เป็น ชั้น routing + focused context ที่โหลดเมื่อจำเป็น
• Layer 1 - protocol file: ไม่ใช่ภาพรวมโค้ดเบสหรือ style guide แต่เป็น เอกสารสำหรับ routing
  • ระบุ persona ที่ใช้ได้และเงื่อนไขการเรียกใช้, skill กับประเภทงานที่รับผิดชอบ, การเชื่อมต่อ MCP และวัตถุประสงค์ของมัน
  • ใส่เฉพาะข้อเท็จจริงขั้นต่ำของ repo ที่เอเจนต์ค้นพบเองไม่ได้ และไม่ใส่อย่างอื่นเกินจากนั้น
• Layer 2 - persona/skill files: โหลดแบบเลือกตามประเภทงาน
  • เอเจนต์ฝั่ง UX และเอเจนต์ฝั่ง backend จะโหลดคอนเท็กซ์คนละชุด และไม่โหลดคอนเท็กซ์ของอีกฝ่าย
• Layer 3 - maintenance sub-agent: เอเจนต์เฉพาะทางที่ดูแลให้ protocol file ถูกต้องเสมอ
  • เอกสารเสื่อมสภาพได้ — แม้งานวิจัยของ ETH Zurich จะทดสอบด้วยไฟล์ที่เพิ่งสร้างใหม่ ก็ยังพบว่าประสิทธิภาพลดลง
  • ถ้า AGENTS.md ถูกปล่อยทิ้งไว้ 6 เดือนแล้วระบุ dependency ที่ถูกเปลี่ยนไปแล้ว หรือโครงสร้างไดเรกทอรีที่ไม่ตรงปัจจุบัน ปัญหาจะยิ่งรุนแรงกว่าเดิมมาก
• ปัจจุบันยังไม่มี coding agent หลักตัวใดให้ lifecycle hook ที่ทำให้สถาปัตยกรรมนี้ทำได้ง่าย — พอจะจำลองได้ด้วย sub-agent และ scoped context แต่ยังเป็นช่องว่างของเครื่องมือที่ไม่มีใครเติมเต็ม

การปรับแต่งอัตโนมัติ

• Arize AI ใช้ลูปการปรับแต่งอัตโนมัติแทนการเขียนคำสั่งใน CLAUDE.md ด้วยมือ
  • รันเอเจนต์กับงานสำหรับฝึก → ประเมินผลลัพธ์ → ให้ LLM สร้างฟีดแบ็กต่อสาเหตุความล้มเหลว → ปรับปรุงคำสั่งด้วย meta-prompting → วนซ้ำ
  • ในการทดสอบแบบ cross-repo ได้ +5.19% และแบบ in-repo ได้ +10.87% ในด้านความแม่นยำ
• ข้อเท็จจริงชวนอึดอัดที่ optimizer พบคือ: สิ่งที่ช่วยให้คนเข้าใจโค้ดเบส ไม่จำเป็นต้องเป็นสิ่งที่ LLM ต้องใช้ในการนำทางเสมอไป
  • ข้อมูลอย่าง "บริการนี้ใช้ repository pattern" ดูมีประโยชน์สำหรับนักพัฒนาอย่างชัดเจน แต่สำหรับโมเดลอาจเป็น noise
  • ในทางกลับกัน สิ่งที่โมเดลต้องการจริง ๆ (เช่น การแยกแยะ import path เฉพาะ, กฎการตั้งชื่อไฟล์ที่ไม่เป็นธรรมชาติ) นักพัฒนามักซึมซับไว้เองจนไม่คิดจะเขียนมันลงไปด้วยซ้ำ
• การเขียน AGENTS.md ด้วยมือมีสมมติฐานว่า นักพัฒนารู้ว่าเอเจนต์ต้องการอะไร
  • แต่หลักฐานเชิงประจักษ์บอกเป็นนัยว่าอาจไม่ใช่
  • ตัว optimizer ช่วยค้นหาความต่างระหว่าง "สิ่งที่คิดว่าสำคัญ" กับ "สิ่งที่เปลี่ยนผลลัพธ์จริง"
• อย่างไรก็ดี นี่ไม่ได้หมายความว่าควรเลิกเขียนไปเลย — 5% มีความหมาย แต่ยังไม่ถึงขั้นพลิกเกม ความหมายคือ อย่ายึดสัญชาตญาณแน่นเกินไป และต้องทดสอบจริง

กรอบความคิดที่ถูกต้องในการมอง AGENTS.md

• มอง AGENTS.md เป็น บันทึกของกระบวนการที่ยังแก้ไม่เสร็จ
• ทุกบรรทัดที่เพิ่มเข้าไปคือสัญญาณว่ามีบางอย่างในโค้ดเบสที่คลุมเครือจนทำให้ AI agent สับสนได้ และมีโอกาสสูงที่ผู้ร่วมพัฒนาใหม่ที่เป็นมนุษย์ก็จะงงเช่นกัน
• การตอบสนองที่ถูกต้องไม่ใช่การขยายไฟล์คอนเท็กซ์ แต่คือ แก้ที่ต้นเหตุ
  • เอเจนต์เอา utility ไปไว้ในไดเรกทอรีผิด → แปลว่าโครงสร้างไดเรกทอรีเองชวนสับสน จึงควรจัดระเบียบใหม่
  • เอเจนต์ยังใช้ dependency ที่เลิกใช้ไปแล้ว → แปลว่าโครงสร้าง import เปิดช่องให้หยิบของผิดได้ง่ายเกินไป จึงควรแก้
  • เอเจนต์ลืมเช็ก type → อย่าพึ่งคำสั่ง แต่ให้ build pipeline จับโดยอัตโนมัติ
• AGENTS.md คือ เครื่องมือวินิจฉัย ไม่ใช่การตั้งค่าถาวร — เพิ่มบรรทัดเข้าไป, สืบหาว่าทำไมเอเจนต์ถึงทำพลาดแบบเดิมซ้ำ ๆ, แก้ต้นเหตุ แล้วลบบรรทัดนั้นทิ้ง
• เทคนิคที่น่าลอง: เริ่มจาก AGENTS.md ที่เกือบว่าง แล้วใส่เพียงคำสั่งว่า "ถ้าพบสิ่งที่น่าแปลกใจหรือชวนสับสนในโปรเจ็กต์นี้ ให้ทิ้งคอมเมนต์ไว้" สิ่งที่เอเจนต์เสนอให้เพิ่มส่วนใหญ่มักไม่ใช่ของที่ควรเก็บถาวร แต่เป็น ป้ายชี้จุดที่โค้ดเบสยังไม่ชัดเจน

คำแนะนำเชิงปฏิบัติ

• หยุดรัน /init — หาก repo ไม่ได้อยู่ในสภาพไร้เอกสารโดยสิ้นเชิง ผลลัพธ์ที่สร้างอัตโนมัติมักซ้ำกับเอกสารที่มีอยู่แล้ว
• ก่อนเพิ่มหนึ่งบรรทัดลงใน AGENTS.md ให้ถามตัวเองว่า "ถ้าเอเจนต์อ่านโค้ด มันจะรู้ได้ไหม?" ถ้ารู้ได้ ก็ไม่ควรเขียน
• เมื่อเอเจนต์ล้มเหลวซ้ำ ๆ ให้ แก้โค้ดเบสก่อน แทนที่จะรีบขยายไฟล์คอนเท็กซ์
  • ปรับปรุงโครงสร้างโค้ด, เพิ่มกฎ linter, ขยาย test coverage — แล้วค่อยแตะ AGENTS.md เฉพาะเมื่อยังไม่พอจริง ๆ
• หากคุณรันเอเจนต์ในวงกว้างบน CI/CD หรือ pipeline รีวิวอัตโนมัติ ควรตระหนักว่าต้นทุนส่วนเกิน 15~20% จะ ทบต้นสะสม ตลอดการรันหลายพันครั้ง
• สัญชาตญาณที่อยาก onboarding เอเจนต์เหมือนพนักงานใหม่ (พาชมออฟฟิศ, อธิบายผังองค์กร, อธิบายสถาปัตยกรรม) เป็นเรื่องธรรมชาติ แต่ coding agent ไม่ใช่พนักงานใหม่ — มันสามารถ grep ทั้งโค้ดเบสได้ก่อนที่คุณจะพิมพ์ prompt จบเสียอีก สิ่งที่เอเจนต์ต้องการ ไม่ใช่แผนที่ แต่เป็นตำแหน่งของกับระเบิด

[lloydkwon]

สุดท้ายก็มีคนบอกว่านี่คือการต่อสู้เรื่อง context...
ผมว่าคงต้องแยกทำ md สำหรับ agent กับ md สำหรับผู้ใช้ต่างหากหรือเปล่า

[lukeio]

เห็นด้วยอย่างยิ่งครับ โครงสร้างที่อ่านง่ายสำหรับมนุษย์ (README) กับโครงสร้างที่ LLM แยกวิเคราะห์ได้ง่าย (AGENTS.md) นั้นต่างกันโดยสิ้นเชิง ถ้าสร้างคอนเท็กซ์ทั้งหมดอัตโนมัติแล้วโยนเข้าไปแบบไม่เลือก ก็มีแต่จะเปลืองค่าใช้จ่ายโทเค็น API และผมก็มักเจอด้วยว่ากลับยิ่งทำให้อาการหลอนของโมเดลรุนแรงขึ้น สุดท้ายแล้ว ถึงจะน่ารำคาญอยู่บ้าง แต่ดูเหมือนว่าการให้มนุษย์ย่อและขัดเกลาคำสั่งสำหรับเอเจนต์ด้วยตัวเองจะมีประสิทธิภาพที่สุดครับ

[sonnet]

แต่แรกเริ่มมี README อยู่แล้ว และ AGENT.md ก็คือ README ที่ทำขึ้นมาเพื่อเอเจนต์นั่นเอง

[jaehar16]

แต่สิ่งนั้นมันมีอยู่ใน README แล้วไม่ใช่เหรอ?

[armila]

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

[jjw9512151]

สุดท้ายแล้วดูเหมือนว่าสิ่งสำคัญคือการรักษา context ให้บริสุทธิ์และใช้โทเคนน้อย ๆ .. ในมุมนี้ก็เลยรู้สึกว่าอักษรจีนค่อนข้างมีประโยชน์เหมือนกันนะ 555

[aliveornot]

สำหรับโมเดลแล้ว ภาษาอังกฤษแทบจะเป็นระดับที่ 1 คำเท่ากับ 1 อักษร (โทเค็น) อยู่แล้ว ดังนั้นในทางปฏิบัติก็แทบไม่ต่างจากอักษรจีนไม่ใช่หรือ

[eususu]

โอ้ ไม่เคยคิดถึงแนวทางแบบนี้มาก่อนเลย แต่ดูมีเหตุผลเหมือนกันครับ!

[t7vonn]

โอ ..