Claude Code รองรับ AGENTS.md แล้ว: วิธีใช้งานร่วมกับ CLAUDE.md

Claude Code รองรับ AGENTS.md เข้ามาในเวอร์ชัน v2.1.277: ในโปรเจกต์ที่ไม่มี CLAUDE.md Claude Code จะอ่าน AGENTS.md ของคุณเป็นคำแนะนำระดับโปรเจกต์แทน โดยไม่ต้องใช้ import, symlink หรือการตั้งค่าใด ๆ หาก repo ของคุณมีทั้งสองไฟล์ Claude จะอ่านเฉพาะ CLAUDE.md เท่านั้น เว้นแต่คุณจะเปลี่ยนการตั้งค่า Project instructions ใน /config ให้โหลดทั้งสองไฟล์

หากทีมของคุณใช้ coding agent หลายตัว AGENTS.md ไฟล์เดียวกันที่ Codex และ Cursor อ่านอยู่แล้ว ตอนนี้ยังควบคุมพฤติกรรมของ Claude Code ได้ด้วย บทความนี้จะครอบคลุมเรื่องลำดับความสำคัญ วิธีการย้ายระบบ (migration) และตัวอย่าง AGENTS.md ที่สอน agent ให้ทดสอบ API ของคุณด้วย Apidog CLI

AGENTS.md ใน Claude Code คืออะไร?

AGENTS.md คือไฟล์ Markdown ธรรมดาที่เขียนคำแนะนำสำหรับ coding agent เช่น คำสั่ง build, คำสั่ง test, โค้ดสไตล์ และกฎต่าง ๆ ของโปรเจกต์ ตั้งแต่เวอร์ชัน v2.1.277 เป็นต้นมา Claude Code อ่านไฟล์นี้ผ่าน built-in plugin ดังนั้น repository ที่ตั้งค่าไว้สำหรับ agent ตัวอื่นจะใช้กับ Claude Code ได้ทันทีโดยไม่ต้องเพิ่มไฟล์ใด ๆ ไฟล์นี้ไม่ต้องมีฟิลด์บังคับหรือไวยากรณ์พิเศษใด ๆ

รูปแบบนี้เป็นแบบเปิด (open format) เว็บไซต์ AGENTS.md อธิบายไว้ว่าเป็น "รูปแบบแบบเปิดที่เรียบง่ายสำหรับกำกับ coding agent" ซึ่งถูกใช้ในโปรเจกต์ open-source มากกว่า 60,000 โปรเจกต์ และตอนนี้อยู่ภายใต้การดูแลของ Agentic AI Foundation ในสังกัด Linux Foundation ทั้ง OpenAI Codex และ Cursor ต่างจัดทำเอกสารรองรับ AGENTS.md แล้ว โดยที่ Claude Code เป็นตัวสำคัญที่ยังไม่รองรับ จนกระทั่งรุ่นนี้

หากคุณยังไม่คุ้นเคยกับรูปแบบนี้ เริ่มต้นได้จากบทความ วิธีเขียนไฟล์ AGENTS.md สำหรับทีมพัฒนา API

นี่คือประวัติการเปลี่ยนแปลงในแต่ละเวอร์ชัน จาก changelog อย่างเป็นทางการของ Claude Code:

รัน claude --version ก่อนที่จะเชื่อถือฟีเจอร์เหล่านี้ ในเวอร์ชันที่เก่ากว่า 2.1.277 Claude Code จะอ่านเฉพาะไฟล์ CLAUDE.md เท่านั้น

CLAUDE.md กับ AGENTS.md: อันไหนมีความสำคัญกว่า?

ตามค่าเริ่มต้น CLAUDE.md จะมีความสำคัญกว่า Claude Code จะอ่าน AGENTS.md ก็ต่อเมื่อไม่มี CLAUDE.md อยู่ใน working directory ของคุณหรือใน directory ระดับสูงกว่าใด ๆ เอกสารเกี่ยวกับ memory ของ Claude Code ระบุกรณีไว้ 3 กรณี:

ไม่ใช่ทุกไฟล์จะนับในการตรวจสอบนี้ ไฟล์สามไฟล์นี้จะบล็อก AGENTS.md:

• CLAUDE.md ใน working directory หรือ directory ระดับสูงกว่า
• .claude/CLAUDE.md ใน working directory หรือ directory ระดับสูงกว่า
• CLAUDE.local.md ใน working directory หรือ directory ระดับสูงกว่า

