AGENTS.md แสดงประสิทธิภาพเหนือกว่า skills ในการประเมินเอเจนต์

• ในการประเมินที่มุ่งเป้าไปยัง Next.js 16 API พบว่า ดัชนีเอกสาร AGENTS.md ที่อยู่ในรูทของโปรเจ็กต์ทำคะแนนความแม่นยำได้สูงกว่าแนวทางแบบ skills
• skills เป็นแพ็กเกจ องค์ความรู้เฉพาะโดเมน ในรูปแบบที่เอเจนต์จะเรียกใช้เมื่อจำเป็น แต่เนื่องจากการเรียกใช้ไม่เสถียร จึงมี อัตราผ่านเพียง 53% ในการตั้งค่าพื้นฐาน
• ขณะที่ ดัชนี AGENTS.md ที่บีบอัดเหลือ 8KB ทำ อัตราผ่าน 100% ได้ในทุกการทดสอบ (Build, Lint, Test)
• วิธีนี้ให้ผลลัพธ์ที่เสถียรกว่าการเรียกใช้เชิงรุก เพราะ ตัดจุดตัดสินใจออก, พร้อมใช้งานเสมอ, และแก้ปัญหาเรื่องลำดับ
• ผู้ดูแลเฟรมเวิร์กสามารถ ใส่ดัชนีเอกสารที่ตรงกับเวอร์ชันไว้ใน AGENTS.md เพื่อเพิ่มความแม่นยำของการสร้างโค้ดได้

---

ที่มาของปัญหา

• เอเจนต์เขียนโค้ดด้วย AI มีข้อจำกัดตรงที่ ข้อมูลฝึกมักอิงกับ API เวอร์ชันเก่า จึงจัดการกับเฟรมเวิร์กรุ่นใหม่ได้ไม่แม่นยำ
  • เช่น 'use cache', connection(), forbidden() ของ Next.js 16 ไม่มีอยู่ในข้อมูลฝึกเดิมของโมเดล
• ในทางกลับกัน สำหรับโปรเจ็กต์เวอร์ชันเก่า โมเดลก็อาจ เสนอ API รุ่นใหม่ที่ไม่มีอยู่จริง ได้เช่นกัน
• เพื่อแก้ปัญหานี้ จึงมีการทดลองแนวทาง เข้าถึงเอกสารที่ตรงกับเวอร์ชัน

สองแนวทาง

• Skills: แพ็กเกจ มาตรฐานเปิด ที่รวมพรอมป์ต์ เครื่องมือ และเอกสารไว้ด้วยกัน โดยเอเจนต์จะเรียกใช้เมื่อจำเป็น
• AGENTS.md : ไฟล์คอนเท็กซ์แบบต่อเนื่องที่อยู่ในรูทของโปรเจ็กต์ และอ้างอิงได้เสมอในทุกเทิร์นของบทสนทนา
• มีการประเมินเปรียบเทียบทั้งสองวิธีโดยอิงจากเอกสาร Next.js ชุดเดียวกัน

ข้อจำกัดของแนวทาง Skills

• ผลการประเมินพบว่า 56% ของการทดสอบไม่มีการเรียกใช้ skill และอัตราผ่านพื้นฐานอยู่ที่ 53% โดยแทบไม่ดีขึ้น
• ในบางหัวข้อกลับทำคะแนน ต่ำกว่าค่าพื้นฐานด้วยซ้ำ (เช่น ทดสอบได้ 58% เทียบกับ 63%)
• สิ่งนี้ถูกชี้ว่าเป็นข้อจำกัดที่โมเดลปัจจุบันยัง ใช้งานเครื่องมือได้ไม่เสถียรพอ

การทดลองเพิ่มคำสั่งแบบชัดเจน

• เมื่อลองเพิ่ม คำสั่งแบบชัดเจน ใน AGENTS.md ว่า “ให้เรียกใช้ skill ก่อนเขียนโค้ด” พบว่า อัตราผ่านเพิ่มเป็น 79%
• แต่ ความต่างเพียงเล็กน้อยของถ้อยคำในคำสั่ง กลับส่งผลต่อผลลัพธ์อย่างมาก
  • “เรียกใช้ skill ก่อน” → โมเดลยึดติดกับรูปแบบในเอกสารและพลาดบริบทของโปรเจ็กต์
  • “สำรวจโปรเจ็กต์ก่อนแล้วค่อยเรียก skill” → ให้ผลลัพธ์ดีกว่า
