CLAUDE.md และ AGENTS.md คืออะไร เขียนอย่างไร พร้อมตัวอย่าง

ทุกครั้งที่เปิด session ใหม่ agent เริ่มจากศูนย์ ไม่รู้ว่าโปรเจกต์นี้ใช้ pnpm ไม่รู้ว่ารันเทสต์ด้วยคำสั่งอะไร และไม่รู้ว่าโฟลเดอร์ไหนห้ามแตะ ถ้าคุณพิมพ์อธิบายเรื่องเดิมซ้ำทุกเช้า นั่นคือสัญญาณว่าโปรเจกต์ควรมีไฟล์ CLAUDE.md หรือ AGENTS.md

CLAUDE.md และ AGENTS.md คืออะไร

CLAUDE.md และ AGENTS.md คือไฟล์ Markdown ธรรมดาที่วางไว้ในโปรเจกต์ เพื่อเก็บสิ่งที่ AI coding agent ต้องรู้ทุกครั้ง เช่น คำสั่ง build และ test ข้อตกลงในการเขียนโค้ด และสิ่งที่ห้ามทำ เครื่องมือจะโหลดไฟล์นี้เข้า context เองตอนเริ่ม session

สองไฟล์นี้ทำหน้าที่เดียวกันแต่มาจากคนละฝั่ง CLAUDE.md เป็นไฟล์ของ Claude Code ส่วน AGENTS.md เริ่มจาก OpenAI สำหรับ Codex แล้วกลายเป็นรูปแบบกลางที่หลายเครื่องมือใช้ร่วมกัน เมื่อ 9 ธันวาคม 2568 OpenAI มอบ AGENTS.md ให้ Agentic AI Foundation ภายใต้ Linux Foundation ดูแล และ ณ พฤศจิกายน 2569 เว็บ agents.md ระบุว่ามีโปรเจกต์ open source ใช้มากกว่า 60,000 โปรเจกต์

ทั้งสองไฟล์ไม่มีรูปแบบบังคับ และ agent อ่านเป็น context ที่พยายามทำตาม ไม่ใช่การตั้งค่าที่บังคับได้ ถ้าต้องห้ามจริง เช่น ห้ามอ่าน .env เอกสารของ Claude Code แนะนำให้ใช้ permission rule หรือ hook แทน (ดูการติดตั้งใน คู่มือ Claude Code)

Claude Code และ Codex CLI อ่านไฟล์ไหน จากที่ไหนบ้าง

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

Claude Code โหลด CLAUDE.md อย่างไร

ตอนเริ่ม session Claude Code โหลด CLAUDE.md และ CLAUDE.local.md จากโฟลเดอร์ที่เปิดและทุกโฟลเดอร์เหนือขึ้นไป เรียงจากไฟล์ระดับองค์กร ไฟล์ส่วนตัว ไฟล์ของโปรเจกต์ แล้วจึง CLAUDE.local.md ทุกไฟล์ถูกต่อกัน ไม่ได้ทับกัน ถ้ากฎสองข้อขัดกัน Claude อาจเลือกข้อใดข้อหนึ่ง

CLAUDE.md ดึงไฟล์อื่นเข้ามาได้ด้วย @path/to/file โดย path แบบ relative นับจากไฟล์ที่เขียน import และซ้อนได้ลึกสุด 4 ชั้น ส่วน AGENTS.md จะถูกอ่านเมื่อไม่มี CLAUDE.md, .claude/CLAUDE.md หรือ CLAUDE.local.md ในโฟลเดอร์ที่ทำงานหรือโฟลเดอร์เหนือขึ้นไป ถ้ามีทั้งสองแบบ ค่าเริ่มต้นคืออ่าน CLAUDE.md อย่างเดียว เปลี่ยนได้ใน /config ที่หัวข้อ Project instructions และ Claude Code ไม่อ่าน AGENTS.override.md

Codex CLI หา AGENTS.md อย่างไร

Codex อ่านไฟล์ใน ~/.codex (หรือ CODEX_HOME) ก่อน โดยใช้ AGENTS.override.md ถ้ามี ไม่อย่างนั้นใช้ AGENTS.md จากนั้นไล่จากรากโปรเจกต์ (ปกติคือราก git) ลงมาถึงโฟลเดอร์ปัจจุบัน แต่ละโฟลเดอร์ใช้ไม่เกินหนึ่งไฟล์ ตามลำดับ AGENTS.override.md, AGENTS.md แล้วจึงชื่อสำรองที่ตั้งไว้ ไฟล์ที่ใกล้โฟลเดอร์ปัจจุบันอยู่ท้ายสุดจึงมีน้ำหนักกว่า Codex สร้างชุดคำสั่งนี้ครั้งเดียวต่อ session แก้ไฟล์แล้วต้องเปิด Codex ใหม่ ปรับเพดานขนาดและชื่อสำรองได้ใน config (ดูเพิ่มใน คู่มือ Codex CLI)