ส่วนไฟล์เหล่านี้ไม่บล็อก และยังคงถูกโหลดควบคู่กับ AGENTS.md: ไฟล์ user ของคุณที่ ~/.claude/CLAUDE.md ไฟล์ CLAUDE.md ที่องค์กรจัดการ และไฟล์ต่าง ๆ ใน .claude/rules/

ระวังกับดักของ CLAUDE.local.md: หากคุณสร้างไฟล์นี้ไว้ส่วนตัวเพื่อจดโน้ตที่ไม่ commit ขึ้นมา Claude จะหยุดอ่าน AGENTS.md ของทีมสำหรับคุณทันที

Claude Code โหลดอะไร และเมื่อไร

เมื่อไม่มีอะไรบล็อก Claude Code จะอ่าน:

1. ตอนเริ่มเซสชัน: ทุก AGENTS.md และ .claude/AGENTS.md ใน working directory และ directory ระดับสูงกว่าทั้งหมด เซสชันแบบ interactive จะพิมพ์ข้อความลักษณะนี้ออกมา เช่น no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md
2. ใน subdirectory: ไฟล์ AGENTS.md ของ subdirectory นั้น จะถูกอ่านเมื่อ Claude เปิดไฟล์ในโฟลเดอร์นั้นด้วย Read tool และโฟลเดอร์ดังกล่าวไม่มี CLAUDE.md ของตัวเอง
3. Import: import แบบ @path ที่อยู่ภายใน AGENTS.md จะถูกขยายออก และ pattern ของ claudeMdExcludes ก็จะถูกนำไปใช้ด้วย

Claude Code ไม่อ่าน AGENTS.local.md, AGENTS.override.md หรือไฟล์ใด ๆ ภายใต้ .agents/ หากคุณแชร์ repo กับผู้ใช้ Codex ซึ่งมีเอกสารรองรับ AGENTS.override.md โปรดคำนึงถึงเรื่องนี้ด้วย

วิธีเปลี่ยนว่า Claude Code จะโหลดไฟล์คำแนะนำแบบใด

พิมพ์ /config ในเซสชัน แล้วตั้งค่า Project instructions เป็นค่าใดค่าหนึ่งจากสี่ค่านี้:

สำหรับทีมส่วนใหญ่ที่ใช้ agent หลายตัว claude-md-and-agents-md คือค่าที่คุณต้องการ เพราะช่วยให้ CLAUDE.local.md ส่วนตัวของคุณยังทำงาน และยังโหลด AGENTS.md ที่แชร์ร่วมกันได้ด้วย

คุณตั้งค่าผ่านไฟล์ settings แทนได้เช่นกัน Claude Code อ่านค่านี้จาก ~/.claude/settings.json, ไฟล์ --settings หรือ managed settings และจะเมินค่านี้ในไฟล์ settings ระดับโปรเจกต์และ local:

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

ก่อนเวอร์ชัน v2.1.285 plugin ID คือ agents-md@builtin เวอร์ชันตั้งแต่ 2.1.285 เป็นต้นไปจะอ่านได้ทั้งสอง ID ดังนั้นใช้ ID เดิมหากมีเครื่องที่ติดตั้งเวอร์ชันเก่าแชร์ไฟล์เดียวกัน การเปลี่ยนแปลงนี้จะมีผลตั้งแต่ข้อความถัดไปของคุณ

หาก Project instructions ไม่ปรากฏใน /config เซสชันของคุณจะโหลด AGENTS.md ไม่ได้: ทั้งนี้เพราะคุณใช้เวอร์ชันก่อน 2.1.277, คุณปิดใช้งาน built-in plugin ผ่าน /plugin หรือนี่เป็นเซสชันแรกหลังอัปเกรด (จะใช้ได้ตั้งแต่เซสชันถัดไป)

วิธีย้ายจากวิธีแก้ปัญหา AGENTS.md แบบเดิม

หลายทีมเชื่อม AGENTS.md เข้ากับ Claude Code ด้วยตนเองก่อนรุ่นนี้ออกมา เอกสารแนะนำวิธีจัดการดังนี้:

เก็บ import แบบ @AGENTS.md เอาไว้หากยังมีคนในทีมที่ใช้เวอร์ชันเก่ากว่า 2.1.277 อยู่ นี่คือรูปแบบเดียวที่ใช้งานได้กับทุกเวอร์ชัน

เลือก import หรือ symlink?

หากคุณต้องการกฎเฉพาะของ Claude เพิ่มเติมจากไฟล์ที่แชร์ร่วมกัน ให้ใช้ import โดย Claude จะอ่านไฟล์ที่ import มาก่อน แล้วจึงอ่านส่วนที่เหลือ:

