AGENTS.md คืออะไร? วิธีเขียนไฟล์คำสั่งสำหรับ AI Coding

AGENTS.md คืออะไร

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

เหตุผลที่ convention นี้เกิดขึ้นนั้นเป็นเรื่องของการใช้งานจริง สมาชิกใหม่ในทีมของคุณจะอ่าน 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

ให้ระบุข้อมูลที่ 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 ตัดสินใจเอง มันมักจะแก้ไขโค้ดมากกว่าที่คุณร้องขอ: ทักษะที่ถูกนำไปใช้กันอย่างแพร่หลายคือการยืนกรานให้แก้ไขเฉพาะจุดที่จำเป็นและเล็กที่สุดที่ใช้งานได้จริง

สิ่งที่ห้ามใส่ไว้ในไฟล์

ห้ามใส่ข้อมูลลับไว้ในไฟล์เหล่านี้เด็ดขาด เนื่องจากไฟล์จะถูก commit ลง git, ถูกโหลดเข้าสู่ context ในทุกเซสชัน และถูกส่งไปยังผู้ให้บริการโมเดลในทุกคำขอ การใส่ API key ไว้ใน AGENTS.md เท่ากับเป็นการทิ้ง API key ไว้ในประวัติของ repository และใน log ของบุคคลที่สาม ให้ใช้วิธีอ้างอิงถึงข้อมูลลับแทนการคัดลอกมาวาง เช่น "รหัสผ่านฐานข้อมูลอยู่ใน .env ซึ่งถูก gitignore ไว้แล้ว ให้ถามก่อนที่จะอ่าน" รายละเอียดเกี่ยวกับแนวทางปฏิบัติที่กว้างขึ้นครอบคลุมอยู่ใน การเก็บข้อมูลรับรองให้พ้นจากมือของ agent

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

CLAUDE.md คือแนวคิดเดียวกันสำหรับ Claude Code

Claude Code จะอ่าน CLAUDE.md และไม่ได้อ่าน AGENTS.md โดยอัตโนมัติ ไฟล์โปรเจกต์จะอยู่ที่ ./CLAUDE.md หรือ ./.claude/CLAUDE.md, การตั้งค่าส่วนบุคคลสำหรับทุกโปรเจกต์จะอยู่ใน ~/.claude/CLAUDE.md และองค์กรสามารถผลักไฟล์ระดับเครื่องไปที่ /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 มากขึ้นและทำให้ประสิทธิภาพในการปฏิบัติตามกฎลดลง หากคุณต้องการทราบว่ามีอะไรอื่นที่แย่งพื้นที่นั้นอยู่ สิ่งที่เติมเต็มหน้าต่าง context ของ agent จะอธิบายรายละเอียดไว้

มีประเด็นหนึ่งที่ควรเน้นย้ำ AGENTS.md เป็นเพียงคำแนะนำ ไม่ใช่ระบบการอนุญาต เนื้อหาจะถูกส่งไปเป็น context ปกติ ดังนั้นโมเดลจะอ่านและปฏิบัติตามเป็นส่วนใหญ่ แต่ไม่มีสิ่งใดขัดขวางการกระทำที่ขัดต่อกฎได้ เมื่อกฎที่คุณเขียนถูกข้ามไปโดยเงียบๆ และคุณไม่ทราบสาเหตุ ให้ตรวจสอบผ่าน สาเหตุที่คำสั่งถูกละเลย ก่อนที่จะเขียนคำสั่งใหม่เป็นครั้งที่สาม สำหรับกฎที่ต้องปฏิบัติตามทุกครั้ง เช่น "ห้าม 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 รับประกันได้หรือไม่ว่าเอเจนต์จะปฏิบัติตาม?

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

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

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

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

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