# ~/.codex/config.toml
project_doc_max_bytes = 65536
project_doc_fallback_filenames = ["CLAUDE.md"]

ควรเขียนอะไรใน CLAUDE.md หรือ AGENTS.md

ควรเขียนสิ่งที่ agent ต้องรู้ทุก session แต่เดาเองจากโค้ดไม่ได้ ได้แก่ คำสั่ง build, test และ lint ที่ถูกต้อง โฟลเดอร์ที่มีกติกาพิเศษ ข้อตกลงที่ต่างจากค่าปกติ ข้อห้าม และวิธีตรวจงานก่อนบอกว่าเสร็จ

ไฟล์นี้ถูก commit เข้า git และถูกส่งให้โมเดลทุก session secret จึงไม่ควรอยู่ในนั้นเลย กฎที่ linter บังคับอยู่แล้วคือการจ่าย context ซ้ำ ส่วนข้อมูลเก่าอันตรายที่สุด เพราะ agent จะรันคำสั่งที่เลิกใช้ไปแล้วอย่างมั่นใจ คำสั่ง /doctor ของ Claude Code ช่วยเสนอตัดส่วนที่ agent อ่านเองจากโค้ดได้

เขียนให้ตรวจได้ เอกสารเดียวกันยกตัวอย่างว่า “Use 2-space indentation” ได้ผลกว่า “Format code properly” และ “Run npm test before committing” ได้ผลกว่า “Test your changes” จังหวะที่ควรเพิ่มกฎคือเมื่อ agent ทำผิดเรื่องเดิมเป็นครั้งที่สอง ยิ่งปล่อยให้ agent ทำงานเองมาก เช่น ตอน vibe coding ไฟล์นี้ยิ่งสำคัญ

ทำไมไฟล์กฎควรสั้น

ไฟล์กฎควรสั้นเพราะถูกโหลดเข้า context window ทุก session ก่อนที่คุณจะพิมพ์อะไรเลย ยิ่งยาวยิ่งกินที่ที่ควรเหลือไว้ให้โค้ดและผลเทสต์ และเอกสารของ Claude Code ระบุว่าไฟล์ยาวทำให้ agent ทำตามได้แย่ลง จึงแนะนำให้แต่ละ CLAUDE.md ไม่เกิน 200 บรรทัด

ฝั่ง Codex มีเพดานชัดกว่า คือทุกไฟล์รวมกันได้ไม่เกิน 32 KiB ตามค่าเริ่มต้นของ project_doc_max_bytes พอถึงเพดาน Codex จะหยุดเพิ่มไฟล์ กฎในโฟลเดอร์ย่อยที่อยู่ท้ายสายจึงอาจหายไปโดยไม่รู้ตัว อ่านเรื่องพื้นที่นี้เพิ่มได้ที่ Context window คืออะไร

• ย้ายกฎเฉพาะส่วนไปไว้ใกล้โค้ด ใช้ไฟล์กฎในโฟลเดอร์ย่อย หรือ .claude/rules/ ที่ตั้ง paths ซึ่งโหลดเมื่อทำงานกับไฟล์ที่ตรงเท่านั้น
• import ไม่ได้ช่วยประหยัด ไฟล์ที่ดึงด้วย @path ถูกโหลดพร้อมไฟล์ที่ import มัน
• โน้ตถึงคนให้ใช้ HTML comment comment ระดับบล็อกใน CLAUDE.md ถูกตัดออกก่อนส่งให้โมเดล
• กฎในไฟล์รอดจากการ compact CLAUDE.md ที่รากโปรเจกต์ถูกอ่านใหม่หลัง /compact ต่างจากคำสั่งในแชต

ตัวอย่าง AGENTS.md สำหรับโปรเจกต์ Node.js และ TypeScript

ตัวอย่างนี้เป็น AGENTS.md ของ API ระบบสั่งซื้อที่เขียนด้วย Node.js และ TypeScript ยาวราว 35 บรรทัด ใช้เป็น CLAUDE.md ได้ทันทีโดยเปลี่ยนแค่ชื่อไฟล์ จะเขียนเป็นภาษาอังกฤษหรือไทยก็ได้

# AGENTS.md

## Project
Order management API. Node.js 22, TypeScript (strict), Fastify,
PostgreSQL via Prisma, Vitest. Package manager: pnpm, never npm or yarn.

## Commands
- Typecheck: `pnpm typecheck`
- Lint and format: `pnpm lint --fix`
- All tests: `pnpm test`
- One test file: `pnpm vitest run src/services/orders.test.ts`
- New migration: `pnpm prisma migrate dev --name <short_name>`

## Layout
- `src/routes/`: HTTP handlers only, no business logic
- `src/services/`: business logic; every exported function needs a test
- `src/lib/money.ts`: all money math lives here
- `prisma/migrations/`: generated by Prisma, never edit by hand

