CLAUDE.md และ AGENTS.md คืออะไร ควรเขียนอะไร และทำไม agent ถึงไม่ทำตามกฎ

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

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

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

# CLAUDE.md
@AGENTS.md

วิธีนี้ทำให้กฎอยู่ในที่เดียว ไม่แตกต่างกันระหว่างสองไฟล์

agent อ่านไฟล์เหล่านี้อย่างไร

เนื้อหาของไฟล์คำสั่งถูกใส่เข้าหน้าต่างบริบทของโมเดลพร้อมกับ system prompt และอยู่ตรงนั้นตลอดทั้งเซสชัน จากข้อเท็จจริงนี้มีผลสำคัญสามข้อ

• ทุกบรรทัดกินพื้นที่ในบริบท ไฟล์ถูกอ่านทั้งหมดทุกครั้งที่เริ่มทำงาน แม้งานปัจจุบันต้องการแค่หนึ่งในสิบของเนื้อหา
• นี่คือข้อความ ไม่ใช่กฎที่บังคับใช้ได้ โมเดลพิจารณามันพร้อมกับบริบทอื่น และไม่มีอะไรรับประกันว่าจะปฏิบัติตามได้ 100% ข้อห้ามที่เข้มงวดต้องได้รับการหนุนด้วยกลไก เช่น การตรวจสอบ hooks สิทธิ์การเข้าถึง
• ไฟล์ซ้อนกันได้ Claude Code โหลด CLAUDE.md จากรากโปรเจกต์และจากโฟลเดอร์ผู้ใช้ ~/.claude/ ส่วนไฟล์ในโฟลเดอร์ย่อยจะถูกโหลดเมื่อ agent ทำงานกับไฟล์ในโฟลเดอร์เหล่านั้น จึงสามารถวางกฎของโมดูลไว้ข้างโมดูลนั้นได้

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

ไฟล์คำสั่งที่ดีคือแผนที่ ไม่ใช่หนังสือเรียน มันตอบคำถามที่ agent จะถามเพื่อนร่วมงานที่มีประสบการณ์ในวันแรก

1. วิธีสร้างและตรวจสอบโปรเจกต์

ส่วนที่มีคุณค่าที่สุด คือคำสั่งที่เฉพาะเจาะจงซึ่ง agent ต้องรันก่อนจะพูดว่า «เสร็จแล้ว» ได้แก่ เทสต์ linter การตรวจชนิดข้อมูล และการเปิดสภาพแวดล้อม ถ้าไม่มีสิ่งเหล่านี้ agent จะตรวจงานของตัวเองด้วยการคาดเดา

2. ข้อจำกัดที่เข้มงวด

รายการสั้น ๆ ของสิ่งที่ห้ามละเมิดไม่ว่าในสถานการณ์ใด เช่น หลักความปลอดภัยและข้อมูล เขียนเป็นหลักที่ไม่เปลี่ยน ไม่ใช่คำสั่งการทำงาน: «คำสั่ง SQL ทุกตัวต้องใช้ parameter» แทนที่จะเป็น «ใช้ฟังก์ชันนั้นในไฟล์นั้น»

3. แผนที่โปรเจกต์

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

4. สถานะงานเก็บไว้ที่ไหน

ต้องดูที่ไหนเพื่อทำงานต่อจากเซสชันก่อนหน้า เช่น ไฟล์แผนงาน บันทึกความคืบหน้า backlog วิธีนี้แก้อาการ «ความจำเสื่อม» ของ agent ระหว่างเซสชัน

สิ่งที่ไม่ควรเขียน

• สิ่งที่ agent รู้ได้จากโค้ด รายการ dependencies อยู่ใน package.json หรือ pyproject.toml โครงสร้างคลาสอยู่ในตัวโค้ดเอง
• คำแนะนำทั่วไป เช่น «เขียนโค้ดให้สะอาด» หรือ «ระวังให้ดี» ไม่เปลี่ยนพฤติกรรม และเปลืองพื้นที่เปล่า ๆ
• ประวัติโปรเจกต์และบันทึกชั่วคราว เช่น «เดือนมีนาคมเราย้ายจาก MySQL 5.7» ไม่ช่วยงานปัจจุบัน
• คำสั่งละเอียดสำหรับงานที่นาน ๆ ทำที ขั้นตอน deploy หรือการย้ายข้อมูลที่ทำสัปดาห์ละครั้ง ควรแยกไปไว้เอกสารหรือ skill ต่างหาก
• ความลับ ไฟล์อยู่ใน repository และถูกส่งเข้าโมเดลทั้งหมด โทเคนและรหัสผ่านควรเก็บไว้ในตัวแปรสภาพแวดล้อมเท่านั้น

ทำไม agent ถึงเพิกเฉยต่อกฎที่เขียนไว้ในไฟล์

