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

ตอนนี้ภูมิทัศน์ถูกแบ่งตามเครื่องมือ:

• CLAUDE.md คือสิ่งที่ Claude Code มองหา
• GEMINI.md คือข้อตกลงของ Antigravity CLI
• AGENTS.md คือมาตรฐานข้ามเครื่องมือที่ Codex และคนอื่น ๆ อ่าน ออกแบบมาให้เป็นกลาง

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

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

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

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

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

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

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

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

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

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