AGENTS.md คืออะไร

AGENTS.md คือไฟล์คำแนะนำสำหรับ AI Coding Agent ที่อยู่ร่วมกับ Source Code ของโปรเจกต์ จุดประสงค์คือบอก Context การทำงานที่ควรใช้ซ้ำ เช่น Project นี้ใช้ Technology อะไร Run ด้วยคำสั่งไหน มีข้อจำกัดอะไร และก่อนส่งงานต้องตรวจอะไร

แนวคิดคล้ายการเขียน README สำหรับผู้ช่วยที่ลงมือแก้ Code ให้เรา เพียงแต่เนื้อหาควรเน้น กฎการทำงาน มากกว่าคำอธิบาย Product ยาว ๆ

ทำไมควรมี

ถ้าไม่มีคำแนะนำกลาง ทุก Prompt ต้องคอยบอกซ้ำว่า “อย่าติดตั้ง Library เพิ่ม”, “ใช้ Component เดิมก่อน”, “Run build ก่อนจบ” หรือ “อย่าเปลี่ยนโครงสร้าง Project”

AGENTS.md ช่วยทำให้คำสั่งเหล่านี้อยู่ใกล้ Code และใช้ซ้ำได้ แต่ Prompt ของ Task ก็ยังต้องบอกสิ่งเฉพาะงาน เช่น วันนี้ต้องทำหน้า Clients จาก Design ไหน

โครงสร้างที่กระชับและใช้งานได้

ผมแนะนำ 5 ส่วนหลัก

# Project Overview
# Development Commands
# Code Guidelines
# UI Guidelines
# Before Completing a Task

ถ้า Project มีข้อกำหนดพิเศษค่อยเพิ่ม ไม่จำเป็นต้องสร้างหัวข้อจำนวนมากเพียงเพราะ Agent อ่านได้

Project Overview

ส่วนนี้บอกสั้น ๆ ว่า Project คืออะไร ใช้ Stack อะไร และ Scope สำคัญเป็นอย่างไร เช่น React + Vite, เก็บข้อมูลด้วย LocalStorage และไม่เพิ่ม Backend ในเวอร์ชันนี้

อย่าใส่ Product requirement ทุกหน้าลงที่นี่ ถ้ามี PROJECT.md อยู่แล้ว ให้บอก Agent ไปอ่านไฟล์นั้นเมื่อต้องเข้าใจ Feature

Development Commands

ให้ใช้คำสั่งที่มีอยู่จริงใน package.json เช่น

npm run dev
npm run build

ไม่ควรเขียน npm run lint ถ้า Project ไม่มี Script นี้ เพราะ Agent อาจพยายามรันแล้วเสียเวลาแก้สิ่งที่ไม่ได้มีอยู่จริง

Code Guidelines

กฎที่มีประโยชน์ เช่น

  • รักษาโครงสร้างโปรเจกต์เดิม
  • ใช้ Component ที่มีอยู่ก่อนสร้าง Component ใหม่
  • ไม่ติดตั้ง Library เพิ่มโดยไม่จำเป็น
  • เปลี่ยนเฉพาะส่วนที่เกี่ยวข้องกับ Task
  • ถ้าต้องเปลี่ยน Architecture ให้บอกเหตุผลก่อน

กฎลักษณะนี้ช่วยลดการ Refactor เกิน Scope ซึ่งเป็นปัญหาที่พบได้เมื่อ Agent อยาก “ปรับให้ดีขึ้น” มากกว่าสิ่งที่เราขอ

UI Guidelines

ส่วนนี้ไม่ควรพยายามแทน DESIGN.md ทั้งไฟล์ แต่ควรบอกลำดับความสำคัญของ Design Context เช่น

- ถ้ามี DESIGN.md ให้ใช้เป็นกฎ Design ร่วมของโปรเจกต์
- ถ้า Task ระบุหน้าจอ Google Stitch ให้หน้าจอนั้นเป็น Source of truth
- ห้าม redesign Application shell โดยไม่ได้รับคำสั่ง
- ใช้ Shared Component เดิมก่อนสร้างของใหม่

นี่ช่วย Agent ตัดสินใจเมื่อมี Context หลายชุดพร้อมกัน

Before Completing a Task

ส่วนนี้เป็นหนึ่งในส่วนที่คุ้มที่สุด เพราะคำว่า “เสร็จ” ของ Agent ควรมีเกณฑ์

ตัวอย่าง

- ตรวจ error ที่เกี่ยวข้องกับการแก้ไข
- เปิดหรือทดสอบ Flow ที่เปลี่ยนเมื่อทำได้
- Run production build
- สรุปไฟล์ที่แก้และสิ่งที่ควรตรวจต่อ

อย่าระบุเครื่องมือที่ Project ไม่มี ให้กฎตรงกับ Environment จริง

AGENTS.md ไม่ได้แทน Prompt ของ Task

ไฟล์นี้บอก “วิธีทำงานทั่วไป” แต่ไม่ได้รู้ว่า Task วันนี้คืออะไร Prompt ยังควรชัดว่าให้ทำหน้าไหน อ่าน Design จากไหน และห้ามแตะส่วนไหน

ตัวอย่าง Prompt ที่ดีอาจสั้นลงเพราะมีกฎกลางแล้ว

อ่าน AGENTS.md ก่อนเริ่ม
จากนั้นอ่านหน้า Clients ใน Google Stitch ผ่าน MCP
สร้างเฉพาะ Clients page โดยยึด UI จาก Stitch เป็น Source of truth
ห้าม redesign App shell

อย่าใส่กฎมากเกินไป

Agent ต้องประมวล Context หลายอย่าง ถ้า AGENTS.md ยาวมากและมีข้อยกเว้นซ้อนกัน มันอาจจับกฎสำคัญได้ยากขึ้น

ให้เริ่มจากกฎที่ผิดแล้วมีผลต่อ Project จริง เช่น Dependency, UI source, Build และ Scope แล้วค่อยเพิ่มเมื่อพบปัญหาซ้ำ

AGENTS.md, DESIGN.md และ Prompt ทำงานร่วมกันอย่างไร

ให้คิดแบบนี้

  • AGENTS.md = วิธีทำงานใน Repository
  • DESIGN.md = กฎและ Foundation ของ UI
  • Design Reference = หน้าตาที่ต้องยึด
  • Prompt = งานเฉพาะรอบนี้

เมื่อแต่ละอย่างทำหน้าที่ของตัวเอง Context จะไม่ปนกัน และ Agent มีโอกาสทำงานได้สม่ำเสมอกว่าเดิม

อ่านต่อได้ใน ทำไม AI Coding Agent ทำ UI ไม่เหมือน Google Stitch ซึ่งเป็นตัวอย่างชัดว่าการมีไฟล์ Context อย่างเดียวไม่พอถ้า Prompt ไม่ระบุ Source of truth ครับ

FROM DESIGN TO REAL APP

อยากลองทำตั้งแต่ Vibe Design ไปจนเป็น Web App ที่ใช้งานได้จริง?

ดูรายละเอียดคอร์ส Design to Web App with AI และ Workflow ที่ใช้ Google Stitch, MCP และ AI Coding Agent ทำโปรเจกต์จริงแบบเป็นขั้นตอน

ดูรายละเอียดคอร์ส ↗