เรื่องที่พบบ่อยคือ agent ทำผิด จึงมีการเพิ่มกฎหนึ่งข้อในไฟล์ ทำผิดอีก เพิ่มอีกข้อ อีกสองสามเดือนต่อมาไฟล์มีหลายร้อยบรรทัด และกฎความปลอดภัยที่สำคัญถูก agent ละเมิดราวกับว่าไม่มีอยู่ มักมีสาเหตุสี่ประการที่ทำงานพร้อมกัน

ไฟล์บวมเกินไป

ไฟล์ 600 บรรทัดมีขนาดราว 10–20 พันโทเคน หน้าต่างบริบทดูใหญ่ แต่มันต้องแบ่งกับโค้ด ผลลัพธ์ของคำสั่ง และประวัติการสนทนา ยิ่งคำสั่งกินพื้นที่มาก กฎแต่ละข้อก็ได้รับความสนใจน้อยลง และพื้นที่สำหรับงานจริงก็ยิ่งแคบลง

กฎอยู่กลางไฟล์

โมเดลภาษาใช้ข้อมูลที่อยู่กลางข้อความยาวได้แย่กว่าข้อมูลที่อยู่ต้นและท้าย กฎที่อยู่บรรทัดที่สามร้อยจากหกร้อยจึงอยู่ในจุดที่อ่อนที่สุดพอดี

ไม่มีลำดับความสำคัญ

ข้อห้ามที่ไม่มีการต่อรองกับคำแนะนำเล็กน้อยเรื่องสไตล์ถูกเขียนในรูปแบบเดียวกันคือหนึ่งบรรทัดในรายการ agent ไม่มีทางรู้ว่าอะไรสำคัญกว่า และถ้าในไฟล์มีกฎสไตล์ที่ขัดแย้งกันสามข้อ พฤติกรรมจะสุ่มไปตามแต่ละครั้งที่รัน

ค่อย ๆ เน่า

การเพิ่มกฎไม่มีค่าใช้จ่าย แต่การลบออกทำให้กลัว: «เผื่อมีอะไรผูกกับมันอยู่» ไฟล์จึงโตขึ้นเรื่อย ๆ ส่วนสัดส่วนบรรทัดที่มีประโยชน์ก็ลดลง วัดได้ด้วยอัตราส่วนสัญญาณต่อสัญญาณรบกวน คือดูว่ามีกี่บรรทัดที่จำเป็นจริงสำหรับงานทั่วไป และกี่บรรทัดที่ไม่จำเป็น

วิธีแก้: ตัวกำหนดเส้นทางแทนกำแพงข้อความ

การแก้สาเหตุเดียวไม่ได้ผล ถ้าตัดไฟล์ให้สั้นแต่ไม่จัดโครงสร้าง กฎก็ยังปนกันอยู่ ต้องใช้ชุดมาตรการร่วมกัน

1. ทำให้ไฟล์หลักเป็นตัวกำหนดเส้นทาง 50–150 บรรทัด: คำสั่งตรวจสอบ ข้อจำกัดที่เข้มงวด แผนที่โปรเจกต์ และลิงก์ไปยังเอกสารเฉพาะเรื่อง
2. แยกหัวข้อออกเป็นไฟล์ของตัวเอง เช่น docs/agents/deploy.md และ docs/agents/database.md agent จะเปิดอ่านเมื่อจำเป็น ใน Claude Code กระบวนการที่ทำซ้ำ ๆ เหมาะกับ skills เพราะโหลดเฉพาะเมื่อต้องการ
3. ยกสิ่งสำคัญขึ้นไปไว้บนสุด ข้อจำกัดที่เข้มงวดวางไว้ต้นไฟล์ เป็นบล็อกสั้น ๆ ที่มีป้าย MUST ชัดเจน
4. ขจัดความขัดแย้ง แต่ละหัวข้อมีกฎเพียงข้อเดียว ถ้ามีข้อยกเว้น ให้เขียนไว้ข้างกฎนั้นเลย
5. หนุนกฎด้วยกลไก ถ้าการละเมิดรับไม่ได้ การเขียนข้อความอย่างเดียวไม่พอ ต้องมีการตรวจสอบที่จับได้ เช่น linter เทสต์ hook pre-commit หรือ hook ของ agent หรือการปิดกั้นด้วยสิทธิ์การเข้าถึง
6. ทบทวนเป็นประจำ ตั้งขีดจำกัดจำนวนบรรทัด และทุกครั้งที่เพิ่มอะไร ให้ถามว่าอะไรลบหรือย้ายออกได้บ้าง

กฎหรือการตรวจสอบ?

ตัวอย่าง AGENTS.md ที่กระชับ

# AGENTS.md — backend การชำระเงิน (FastAPI, PostgreSQL)

## MUST — ห้ามละเมิด
- จำนวนเงินเป็น int หน่วยสตางค์ ห้ามใช้ float เด็ดขาด
- SQL ต้องใช้ parameter เท่านั้น ห้ามใช้ f-string
- ห้ามแก้ migration ที่ถูกนำไปใช้แล้ว ให้เพิ่ม migration ใหม่เท่านั้น
- ความลับมาจากตัวแปรสภาพแวดล้อมเท่านั้น

