AGENTS.md และ HUMAN.md คืออะไร พร้อมวิธีเขียน

AGENTS.md คืออะไร

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

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

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

ตำแหน่งที่วางไฟล์และไฟล์ใดมีผลเหนือกว่า

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

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 หากวางไว้ในไฟล์ที่ราก กฎจะถูกโหลดในทุกงานที่ไม่เกี่ยวข้องและไม่ก่อประโยชน์ใด ๆ

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

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

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

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

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

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

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

CLAUDE.md คือแนวคิดเดียวกันในรูปแบบของ Claude Code

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

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

@AGENTS.md

## Claude Code

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

หากไม่มีเนื้อหาเพิ่มเติมที่ต้องเพิ่ม ให้ใช้ symlink ได้:

ln -s AGENTS.md CLAUDE.md

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

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

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

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

โครงการ 2 โครงการในรายการ GitHub trending เมื่อวันที่ 30 July 2026 แสดงให้เห็นว่าแนวทางนี้กำลังมุ่งไปทางใด

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

Initialize DOX tree for this project now.

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

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

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

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

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

ข้อควรระวังประการหนึ่ง HUMAN.md เป็นโปรไฟล์ของบุคคล จึงเป็นข้อมูลละเอียดอ่อนโดยนิยาม อย่าเก็บไฟล์นี้ไว้ใน repository สาธารณะ ให้เก็บไว้ใน ~/.claude/CLAUDE.md หรือใน CLAUDE.local.md ที่ถูก gitignore ซึ่งอยู่ที่รากของโครงการ ไฟล์นี้จะถูกโหลดพร้อมกับไฟล์ที่ 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.

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

FAQ

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

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

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

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

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

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

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

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