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, เชื่อมต่อผู้ให้บริการของคุณ และทำให้เรือของคุณทำงาน