AGENTS.md คืออะไร? วิธีเขียนคู่มือสำหรับ AI Coding Agent

AGENTS.md คืออะไร

AGENTS.md เป็นไฟล์ Markdown ธรรมดาที่วางไว้ที่ root ของ repository เพื่อบอก coding agent ว่าควรทำงานกับโปรเจกต์นั้นอย่างไร เว็บไซต์อย่างเป็นทางการอธิบายไว้ว่าเป็น "README สำหรับ agent: พื้นที่เฉพาะที่คาดการณ์ได้เพื่อจัดเตรียมบริบทและคำแนะนำที่จะช่วยให้ AI coding agent ทำงานกับโปรเจกต์ของคุณได้" รูปแบบนี้ได้รับการดูแลโดย Agentic AI Foundation ภายใต้ Linux Foundation และมี agent มากกว่ายี่สิบตัวที่อ่านไฟล์นี้ รวมถึง Codex, Cursor, Jules, Devin และ GitHub Copilot (ข้อมูล ณ เดือนกรกฎาคม 2026)

เหตุผลที่ธรรมเนียมนี้เกิดขึ้นมาจากความจำเป็นในทางปฏิบัติ สมาชิกใหม่ในทีมของคุณจะอ่าน README, เดาคำสั่ง build และถามคนอื่นเมื่อการเดานั้นผิดพลาด แต่ agent ไม่สามารถถามได้ มันจะเดา, รัน npm test บนโปรเจกต์ที่ใช้ pnpm test, อ่านข้อผิดพลาดที่เกิดขึ้น แล้วลองวิธีอื่น ซึ่งคุณต้องจ่ายค่าใช้จ่ายสำหรับทุก token เหล่านั้น การเขียนคำสั่งที่ถูกต้องลงไปเพียงครั้งเดียวจะช่วยขจัดความล้มเหลวในรูปแบบนี้ทั้งหมด

ไม่มีฟิลด์ที่บังคับต้องมี เว็บไซต์ระบุไว้อย่างชัดเจนว่า: "AGENTS.md เป็นเพียง Markdown มาตรฐาน ใช้หัวข้อใดก็ได้ที่คุณต้องการ; agent จะแยกวิเคราะห์ข้อความที่คุณให้มาเท่านั้น" นั่นคือข้อกำหนดทั้งหมด คุณค่าของมันไม่ได้อยู่ที่รูปแบบ แต่อยู่ที่การที่ไฟล์นี้วางอยู่ใน path ที่เครื่องมือทุกตัวมองหาอยู่แล้ว

ตำแหน่งของไฟล์และลำดับความสำคัญ

ให้วางไฟล์แรกไว้ที่ root ของ repository สำหรับ monorepo คุณสามารถเพิ่มไฟล์ไว้ภายในแต่ละ subproject ได้ โดยมีกฎง่ายๆ คือ "agent จะอ่านไฟล์ที่ใกล้ที่สุดในโครงสร้างไดเรกทอรีโดยอัตโนมัติ ดังนั้นไฟล์ที่อยู่ใกล้ที่สุดจึงมีลำดับความสำคัญสูงสุด" หากเกิดความขัดแย้งระหว่างสองไฟล์ ระบบจะยึดตามไฟล์ที่กำลังแก้ไขอยู่เป็นหลัก และสิ่งที่คุณพิมพ์ลงในแชทจะถือว่ามีลำดับความสำคัญเหนือกว่าไฟล์ทั้งสอง

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

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

สิ่งที่ควรระบุไว้ใน AGENTS.md

ให้ระบุข้อมูลที่ AI agent ไม่สามารถสรุปได้จากการอ่านโค้ดเพียงอย่างเดียว โดยเริ่มจากคำสั่ง build, test และ lint ที่ถูกต้องในรูปแบบที่คุณจะคัดลอกไปวางใน terminal ให้เพิ่มคำสั่งสำหรับรันการทดสอบเพียงรายการเดียวเข้าไปด้วย เพราะหาก agent ทราบเพียงวิธีรันชุดทดสอบทั้งหมด มันจะรันซ้ำถึง 40 ครั้ง ให้ระบุข้อตกลง (conventions) ที่แตกต่างไปจากค่าเริ่มต้นของเครื่องมือ เนื่องจาก agent ทราบค่าเริ่มต้นอยู่แล้วและต้องการทราบเพียงจุดที่คุณปรับเปลี่ยนเท่านั้น นอกจากนี้ให้เพิ่มรูปแบบของ commit message และกฎการส่ง pull request หากคุณมีกำหนดไว้