@AGENTS.md

## Claude Code

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

หากไม่ต้องการอะไรที่เฉพาะกับ Claude symlink ก็ใช้ได้:

ln -s AGENTS.md CLAUDE.md

มีข้อควรระวังสองข้อ: เครื่องมือ Edit และ Write ของ Claude ไม่สามารถเขียนผ่าน symlink ได้ และ Git บน Windows จะ checkout symlink ที่ถูก commit เป็นไฟล์ข้อความบรรทัดเดียว เว้นแต่จะเปิดใช้ core.symlinks หากมีคนในทีมใช้ Windows ให้เลือกใช้ import

ไม่ว่าจะเลือกวิธีใด ให้รัน /context all ในเซสชันถัดไป แล้วตรวจสอบว่า CLAUDE.md ปรากฏอยู่ใต้หัวข้อ Memory files

AGENTS.md ไฟล์เดียว สำหรับ Codex, Cursor และ Claude Code

จุดเด่นของวิธีนี้คือการมีแหล่งความจริง (source of truth) เดียว ให้คุณใส่คำสั่ง build, คำสั่ง test และข้อตกลงต่าง ๆ ไว้ใน AGENTS.md ที่รากของ repo แล้วทั้ง Codex, Cursor และ Claude Code จะอ่านไฟล์นั้นทั้งหมด

โครงสร้างที่ใช้งานจริงได้:

• AGENTS.md ที่ราก repo: ทุกสิ่งที่ทุก agent ต้องใช้ คำสั่งต่าง ๆ, แผนผังโฟลเดอร์, กฎสไตล์โค้ด, และสิ่งที่ห้ามแตะ
• AGENTS.md ใน subfolder ขนาดใหญ่: กฎที่มีผลเฉพาะโฟลเดอร์นั้น เช่น services/payments/AGENTS.md Claude Code จะโหลดไฟล์เหล่านี้ตามความจำเป็นเมื่ออ่านไฟล์ในโฟลเดอร์นั้น
• CLAUDE.md แบบเลือกใช้: เฉพาะเมื่อคุณต้องการพฤติกรรมเฉพาะของ Claude เช่น plan mode หรือ hooks เริ่มไฟล์ด้วย @AGENTS.md

ข้อควรรู้หนึ่งประการ: AGENTS.md ที่โหลดผ่านการตั้งค่านี้จะไม่เรียก hook InstructionsLoaded และจะไม่ถูกโหลดจาก directory ที่ระบุผ่าน --add-dir หากคุณพึ่งพาสองกรณีนี้ ให้ใช้วิธี import แบบ @AGENTS.md แทน

สอน agent ของคุณให้ทดสอบ API ด้วย Apidog CLI ผ่าน AGENTS.md

เขียนกฎการทดสอบ API เพียงครั้งเดียว แล้วไม่ว่า agent ตัวใดจะเปิด repo ก็จะรันการทดสอบด้วยวิธีเดียวกัน Apidog CLI ให้ผลลัพธ์ JSON ที่มีโครงสร้างซึ่ง agent อ่านได้ ทำให้วงจรการทำงานทั้งหมดอยู่ใน terminal ได้

ติดตั้งครั้งเดียวต่อเครื่อง:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install

ทางลัดอีกแบบ: บอก agent ของคุณว่า "อ่าน https://apidog.com/apidog-cli-installation-guide.md แล้วตั้งค่า Apidog CLI" คู่มือนี้เขียนไว้สำหรับ agent โดยเฉพาะ ครอบคลุมการติดตั้ง การล็อกอิน และการติดตั้ง skill

จากนั้นเพิ่มส่วนแบบนี้เข้าไปใน AGENTS.md ของคุณ:

## API testing (Apidog CLI)

- Apidog project ID: 123456. Staging environment ID: 7890.
- Never build Apidog JSON payloads from memory. Run
  `apidog cli-schema get <key>` first, then
  `apidog cli-schema validate <key> --file <path>`, and write only after it passes.
- After changing any handler under `src/routes/`, find its endpoint with
  `apidog endpoint list --project 123456` and its cases with
  `apidog test-case list --project 123456 --endpoint <endpointId>`.
- If a route has no test case, create one with
  `apidog test-case create --project 123456 --file case.json`.
- Run cases with
  `apidog run --test-case <caseId> --project 123456 -e 7890 -r cli,json`
  and summarize every failure before you say the task is done.
