วิธีเขียนไฟล์ AGENTS.md สำหรับเอเจนต์เขียนโค้ด

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

คู่มือนี้อธิบายว่าควรใส่อะไร พร้อมเทมเพลต วิธีที่ Claude Code และ Gemini CLI หาไฟล์ และการทดสอบสั้น ๆ ขั้นตอนเดียวกันใช้ได้เมื่อคุณเริ่มเอเจนต์จากโทรศัพท์ด้วย Mono by Reunified

1. ตัดสินใจว่าอะไรควรอยู่ในไฟล์

เว็บไซต์ agents.md เรียกไฟล์นี้ว่า README สำหรับเอเจนต์ ใส่ข้อเท็จจริงที่ทุกเซสชันต้องรู้ และข้ามสิ่งที่เอเจนต์เรียนรู้ได้จากโค้ดเอง

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

2. เริ่มจากเทมเพลตสั้น ๆ

นี่คือตัวอย่างสมมติสำหรับ “tidy-recipes” เว็บแอป TypeScript ที่ใช้ pnpm:

# AGENTS.md

## Overview
TypeScript web app for saving recipes. Components live in src/components.

## Setup
- `pnpm install`

## Test and lint
- `pnpm test` and `pnpm lint`

## Code style
- TypeScript only. One component per file.

## Boundaries
- Never edit db/migrations/.
- Ask before adding a dependency.

## Before you finish
- Run `pnpm test` and `pnpm lint`.
- List the files you changed and the test results.

ใส่เฉพาะคำสั่งที่คุณเคยรันในรีโพซิทอรีนี้แล้ว เพราะถ้าคำสั่งผิด เอเจนต์ก็จะเชื่อตามนั้น

3. เขียนกฎที่ตรวจสอบได้

กฎที่ดีช่วยให้คุณตรวจภายหลังได้ว่าเอเจนต์ทำตามหรือไม่

เขียนขอบเขตเป็นกฎแบบ “ห้าม” และ “ถามก่อน” บรรทัดละหนึ่งข้อ

4. ทำให้ Claude Code และ Gemini CLI อ่านไฟล์

เว็บไซต์ agents.md แสดงรายชื่อ Codex, Gemini CLI, opencode และเอเจนต์อื่นที่รองรับรูปแบบนี้ แต่บางตัวต้องตั้งค่าก่อน

โดยค่าเริ่มต้น Claude Code เวอร์ชันใหม่ ๆ จะอ่าน AGENTS.md ก็ต่อเมื่อไม่มี CLAUDE.md, .claude/CLAUDE.md หรือ CLAUDE.local.md ในไดเรกทอรีที่ทำงานอยู่หรือไดเรกทอรีที่อยู่เหนือขึ้นไป (ดูเอกสาร memory) ถ้าคุณมีไฟล์ใดไฟล์หนึ่งในนั้น หรือใช้เวอร์ชันเก่ากว่า ให้ import AGENTS.md จาก CLAUDE.md โปรเจกต์ tidy-recipes มี CLAUDE.md เก่าอยู่ จึงให้เพิ่มบรรทัดนี้ไว้บนสุด แล้วเก็บโน้ตที่ใช้กับ Claude เท่านั้นไว้ด้านล่าง:

@AGENTS.md

Prefer small commits.

เริ่มเซสชันใหม่ รัน /context แล้วตรวจว่า CLAUDE.md อยู่ใต้หัวข้อ Memory files ถ้าไม่มี CLAUDE.md คำสั่ง /memory จะแสดงพาธของ AGENTS.md แทน

Gemini CLI อ่าน GEMINI.md โดยค่าเริ่มต้น หากต้องการเพิ่ม AGENTS.md ให้ใส่ค่านี้ใน .gemini/settings.json ของโปรเจกต์ (ดูเอกสาร GEMINI.md):

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

เริ่มเซสชันใหม่ แล้วรัน /memory show เพื่อดูว่าโหลดอะไรมาบ้าง สำหรับเอเจนต์อื่น ให้ตรวจเอกสารของเอเจนต์นั้น

5. ทดสอบไฟล์ด้วยงานเล็ก ๆ

ในเซสชันใหม่ ให้งานนี้กับเอเจนต์:

ก่อนอื่น ให้แสดงรายการกฎของโปรเจกต์ที่คุณโหลดมา และไฟล์ที่กฎแต่ละข้อมาจาก จากนั้นเปลี่ยนข้อความบนปุ่ม “Save recipe” เป็น “Save” ใน src/components/SaveButton.tsx ห้ามเปลี่ยนอย่างอื่น

ตรวจผลลัพธ์เทียบกับไฟล์:

• เอเจนต์ระบุชื่อ AGENTS.md (หรือ CLAUDE.md ที่มีการ import)
• เอเจนต์รัน pnpm test และ pnpm lint แล้วรายงานผล
• เอเจนต์ไม่แตะ db/migrations/ และไม่เพิ่ม dependency
• เอเจนต์ระบุไฟล์ที่เปลี่ยน

ตรวจการแก้ไขด้วยตัวเองโดยใช้ git diff (ดูการตรวจโค้ดที่ AI แก้) ถ้าเอเจนต์บอกกฎไม่ได้ แสดงว่าไฟล์น่าจะไม่ได้โหลด ให้กลับไปที่ขั้นตอนที่ 4 ถ้าบอกกฎได้แต่ไม่ทำตาม ให้เขียนกฎนั้นให้ชัดเจนขึ้น

6. รักษาไฟล์ให้สั้นและเป็นปัจจุบัน

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

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

ไฟล์นี้ชี้แนะเอเจนต์ แต่ไม่ได้บังคับอะไร หากต้องการกันไม่ให้เกิดการกระทำใด ให้ใช้การตั้งค่าสิทธิ์ของเอเจนต์ หรือปฏิเสธคำขอ (ดูคู่มือสิทธิ์ของเครื่องมือ)

ใน Mono เอเจนต์เริ่มทำงานในไดเรกทอรีของโปรเจกต์บนคอมพิวเตอร์ของคุณ ซึ่งเป็นที่ที่เอเจนต์มองหาไฟล์เหล่านี้ คุณเปิด AGENTS.md, CLAUDE.md หรือ .gemini/settings.json ในตัวแก้ไขของ Mono ได้ จากโทรศัพท์ก็ได้ และการแก้ไขจะบันทึกเองอัตโนมัติ หากต้องการสร้างไฟล์ ให้ขอให้เอเจนต์สร้าง หรือเปิดเทอร์มินัลจากการ์ดโปรเจกต์ Mono ไม่ได้ตรวจไฟล์ และไม่ได้เปลี่ยนว่าเอเจนต์จะโหลดไฟล์ไหน Mono ยังไม่เปิดให้ใช้ แต่คุณเข้าร่วมรายชื่อรอได้