CLAUDE.md คือไฟล์ markdown ธรรมดาที่อยู่ใน root ของโปรเจกต์ของคุณ Claude จะอ่านไฟล์นี้โดยอัตโนมัติทุกเซสชัน ระดับโปรเจกต์: ./CLAUDE.md ทั่วโลก (ทุกโปรเจกต์): ~/.claude/CLAUDE.md ไฟล์โปรเจกต์จะแทนที่ไฟล์ทั่วโลก: ไฟล์ทั่วโลกจะเก็บค่าเริ่มต้นของคุณ ส่วนไฟล์โปรเจกต์จะเก็บรายละเอียดเฉพาะของ repo นี้
ลองนึกภาพว่ามันเป็นเอกสารแนะนำที่คุณมอบให้กับผู้รับเหมาที่มีทักษะสูงแต่ไม่รู้อะไรเกี่ยวกับโปรเจกต์ของคุณเลย หากไม่มีเอกสารนี้ ทุกเซสชันจะเริ่มต้นด้วย Claude ที่เดาสแต็กของคุณ, ข้อตกลงการตั้งชื่อของคุณ และการตัดสินใจในอดีตของคุณ การเดาจะกลายเป็นโค้ด โค้ดจะกลายเป็นบั๊ก CLAUDE.md จะช่วยลดขั้นตอนนั้น ไฟล์ดีกว่า prompt ที่ฉลาด เพราะมันทำงานได้ไม่ว่าคุณจะจำได้หรือไม่ก็ตาม
ห้าส่วนที่คุ้มค่าแก่การมีอยู่ แต่ละส่วนมีสามถึงหกบรรทัด:
1. Stack: เฟรมเวิร์ก, DB, การยืนยันตัวตน, อีเมล, พร้อมเวอร์ชัน "Next.js 16, Postgres บน Neon, Resend สำหรับอีเมล, Stripe สำหรับการชำระเงิน, Supabase สำหรับการยืนยันตัวตน"
2. Routes: ที่อยู่ของสิ่งต่างๆ "App อยู่ใน /app, server actions อยู่ใน /actions, API อยู่ภายใต้ /app/api/v2, shared components อยู่ใน /components/ui"
3. Conventions: กฎที่ชัดเจนสำหรับคุณ แต่ Claude มองไม่เห็น "เงินเป็นหน่วยเซ็นต์ (int), วันที่เป็น UTC, ชื่อไฟล์เป็น kebab-case, ID เป็น UUID v4"
4. Security Rules: สิ่งที่ไม่ควรเกิดขึ้นเด็ดขาด "ห้ามบันทึก API keys. กำหนดพารามิเตอร์ SQL ทั้งหมด. จำกัดอัตราการเรียกใช้ (rate-limit) ทุก public endpoints"
5. Don't Do This: ข้อผิดพลาดที่คุณเคยเจอมาแล้ว "ห้ามเพิ่ม deps โดยไม่ขออนุญาต. ห้ามรัน migrations จาก local ไปยัง prod."
เทมเพลตที่ใช้งานได้จริง. แทนที่ด้วยรายละเอียดโปรเจกต์จริงของคุณ:
# Plinko Grant Tracker
## Stack
- Next.js 16, Postgres (Neon), Resend, Stripe
- Auth: Supabase Auth with Google OAuth
## Routes
- App in /app, actions in /actions, API under /app/api/v2
## Conventions
- Money in cents (int), dates UTC, filenames kebab-case
- IDs: UUID v4. Boolean columns: is_ or has_ prefix
## Security Rules
- Never log secrets, parameterize SQL
- Rate-limit all POST/PUT/DELETE endpoints (10/min per IP)
- New Supabase tables ship with RLS policies in same commit
## Don't Do This
- Don't add deps without asking
- Don't run migrations from local against prod
- Don't use select(*)สังเกตความเฉพาะเจาะจง. "10/min per IP" สามารถนำไปปฏิบัติได้. "ใช้ rate limiting" ไม่ใช่.
ข้อผิดพลาดที่แพงที่สุด: กฎที่คลุมเครือที่ฟังดูเฉพาะเจาะจง
อ่อนแอ: "จัดการเงินอย่างระมัดระวัง" Claude จะจัดการเงินในแบบที่คิดว่าดีที่สุด ซึ่งอาจไม่ตรงกับระบบของคุณ
แข็งแกร่ง: "จำนวนเงินทั้งหมดเป็นจำนวนเต็มเซ็นต์ ห้ามใช้ทศนิยม ห้ามแสดงจำนวนเซ็นต์ดิบ; ให้หารด้วย 100 และจัดรูปแบบด้วยสัญลักษณ์สกุลเงิน" ประเภทการจัดเก็บ, กฎการประมวลผล, กฎการแสดงผล ไม่มีความคลุมเครือ
ข้อผิดพลาดที่สอง: การเขียนความปรารถนาแทนที่จะเป็นข้อจำกัด "เราให้ความสำคัญกับโค้ดที่สะอาดและอ่านง่าย" คือความปรารถนา "ไฟล์ที่มีมากกว่า 200 บรรทัดจะถูกแบ่งเป็นโมดูล" คือข้อจำกัด ความปรารถนาต้องใช้การตัดสินใจ; ข้อจำกัดทำให้เกิดพฤติกรรมที่สอดคล้องกัน เติม CLAUDE.md ของคุณด้วยข้อจำกัด
CLAUDE.md เป็นเอกสารที่มีชีวิตชีวา สามสัญญาณที่บ่งบอกว่าต้องอัปเดต:
คุณวางบริบทเดียวกันลงใน prompt เป็นครั้งที่สอง หากคุณพูดซ้ำอีกครั้ง แสดงว่ามันควรอยู่ใน CLAUDE.md
Claude ทำผิดพลาดที่กฎน่าจะป้องกันได้ ความผิดพลาดคือกฎ เขียนมันก่อนเซสชันถัดไป
คุณอธิบายข้อตกลงกับเพื่อนร่วมงาน หากคุ้มค่าที่จะพูดออกไป ก็คุ้มค่าที่จะโหลดโดยอัตโนมัติ
ระเบียบวินัยด้านความยาว: สามถึงหกหัวข้อย่อยต่อส่วน; เกินแปด ให้แยกส่วน CLAUDE.md ที่ยาวเกินกว่าจะอ่านคร่าวๆ จะหยุดทำงานเพราะกฎสำคัญจะถูกฝังอยู่ หกบรรทัดที่ถูกต้องดีกว่าหกสิบบรรทัดที่ซ้ำซ้อน
การขยายขนาดเกินประมาณ 300 บรรทัด: แยกเป็นไฟล์หัวข้อด้วยการรวม @filename:
# CLAUDE.md (root)
@rules/stack.md
@rules/security.md
@rules/db-migrations.mdแต่ละไฟล์หัวข้อจะยังคงเน้นเฉพาะเรื่อง; ไฟล์ root จะยังคงสั้น
Commit CLAUDE.md ไปยังระบบควบคุมเวอร์ชัน กฎจะสามารถตรวจสอบได้ใน PRs และเพื่อนร่วมทีมใหม่จะโคลน repo โดยที่ Claude ได้รับการกำหนดค่าไว้แล้ว เพิ่มกฎ Don't Do This แต่ละข้อใน commit เดียวกันกับการแก้ไขบั๊กที่สอนกฎนั้น ข้อควรระวัง: ทำให้เส้นทางเฉพาะของเครื่องเป็นแบบทั่วไปก่อนที่จะ commit
อะไรที่ควรอยู่ใน CLAUDE.md เทียบกับ prompt? รัศมีการระเบิด หากกฎป้องกันข้อผิดพลาดประเภทหนึ่งที่ใช้เวลาแก้ไขหนึ่งชั่วโมงขึ้นไป มันจะอยู่ใน CLAUDE.md คำแนะนำเฉพาะเซสชันจะอยู่ใน prompts
สร้าง CLAUDE.md แรกของคุณในสิบนาที ให้ Claude ใช้ prompt นี้:
"ฉันกำลังตั้งค่า Claude Code สำหรับโปรเจกต์ที่มีสแต็กนี้: [stack] ข้อตกลงสำคัญที่คนใหม่จะไม่รู้: [conventions] กฎความปลอดภัยที่ไม่ควรละเมิดเด็ดขาด: [rules] สิ่งที่เคยทำให้เกิดบั๊กมาก่อน: [traps] ร่าง CLAUDE.md ที่มีห้าส่วน: Stack, Routes, Conventions, Security Rules, Don't Do This"
ฉบับร่างแรกจะให้คุณ 80 เปอร์เซ็นต์ ปรับปรุงด้วยสิ่งที่ Claude พลาดไป; อีก 20 เปอร์เซ็นต์ที่เหลือคือสิ่งที่เฉพาะเจาะจงกับประสบการณ์จริงของคุณกับโปรเจกต์
CLAUDE.md ที่ root ของโปรเจกต์จะโหลดสแต็ก, เส้นทาง, ข้อตกลง, กฎความปลอดภัย และข้อผิดพลาดของคุณเข้าสู่ทุกเซสชัน ไฟล์ทั่วโลกสำหรับค่าเริ่มต้นข้ามโปรเจกต์, ไฟล์โปรเจกต์สำหรับการแทนที่ ข้อจำกัด ไม่ใช่ความปรารถนา หกบรรทัดที่ถูกต้องดีกว่าหกสิบ อัปเดตเมื่อใดก็ตามที่ Claude ทำผิดพลาดที่กฎที่เขียนไว้จะป้องกันได้