จุดเจ็บ: ทำไม AI เขียนโค้ดพังซ้ำที่เดิม

คนที่ใช้ Cursor, Windsurf หรือ Claude Code เขียนโปรเจกต์ เจอภาวะหนึ่งซ้ำๆ AI ส่งโค้ดมาเป็นพืด ก๊อปวางรัน — build พัง, เทสต์แดง, ติดตั้ง dependency ผิดที่ ปัญหาไม่ใช่ AI โง่ แต่มันไม่รู้ “กฎเบื้องหลัง” ของโปรเจกต์คุณ

AGENTS.md คือไฟล์ Markdown ที่วางไว้ root ของโปรเจกต์ เขียนขึ้นเพื่อให้ AI อ่านโดยเฉพาะ บอกว่าจะ build ยังไง รันเทสต์ยังไง ต้องทำตามมาตรฐานอะไร README.md เขียนให้คนอ่าน อัดไปด้วยแนะนำโปรเจกต์ คู่มือ contribute เรื่องแบรนด์ AI ที่อ่าน README เหมือนพนักงานใหม่วันแรกที่ถูกยัดแคตตาล็อกบริษัท แล้วโดนสั่งให้เขียนโค้ดทันที — รู้ว่าบริษัททำอะไร แต่ไม่รู้คำสั่ง build ไม่รู้วิธีรันเทสต์ ไม่รู้ ESLint rule คืออะไร ผลคือต้องนั่งแก้ในแชทซ้ำๆ “ใช้ pnpm ไม่ใช่ npm” “เทสต์อยู่ที่ packages/web” “อย่าลืมรัน lint” แก้ร้อยรอบ โปรเจกต์ก็ยังรก

งานรับทำเจ็บตรงๆ คุณรับงาน outsource Next.js + Prisma ใช้ Cursor เร่งงาน AI กลับใช้ npm install ทั้งที่ตั้ง pnpm workspace ไว้ มันไม่รู้ว่า schema ฐานข้อมูลอยู่โฟลเดอร์ไหน migration ที่ generate ออกมาเลยพัง ลูกค้ากดดัน คุณเสียสามชั่วโมง debug โค้ดที่ AI สร้าง — เงินนี้ได้มาแบบอึดอัด

3 ฉากพังคลาสสิกที่ AI ไม่รู้กฎโปรเจกต์: ① สับสน package manager (โปรเจกต์ใช้ pnpm แต่ AI ดีฟอลต์ npm install) ติดตั้งผิดที่ workspace พัง ② หาทางเข้าเทสต์ไม่เจอ (เทสต์อยู่ใต้ packages/web แต่ AI รัน pnpm test ที่ root ขึ้น “ไม่พบไฟล์เทสต์”) ③ สไตล์โค้ดไม่ตรงกัน (โปรเจกต์ใช้ ESLint + Prettier แต่ AI สร้างโค้ดย่อหน้าผิด quote ผิด CI แดงทันที)

โอกาส: AGENTS.md แยก “เอกสารคน” ออกจาก “เอกสารเครื่อง” แบบเด็ดขาด

โปรเจกต์ open source AGENTS.md บน GitHub (repo github.com/agentsmd/agents.md ณ วันที่ 2026-08-25 มีดาวราว 24,000) แก้ปัญหานี้ตรงๆ แนวคิดเรียบง่าย: วางไฟล์ Markdown ที่ root บอก AI ว่าจะ build ยังไง รันเทสต์ยังไง ทำตามสไตล์โค้ดอะไร

มันไม่ใช่ตัวแทน README แต่เป็นของเสริม README รับใช้ contributor ที่เป็นคน AGENTS.md รับใช้ agent AI แบ่งหน้าที่ชัด ไม่ทับกัน

ตามโพสต์ต้นทาง AGENTS.md ถูกใช้ในโปรเจกต์ open source หลายหมื่นโปรเจกต์ (ตัวเลขแม่นยำรอตรวจ) ครอบคลุม VS Code, Cursor, Windsurf, Aider, GitHub Copilot และเครื่องมือ AI เขียนโค้ดหลักๆ (ยืนยันจากหลักฐาน) นอกจากนี้ตามเสียงในชุมชน OpenAI Codex, Google Jules ก็รองรับด้วย (⚠️ยังไม่ยืนยัน) ถ้าวันนี้คุณไม่เรียน เท่ากับปล่อยให้ AI พูดสำเนียงต่างถิ่นกับคุณ

