รู้ตัวกันไหมครับว่า ทุกครั้งที่ coding agent ของคุณทำงาน มันอ่านไฟล์ AGENTS.md ใหม่ทั้งไฟล์ ทุกบรรทัด ในทุก request ข้อตกลง TypeScript โน้ตสถาปัตยกรรม ฟอร์แมต commit ทุกอย่าง ทุกครั้ง ต่อให้งานจริงคือ "เปลี่ยนชื่อ CSS variable ตัวนี้ที"

ผมเพิ่งมารู้ตัวตอนที่เปิดดูไฟล์ของตัวเอง ความยาว 300 กว่าบรรทัด บางบรรทัดผมยังจำไม่ได้ด้วยซ้ำว่าเคยเขียนเมื่อไหร่ Frontier model ทำตามคำสั่งได้ราว 150 ถึง 200 ข้อแบบพึ่งพาได้ AGENTS.md ที่บวม ๆ ผลาญงบตรงนั้นไปทุก request ตั้งแต่ก่อน agent จะได้ทำงานจริงด้วยซ้ำ ทางแก้จึงไม่ใช่คำสั่งที่ดีขึ้น แต่คือคำสั่งที่น้อยลง

AGENTS.md คืออะไร?

AGENTS.md เป็นไฟล์ Markdown ที่คุณ check in ไว้ใน repository เพื่อปรับแต่งพฤติกรรมของ AI coding agent ใน repo นั้น agent จะอ่านมันตอนเริ่ม session ใต้ system prompt พอดี มันจึงทำหน้าที่เป็นชั้น configuration คั่นระหว่างคำสั่งพื้นฐานของ agent กับโค้ดเบสจริงของคุณ

คำแนะนำสองแบบที่ชอบไหลเข้าไปอยู่ในไฟล์นี้คือ

• ของส่วนตัว วิธีที่คุณชอบให้เขียน commit แพทเทิร์นที่คุณถนัด นิสัยการตั้งชื่อ
• ของโปรเจกต์ โปรเจกต์นี้ทำอะไร ใช้ package manager ตัวไหน architecture decision ไหนที่ตายตัวแล้ว

มันเป็น open standard และมี tool รองรับหลายตัว แต่ก็ไม่ครบทุกตัว Claude Code ตามประวัติแล้วมองหา CLAUDE.md แทน ถ้าคุณใช้ทั้งคู่ ซิมลิงก์ช่วยให้ทั้งสองฝั่งอ่านไฟล์เดียวกัน

# macOS/Linux ใช้คำสั่งนี้เพื่อให้ Claude Code กับ tool สาย AGENTS.md อ่านไฟล์เดียวกัน
ln -s AGENTS.md CLAUDE.md

ทำไม AGENTS.md ตัวใหญ่ถึงทำให้ agent แย่ลง

ไฟล์มันโตขึ้นผ่าน feedback loop ที่ตอนนั้นรู้สึก productive มาก เหมือนวิ่งบนลู่วิ่งที่ไม่มีวันถึงไหน

1. agent ทำอะไรที่คุณไม่ชอบ
2. คุณเพิ่มกฎไปห้าม
3. ทำซ้ำสักสองสามร้อยครั้งในเวลาไม่กี่เดือน
4. คุณได้ ball of mud มาหนึ่งก้อน

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

ความเสื่อมแบบนี้มาจากกลไกสองตัว

ทุกบรรทัดมีราคาเป็น token ในทุก request

บทความของ Kyle Corbitt เรื่องการเขียน CLAUDE.md ที่ดีเสนอไอเดีย instruction budget เอาไว้

Frontier LLM สาย thinking ทำตามคำสั่งได้ราว 150 ถึง 200 ข้ออย่างสม่ำเสมอพอใช้ได้ โมเดลเล็กจดจ่อกับคำสั่งได้น้อยกว่าโมเดลใหญ่ และโมเดลสายไม่คิดก็จดจ่อได้น้อยกว่าโมเดลสายคิด

คำสั่งทุกข้อใน AGENTS.md ของคุณแย่งงบกันเอง มันถูกโหลดเข้ามาไม่ว่าจะเกี่ยวกับงานปัจจุบันหรือไม่ กฎเรื่อง API pagination ก็เลยนั่งกินสมาธิอยู่ตอนที่ agent กำลังไล่ debug CSS

