AGENTS.md: ไฟล์บริบทเดียวสำหรับทุกเอเจนต์การเขียนโค้ด (Codex, Antigravity, Claude)

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

AGENTS.md คือคำตอบสำหรับความยุ่งเหยิงนั้น: ไฟล์ Markdown ธรรมดาไฟล์หนึ่งที่อยู่ที่รากของ repo ของคุณ ซึ่งเอเจนต์การเขียนโค้ดใด ๆ จะอ่านก่อนที่มันจะสัมผัสโค้ดของคุณ

AGENTS.md คืออะไร

ไม่มีเวทมนตร์ มันคือไฟล์ Markdown ที่ชื่อว่า AGENTS.md ซึ่งมักจะอยู่ที่รากของ repository ที่เอเจนต์โหลดเป็นคำแนะนำก่อนที่จะเริ่มทำงาน คิดว่ามันเป็น README ที่คุณเขียนให้กับเพื่อนร่วมทีม AI ของคุณแทนที่จะเป็นเพื่อนร่วมทีมมนุษย์: โครงการคืออะไร, วิธีการสร้างและทดสอบ, ข้อกำหนดที่ต้องเคารพ และกับดักที่ต้องหลีกเลี่ยง

มันเป็นข้อตกลงที่เปิดกว้าง ซึ่ง Codex และเครื่องมือของเอเจนต์ที่เพิ่มขึ้นเรื่อย ๆ ได้อ่าน โดยมีเป้าหมายที่ชัดเจนในการพกพาข้ามเครื่องมือเหล่านั้น ไฟล์เดียว หลายเอเจนต์ แทนที่จะเป็นไฟล์ที่ปรับแต่งเฉพาะสำหรับแต่ละเครื่องมือ

AGENTS.md vs CLAUDE.md vs GEMINI.md

ตอนที่เขียนคู่มือนี้ครั้งแรก แต่ละเครื่องมือมองหาไฟล์ของตัวเอง ตั้งแต่นั้นมา เครื่องมือส่วนใหญ่ได้หันมาใช้ AGENTS.md ร่วมกัน:

• Codex อ่าน AGENTS.md เช่นเดียวกับ GitHub Copilot CLI, Cursor, Amp และเอเจนต์ CLI รุ่นใหม่ส่วนใหญ่
• Claude Code อ่าน CLAUDE.md และตั้งแต่เวอร์ชัน 2.1.277 มันยังอ่าน AGENTS.md เองด้วย เมื่อไดเรกทอรีทำงานของคุณและไดเรกทอรีที่อยู่สูงกว่าไม่มี CLAUDE.md หรือ CLAUDE.local.md เมื่อมี CLAUDE.md อยู่ Claude จะอ่านเฉพาะไฟล์นั้น เว้นแต่คุณเปลี่ยนการตั้งค่า Project instructions ใน /config
• Antigravity CLI อ่าน AGENTS.md หรือ GEMINI.md ที่รากของ repository หรือในไดเรกทอรีย่อยใดก็ได้ รวมถึงโฟลเดอร์ .agents/rules/ และกฎส่วนกลางใน ~/.gemini/

เนื้อหานั้นเกือบจะเหมือนกันในทั้งสาม: บริบทของโครงการ, คำสั่ง, ข้อกำหนด สิ่งที่ยังแตกต่างกันคือไฟล์ที่เครื่องมือเลือกใช้เมื่อมีหลายไฟล์อยู่พร้อมกัน นั่นคือเหตุผลที่การทำซ้ำกฎเดียวกันในสามไฟล์ด้วยมือเป็นเกมที่แพ้ (เพิ่มเติมเกี่ยวกับการทำให้มันซิงค์ด้านล่าง) เราได้ตรวจสอบพฤติกรรมเหล่านี้เมื่อวันที่ 10 ตุลาคม 2026 โดยเทียบกับเอกสารเรื่องหน่วยความจำ (memory) ของ Claude Code และเอกสารเรื่องกฎ (rules) ของ Antigravity

หากคุณทำงานส่วนใหญ่ใน Claude Code คู่มือ CLAUDE.md ของเราจะเจาะลึกในโครงสร้างเฉพาะของ Claude AGENTS.md คือพี่น้องที่เป็นกลางของไฟล์นั้น

สิ่งที่ควรใส่ในนั้น

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

• เทคโนโลยีในหนึ่งลมหายใจ "Next.js 16, TypeScript, Prisma, MariaDB" ไม่มีประวัติ ไม่มีการตลาด
• คำสั่งที่สำคัญ วิธีการติดตั้ง รัน สร้าง ทดสอบ และ lint คำสั่งที่แน่นอน: npm test ไม่ใช่ "รันการทดสอบ"
• ข้อกำหนด การตั้งชื่อ การจัดเรียงไฟล์ การจัดการข้อผิดพลาด รูปแบบที่คุณบังคับใช้จริงในการตรวจสอบ
• แผนที่ไดเรกทอรี สองบรรทัดเกี่ยวกับที่ตั้งของสิ่งต่าง ๆ เพื่อให้เอเจนต์หยุดการค้นหาแบบสุ่ม
• กฎการอ่านก่อนสัมผัส "อ่าน docs/payments.md ก่อนแก้ไขสิ่งใดภายใต้ billing/" นิสัยเดียวนี้ช่วยป้องกันความเสียหายได้มาก
• สิ่งที่ไม่ควรทำอย่างเด็ดขาด "อย่าสร้างสาขาโดยไม่ได้รับการขอร้อง" "ไม่มีเส้นทางเครื่องจักรที่แน่นอนในไฟล์ที่ถูกคอมมิท"