• ด้วย ความเปราะบางด้านภาษา แบบนี้ จึงทำให้ความน่าเชื่อถือในการใช้งานจริงต่ำ

การสร้างการประเมินที่เชื่อถือได้

• การทดสอบระยะแรกมีความน่าเชื่อถือต่ำ เพราะมีปัญหาเรื่องพรอมป์ต์ที่กำกวมและการตรวจสอบซ้ำซ้อน
• จึงมีการปรับปรุงโดยเสริม การตรวจสอบตามพฤติกรรม และเน้นการทดสอบ API ของ Next.js 16 ที่ไม่ได้อยู่ในข้อมูลฝึก
• API หลักที่ใช้ทดสอบ ได้แก่ connection(), 'use cache', cacheLife(), forbidden(), proxy.ts, cookies(), headers(), after(), refresh() เป็นต้น

การทดลองแนวทาง AGENTS.md

• ตัดกระบวนการให้เอเจนต์ต้องเลือกเองออก แล้ว ฝังดัชนีเอกสารลงใน AGENTS.md โดยตรง
• ดัชนีนี้ไม่ได้เก็บเอกสารทั้งหมด แต่เป็น รายการพาธเอกสารแยกตามเวอร์ชัน
• มีคำสั่งเพิ่มเติมว่า
  IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any Next.js tasks.
  • เพื่อชี้นำให้โมเดล ให้ความสำคัญกับการให้เหตุผลจากเอกสารมากกว่าการอิงข้อมูลที่ฝึกมาก่อน

ผลการประเมิน

• เมื่อฝังดัชนีไว้ใน AGENTS.md ได้อัตราผ่าน 100%
  • ทั้ง Build, Lint และ Test ให้ผลสมบูรณ์ทั้งหมด
• สถิติเปรียบเทียบ:
  • Baseline 53%, Skill แบบพื้นฐาน 53%, Skill+คำสั่ง 79%, AGENTS.md 100%
• เหตุผลที่ แนวทางคอนเท็กซ์แบบพาสซีฟเหนือกว่าการเรียกใช้เชิงรุก
  1. ไม่มีจุดตัดสินใจ — ข้อมูลมีอยู่เสมอ
  2. พร้อมใช้งานอย่างสม่ำเสมอ — ถูกรวมอยู่ใน system prompt ทุกเทิร์น
  3. ตัดปัญหาเรื่องลำดับ — ไม่ต้องพึ่งลำดับในการสำรวจเอกสาร

การแก้ปัญหาความจุของคอนเท็กซ์

• ดัชนีเริ่มต้นมีขนาด 40KB แต่ ย่อเหลือ 8KB ด้วยการบีบอัด (ลดลง 80%)
• ใช้โครงสร้างคั่นด้วยไปป์ (|) เพื่อ เก็บพาธเอกสารและชื่อไฟล์ด้วยพื้นที่น้อยที่สุด
• เอเจนต์จะอ่านเฉพาะไฟล์ที่จำเป็นจากไดเรกทอรี .next-docs/ เพื่อใช้ ข้อมูลเวอร์ชันที่แม่นยำ

วิธีนำไปใช้

• ตั้งค่าได้ด้วยคำสั่งบรรทัดเดียว

  npx @next/codemod@canary agents-md
  

• คำสั่งนี้จะ
  1. ตรวจจับเวอร์ชันของ Next.js
  2. ดาวน์โหลดเอกสารของเวอร์ชันนั้นไปไว้ใน .next-docs/
  3. แทรกดัชนีที่บีบอัดแล้วลงใน AGENTS.md
• ใช้งานได้เหมือนกันใน เอเจนต์ที่รู้จัก AGENTS.md เช่น Cursor

ข้อสื่อถึงนักพัฒนาเฟรมเวิร์ก

• แม้ว่า Skills ยังมีประโยชน์ แต่หากต้องการเพิ่มความแม่นยำของการสร้างโค้ดโดยทั่วไป แนวทาง AGENTS.md มีประสิทธิภาพกว่า
• Skills เหมาะกับเวิร์กโฟลว์ที่เน้นงานเฉพาะ เช่น การอัปเกรดเวอร์ชัน, การย้ายไป App Router
• ข้อแนะนำคือ
  • อย่ารอให้ skills ดีขึ้น แต่ เริ่มใช้ AGENTS.md ได้ทันที
  • ใส่เฉพาะดัชนีเอกสาร เพื่อลดคอนเท็กซ์ให้เล็กที่สุด
  • ตรวจสอบด้วย การประเมินที่เน้น API ซึ่งไม่มีอยู่ในข้อมูลฝึก
  • ออกแบบเอกสารให้มี โครงสร้างการค้นหาแบบละเอียด