จงระบุให้ชัดเจนพอที่จะตรวจสอบผลลัพธ์ได้ คำสั่งอย่าง "ใช้การเยื้อง 2 ช่อง" เป็นคำสั่งที่ใช้งานได้จริงเพราะสามารถตรวจสอบได้ว่าทำหรือไม่ทำ แต่คำสั่งอย่าง "จัดรูปแบบโค้ดให้เหมาะสม" นั้นใช้ไม่ได้เพราะไม่สามารถตรวจสอบได้ เช่นเดียวกับการระบุตำแหน่งไฟล์: "API handlers อยู่ใน src/api/handlers/" ย่อมดีกว่าการบอกว่า "จัดระเบียบไฟล์ให้ดี"

กฎเชิงลบก็มีความสำคัญเช่นกัน เช่น "ห้ามแก้ไขไฟล์ภายใต้ dist/ เนื่องจากถูกสร้างขึ้นโดย npm run build" จะช่วยป้องกันข้อผิดพลาดเฉพาะจุด และเนื่องจากมีการระบุสาเหตุไว้ agent จึงสามารถอนุมานกรณีที่คล้ายคลึงกันที่คุณไม่ได้เขียนไว้ได้ กฎเกี่ยวกับขอบเขต (scope) ก็ควรระบุไว้ที่นี่เช่นกัน เพราะหากปล่อยให้ agent ตัดสินใจเอง มันมักจะแก้ไขโค้ดมากกว่าที่คุณต้องการ: ทักษะหนึ่งที่ถูกนำไปใช้กันอย่างแพร่หลายคือการยืนกรานให้แก้ไขเฉพาะจุดที่จำเป็นน้อยที่สุดเพื่อให้งานสำเร็จ

What never belongs in one

Never put a secret in one of these files. The file is committed to git, loaded into context at the start of every session, and sent to a model provider on every request. An API key in an AGENTS.md is an API key in your repository history and in a third party's logs. Point at the secret instead of pasting it: "the database password is in .env, which is gitignored; ask before reading it." The wider discipline is covered in keeping credentials out of an agent's reach.

Leave out anything the agent can derive by looking. A pasted directory listing, a copy of your dependency list, an architecture overview that restates the folder names: all of it goes stale the week after you write it, and it costs context on every session in the meantime. Keep the pitfalls and the reasons. Drop the inventory. The reasons are worth separating out, because an agent that cannot see why an unusual shape exists will quietly refactor it away, which is the case for keeping a DESIGN.md next to this one.

CLAUDE.md คืออินสแตนซ์ของ Claude Code ที่ใช้แนวคิดเดียวกัน

Claude Code จะอ่าน CLAUDE.md และไม่ได้อ่าน AGENTS.md โดยอัตโนมัติ ไฟล์โปรเจกต์จะอยู่ที่ ./CLAUDE.md หรือ ./.claude/CLAUDE.md ส่วนการตั้งค่าส่วนบุคคลสำหรับทุกโปรเจกต์จะอยู่ใน ~/.claude/CLAUDE.md และองค์กรสามารถผลักไฟล์ระดับเครื่อง (machine-wide) ไปไว้ที่ /etc/claude-code/CLAUDE.md บน Linux ได้ ไฟล์ที่ถูกค้นพบจะถูกนำมาต่อกันจาก root ของระบบไฟล์ลงมาจนถึงไดเรกทอรีทำงานของคุณ ดังนั้นไฟล์ที่อยู่ใกล้กับตำแหน่งที่คุณเริ่มเซสชันมากที่สุดจะถูกอ่านเป็นลำดับสุดท้าย ทุกเซสชันที่คุณเริ่มในไดเรกทอรีนั้นจะโหลด stack เดียวกัน ซึ่งทำให้สามารถรันสองเซสชันควบคู่กันบนเครื่องเดียวได้ และ เซสชันเหล่านั้นสามารถส่งต่องานให้กันและกันได้ในขณะที่รันอยู่