ความผิดพลาดที่ทำให้เอเจนต์ไม่สนใจ

ไฟล์บริบทล้มเหลวอย่างเงียบ ๆ เอเจนต์ไม่แสดงข้อผิดพลาด มันแค่ค่อย ๆ เบี่ยงเบนไป สาเหตุทั่วไป:

1. ยาวเกินไป ไฟล์ 600 บรรทัดฝังห้ากฎที่สำคัญ ตัดสิ่งใดที่เอเจนต์สามารถอนุมานจากโค้ดเอง
2. ความขัดแย้ง "เขียนการทดสอบเสมอ" ในส่วนหนึ่ง "ข้ามการทดสอบสำหรับต้นแบบ" ในอีกส่วนหนึ่ง เอเจนต์เลือกหนึ่งแบบสุ่ม
3. เส้นทางเฉพาะเครื่อง /Users/you/project/... ในไฟล์ที่ถูกคอมมิททำให้เกิดปัญหาสำหรับเพื่อนร่วมทีมทุกคน และสำหรับเอเจนต์ทุกตัวในเครื่องอื่น ๆ เก็บเส้นทางให้สัมพันธ์
4. คำสั่งที่ล้าสมัย คำสั่งทดสอบเปลี่ยนไปเมื่อหกเดือนที่แล้ว ไฟล์ไม่เปลี่ยน ตอนนี้เอเจนต์รันสิ่งที่ผิดด้วยความมั่นใจเต็มที่
5. ไม่มีลำดับความสำคัญ ทุกอย่างคือ "สำคัญ" ดังนั้นไม่มีอะไรเลย วางสิ่งที่ไม่สามารถเจรจาได้ไว้ข้างหน้าและติดป้ายกำกับ
6. การทิ้งเอกสาร นี่คือคำแนะนำ ไม่ใช่วิกิ ลิงก์ไปยังเอกสารของคุณ อย่าคัดลอกไปในนั้น

การรักษาบริบทเดียวกันข้ามผู้ให้บริการ

นี่คือส่วนที่มีประโยชน์ซึ่งคู่มือส่วนใหญ่ข้ามไป หากคุณหรือทีมของคุณใช้เอเจนต์ CLI มากกว่าหนึ่งตัว คุณไม่ต้องการสำเนาสามชุดของกฎเดียวกันที่ค่อย ๆ เพี้ยนไปจากกัน

สองวิธีที่สะอาด:

• AGENTS.md ไฟล์เดียว ไม่มีอย่างอื่น หากไม่มีใครต้องการกฎที่ใช้กับ Claude เท่านั้น ให้เก็บ AGENTS.md ไว้ไฟล์เดียว: Codex, Antigravity CLI และ Claude Code 2.1.277 ขึ้นไปล้วนอ่านไฟล์นี้ ข้อควรระวังคือปัญหาจะเกิดขึ้นอย่างเงียบ ๆ: CLAUDE.md หรือ CLAUDE.local.md ส่วนตัวที่เพิ่มเข้ามาภายหลัง จะทำให้ Claude Code หยุดอ่าน AGENTS.md
• ไฟล์มาตรฐานไฟล์เดียว การนำเข้าหนึ่งครั้ง เก็บทุกอย่างใน AGENTS.md และเริ่ม CLAUDE.md ด้วยบรรทัด @AGENTS.md จากนั้นเขียนกฎเฉพาะของ Claude ไว้ด้านล่าง Claude จะอ่านไฟล์ที่นำเข้าก่อน repository ของเราเองก็ทำงานแบบนี้: CLAUDE.md ของเรามีเพียงบรรทัดเดียวนั้น ลิงก์สัญลักษณ์ (ln -s AGENTS.md CLAUDE.md) ก็ใช้ได้เช่นกัน แต่ใช้ได้ไม่ดีบน Windows ซึ่งการสร้างลิงก์สัญลักษณ์ต้องใช้สิทธิ์ผู้ดูแลระบบหรือโหมดนักพัฒนา และ clone ที่ไม่มี core.symlinks จะได้ไฟล์ข้อความหนึ่งบรรทัดแทนคำแนะนำของคุณ

ไม่ว่าจะด้วยวิธีใดก็ตาม กฎคือเขียนบริบทเพียงครั้งเดียว ไม่ใช่ครั้งต่อผู้ให้บริการ นั่นคือวิธีเดียวที่จะทำให้มันถูกต้อง เพราะไฟล์เดียวคือไฟล์เดียวที่ผู้คนดูแลจริง ๆ

เมื่อคุณรันหลายเอเจนต์พร้อมกัน