• เป้าหมายคือ เปลี่ยนจากการให้เหตุผลที่ยึดข้อมูลฝึกล่วงหน้า ไปสู่การให้เหตุผลแบบอิงการค้นคืนข้อมูล และ AGENTS.md คือวิธีที่ทำสิ่งนี้ได้อย่างเสถียรที่สุด

[channprj]

> เอเจนต์เขียนโค้ด AI มีข้อจำกัดตรงที่ข้อมูลฝึกสอนอิงกับ API เวอร์ชันเก่า จึงจัดการเฟรมเวิร์กล่าสุดได้ไม่แม่นยำนัก

พอใช้ Context7 แล้ว ปัญหาข้างต้นก็พอแก้ได้ในระดับหนึ่งครับ

https://context7.com

[slowandsnow]

เป็นเพราะ context7 ไม่มีประสิทธิภาพ จึงใช้สองวิธีข้างต้น...

[channprj]

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

อีกอย่าง ทั้งในบทความของ GeekNews และต้นฉบับของ Vercel ก็ไม่ได้มีการพูดถึง context7 เลย ผมเลยขอฝากความเห็นไว้ เพราะรู้สึกว่าคุณตีความเนื้อหาไปล่วงหน้าประมาณครึ่งก้าว

(ขอเสริมไว้เป็นข้อมูลว่า เรื่องที่ Skills หรือ AGENTS.md ที่เขียนมาดีสามารถช่วยประหยัดโทเคนได้ เป็นสิ่งที่ทราบกันดีอยู่แล้ว และผมเองก็ทราบเรื่องนี้ดีเช่นกัน)

[GN⁺]

ความเห็นบน Hacker News

• โมเดลไม่ใช่ AGI แค่เป็น เครื่องสร้างข้อความ ที่ถูกฝึกให้ก่อให้เกิดผลอย่างการแก้ไขไฟล์หรือเรียกใช้เครื่องมือได้
  โมเดลไม่ได้ "เข้าใจ" สกิลของผู้ใช้แล้วนำไปใช้ แต่สร้างข้อความแบบนั้นได้เพราะ reinforcement learning (RL) จากตัวอย่างที่มนุษย์สร้างและบันทึกการใช้งาน
  เหตุผลที่มันไม่ใช้สกิลเสมอไปก็เพราะยังไม่ได้เรียนรู้เคสแบบนั้นมากพอ ถ้าบังคับด้วย RL มากเกินไป โมเดลอาจยิ่งโง่ลงได้
  ตอนนี้เรากำลังสะสมบันทึกการใช้สกิล เพื่อให้โมเดลในอนาคตเรียนรู้ได้ดีขึ้นว่าควรใช้สกิลเมื่อไร
  AGENTS.md ก็เป็นแค่ context อย่างหนึ่ง โมเดลถูกฝึกให้ทำตาม context มาตั้งแต่แรกแล้ว

  • ความต่างระหว่าง AGENTS.md กับสกิล สุดท้ายคือปัญหาว่า มันถูกแทรกเข้าไปใน context อย่างไร
    frontmatter ของสกิลก็ถูกรวมอยู่ใน context เหมือนกัน ดังนั้นถ้า AGENTS.md ทำงานดีกว่า ก็เป็นเพราะวิธีดึงและใส่ข้อมูลของสกิลต่างกัน
    เอเจนต์บางตัวอาจใช้โมเดลเล็กกว่า (เช่น Haiku) เพื่อตัดสินใจว่าจะส่งข้อมูลสกิลอะไรไปให้โมเดลใหญ่กว่า (เช่น Sonnet, Opus)
    สุดท้ายประเด็นหลักก็คือข้อมูลอะไรได้เข้าไปอยู่ใน “พรอมป์ต์ดิบ”
  • มันไม่ใช่ AGI จริง ๆ โดยพื้นฐานแล้วก็แค่ autocomplete ที่ถูกเสริมความสามารถ
    มีประโยชน์ แต่ไม่สมบูรณ์แบบ และดูเหมือนเทคโนโลยี GPT เองจะเข้าสู่ช่วง ประสิทธิภาพเริ่มนิ่ง แล้ว
    ส่วนที่จะพัฒนาต่อจากนี้คือระบบเสริมอย่างสกิล แต่ฟีเจอร์สกิลที่มีอยู่ตอนนี้ยังสู้การเขียน AGENTS.md ตรง ๆ ไม่ได้
  • ฉันก็เคยทดลองคล้ายกัน โดยให้ system prompt โหลดสกิลที่เกี่ยวข้องไว้ล่วงหน้า และให้ user prompt เรียกใช้เมื่อจำเป็น
  • มีคนถามว่า RL คืออะไร
  • มีคอมเมนต์มุกที่เอาคำพูดว่า “โมเดลไม่ใช่ AGI” ไปเทียบกับ ข้อถกเถียงเรื่องชื่อ GNU/Linux