เส้นทางที่ 1: เขียน AGENTS.md ขั้นต่ำใช้งานได้จริง

ต้นทุนต่ำมาก สร้างไฟล์ใหม่ เขียนสามท่อนก็พอ

พื้นฐานที่ต้องรู้: ตัวอย่างใช้ pnpm (ประหยัดดิสก์กว่า npm รองรับ monorepo workspace) turbo คือเครื่องมือจัดงานใน monorepo พารามิเตอร์ --filter ระบุให้ทำเฉพาะ sub-package ไม่กระทบทั้ง repo

ท่อนแรก “Dev environment tips”: บอก AI ว่าโปรเจกต์ใช้ package manager อะไร วิธีกระโดดเข้า sub-package วิธีสร้างโมดูลใหม่ เช่นตัวอย่างจากทางการ:

• pnpm dlx turbo run where <project_name> — กระโดดเข้าโฟลเดอร์ sub-package ที่ระบุ ไม่ต้อง ls ทีละโฟลเดอร์
• pnpm install --filter <project_name> — ติดตั้งเฉพาะ dependency ของ sub-package นั้น ไม่กระทบทั้ง monorepo
• pnpm create vite@latest <project_name> -- --template react-ts — สร้าง sub-package React + Vite พร้อม TypeScript check

คำสั่งพวกนี้ AI เดาเองไม่ได้ แต่พอเขียนลงไปมันทำตาม

ท่อนสอง “Testing instructions”: บอก AI วิธีรันเทสต์ CI plan อยู่ที่ไหน ก่อน commit ต้องรันเช็คอะไรบ้าง ตัวอย่างจากทางการรวมถึง:

• pnpm turbo run test --filter <project_name> — รันเช็คทั้งหมดของ sub-package ที่ระบุ
• pnpm vitest run -t "<test name>" — รันเฉพาะเทสต์ที่ตรงชื่อ
• “Fix any test or type errors until the whole suite is green” — จนกว่าทั้งชุดจะเขียว ห้ามหยุด
• “Add or update tests for the code you change, even if nobody asked” — ประโยคนี้สำคัญที่สุด ถ้าไม่เขียน AI มักขี้เกียจไม่เขียนเทสต์

ท่อนสาม “PR instructions”: กำหนดรูปแบบ commit title บังคับรัน lint กับ test ตัวอย่างจากทางการคือ Title format: [<project_name>] <Title> และ “Always run pnpm lint and pnpm test before committing”

สามท่อนรวมกันไม่ถึง 50 บรรทัด แต่ดึงอัตราผ่านครั้งแรกของโค้ดที่ AI สร้างขึ้นได้ชัดเจน (ตามเสียงชุมชน ตัวเลขแม่นยำรอตรวจ)

เส้นทางที่ 2: ซ้อนใช้ใน monorepo ขนาดใหญ่

ถ้ารับงานระดับองค์กร codebase เป็นโครงสร้าง monorepo (หลายโปรเจกต์ที่เกี่ยวข้องอยู่ใน Git repo เดียว เช่น frontend, backend, shared code แยกคนละโฟลเดอร์) AGENTS.md ไฟล์เดียวไม่พอ AGENTS.md รองรับการซ้อน: วางไฟล์เฉพาะในแต่ละโฟลเดอร์ย่อย AI จะอ่าน “ไฟล์ที่ใกล้ที่สุด” อัตโนมัติ

วิธีปฏิบัติ: AGENTS.md ที่ root เขียนกฎทั้ง repo (package manager, CI flow, ข้อควรระวังด้านความปลอดภัย) แล้วใน packages/web/, packages/api/, packages/shared/ วางอีกไฟล์ เขียนคำสั่ง build เฉพาะ ทางเข้าเทสต์ dependency พิเศษของ sub-package นั้น เช่น frontend ต้องเขียน “ใช้ component library shadcn, สไตล์ใช้ Tailwind, ไอคอนใช้ lucide-react” backend ต้องเขียน “migration ใช้ Prisma, API route อยู่ใต้ src/routes, auth ใช้ JWT”

ตอน AI ทำงานในโฟลเดอร์ย่อย มันจะโหลด AGENTS.md ที่ใกล้ที่สุดอัตโนมัติ ลำดับความสำคัญสูงกว่า root แปลว่าในโปรเจกต์เดียวกัน AI ช่วย frontend กับ AI ช่วย backend ได้คำสั่งคนละชุด ไม่ปนกัน

เส้นทางที่ 3: เอามาเป็นจุดขายรับงาน

