CLAUDE.md là một tệp markdown đơn giản ở thư mục gốc của dự án của bạn. Claude tự động đọc nó trong mỗi phiên. Cấp độ dự án: ./CLAUDE.md. Toàn cầu (tất cả các dự án): ~/.claude/CLAUDE.md. Dự án ghi đè toàn cầu: tệp toàn cầu chứa các giá trị mặc định của bạn, tệp dự án chứa các chi tiết cụ thể của kho lưu trữ này.
Hãy coi nó như tài liệu giới thiệu bạn đưa cho một nhà thầu có kỹ năng cao nhưng không biết gì về dự án của bạn. Nếu không có nó, mỗi phiên bắt đầu với việc Claude đoán ngăn xếp của bạn, quy ước đặt tên của bạn và các quyết định trước đây của bạn. Đoán trở thành mã, mã trở thành lỗi. CLAUDE.md rút ngắn chuỗi đó. Một tệp tốt hơn một lời nhắc thông minh vì nó hoạt động cho dù bạn có nhớ hay không.
Năm phần xứng đáng với công sức của chúng. Mỗi phần từ ba đến sáu dòng gạch đầu dòng:
1. Ngăn xếp: framework, DB, auth, email, với các phiên bản. "Next.js 16, Postgres trên Neon, Resend cho email, Stripe cho thanh toán, Supabase cho auth."
2. Tuyến đường: nơi mọi thứ tồn tại. "Ứng dụng trong /app, hành động máy chủ trong /actions, API dưới /app/api/v2, các thành phần được chia sẻ trong /components/ui."
3. Quy ước: các quy tắc rõ ràng với bạn, vô hình với Claude. "Tiền bằng xu (số nguyên), ngày UTC, tên tệp kebab-case, ID là UUID v4."
4. Quy tắc bảo mật: những điều không bao giờ được xảy ra. "Không bao giờ ghi nhật ký khóa API. Tham số hóa tất cả SQL. Giới hạn tốc độ tất cả các điểm cuối công khai."
5. Đừng làm điều này: những cái bẫy bạn đã từng mắc phải. "Đừng thêm phụ thuộc mà không hỏi. Đừng chạy migration từ local lên prod."
Một mẫu đã được làm việc. Thay thế bằng chi tiết dự án thực của bạn:
# 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(*)Lưu ý sự cụ thể. "10/phút mỗi IP" là có thể thực hiện được. "Sử dụng giới hạn tốc độ" thì không.
Sai lầm đắt giá nhất: các quy tắc mơ hồ nghe có vẻ cụ thể.
Yếu: "Xử lý tiền cẩn thận." Claude sẽ xử lý tiền theo cách nó cho là tốt nhất, điều này có thể không khớp với hệ thống của bạn.
Mạnh: "Tất cả các số tiền là số nguyên xu. Không bao giờ là số thập phân. Không bao giờ hiển thị số xu thô; chia cho 100 và định dạng với ký hiệu tiền tệ." Loại lưu trữ, quy tắc xử lý, quy tắc hiển thị. Không có sự mơ hồ.
Sai lầm thứ hai: viết những khát vọng thay vì những ràng buộc. "Chúng tôi coi trọng mã sạch, dễ đọc" là một khát vọng. "Các tệp trên 200 dòng được chia thành các module" là một ràng buộc. Khát vọng đòi hỏi sự phán đoán; ràng buộc tạo ra hành vi nhất quán. Điền CLAUDE.md của bạn bằng các ràng buộc.
CLAUDE.md là một tài liệu sống. Ba tín hiệu cho thấy nó cần cập nhật:
Bạn dán cùng một ngữ cảnh vào một lời nhắc lần thứ hai. Nếu bạn nói lại điều đó, nó thuộc về CLAUDE.md.
Claude mắc lỗi mà một quy tắc lẽ ra đã ngăn chặn. Lỗi chính là quy tắc. Viết nó trước phiên tiếp theo.
Bạn giải thích một quy ước cho một đồng nghiệp. Nếu nó đáng để nói ra, nó đáng để tải tự động.
Kỷ luật độ dài: ba đến sáu dấu đầu dòng mỗi phần; quá tám, chia phần. Một CLAUDE.md quá dài để lướt qua sẽ ngừng hoạt động vì các quy tắc quan trọng bị chôn vùi. Sáu dòng đúng tốt hơn sáu mươi dòng thừa.
Mở rộng quá khoảng 300 dòng: chia thành các tệp chủ đề với các bao gồm @filename:
# CLAUDE.md (root)
@rules/stack.md
@rules/security.md
@rules/db-migrations.mdMỗi tệp chủ đề vẫn tập trung; thư mục gốc vẫn ngắn gọn.
Cam kết CLAUDE.md vào kiểm soát phiên bản. Các quy tắc trở nên có thể xem xét trong PR, và một đồng đội mới sao chép kho lưu trữ với Claude đã được cấu hình. Thêm mỗi quy tắc Don't Do This trong cùng một cam kết với bản sửa lỗi đã dạy nó. Một lưu ý: tổng quát hóa các đường dẫn cụ thể của máy trước khi cam kết.
Điều gì thuộc về CLAUDE.md so với một lời nhắc? Phạm vi ảnh hưởng. Nếu một quy tắc ngăn chặn một loại lỗi mất một giờ hoặc hơn để sửa, nó sẽ nằm trong CLAUDE.md. Các hướng dẫn cụ thể của phiên vẫn nằm trong lời nhắc.
Tạo CLAUDE.md đầu tiên của bạn trong mười phút. Đưa cho Claude lời nhắc này:
"Tôi đang thiết lập Claude Code cho một dự án với ngăn xếp này: [ngăn xếp]. Các quy ước chính mà người mới sẽ không biết: [quy ước]. Các quy tắc bảo mật không bao giờ được vi phạm: [quy tắc]. Những điều đã gây lỗi trước đây: [bẫy]. Soạn thảo một CLAUDE.md với năm phần: Ngăn xếp, Tuyến đường, Quy ước, Quy tắc bảo mật, Đừng làm điều này."
Bản nháp đầu tiên cung cấp cho bạn 80 phần trăm. Tinh chỉnh nó với những gì Claude đã bỏ lỡ; 20 phần trăm còn lại là những gì cụ thể cho trải nghiệm thực tế của bạn với dự án.
CLAUDE.md ở thư mục gốc của dự án tải ngăn xếp, tuyến đường, quy ước, quy tắc bảo mật và bẫy của bạn vào mỗi phiên. Tệp toàn cầu cho các giá trị mặc định giữa các dự án, tệp dự án để ghi đè. Ràng buộc, không phải khát vọng. Sáu dòng đúng tốt hơn sáu mươi. Cập nhật nó bất cứ khi nào Claude mắc lỗi mà một quy tắc đã viết lẽ ra đã ngăn chặn.