## ตรวจสอบก่อนพูดว่า «เสร็จแล้ว»
docker compose up -d     # สภาพแวดล้อม
make lint                # ruff + mypy
make test                # pytest
make e2e                 # สถานการณ์การสั่งซื้อ
เทสต์ unit ผ่านแต่ไม่มี e2e ยังไม่ถือว่า «เสร็จ»

## แผนที่
- app/payments/   — คำนวณเงิน ส่วนลด webhook ของผู้ให้บริการ
- app/api/        — HTTP endpoints
- tests/e2e/      — สถานการณ์ของผู้ใช้
รายละเอียด: docs/agents/architecture.md, docs/agents/database.md

## สถานะการทำงาน
- PLAN.md      — เป้าหมายปัจจุบัน เกณฑ์ความสำเร็จ ขั้นตอนถัดไป
- PROGRESS.md  — สิ่งที่ทำและวิธีตรวจสอบ ทางตัน
- BACKLOG.md   — สิ่งที่พบ «เผื่อ» จดไว้ที่นี่ ไม่ต้องแก้ตอนนี้

เมื่อจบเซสชัน อัปเดต PROGRESS.md และขั้นตอนถัดไปใน PLAN.md

สังเกตสิ่งที่ไม่มีในตัวอย่างนี้: รายการไลบรารี คำแนะนำด้านสไตล์ ประวัติโปรเจกต์ ทั้งหมดนี้มองเห็นได้จากโค้ด หรือถูกยึดไว้ด้วยการตรวจสอบ หรืออยู่ในเอกสารเฉพาะเรื่อง

ความจำข้ามเซสชัน: ไฟล์คำสั่งบวกไฟล์แผนงาน

ไฟล์คำสั่งอธิบายวิธีทำงานในโปรเจกต์ แต่ไม่ได้บอกว่าตอนนี้เกิดอะไรขึ้น จึงต้องมีไฟล์สถานะแยกต่างหากที่ agent อ่านตอนเริ่มและอัปเดตตอนจบเซสชัน ในไฟล์นั้นมี เป้าหมาย สิ่งที่ทำไปแล้วพร้อมวิธีตรวจสอบ การตัดสินใจพร้อมเหตุผล ตัวเลือกที่ถูกปฏิเสธ และขั้นตอนถัดไปหนึ่งประโยค วิธีทดสอบคุณภาพก็ง่าย: เปิดเซสชันใหม่ พิมพ์ «ทำต่อ» แล้วดูว่า agent เริ่มทำงานที่มีประโยชน์ได้โดยไม่ต้องถามหรือไม่

อย่าสับสนสองไฟล์นี้ คำสั่งเปลี่ยนแปลงน้อยและใช้กับทุกงาน ส่วนแผนงานเปลี่ยนทุกเซสชันและใช้กับงานปัจจุบัน ถ้าผสมกัน ไฟล์คำสั่งจะบวมขึ้นอย่างรวดเร็วด้วยหมายเหตุที่ล้าสมัย

วิธีตรวจว่าไฟล์ใช้งานได้จริงหรือไม่

ไฟล์คำสั่งก็ต้องได้รับการตรวจสอบ เลือกงานทั่วไปสักสองสามอย่าง เช่น แก้บั๊ก ฟีเจอร์เล็ก ๆ และ refactor แล้วดูว่า agent ทำอะไรโดยไม่มีคำแนะนำเพิ่ม มันรันคำสั่งที่ถูกต้องหรือไม่ เปิดเอกสารเฉพาะเรื่องที่เหมาะสมหรือไม่ และปฏิบัติตามข้อจำกัดที่เข้มงวดหรือไม่ ถ้ากฎถูกละเมิด ให้ถามตัวเองก่อนว่ากฎนั้นมองเห็นได้หรือไม่ ขัดแย้งกับอะไรหรือไม่ และเปลี่ยนเป็นการตรวจสอบอัตโนมัติได้หรือไม่ การเพิ่มบรรทัดใหม่เป็นทางเลือกสุดท้าย

สรุป

CLAUDE.md และ AGENTS.md คือจุดเริ่มต้นของ agent เมื่อเข้าสู่โปรเจกต์ ไฟล์เหล่านี้ได้ผลเมื่อยังเป็นแผนที่สั้น ๆ ได้แก่ คำสั่งตรวจสอบ ข้อจำกัดที่เข้มงวดอยู่ด้านบน และลิงก์ไปยังรายละเอียดและไฟล์แผนงาน ถ้ากฎถูกเพิกเฉย สาเหตุเกือบทุกครั้งคือไฟล์ที่บวมและไม่มีโครงสร้าง ส่วนกฎที่สำคัญจริงต้องได้รับการหนุนด้วยการตรวจสอบและ hooks วิธีจัดโครงสร้างคำสั่งและสถานะของ agent ถูกอธิบายในทางปฏิบัติในหลักสูตร harness engineering