หาก repository ของคุณมีไฟล์ AGENTS.md อยู่แล้ว ไม่จำเป็นต้องดูแลสำเนาชุดที่สอง ให้ทำการ import เข้ามาแล้วเพิ่มเฉพาะส่วนที่เป็นของ Claude เท่านั้น:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

การใช้ symlink สามารถทำได้เมื่อคุณไม่มีข้อมูลอื่นที่ต้องเพิ่ม:

ln -s AGENTS.md CLAUDE.md

คำสั่งนี้จะไม่แสดงผลลัพธ์ใดๆ หากสำเร็จ ในเซสชันถัดไปให้รัน /context และตรวจสอบว่า CLAUDE.md ปรากฏขึ้นภายใต้หัวข้อ Memory files หากไฟล์ไม่อยู่ในรายการดังกล่าว แสดงว่าไฟล์ไม่ได้ถูกโหลดและไม่มีการนำค่าใดๆ ไปใช้ หากต้องการสร้างร่างแรกแทนการเขียนเอง ให้รัน /init ซึ่งจะอ่าน codebase และสร้างไฟล์เริ่มต้นขึ้นมา และหากมีไฟล์ CLAUDE.md อยู่แล้ว ระบบจะแนะนำการปรับปรุงแทนการเขียนทับ

ควรดูแลให้แต่ละไฟล์มีความยาวไม่เกิน 200 บรรทัด ไฟล์ที่ยาวเกินไปจะกินพื้นที่หน้าต่างบริบท (context window) มากขึ้นและทำให้ประสิทธิภาพในการปฏิบัติตามคำสั่งลดลง หากต้องการทราบว่ามีสิ่งใดบ้างที่แย่งพื้นที่ในส่วนนั้น สิ่งที่เติมเต็มหน้าต่างบริบทของเอเจนต์ จะอธิบายรายละเอียดไว้

มีประเด็นหนึ่งที่ควรเน้นย้ำ ไฟล์ AGENTS.md เป็นเพียงแนวทาง ไม่ใช่ระบบการอนุญาต เนื้อหาจะถูกส่งไปในฐานะบริบททั่วไป ดังนั้นโมเดลจะอ่านและปฏิบัติตามเป็นปกติ แต่ไม่มีสิ่งใดมาขัดขวางการกระทำที่ขัดแย้งกับไฟล์นี้ได้ เมื่อกฎที่คุณเขียนถูกละเลยไปเฉยๆ และคุณไม่ทราบสาเหตุ ให้ตรวจสอบ เหตุผลที่คำสั่งถูกละทิ้ง ก่อนที่จะเขียนคำสั่งนั้นใหม่เป็นครั้งที่สาม สำหรับกฎที่ต้องบังคับใช้ทุกครั้ง เช่น "ห้าม push ไปที่ main" ให้ใช้ hook หรือการตั้งค่าสิทธิ์แทน เพราะสิ่งเหล่านั้นทำงานในระดับโค้ดและไม่ขึ้นอยู่กับการตัดสินใจของโมเดลว่าจะปฏิบัติตามหรือไม่

เครื่องมือที่ช่วยเขียนไฟล์เหล่านี้ให้คุณ

โครงการสองโครงการที่ติดอันดับ GitHub trending เมื่อวันที่ 30 กรกฎาคม 2026 แสดงให้เห็นถึงทิศทางของธรรมเนียมปฏิบัติในเรื่องนี้

agent0ai/dox (มี 1,368 ดาว ณ เดือนกรกฎาคม 2026) เป็นเฟรมเวิร์กสำหรับรักษาโครงสร้างไฟล์ AGENTS.md ให้เป็นปัจจุบันอยู่เสมอ โครงการนี้ไม่มีแพ็กเกจและไม่มี runtime ให้ติดตั้ง คุณเพียงแค่คัดลอกเนื้อหาจาก AGENTS.md ของโครงการมาไว้ในไฟล์ AGENTS.md ที่ root ของคุณ นั่นถือเป็นการติดตั้ง สำหรับโครงการที่มีอยู่แล้ว คุณสามารถสั่งงาน agent ของคุณได้ดังนี้:

Initialize DOX tree for this project now.

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

HUMAN.md เคล็ดลับเดียวกันที่ใช้กับตัวคุณ

Intuition-Lab/personal-model (มี 1,260 ดาว ณ เดือนกรกฎาคม 2026) นำรูปแบบนี้มาใช้กับบุคคลแทนที่จะเป็น repository โครงการนี้กำหนดให้ HUMAN.md ของคุณเป็นผลลัพธ์ของระบบมากกว่าจะเป็นไฟล์ที่คุณพิมพ์ขึ้นมาเอง โดยนิยามว่าเป็น "แบบจำลองที่มีชีวิตของสิ่งที่สำคัญในปัจจุบัน วิธีที่คุณมักจะตัดสินใจ และทิศทางที่ความสนใจของคุณกำลังมุ่งไป" เครื่องมือนี้ทำงานในเครื่องบน macOS 13 หรือใหม่กว่า โดยจะบันทึกกิจกรรมหลังจากที่คุณให้สิทธิ์บน macOS และเปิดเผยผลลัพธ์ให้กับ agent ผ่านทาง MCP (model context protocol) เส้นทางการติดตั้งโดยย่อคือ:

uv tool install personal-model
persome onboard
persome model open --after 30

คุณไม่จำเป็นต้องใช้สิ่งเหล่านั้นทั้งหมดเพื่อให้ได้รับประโยชน์ส่วนใหญ่ HUMAN.md ที่เขียนด้วยมือมีความยาวประมาณ 20 บรรทัด ประกอบด้วยบทบาทของคุณ, เขตเวลาของคุณ, stack ที่คุณใช้งานจริง, การตัดสินใจที่คุณทำไปแล้วและไม่ต้องการให้รื้อฟื้นใหม่ รวมถึงระดับความละเอียดของคำอธิบายที่คุณต้องการได้รับกลับมา มันช่วยประหยัดเวลาในการอธิบายซ้ำๆ เหมือนกับที่ไฟล์ของโครงการช่วยไว้ แต่เป็นในระดับที่สูงขึ้นไปอีกขั้น

ข้อควรระวังประการหนึ่ง HUMAN.md คือโปรไฟล์ของบุคคล ดังนั้นโดยนิยามแล้วมันจึงเป็นข้อมูลที่ละเอียดอ่อน ควรเก็บไว้ให้ห่างจาก repository สาธารณะ ให้เก็บไว้ใน ~/.claude/CLAUDE.md หรือใน CLAUDE.local.md ที่ถูก gitignore ไว้ที่ root ของโครงการ ซึ่งจะถูกโหลดควบคู่ไปกับไฟล์ที่ commit ไว้และได้รับการปฏิบัติในลักษณะเดียวกัน

เทมเพลตเริ่มต้นที่คุณสามารถคัดลอกได้

เนื้อหาส่วนนี้ถูกทำให้สั้นโดยเจตนา ให้ลบส่วนที่ไม่เกี่ยวข้องออก และหลีกเลี่ยงการเพิ่มส่วนที่คุณไม่สามารถดูแลให้เป็นปัจจุบันได้

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

เขียนเนื้อหาขึ้นมาก่อน แล้วจึงแก้ไขในภายหลัง สัญญาณที่บ่งบอกว่าควรเพิ่มบรรทัดใหม่คือการที่คุณพิมพ์คำแก้ไขเดิมซ้ำในแชทสองครั้ง กฎข้อนี้เพียงข้อเดียวจะช่วยให้ไฟล์มีประโยชน์และป้องกันไม่ให้ไฟล์ขยายตัวจนกลายเป็นเอกสารที่ไม่มีใครอ่าน รวมถึงเครื่องจักรด้วย เมื่อไฟล์มีความเสถียรแล้ว มันจะถูกจัดเก็บไปพร้อมกับ repository ซึ่งมีความสำคัญอย่างยิ่งเมื่อ agent ทำงานในที่อื่นที่ไม่ใช่แล็ปท็อปของคุณ โดย การรัน coding agent บนเซิร์ฟเวอร์ของคุณเอง ได้ครอบคลุมการตั้งค่าดังกล่าวไว้แล้ว