AGENTS.md ระดับ repo ตอบคำถาม "โครงการนี้คืออะไร" มันไม่ตอบคำถาม "เอเจนต์นี้คือใคร" เมื่อคุณรันเอเจนต์ Backend, เอเจนต์ Frontend และเอเจนต์ QA พร้อมกันในโค้ดเดียวกัน แต่ละตัวต้องการบริบทโครงการที่ใช้ร่วมกันบวกกับบทบาทของตัวเอง

นั่นคือชั้นที่ AgentsRoom เพิ่มขึ้นบน AGENTS.md เอเจนต์แต่ละตัวจะได้รับ บทบาทเฉพาะ พร้อมกับคำสั่งระบบของตัวเอง (DevOps, Frontend, Security และอื่น ๆ) ดังนั้นไฟล์ที่ใช้ร่วมกันจึงยังคงเบาในขณะที่เอเจนต์แต่ละตัวยังคงรู้หน้าที่ของตน มันถูกออกแบบมาให้ ไม่ขึ้นกับผู้ให้บริการ ดังนั้นการตั้งค่าเดียวกันจึงรัน Claude, Codex หรือ Antigravity ข้างกัน และคำแนะนำที่คุณทำซ้ำจะอยู่ใน Prompt Library แทนที่จะต้องพิมพ์ใหม่ในทุกเซสชัน

เมื่อคุณถึงจุดนั้น วิธีการ รันหลายเอเจนต์พร้อมกันโดยไม่สูญเสียการติดตาม คือการอ่านถัดไปที่เป็นธรรมชาติ

สิ่งที่ต้องจำ

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

ต้องการให้เอเจนต์ทุกตัวอยู่บนหน้าจอเดียว โดยแต่ละตัวมีบทบาทของตัวเองและบริบทที่ใช้ร่วมกันของคุณ? ดาวน์โหลด AgentsRoom, เชื่อมต่อผู้ให้บริการของคุณ และทำให้เรือของคุณทำงาน

คำถามที่พบบ่อย

ไฟล์ AGENTS.md คืออะไร?

ไฟล์ Markdown ที่มักอยู่ที่รากของ repository ซึ่งเอเจนต์การเขียนโค้ดโหลดเป็นคำแนะนำถาวรก่อนเริ่มทำงาน: โครงการคืออะไร, วิธีการสร้างและทดสอบ, ข้อกำหนดที่ต้องเคารพ และกับดักที่ต้องหลีกเลี่ยง มันเป็นข้อตกลงเปิดที่ใช้ร่วมกันระหว่างเครื่องมือต่าง ๆ ไม่ใช่ไฟล์ของเครื่องมือใดเครื่องมือหนึ่ง และถูกอ่านโดย Codex, Antigravity CLI, GitHub Copilot CLI, Cursor, Amp และ Claude Code ตั้งแต่เวอร์ชัน 2.1.277

Claude Code อ่าน AGENTS.md หรือไม่?

อ่าน ตั้งแต่ Claude Code 2.1.277 แต่เฉพาะเมื่อไม่มี CLAUDE.md, .claude/CLAUDE.md หรือ CLAUDE.local.md ในไดเรกทอรีทำงานของคุณหรือไดเรกทอรีที่อยู่สูงกว่า จากนั้นมันจะโหลด AGENTS.md ทุกไฟล์ตั้งแต่ไดเรกทอรีทำงานไล่ขึ้นไปด้านบน และโหลด AGENTS.md ของไดเรกทอรีย่อยเมื่อมันเปิดไฟล์ในไดเรกทอรีนั้น หากมี CLAUDE.md อยู่ Claude จะอ่านเฉพาะไฟล์นั้น เว้นแต่คุณตั้งค่า Project instructions เป็น claude-md-and-agents-md ใน /config สำหรับเวอร์ชันที่เก่ากว่า ให้ใส่บรรทัด @AGENTS.md ไว้ที่ด้านบนสุดของ CLAUDE.md

Antigravity ใช้ AGENTS.md หรือ GEMINI.md?

ทั้งสองอย่าง Antigravity อ่าน AGENTS.md, GEMINI.md หรือโฟลเดอร์ .agents/rules/ ที่รากของ repository หรือในไดเรกทอรีย่อยใดก็ได้ รวมถึงกฎส่วนกลางจาก ~/.gemini/ กฎต่าง ๆ จะเสริมกันแทนที่จะเขียนทับกัน และเมื่อกฎสองข้อขัดแย้งกัน กฎของไดเรกทอรีที่เจาะจงกว่าจะเป็นฝ่ายชนะ

ควรเก็บ AGENTS.md หรือ CLAUDE.md?

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

ควรวาง AGENTS.md ไว้ที่ไหน?

ที่รากของ repository สำหรับกฎที่ใช้ได้ทุกที่ Claude Code และ Antigravity ยังอ่านไฟล์ AGENTS.md ในไดเรกทอรีย่อยด้วย ดังนั้นแพ็กเกจหรือเซอร์วิสที่มีคำสั่งของตัวเองจึงมีไฟล์ของตัวเองได้ ซึ่งจะถูกอ่านเมื่อเอเจนต์ทำงานในโฟลเดอร์นั้น