- Do not edit or delete endpoints in Apidog unless the task asks for it.

ต่อไปนี้ prompt เดียวจะทำงานได้ทั้งใน Claude Code, Codex หรือ Cursor:

I changed POST /orders to require a currency field. Update the Apidog test
case for it and run it against staging, following AGENTS.md.

Agent จะทำตามกฎของคุณและรันคำสั่งลักษณะนี้:

apidog endpoint list --project 123456
apidog test-case list --project 123456 --endpoint <endpointId>
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project 123456 --file case.json
apidog run --test-case <caseId> --project 123456 -e 7890 -r cli,json

flag ทุกตัวข้างต้นมาจาก apidog <cmd> --help บน Apidog CLI 2.2.12 คำสั่ง apidog run บรรทัดเดียวกันที่ใส่ -r junit สามารถใช้ใน CI ได้ และ --upload-report จะส่งภาพรวมการรันไปยังแอป เพื่อให้ทีมของคุณเห็นผล ส่วนรายละเอียดฝั่ง Claude Code ดูได้ที่ วิธีใช้ Apidog CLI ใน Claude Code และผู้ใช้ Codex สามารถตามได้ที่ การใช้ Apidog CLI ใน Codex Apidog Free รองรับผู้ใช้ได้ถึง 4 คน ทีมเล็กจึงเริ่มลองใช้ได้ตั้งแต่วันนี้

แก้ปัญหา: ทำไม AGENTS.md ของฉันไม่ถูกโหลด

1. ตรวจหา CLAUDE.md ในเส้นทาง directory. หากมี CLAUDE.md, .claude/CLAUDE.md หรือ CLAUDE.local.md ใน working directory ของคุณหรือ directory ระดับสูงกว่า ไฟล์นั้นจะมีความสำคัญกว่าตามค่าเริ่มต้น ส่วน ~/.claude/CLAUDE.md ของคุณไม่นับในกรณีนี้
2. ตรวจสอบเวอร์ชัน. รัน claude --version คุณต้องใช้เวอร์ชัน 2.1.277 ขึ้นไป และ 2.1.281 ขึ้นไปสำหรับ Bedrock, Vertex AI, Foundry, gateway หรือกรณีปิด telemetry
3. ตรวจสอบการตั้งค่า. เปิด /config และให้แน่ใจว่า Project instructions ไม่ได้ตั้งเป็น claude-md หรือ managed-only
4. ยืนยันว่าโหลดสำเร็จ. รัน /memory แล้วมองหา path ของ AGENTS.md ในรายการ

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

Claude Code อ่าน AGENTS.md แล้วหรือยัง? ใช่ ตั้งแต่ v2.1.277 เมื่อไม่มี CLAUDE.md ใน working directory ของคุณหรือ directory ระดับสูงกว่า Claude Code จะอ่าน AGENTS.md เป็นคำแนะนำระดับโปรเจกต์โดยอัตโนมัติ

ถ้าฉันมีทั้ง CLAUDE.md และ AGENTS.md Claude Code จะใช้อันไหน? เฉพาะ CLAUDE.md ตามค่าเริ่มต้น ให้ตั้งค่า Project instructions เป็น claude-md-and-agents-md ใน /config เพื่อโหลดทั้งสองไฟล์ โดยให้ CLAUDE.md มาก่อน

ควรลบ CLAUDE.md ที่ import @AGENTS.md ทิ้งหรือไม่? ไม่จำเป็น การ import แบบนี้ไม่เคยโหลด AGENTS.md ซ้ำ และยังใช้งานได้กับเพื่อนร่วมทีมที่ยังใช้เวอร์ชันก่อน 2.1.277 ให้ลบทิ้งเฉพาะเมื่อไม่มีเนื้อหาอื่นอยู่ข้างในและทุกคนอัปเกรดครบแล้ว

Claude Code อ่าน AGENTS.override.md เหมือน Codex หรือไม่? ไม่ Claude Code เมิน AGENTS.override.md, AGENTS.local.md และไฟล์ใด ๆ ภายใต้ .agents/

AGENTS.md ใช้งานได้บน Amazon Bedrock หรือ Google Vertex AI หรือไม่? ใช้ได้ ตั้งแต่ v2.1.281 เวอร์ชันก่อนหน้าบน Bedrock, Vertex AI, Foundry, gateway หรือกรณีปิด telemetry จะอ่านเฉพาะ CLAUDE.md ให้ใช้ import แบบ @AGENTS.md ในกรณีนั้นแทน