FAQ

AGENTS.md เป็นไฟล์เดียวกับ CLAUDE.md หรือไม่?

ทั้งสองไฟล์มีแนวคิดเดียวกันภายใต้ชื่อไฟล์ที่ต่างกัน Claude Code จะอ่าน CLAUDE.md และเพิกเฉยต่อ AGENTS.md เว้นแต่คุณจะเชื่อมโยงไฟล์เข้าด้วยกัน ให้เลือกไฟล์ใดไฟล์หนึ่งเป็นแหล่งข้อมูลหลัก (source of truth) แล้วเชื่อมโยงอีกไฟล์เข้าด้วยกัน โดยใช้บรรทัดที่เขียนว่า @AGENTS.md ไว้ที่ด้านบนของไฟล์ CLAUDE.md หรือใช้ ln -s AGENTS.md CLAUDE.md การเก็บสำเนาที่สมบูรณ์สองชุดแยกกันจะทำให้ข้อมูลไม่ตรงกันภายในเวลาไม่ถึงหนึ่งเดือน

การเขียน AGENTS.md รับประกันได้หรือไม่ว่าเอเจนต์จะปฏิบัติตาม?

ไม่ การเขียน AGENTS.md ไม่ได้รับประกัน เพราะเนื้อหาจะถูกส่งไปในรูปแบบบริบท (context) ซึ่งโมเดลจะอ่านและปฏิบัติตามโดยทั่วไป แต่ไม่มีกลไกใดที่ขัดขวางการกระทำที่ขัดแย้งกับเนื้อหาดังกล่าว คำสั่งที่คลุมเครือมักจะถูกปฏิบัติตามได้น้อยที่สุด และหากมีสองไฟล์ที่ให้คำแนะนำที่ขัดแย้งกัน เอเจนต์จะเลือกทำตามไฟล์ใดไฟล์หนึ่งโดยสุ่ม สำหรับกฎที่ต้องบังคับใช้ทุกครั้ง ให้ใช้ hook หรือกฎการอนุญาต (permission rule) ซึ่งไคลเอนต์จะบังคับใช้โดยไม่ขึ้นอยู่กับการตัดสินใจของโมเดล

ควร commit ไฟล์ AGENTS.md ลงใน git หรือไม่?

ควรทำ สำหรับข้อมูลที่เป็นจริงเกี่ยวกับโปรเจกต์ เช่น คำสั่ง build, โครงสร้างไฟล์ หรือข้อตกลงในการทำงาน นี่คือจุดประสงค์หลักของไฟล์ดังกล่าว เพื่อให้เอเจนต์ของเพื่อนร่วมทีมเริ่มต้นด้วยบริบทเดียวกันกับคุณ ส่วนข้อมูลที่เป็นเรื่องส่วนตัวหรือเฉพาะเจาะจงกับเครื่องใดเครื่องหนึ่ง ควรเก็บไว้ในไฟล์แยกต่างหากที่ตั้งค่า gitignore ไว้ และห้ามเก็บข้อมูลรับรอง (credentials) ไว้ในไฟล์เหล่านี้โดยเด็ดขาด

HUMAN.md คืออะไรและฉันจำเป็นต้องมีหรือไม่?

HUMAN.md คือโปรไฟล์ของบุคคลในรูปแบบที่เครื่องอ่านได้ แทนที่จะเป็นโปรไฟล์ของโปรเจกต์ โดยจะเก็บข้อมูลบทบาทของคุณ ข้อจำกัด และการตัดสินใจที่คุณได้ตกลงไว้แล้ว เพื่อไม่ให้ต้องกลับมาถกเถียงกันใหม่ในทุกเซสชัน คุณไม่จำเป็นต้องใช้เครื่องมือใดๆ ในการเริ่มต้น เพียงแค่เขียนข้อความประมาณ 20 บรรทัดลงในไฟล์คำสั่งระดับผู้ใช้ (user-level instructions) ก็จะได้รับประโยชน์ส่วนใหญ่แล้ว ให้ถือว่าไฟล์นี้เป็นข้อมูลส่วนบุคคลและเก็บไว้ภายนอก repository ใดๆ ที่คุณ push ขึ้นไป