ทุกวันนี้ token ถูกเหมือนน้ำประปา แต่สมาธิแพงเหมือนกาแฟ specialty

กฎเก่าอันตรายกว่ากฎที่ไม่มี

เอกสารมันเน่าได้ นักพัฒนาที่เป็นมนุษย์มีความกังขาติดตัว อ่านเอกสารแล้วเห็นว่าไม่ตรงกับโค้ดก็เมินเฉย แต่ agent อ่านเอกสารเดิมทุก request แล้วเชื่อสนิท

เนื้อหาที่เน่าเร็วที่สุดคือโครงสร้างไฟล์ และนี่คือพลาดที่ผมเห็นบ่อยที่สุด ถ้า AGENTS.md ของคุณเขียนว่า authentication logic อยู่ที่ src/auth/handlers.ts แล้วไฟล์นั้นถูกย้าย agent จะงมในที่ผิดอย่างมั่นใจ ซ้ำแล้วซ้ำเล่า แล้วรายงานกลับมาว่ามันหาแล้ว (น่าเชื่อถือซะด้วย)

ผมเจอของจริงมาแล้ว โปรเจกต์หนึ่งย้ายโฟลเดอร์ auth จาก src/auth ไปอยู่ใต้ packages/ แต่ลืมแก้ AGENTS.md บรรทัดเดียว agent งมอยู่ใน path ที่ไม่มีอยู่จริงอยู่ครึ่งชั่วโมง แล้วสรุปอย่างมั่นใจว่าควรสร้างไฟล์ใหม่ขึ้นมาเองเลย

เพราะงั้นอย่าเขียน path เขียนความสามารถ ชี้รูปร่างของโปรเจกต์ว่า มี auth module มี billing module แล้วปล่อยให้ agent หา path ปัจจุบันเองตอนวางแผน คอนเซปต์โดเมนอย่าง organization กับ workspace เปลี่ยนช้ากว่า path แต่ก็ยังไหลตามโค้ดเบสที่วิ่งเร็ว ใช้มือเบา ๆ ไว้ทุกจุด

root AGENTS.md ควรมีอะไรจริง ๆ

โหดเข้าไว้ ของจำเป็นมีสามอย่าง

1. คำอธิบายโปรเจกต์หนึ่งประโยค
2. package manager ถ้าไม่ใช่ npm
3. คำสั่ง build และ typecheck ถ้าไม่ใช่มาตรฐาน

ไฟล์ทั้งไฟล์จบแค่นั้นก็พอ ที่เหลือทั้งหมดย้ายไปอยู่ที่อื่น

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

นี่คือ component library ของ React สำหรับทำ data visualization ที่เข้าถึงได้

ส่วนบรรทัด package manager ช่วยตัด error ได้ทั้งกอง

โปรเจกต์นี้ใช้ pnpm workspaces

ถ้าไม่มีบรรทัดนี้ agent จะเดาเองว่า npm แล้ว generate คำสั่งที่รันไม่ผ่าน หรือไม่ก็ใช้ corepack ซึ่งจัดการให้เองอัตโนมัติแบบไม่คิดเงิน instruction budget สักหน่วย

Progressive disclosure ชี้ไปหากฎ อย่ายัดเข้ามา

หลักการที่มาแทน ball of mud คือ ให้ agent แค่สิ่งที่จำเป็นตอนนี้ แล้วชี้ทางไปหาทุกอย่างที่เหลือ

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

ส่วนข้อตกลง TypeScript ใน AGENTS.md ของคุณ ห้าสิบบรรทัดที่เขียนว่า ใช้ const เสมอ ห้ามใช้ var ใช้ interface ดีกว่า type ก็ย้ายไปอยู่ไฟล์แยก แล้ว root file เหลือหนึ่งบรรทัด

ข้อตกลงเรื่อง TypeScript ดูได้ที่ docs/TYPESCRIPT.md

ประโยชน์มาเร็วมาก

• กฎ TypeScript โหลดเฉพาะตอน agent กำลังเขียน TypeScript จริง ๆ งาน debug CSS กับงาน dependency ไม่ต้องจ่ายค่าน้ำมันให้มันอีกต่อไป
• root file ยังอ่านรู้เรื่องสำหรับมนุษย์
• ไฟล์ของแต่ละโดเมนดูแลโดยคนที่เป็นเจ้าของโดเมนนั้นจริง ๆ