• ในการประเมินพบว่า 56% ของกรณี สกิลไม่ถูกเรียกใช้เลยแม้แต่ครั้งเดียว หมายความว่ามีเอกสารอยู่แต่ไม่ถูกใช้ เลยมีมุกว่า “อย่างน้อยก็ผ่าน Turing test นะ..."

  • มีคนตอบขำ ๆ ว่า “AI ก็ RTFM เหมือนกัน”
  • ฉันก็ขำ แต่ถ้าพูดจริงจัง มนุษย์เองก็มักเชื่อถือไม่ได้บ่อยเหมือนกัน
    ความต่างคือ AI ยอมรับคำสั่งให้แก้โดยไม่มีอีโก้
    ยังไม่ถึงระดับ senior developer แต่ทำตามคำสั่งได้ดีกว่า junior

• ข้อค้นพบสำคัญคือ compression ของ document pointer ได้ผลดี
  ถึงมนุษย์จะอ่านยาก แต่สำหรับ LLM มันเป็นโครงสร้างอ้างอิงที่ตรงและมีประสิทธิภาพ
  ต่อไป แทนที่จะใช้ heuristic อย่าง agents.md/claude.md/skills.md ก็มีโอกาสสูงที่จะมีการทำมาตรฐานเป็น compressed index format ที่โหลดตลอดเวลา
  ชุดทดสอบ API ก็อาจถูกนำกลับมาใช้ตรวจสอบประสิทธิภาพโค้ดของ LLM ได้ด้วย
  ยิ่งการใช้งาน LLM แพร่หลายมากขึ้น ไลบรารีและ API ก็ต้องพัฒนาให้สอดคล้องกัน

  • บทเรียนอีกข้อคือ “สำรวจโปรเจกต์ก่อน แล้วค่อยเรียกสกิล” ดีกว่า “ต้องใช้สกิลเสมอ”
    ใน Antigravity (= อิงจาก GEMINI.md) มีการตั้งให้ทำตามกฎของ AGENTS.md แต่ถูกเมิน
    แต่พรอมป์ต์ที่ว่า “ตรวจดูว่ามี AGENTS.md ในโปรเจกต์หรือไม่” กลับใช้ได้ผลทุกครั้ง
    เป็นปรากฏการณ์ที่ชวนทึ่ง คล้ายสมัยที่ “let’s think step by step” ช่วยชักนำ chain of thought
  • มีคนแย้งว่าเรียกว่า “compression” แต่จริง ๆ ก็แทบจะเป็นแค่ minify มากกว่าไหม
  • มีความเห็นว่าถ้าใช้ขึ้นบรรทัดใหม่แทนเครื่องหมาย pipe จะอ่านง่ายกว่า

• ถ้าใส่ AGENTS.md เข้าไปใน system prompt โดยตรง มันก็จะอยู่ใน context ตลอด
  แต่การใส่ทุกสกิลทุกครั้งก็สิ้นเปลือง จึงต้องมีแนวทางแบบ advanced tool use ของ Anthropic ที่ค่อยเรียกเมื่อจำเป็น
  ท้ายที่สุดมันคือปัญหาเรื่อง สมดุลระหว่าง context กับต้นทุน ถ้ามีงบพอ การบีบอัดแล้วใส่ไว้ใน AGENTS.md ก็มีประสิทธิภาพดี

  • สกิลเองก็ถูกประกาศอยู่ใน context เหมือนกัน ดูเหมือนว่าการบีบอัดแล้วใส่ลง AGENTS.md ตรง ๆ จะได้ผลดีกว่า
  • ดูเหมือน Vercel จะสับสนระหว่างสกิลกับการตั้งค่า context ทั้งสองอย่างมีจุดประสงค์ต่างกันโดยสิ้นเชิง จึง ควรใช้ทั้งคู่ร่วมกัน
  • นี่ก็เป็นเหตุผลที่ แนวทาง RLM ทำงานได้ดี มันใส่เฉพาะข้อมูลที่จำเป็นลงใน context แล้วปล่อยที่เหลือไว้ในสภาพแวดล้อม
    เอเจนต์แบบ จัดการ context ของตัวเอง น่าจะพัฒนาไปมากในปีนี้
  • สุดท้ายก็ต้องใช้ทั้งสองแบบ บางอย่างต้องยัดเข้าคอนเท็กซ์แบบบังคับ (index/sparknotes) และบางอย่างควรเติมแบบไดนามิกผ่านการสำรวจหรือค้นหา
  • ผู้ใช้เดี่ยวอาจแค่แก้ system prompt ก็พอ แต่ในระดับทีมยังจำเป็นต้องใช้สกิลเพื่อคุมมาตรฐานอย่างรูปแบบโค้ด
    Claude ทำตามสกิลได้ไม่ค่อยดี

