CLAUDE.md และ AGENTS.md คืออะไร และทำไมถึงสำคัญ
CLAUDE.md และ AGENTS.md คือไฟล์คำสั่งแบบ Markdown ที่ใช้บรรยายบริบท โปรเจกต์ ข้อจำกัด และแนวทางการเขียนโค้ดให้ AI coding agents อ่านก่อนเริ่มทำงานทุกครั้ง เพื่อให้โมเดลเข้าใจภาพรวม สถาปัตยกรรม และกติกาการใช้เครื่องมือโดยไม่ต้องไล่โค้ดทั้งระบบ ช่วยลดความสับสน การเขียนโค้ดสวนเจตนารมณ์ของโปรเจกต์ และการสร้างฟังก์ชันซ้ำซ้อนโดยไม่จำเป็น ทำหน้าที่คล้ายคู่มือ onboarding ฉบับสั้นสำหรับทีมพัฒนา แต่เขียนให้ AI อ่านและทำตามได้สม่ำเสมอ
AGENTS.md กลายเป็นรูปแบบมาตรฐานในการบรีฟ coding agent ถูกใช้แล้วในโปรเจกต์โอเพนซอร์สมากกว่า 60,000 โปรเจกต์ และทำงานร่วมกับเครื่องมืออย่าง Codex Cursor Copilot Gemini CLI Jules Windsurf Devin และอื่นๆ ผู้ดูแลนิยามว่าเป็นเหมือน README สำหรับ agent คือที่รวมบริบทและคำแนะนำที่คาดเดาได้สำหรับ AI agent ส่วน CLAUDE.md เป็นไฟล์ที่ตั้งใจออกแบบให้ใช้กับ Claude Code โดยตรง แต่แนวทางการเขียนสามารถใช้ร่วมกับ AGENTS.md ได้เหมือนกัน
เอกสาร AI agent instructions ทั้งสองแบบถูกอ่านทุกครั้งที่ agent ทำงานในโปรเจกต์เดียวกัน และใช้กำหนดพฤติกรรมที่คาดหวัง วิธีใช้เครื่องมือ รูปแบบโค้ด และมาตรฐานต่างๆ เพื่อวางรากฐานบริบทให้โมเดล หากเขียนดี โค้ดที่ได้จะสอดคล้องกับโครงสร้าง ระบบคำสั่ง และแนวคิดของโปรเจกต์มากขึ้น แต่ถ้าเขียนวกวน หรือใส่รายละเอียดเกินไป ก็เปลืองบริบทและทำให้โมเดลหลงทางได้ง่าย
มาตรฐานเดียวกันระหว่างแพลตฟอร์ม และข้อดีของ AGENTS.md framework
AGENTS.md framework คือรูปแบบการจัดข้อมูลในไฟล์ AGENTS.md เพื่อบอกภาพรวมโปรเจกต์ สถาปัตยกรรม สแตกเทคโนโลยี คำสั่งที่ใช้บ่อย และข้อตกลงสำคัญ ให้ AI เข้าใจเหมือนอ่าน README ที่เขียนดีสำหรับทีมใหม่ จุดแข็งของ AGENTS.md คือรองรับข้อเท็จจริงเชิงปฏิบัติที่ค่อนข้างคงตัว เช่น การติดตั้ง dependency วิธีรันเทสต์ วิธีสตาร์ต dev server รูปแบบชื่อ pull request และคำสั่งที่ต้องผ่านก่อน merge สิ่งเหล่านี้ไม่เปลี่ยนบ่อย และสำคัญกับทุกงานที่ agent ทำในโปรเจกต์
ผู้ดูแลระบุว่า AGENTS.md เป็นแค่ Markdown ธรรมดา ไม่มีช่องบังคับ ใช้หัวข้ออะไรก็ได้ ตามที่ agent จะอ่านและแยกวิเคราะห์ข้อความ ความยืดหยุ่นตรงนี้ดี แต่ก็เป็นข้อจำกัด เพราะเนื้อหาส่วนใหญ่จะเป็นร้อยแก้ว ไม่ใช่โครงสร้างข้อมูลที่ชัดเจน เช่น กราฟสถาปัตยกรรม หรือ dependency graph จริง ดังนั้นคำอธิบายอย่าง เราใช้ hexagonal architecture จะไม่เท่ากับการให้กราฟว่า module ไหนเรียกใครได้บ้าง คุณจึงควรใช้ AGENTS.md framework เพื่อสรุปหลักการออกแบบในระดับนามธรรม และให้เครื่องมืออื่นช่วยให้รายละเอียดเชิงโครงสร้าง
การที่ AGENTS.md ถูกส่งมอบให้มูลนิธิด้าน Agentic AI ภายใต้ Linux Foundation ทำให้รูปแบบนี้มีที่ดูแลระยะยาว และเปิดทางให้หลายเครื่องมือรองรับร่วมกัน ด้าน Claude Code ก็เลือกสนับสนุนสเปก Markdown ของฝั่ง OpenAI โดยเพิ่มการรองรับ AGENTS.md เมื่อไม่มี CLAUDE.md อยู่ในโฟลเดอร์ รุ่น 2.1.277 จะตรวจและใช้ AGENTS.md แทนได้ทันที การตัดสินใจนี้ช่วยลดการต้องดูแลไฟล์คำสั่งสองชุด และตัดทริกอย่างการสร้าง symlink เพื่อให้ CLAUDE.md และ AGENTS.md ตรงกัน
โครงสร้าง CLAUDE.md ที่ทำงาน และวิธีเขียนให้กระชับ
แนวคิด CLAUDE.md ที่ทำงานคือ เขียนไฟล์คำสั่งให้เหมือนคู่มือ onboarding ที่สั้นที่สุดสำหรับคนใหม่ แต่กระชับระดับเรซูเม่ เพื่อให้ AI เข้าใจโปรเจกต์พอเริ่มทำงานได้โดยไม่ทำลายโค้ดเบส ผู้เขียนบทความต้นทางเล่าว่าตนเคยลดเรซูเม่จาก 4 หน้าเหลือ 2 หน้าโดยตัดคำฟุ่มเฟือยและปรับประโยคให้แน่นที่สุด แล้วเสนอให้เขียน CLAUDE.md แบบเดียวกัน คือใช้ทุกคำอย่างมีเหตุผล โดยทั่วไป ไฟล์ CLAUDE.md ที่ดีควรมีความยาวไม่เกิน 200 บรรทัด เพื่อรักษาพื้นที่บริบทรวมและให้โมเดลมีเหลือไว้ใช้กับโค้ดจริง
โครง AGENTS.md framework สำหรับไฟล์ระดับโปรเจกต์ประกอบด้วยหัวข้อสำคัญ เช่น บรรทัดแนะนำเดียว สถาปัตยกรรม สแตกเทคโนโลยี คำสั่งที่ใช้บ่อย ข้อกำหนด ขอบเขต และแผนที่เอกสารโดเมน ในระดับการใช้งานจะมี CLAUDE.md สามประเภท ได้แก่ ไฟล์ระดับ global ที่อยู่ใต้โฟลเดอร์ ~/.claude ใช้กับทุกโปรเจกต์ ไฟล์ระดับโปรเจกต์ที่ root และไฟล์ใน subdirectory สำหรับโมดูลที่มีบริบทเฉพาะเอง แนวทาง prompt engineering tips ที่สำคัญคือ บรรยายหลักการออกแบบเชิงนามธรรม เช่น การแยกเลเยอร์ การจัด domain logic และวิธี reuse โค้ด แทนการลงรายละเอียดตำแหน่งบรรทัดหรือชื่อไฟล์ซึ่งเปลี่ยนบ่อย
เนื่องจากโมเดลไม่มีความจำถาวร ทุกครั้งที่เริ่มเซสชันใหม่มันจะไม่รู้ว่าคุณเป็นใคร โปรเจกต์คืออะไร และเคยคุยอะไรมาก่อน แต่จะเรียนรู้ทั้งหมดจากบริบทที่คุณส่งเข้าไป การยัดทุกอย่างลง CLAUDE.md จึงไม่ใช่คำตอบ คีย์อยู่ที่เล่า background สั้นๆ สถาปัตยกรรมหลัก และเป้าหมายการใช้โค้ดให้ชัดพอ เพื่อให้โมเดลไม่ต้องอ่านโค้ดทั้งระบบ และไม่เขียนสิ่งที่สวนเจตนารมณ์ หรือสร้างของซ้ำที่มีอยู่แล้ว อีกด้านหนึ่ง แม้ AGENTS.md จะถูกเรียกว่า living documentation แต่ก็ยังต้องให้คนมาอัปเดตตามการเปลี่ยนแปลงของโค้ดเบสอยู่ดี คุณจึงควรวางโครงให้แก้ง่าย และตรวจด้วยสายตาเป็นระยะ
ลำดับขั้นการเขียนไฟล์ AI agent instructions แบบใช้งานได้จริง
มาดูขั้นตอนทีละก้าวเหมือนเพื่อนสอนเพื่อน เพื่อให้ได้ไฟล์ CLAUDE.md หรือ AGENTS.md ที่ใช้งานได้จริง ไม่ใช่แค่ไฟล์สเปกสวยแต่ AI อ่านแล้วงง ก่อนลงมือจำไว้ว่าทุกบรรทัดคือบริบท ถ้าใส่เกินจำเป็นจะเบียดที่ของโค้ดตัวอย่างและคำสั่งจริง ทำให้โมเดลมีข้อมูลมากแต่ไม่ชัด ลำดับด้านล่างช่วยให้คุณไล่จากภาพรวมไปสู่ข้อจำกัดสำคัญ โดยไม่หลงไปเขียนประวัติศาสตร์โปรเจกต์ยาวเป็นนิยาย
- เริ่มจากเขียนบรรทัดแนะนำเดียว สรุปว่าโปรเจกต์นี้ทำอะไร และ AI agent จะถูกใช้ทำงานแบบไหนในโปรเจกต์นั้น
- เพิ่มหัวข้อ Architecture สรุปเลเยอร์หลัก โฟลเดอร์สำคัญ และกติกาการเรียกข้ามเลเยอร์ เช่น controller บางตัวห้ามเรียกชั้น data ตรงๆ
- เขียน Tech stack ระบุภาษา เฟรมเวิร์ก ฐานข้อมูล และเครื่องมือรันงาน เช่น test runner หรือ task queue เพื่อให้ AI เลือกโค้ดและไลบรารีให้ตรงบริบท
- ใส่ Commands ที่ใช้บ่อย เช่น วิธีรันเทสต์ วิธีสตาร์ต dev server และคำสั่งตรวจโค้ดก่อน push หรือ merge ซึ่งเป็นจุดแข็งของ AGENTS.md สำหรับข้อมูลเชิงปฏิบัติ
- กำหนด Conventions และ Boundaries เช่น มาตรฐานโค้ด ชื่อ branch รูปแบบชื่อ PR และสิ่งที่ห้ามทำ เช่น ไม่แตะไฟล์บางกลุ่มหรือไม่แก้สคริปต์ deploy โดยไม่ระบุเหตุผล
รอบขั้นตอนนี้ สิ่งที่ต้องระวังคือความล่อใจที่จะเพิ่มหัวข้อ Never ยาวๆ เพื่อเก็บประวัติความผิดพลาดทั้งหมด แนวทางต้นทางไม่แนะนำให้ทำ เพราะหัวข้อนี้มีแรงจูงใจให้เพิ่มเรื่อยๆ แต่ไม่มีแรงจูงใจให้ลบ ทำให้กลายเป็นสุสานเหตุการณ์เก่าที่ไม่มีใครกลั่นกรอง อีกจุดคืออย่าพยายามใช้ไฟล์นี้แทน governance หรือแทนระบบบังคับใช้มาตรฐาน เพราะ AGENTS.md ถูกออกแบบมาเล่าข้อเท็จจริงเชิงปฏิบัติคงตัว ไม่ได้ออกแบบมาเป็นเมืองกฎหมายเต็มรูปแบบ ถ้าคุณใช้ให้เกินหน้าที่ ไฟล์จะบวมและยากต่อการดูแล
รูปแบบที่ดีช่วยให้โค้ดที่ได้ตรงบริบท และข้อคิดท้ายทาง
การจัดโครง CLAUDE.md ที่ทำงานและ AGENTS.md framework ให้ชัด มีผลตรงต่อคุณภาพโค้ดและงานที่ AI agent สร้าง เพราะเอกสารเหล่านี้เป็นฐานบริบทที่ agent อ่านทุกครั้งก่อนทำงาน และใช้กำหนดพฤติกรรมที่คาดหวัง วิธีใช้เครื่องมือ และรูปแบบโค้ด ถ้าไฟล์เล่า background สั้นแต่ครบ สถาปัตยกรรมหลักชัด สแตกเทคโนโลยีตรง และคำสั่งสำคัญอยู่ในที่เดิมทุกครั้ง โมเดลจะใช้เวลาน้อยลงในการสำรวจโค้ด และลดโอกาสเขียนส่วนที่สวนข้อจำกัดของระบบ
แต่ต้องจำว่าไฟล์คำสั่งเป็นเพียงทางแก้ชั่วคราวสำหรับปัญหาที่ใหญ่กว่า ในบทวิเคราะห์ต้นทางมีการบอกว่า AGENTS.md เป็น workaround ที่ดี แต่ไม่ใช่ solution เพราะข้อมูลที่ใส่ยังเป็นร้อยแก้ว ต้องให้คนปรับตามโค้ดเบสที่เปลี่ยนทุกครั้ง หมายความว่าคุณยังต้องมีเครื่องมือหรือกระบวนการอื่นช่วยดูโครงสร้างจริง เช่น กราฟ dependency ระบบตรวจมาตรฐาน และการรีวิวโค้ดจริง การลงทุนเขียนไฟล์เหล่านี้จึงคุ้ม ถ้าคุณพร้อมดูแลให้กระชับ อัปเดต และเสริมด้วยระบบที่เข้าใจโครงสร้างแบบที่ Markdown ธรรมดาทำไม่ได้
บทสรุปสำหรับเพื่อนสายโค้ดคือ การเขียน AI agent instructions ที่ดีไม่ได้เริ่มจากเขียนเยอะ แต่เริ่มจากการตั้งใจเลือกสิ่งที่จะเล่า ให้ทุกหัวข้อมีหน้าที่ชัด และไม่ปล่อยให้ไฟล์บวมตามกาลเวลา การที่สเปก Markdown ระหว่างแพลตฟอร์มสำคัญรองรับกันแล้ว เช่น การที่ Claude Code ตรวจใช้ AGENTS.md เมื่อไม่มี CLAUDE.md ทำให้คุณมีเวลาไปโฟกัสที่เนื้อหาแทนไฟล์สองชุด ถ้าดูแลให้ดี ไฟล์เดียวนี้จะกลายเป็นคู่มือที่ทำให้ AI เป็นสมาชิกทีมที่ใช้การได้ มากกว่าผู้ช่วยที่ชอบเขียนโค้ดหลุดบริบท