แล้วมันซ้อนต่อได้ docs/TYPESCRIPT.md ชี้ไป docs/TESTING.md ซึ่งชี้ต่อไปยังเอกสารของ test runner ที่คุณใช้ สุดท้ายคุณได้ต้นไม้ที่ค้นหาได้ แล้ว agent เดินตามเท่าที่จำเป็น

Monorepo ไฟล์ AGENTS.md ที่ซ้อนกันจะ merge รวมร่าง

คุณไม่ได้ถูกจำกัดให้มี AGENTS.md ไฟล์เดียว ไฟล์ใน subdirectory จะ merge กับ root ซึ่งตรงกับที่ monorepo ต้องการเป๊ะ root ดูแลสิ่งที่เป็นจริงทุกที่ ไม่ว่าจะเป็นจุดประสงค์ของ repo การนำทางระหว่าง package หรือ tooling ที่ใช้ร่วมกัน ส่วนไฟล์ของแต่ละ package ดูแลสิ่งที่เป็นจริงเฉพาะที่นั้น

root AGENTS.md หน้าตาประมาณนี้

นี่คือ monorepo ที่รวม web service และ CLI tool
ใช้ pnpm workspaces ในการจัดการ dependencies
ดู AGENTS.md ของแต่ละ package สำหรับแนวทางเฉพาะ

ส่วนไฟล์ packages/api/AGENTS.md เขียนไว้แบบนี้

package นี้คือ GraphQL API บน Node.js ที่ใช้ Prisma
ทำตาม docs/API_CONVENTIONS.md สำหรับแพทเทิร์นการออกแบบ API

มีข้อแม้อย่างเดียว agent เห็นไฟล์ที่ merge แล้วทั้งหมดใน context ของมัน ขยะสองชั้นก็ยังเป็นขยะ วินัยเดียวกันจึงต้องใช้ทุกระดับ

วิธีที่ไม่ได้ผล สร้างไฟล์แบบอัตโนมัติ

ทางลัดที่ดูชัดที่สุดคือ init script ที่ generate AGENTS.md ให้คุณ ผมแนะนำให้ข้ามไปเลย

ไฟล์ที่ generate ออกมาปรับให้ดีที่สุดในแง่ความครบถ้วน ไม่ใช่ความยับยั้งชั่งใจ มันยัดทุกอย่างที่ "น่าจะมีประโยชน์ในหลายสถานการณ์" ลงไป ซึ่งก็คือเนื้อหาที่ควรถูกแยกไป progressive disclose ต่างหาก AGENTS.md ที่ generate ออกมาเป็น ball of mud ตั้งแต่วันแรก ก่อนที่บรรทัดไหนจะพิสูจน์ตัวเองได้สักบรรทัด

กฎแต่ละข้อควรอยู่ตรงไหน

Prompt สำหรับ refactor AGENTS.md ของคุณ

ถ้าไฟล์ปัจจุบันของคุณทำให้ใจสั่น ลองวาง prompt นี้ให้ agent ตรง ๆ

Refactor my AGENTS.md file to follow progressive disclosure principles.

1. Find contradictions: identify instructions that conflict with each
   other. For each contradiction, ask me which version to keep.
2. Identify the essentials: keep only what belongs in the root AGENTS.md:
   - a one-sentence project description
   - the package manager, if not npm
   - non-standard build and typecheck commands
   - anything truly relevant to every single task
3. Group the rest: organize remaining instructions into logical
   categories (TypeScript conventions, testing patterns, API design,
   git workflow) and put each in its own markdown file.
4. Output the new structure: a minimal root AGENTS.md with links to the
   separate files, each separate file with its instructions, and a
   suggested docs/ folder layout.
5. Flag for deletion: anything redundant, too vague to be actionable,
   or obvious enough that the agent already knows it ("write clean code").

สมาธิของ agent คือทรัพยากรที่หายากที่สุดใน repo ของคุณ ทุกบรรทัดของ AGENTS.md เผาผลาญมันในทุก request ไม่ว่าบรรทัดนั้นจะยังใช้จริงอยู่หรือไม่ ให้เริ่มจาก

• ประโยคเดียวบอกว่าโปรเจกต์คืออะไร
• package manager ที่ใช้
• คำสั่ง build

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