• ฉันก็กำลังทำงานในพื้นที่ใกล้เคียงกัน พยายามประเมินว่า โครงสร้าง project scaffolding มีผลต่อผลลัพธ์ของ Claude Code/Opencode อย่างไร
  แต่เพราะวิธีทดสอบของ Vercel ไม่ชัดเจน จึงเปรียบเทียบกันได้ยาก

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

  • ฉันเองก็แยกจัดการเป็นสองประเภท
    1. สิ่งที่อิงกฎและถูกบังคับแทรกใน system prompt
    2. สิ่งที่เอเจนต์ไปสำรวจหาเองเมื่อจำเป็น
       และเพื่อลดการเปลืองโทเค็น ไฟล์ใหญ่จะใส่ไว้ใน system prompt แค่ครั้งเดียว

• เวลาเห็นบล็อกเปรียบเทียบ prompt engineering ฉันมักสงสัยเสมอว่า รันครั้งเดียวหรือรันหลายครั้ง
  เพราะ LLM ให้ผลไม่คงที่แม้ใช้อินพุตเดียวกัน

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

• ยังมีวิธีที่อาจดีกว่า AGENTS.md
  คือสร้างโฟลเดอร์ .context แล้วใส่ symbolic link ไปยังเอกสารที่เกี่ยวกับโปรเจกต์ (README, เอกสาร dependency ฯลฯ) เพื่อให้โหลดเข้า context ตลอดเวลา
  วิธีนี้ทำให้ LLM มีข้อมูลที่ต้องใช้ครบตั้งแต่แรก จึงช่วย เพิ่มประสิทธิภาพและลดต้นทุน ได้

  • แต่เอกสาร dependency ไม่ได้สร้างความต่างมากนัก ตรงกันข้าม การใส่ ซอร์สโค้ดเอง ลงในโฟลเดอร์ _vendor มีประโยชน์กว่ามาก
    เพราะ LLM วิเคราะห์โค้ดโดยตรงเพื่อเข้าใจการทำงานได้
  • ก็มีความเห็นว่าการโหลดเอกสารทั้งหมดทุกครั้งไม่มีประสิทธิภาพ สู้ระบุตำแหน่งไว้ใน Claude.md หรือ Agents.md แล้วค่อยให้อ่านเมื่อจำเป็นจะดีกว่า
  • ไม่ควรทำให้ context พองโดยไม่จำเป็น แต่ควรใช้วิธี บีบอัดเฉพาะดัชนีเอกสาร จะมีประสิทธิภาพกว่า
  • การใส่ไฟล์ใหญ่ทุกครั้งเป็น การเปลืองโทเค็น ซึ่งบล็อก Claude Code ก็เคยเตือนไว้แบบเดียวกัน

• นี่คือประสบการณ์จากการสร้างเอเจนต์แบบคัสตอมของฉันเอง

  1. อ้างอิงแนวทาง extraction ของ Claude Code
  2. โหลด AGENTS.md อัตโนมัติไว้ใช้เป็น สารบัญและสรุปย่อ (sparknotes)
  3. จัดการไฟล์ Markdown ตามหัวข้อเป็นสกิล
  4. MCP กับสกิลมีแนวคิดคล้ายกัน ดังนั้นหัวใจคือการสร้างเครื่องมือที่ดี
  5. ทดลองต่อเนื่อง สนุกกับมัน และค่อย ๆ ปรับปรุง
     พอเปลี่ยนให้ read/write_file เข้าไปอยู่ใน state และแสดงใน system prompt มันทำงานดีขึ้นมาก
     ตอนนี้กำลังพยายามพิสูจน์เรื่องนี้ด้วย การประเมินเชิงปริมาณ (evals) ซึ่งจากความรู้สึกแล้วประสิทธิภาพดีมาก