## Conventions
- Store and calculate money in satang as integers. Never use floats.
- Store dates in UTC. Convert to Asia/Bangkok only in responses.
- User-facing error messages are in Thai; logs are in English.
- Validate every request body with the zod schemas in `src/schemas/`.

## Never
- Never commit `.env` or log secrets. Add new variables to `.env.example`.
- Never edit a migration already merged to `main`. Create a new one.
- Never add a dependency without explaining why in your summary.

## Before you say a task is done
1. `pnpm typecheck`, `pnpm lint` and `pnpm test` all pass
2. New logic has tests
3. Summarize what changed and anything you could not verify

• Project stack ที่ agent เดาผิดได้ง่าย เช่น ใช้ pnpm ไม่ใช่ npm
• Commands คำสั่งที่ copy ไปรันได้ทันที รวมวิธีรันเทสต์ไฟล์เดียวให้ agent ตรวจงานได้เร็ว
• Layout เฉพาะโฟลเดอร์ที่มีกติกา ส่วนที่เหลือ agent เปิดดูเองได้
• Conventions กฎที่ต่างจากค่าปกติและพลาดแล้วเสียหาย เช่น ยอดเงินเป็นสตางค์แบบจำนวนเต็ม
• Never ข้อห้ามสั้นๆ พร้อมบอกทางที่ถูกต่อท้าย
• Before you say a task is done นิยามคำว่าเสร็จ ให้ agent มีตัวตรวจก่อนส่งงาน

ใช้ทั้ง Claude Code และ Codex ในทีมเดียว เก็บไฟล์กฎอย่างไร

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

@AGENTS.md

## Claude Code
- Use plan mode for changes under `src/billing/`.

1. มีแค่ AGENTS.md ใช้ได้ถ้าทุกคนใช้ Claude Code v2.1.277 ขึ้นไป แต่ถ้าใครสร้าง CLAUDE.local.md ไว้ Claude จะหยุดอ่าน AGENTS.md ในเครื่องของคนนั้น เว้นแต่ตั้ง Project instructions เป็น claude-md-and-agents-md
2. AGENTS.md คู่กับ CLAUDE.md ที่ import ปลอดภัยที่สุด ใช้ได้ทุกเวอร์ชัน และมีที่ใส่กฎเฉพาะ Claude
3. symlink ด้วย ln -s AGENTS.md CLAUDE.md ใช้ได้ถ้าไม่มีกฎเฉพาะ Claude แต่บน Windows ต้องใช้สิทธิ์ admin หรือ Developer Mode และ git อาจ checkout ออกมาเป็นไฟล์ข้อความบรรทัดเดียว ถ้ามีคนใช้ Windows ให้ใช้ import แทน

ถ้าทีมใช้ CLAUDE.md เป็นหลักอยู่แล้ว อีกทางคือให้ Codex อ่าน CLAUDE.md ผ่าน project_doc_fallback_filenames ตามตัวอย่างข้างบน ซึ่งต้องตั้งในแต่ละเครื่อง และใช้ได้เฉพาะโฟลเดอร์ที่ไม่มี AGENTS.md หลังตั้งค่าให้เช็กด้วย /memory และสั่ง Codex ให้สรุปคำสั่งที่โหลด

ไฟล์กฎโปรเจกต์ใช้กับ buzzAI ได้เหมือนเดิม

CLAUDE.md และ AGENTS.md ถูกอ่านโดยตัวเครื่องมือ ไม่ได้ขึ้นกับว่าเบื้องหลังเป็นโมเดลของใคร เมื่อตั้ง Claude Code ให้ชี้ไปที่ API ของ buzzAI ผ่าน ANTHROPIC_BASE_URL (ดูวิธีใช้ Claude Code กับ API อื่น) หรือตั้ง base URL ใน Codex CLI ไฟล์กฎของคุณก็ทำงานเหมือนเดิม โมเดลที่ใช้คือ Qwen3.8-27B แบบ open-weight

ขนาด context ขึ้นกับแพ็ก Mini ได้ 64K, Day Pass, Week Pass และ Lite ได้ 128K ส่วน Solo และแพ็กบริษัทได้ 256K ในแพ็ก 64K หรือ 128K ไฟล์กฎที่สั้นช่วยให้เหลือที่ให้โค้ดและผลเทสต์มากขึ้น ทุกแพ็กเหมาจ่ายและไม่คิดค่า token สิ่งที่มีขอบเขตคือจำนวน agent ที่รันพร้อมกัน ขนาด context และคิวในช่วงที่คนใช้เยอะ ตอนนี้ API ยังไม่เปิดใช้ เรากำลังเปิดให้ขอร่วมทดสอบรอบที่ 1 และจะส่ง API key ให้ทางอีเมลเมื่อมีผู้สมัครครบโควต้าที่กำหนด ดูวิธีตั้งค่าได้ที่คู่มือ API และแพ็กทั้งหมดที่หน้าราคา