CLAUDE.md

CLAUDE.md คือไฟล์ Markdown ที่เราเขียนกติกาและบริบทของโปรเจกต์ไว้ให้ claude-code อ่านตอนเริ่มทุก session เพราะแต่ละ session เริ่มต้นด้วย context-window ที่ว่างเปล่า ไฟล์นี้จึงเป็นตัวพาความรู้ข้ามรอบให้ เนื้อหาที่ควรใส่คือสิ่งที่เราจะต้องอธิบายซ้ำทุกครั้งอยู่ดี เช่น คำสั่ง build และ test โครงสร้างโปรเจกต์ ข้อตกลงการเขียนโค้ด และกติกาประเภททำแบบนี้เสมอ สัญญาณที่บอกว่าถึงเวลาเพิ่มบางอย่างลงไปคือเมื่อ AI ทำผิดแบบเดิมเป็นครั้งที่สอง หรือเมื่อเราพิมพ์คำอธิบายเดิมซ้ำกับที่เคยพิมพ์เมื่อ session ก่อน

ไฟล์นี้วางได้หลายระดับและถูกโหลดรวมกันทั้งหมด ไม่ใช่ทับกัน ระดับที่กว้างที่สุดคือระดับองค์กรที่ฝ่ายไอทีวางไว้ที่เครื่องทุกคนและผู้ใช้ตัดออกเองไม่ได้ ถัดมาคือระดับผู้ใช้ที่ ~/.claude/CLAUDE.md ซึ่งใช้กับทุกโปรเจกต์ของเรา ระดับโปรเจกต์ที่ ./CLAUDE.md หรือ ./.claude/CLAUDE.md ซึ่ง commit ขึ้น repo ให้ทีมใช้ร่วมกัน และระดับส่วนตัวในโปรเจกต์ที่ ./CLAUDE.local.md ซึ่งควรใส่ไว้ใน gitignore ระบบไล่อ่านขึ้นไปตามลำดับโฟลเดอร์ โดยเนื้อหาที่อยู่ใกล้จุดที่เราเปิดงานจะถูกอ่านทีหลังสุด นอกจากนี้ยังนำเข้าไฟล์อื่นด้วยไวยากรณ์ @path/to/file ได้ และสำหรับโปรเจกต์ใหญ่ยังแยกกติกาเป็นไฟล์ย่อยใน .claude/rules/ โดยกำหนดให้โหลดเฉพาะตอนทำงานกับไฟล์ที่ตรงเงื่อนไขได้ด้วย คำสั่ง /init ช่วยสร้างไฟล์ตั้งต้นให้อัตโนมัติจากการอ่านโค้ดในโปรเจกต์

จุดที่คนเข้าใจผิดบ่อยที่สุดและสำคัญที่สุดคือ CLAUDE.md เป็นบริบท ไม่ใช่การตั้งค่าที่บังคับได้ เอกสารระบุว่าเนื้อหาถูกส่งเข้าไปเป็นข้อความหลังคำสั่งระบบ โมเดลอ่านและพยายามทำตาม แต่ไม่มีการรับประกันว่าจะทำตามเคร่งครัด โดยเฉพาะเมื่อคำสั่งกำกวมหรือขัดกันเอง ถ้าต้องการบังคับให้แน่นอนต้องใช้ hook แทน คำแนะนำเชิงปฏิบัติคือเขียนให้เจาะจงพอที่จะตรวจได้ เช่น เขียนว่าใช้ย่อหน้าสองช่องแทนคำว่าจัดรูปแบบให้เรียบร้อย และคุมความยาวไม่เกิน 200 บรรทัดต่อไฟล์ เพราะไฟล์ที่ยาวกว่านั้นกินบริบทมากและทำให้การทำตามแย่ลง ถ้าเนื้อหาบานให้ย้ายส่วนที่เป็นขั้นตอนหลายชั้นไปเป็น skill ซึ่งโหลดเฉพาะตอนใช้จริง

ตัวอย่างจากบทสนทนาจริง

นักพัฒนา: "พี่ครับ CLAUDE.md ของโปรเจกต์เรายาว 600 บรรทัดแล้ว ใส่ทุกอย่างที่นึกออกเลย แต่รู้สึกว่ามันทำตามน้อยลงกว่าตอนไฟล์สั้นๆ อีก"

หัวหน้าทีม: "นั่นแหละปัญหาครับ เอกสารแนะนำให้คุมไว้ต่ำกว่า 200 บรรทัด เพราะไฟล์ยาวกินบริบทเยอะและทำให้ทำตามได้แย่ลง วิธีแก้คือแยกสามกอง กองที่เป็นข้อเท็จจริงที่ต้องรู้ทุก session เช่นคำสั่ง build ให้อยู่ต่อ กองที่เป็นขั้นตอนหลายชั้นเช่นวิธี deploy ให้ย้ายไปเป็น skill ซึ่งโหลดตอนใช้จริงเท่านั้น ส่วนกองที่ผิดแล้วเสียหายหนักให้ย้ายไปเป็น hook เพราะอันนั้นบังคับได้จริงครับ"

ระวังสับสนกับ

• agents-md : AGENTS.md เป็นไฟล์มาตรฐานกลางที่เครื่องมือหลายค่ายอ่านร่วมกัน ส่วน Claude Code อ่าน CLAUDE.md เท่านั้น ไม่ได้อ่าน AGENTS.md โดยตรง ถ้า repo มี AGENTS.md อยู่แล้ว วิธีที่เอกสารแนะนำคือสร้าง CLAUDE.md ที่นำเข้าไฟล์นั้นด้วย @AGENTS.md เพื่อไม่ต้องเขียนซ้ำสองที่
• memory-system : memory system คือส่วนที่ AI จดสิ่งที่เรียนรู้เองลงไฟล์ ส่วน CLAUDE.md เป็นสิ่งที่คนเขียนเอง ทั้งสองถูกโหลดตอนเริ่ม session เหมือนกันแต่คนละเจ้าของ อันหนึ่งเราสั่ง อีกอันมันจำ
• hook : hook เป็นชั้นบังคับที่รันจริงตามจังหวะที่กำหนด ส่วน CLAUDE.md เป็นบริบทที่โมเดลอ่านแล้วพยายามทำตาม กติกาที่ห้ามพลาดควรอยู่ที่ hook ไม่ใช่ที่นี่