ตลาดรับงาน AI ตอนนี้แดงเถือก — ทุกคนใช้ Cursor เป็น แต่คุณภาพส่งมอบต่างกันสุดขั้ว ถ้าใส่ในใบเสนอราคาสักประโยค “โปรเจกต์นี้ตั้งค่าเอกสารมาตรฐาน AGENTS.md แล้ว AI ช่วยพัฒนาทำตามกฎโปรเจกต์” โอกาสชนะประมูลสูงกว่าคู่แข่งที่พูดแค่ “ผมใช้ AI เขียนโค้ด”

วิธีเล่นจริง: รับงานมาแล้ว สละ 30 นาทีอ่านโครงสร้างโปรเจกต์ลูกค้า แล้วเขียน AGENTS.md เฉพาะงาน เอกสารนี้คือ deliverable ส่วนหนึ่ง — ลูกค้าได้ไป อนาคตใช้ AI ดูแลโค้ดต่อก็ลื่นขึ้น

ตั้งราคาบริการตั้งค่า AGENTS.md แยก (ราคาอ้างอิง ปรับตามตลาดท้องถิ่น): เวอร์ชันพื้นฐาน 2,500 บาท (ตั้งค่าไฟล์เดียว + README อธิบาย) เวอร์ชันองค์กร 15,000 บาท (monorepo ซ้อน + กฎความปลอดภัย + อบรมทีม) รายการส่งมอบ: ① ไฟล์ AGENTS.md เฉพาะงาน ② ตอบข้อสงสัย 30 วันผ่าน LINE ③ วิดีโอเทรน 10 นาที เหมาะกับ: ลูกค้ามีสมาชิก Cursor/Windsurf อยู่แล้วแต่ใช้ไม่เป็น ไม่เหมาะกับ: ลูกค้ายังเขียนมือล้วน ไม่มีเครื่องมือ AI

เคส: คูเมืองความเข้ากันได้ของ AGENTS.md

AGENTS.md ใช้สัญญาอนุญาต MIT (ยืนยันจากชุดข้อมูล) ดูแลโดยชุมชน (โครงสร้าง governance รอตรวจ) เว็บทางการคือ agents.md

ความเข้ากันได้คือคูเมืองที่ใหญ่ที่สุด: ยืนยันจากหลักฐานว่า VS Code, Cursor, Windsurf, Aider, GitHub Copilot รองรับการอ่าน AGENTS.md ทั้งหมด ตามเสียงชุมชน OpenAI Codex, Claude Code, Gemini CLI, Google Jules ก็รองรับด้วย (⚠️ยังไม่ยืนยัน) แปลว่าเขียนไฟล์เดียว AI หลักๆ ใช้ได้หมด — ไม่ต้องเขียน config แยกต่างหาก

เทียบกับทางเลือกอื่น: .cursorrules ของ Cursor ใช้ได้กับ Cursor อย่างเดียว สลับเป็น Windsurf ก็จบ CLAUDE.md ของ Claude Code รับใช้แค่ Claude ระบบ instruction ของ GitHub Copilot ก็อีกชุด คุณสมบัติ “เขียนครั้งเดียว ใช้ได้ทุกที่” ของ AGENTS.md คือเหตุผลที่มันถูกใช้แพร่หลายในเวลาอันสั้น

ต้นทุนย้ายเครื่องมือเป็นศูนย์ วันนี้ใช้ Cursor พรุ่งนี้สลับ Windsurf AGENTS.md ใช้ต่อได้เลย ไม่ต้องเขียนกฎใหม่

เรียกร้อง: คืนนี้เพิ่มคู่มือเครื่องให้โปรเจกต์

เช็คลิสต์ 5 นาที: ① เปิด root ของโปรเจกต์ ② สร้าง AGENTS.md ③ ก๊อปเทมเพลตทางการ (github.com/agentsmd/agents.md) ④ ใส่สามคำสั่ง (build, test, lint) ⑤ ครั้งหน้าให้ AI เขียนโค้ดแล้วสังเกตผล

ถ้าใช้ monorepo คืนนี้เพิ่มอีก 20 นาที ตั้งค่าซ้อนให้ทุก sub-package พรุ่งนี้เปิดงานจะพบว่าโค้ดที่ AI สร้างไม่ต้องมานั่งแก้ซ้ำอีก

AGENTS.md คือการตั้งค่า AI เขียนโค้ดที่คุ้มสุดตอนนี้ — ลงทุน 30 นาที แลกเวลา debug หลายชั่วโมงต่อเดือน