CLAUDE.md: viết gì, đặt ở đâu và kiểm tra Claude đã đọc

Bạn sửa cùng một lỗi của Claude Code ba session liên tiếp: nó chạy test sai thư mục, hoặc đụng vào src/generated/ mà bạn đã dặn để yên. Mỗi session mở ra với context window trắng, nên lời dặn hôm qua không còn ở đó. CLAUDE.md là chỗ ghi lại — dưới đây là vị trí đặt file, nội dung nên viết, và cách kiểm tra Claude có thực sự đọc nó.

CLAUDE.md là context, không phải config

CLAUDE.md là file markdown chứa chỉ dẫn mà Claude Code đọc ở đầu mỗi session: lệnh build, quy ước, và các luật nó không suy ra được từ code. Nguyên tắc gói trong một câu: ngắn, cụ thể, commit vào git.

Ranh giới quan trọng nhất nằm ở chữ "context": Claude đọc file và cố gắng tuân theo, nhưng đây không phải cấu hình được cưỡng chế. Việc bắt buộc phải chạy đúng mỗi lần — ví dụ một bước kiểm tra trước mỗi commit — thuộc về hooks, tức lệnh shell chạy ở những điểm cố định. Permissions, hooks và biến môi trường của project nằm trong file settings như .claude/settings.json.

Hai thứ mang kiến thức qua session: CLAUDE.md chứa chỉ dẫn do bạn viết, auto memory chứa ghi chú Claude tự viết từ những lần bạn sửa nó. Cả hai cùng nạp lúc khởi động. Chưa có file thì chạy /init: Claude đọc codebase rồi viết CLAUDE.md với lệnh build, hướng dẫn test và quy ước nó tìm thấy; nếu file đã tồn tại, /init đề xuất cải thiện thay vì ghi đè.

Bốn vị trí, bốn phạm vi — và không file nào ghi đè file nào

Phạm vi	Vị trí	Áp dụng cho ai
Managed policy	/Library/Application Support/ClaudeCode/CLAUDE.md (macOS), /etc/claude-code/CLAUDE.md (Linux và WSL)	Mọi người trong tổ chức
User	~/.claude/CLAUDE.md	Bạn, ở mọi project
Project	./CLAUDE.md hoặc ./.claude/CLAUDE.md	Team của bạn, qua source control
Local	./CLAUDE.local.md	Bạn, trong project này — nhớ thêm vào .gitignore

Claude Code nạp CLAUDE.md và CLAUDE.local.md từ thư mục làm việc và mọi thư mục cấp trên ngay khi khởi động; file trong thư mục con nạp muộn hơn, lúc Claude đọc file ở chính những thư mục đó. Vậy file nào thắng? Không file nào. Claude Code nối tất cả file nó tìm thấy thay vì cho file này đè file kia. Thứ tự chạy từ rộng đến hẹp — managed, rồi user, rồi project — còn theo cây thư mục thì từ gốc xuống nơi bạn khởi động Claude, nên file gần nhất được đọc sau cùng.

Hệ quả: xung đột là việc của bạn, không phải của công cụ — tài liệu ghi rõ nếu hai luật mâu thuẫn, Claude có thể chọn tùy ý. Trong monorepo, setting claudeMdExcludes bỏ qua CLAUDE.md của team khác theo path hoặc glob.

Viết gì vào, bỏ gì ra

Nên có	Nên bỏ
Lệnh bash Claude không thể đoán	Thứ Claude tự suy ra được khi đọc code
Quy ước code khác với mặc định	Quy ước ngôn ngữ tiêu chuẩn Claude đã biết
Hướng dẫn test và test runner ưu tiên	Tài liệu API chi tiết (hãy link ra ngoài)
Quy ước repo: đặt tên branch, quy tắc PR	Thông tin thay đổi liên tục
Quyết định kiến trúc riêng của project	Giải thích dài hoặc tutorial
Quirk môi trường dev, biến môi trường bắt buộc	Mô tả từng file trong codebase
Gotcha, hành vi không hiển nhiên	Lời khuyên kiểu "viết code sạch"

Bốn luật viết đáng nhớ. Nhắm dưới 200 dòng mỗi file — file dài tốn context và làm giảm mức độ tuân thủ. Cụ thể đến mức kiểm chứng được: "Run npm test before committing" thay vì "Test your changes". Nhấn mạnh tiết kiệm: nếu Claude cứ bỏ qua đúng một chỉ dẫn, thêm "IMPORTANT" cho riêng dòng đó, vì nhấn mạnh cả chục dòng thì không dòng nào nổi bật. Và test từng dòng bằng câu hỏi "bỏ dòng này Claude có làm sai không"; nếu không, cắt.

Thêm vào file khi một lời sửa lặp lại — Claude mắc cùng lỗi hai lần, hoặc bạn gõ lại đúng câu sửa của session trước. Ngược lại, chỉ dẫn hẹp nên chuyển đi: thủ tục nhiều bước thuộc về skills (nạp theo yêu cầu), luật cho một phần codebase thuộc về .claude/rules/, scope theo path khớp. Ghi chú dành cho người thì đặt trong HTML comment dạng block — chúng bị lược bỏ trước khi Claude nhìn thấy file.

Import @path và AGENTS.md: hai bẫy context

CLAUDE.md kéo file khác vào bằng @path/to/file. Đường dẫn tương đối tính từ chính file chứa import, và import lồng được tối đa bốn cấp. Đường dẫn nằm trong backtick hoặc code block thì được bỏ qua. Bẫy nằm ở chỗ: import giúp bạn tổ chức file, nhưng không tiết kiệm context — file được import nạp ngay lúc khởi động cùng với CLAUDE.md trỏ tới nó. Lần đầu project import một file nằm ngoài thư mục làm việc, Claude Code sẽ hỏi bạn duyệt.

Bẫy thứ hai cho repo đã có AGENTS.md: Claude Code chỉ đọc AGENTS.md khi không có CLAUDE.md hoặc CLAUDE.local.md trong thư mục làm việc hay cấp trên. Muốn giữ cả hai, đặt @AGENTS.md ở đầu CLAUDE.md rồi viết phần riêng cho Claude bên dưới.

Kiểm tra Claude có đọc file không

Chạy /context và nhìn mục Memory files. Nếu một CLAUDE.md không nằm trong danh sách đó thì Claude không thấy nó — đừng mất công viết lại nội dung. Chạy /memory để liệt kê vị trí CLAUDE.md, CLAUDE.local.md và auto memory, rồi mở file trong editor.

Chi tiết đáng nhớ cho session dài: sau /compact, Claude đọc lại CLAUDE.md ở gốc project từ đĩa nên chỉ dẫn trong file sống sót, còn chỉ dẫn bạn chỉ nói trong hội thoại thì không. Nói "remember" sẽ lưu vào auto memory; muốn vào CLAUDE.md, hãy nói "add this to CLAUDE.md" hoặc tự sửa file.

Lớp thứ hai: phân loại sự cố trước khi nhờ agent sửa

CLAUDE.md giữ context thường trực, còn context theo từng sự cố đang tới tay agent nhanh hơn trước. Ngày 30/9, Cloudflare mở beta công khai Issues for Workers: nó gom exception lặp lại, lỗi server và error log, rồi gửi được diagnostic context sang một coding agent đã cấu hình, kèm version của Worker bị ảnh hưởng. Cloudflare mô tả luồng trong đó agent đề xuất bản sửa còn chủ sở hữu review và deploy.

Tác giả bài phân tích về tính năng này rút ra bài học không phải "app tự bảo trì được rồi", mà là lỗi giờ đến tay AI nhanh hơn, nên bạn cần quyết định tốt hơn về việc AI nên làm gì tiếp theo. Theo tác giả, nên phân loại sự cố trước khi yêu cầu vá — nếu không, "làm lỗi biến mất" sẽ lặng lẽ thành "gỡ bỏ chính cái luật đang bảo vệ app".

Đây là chỗ hai lớp gặp nhau — và là phán đoán biên tập, không phải khuyến nghị từ nguồn: phần "hành vi đã cam kết" của hệ thống xứng đáng nằm trong CLAUDE.md. Khi agent có sẵn mô tả hành vi đúng, nó mới có cơ sở phân biệt bug thật với một lần hệ thống từ chối đúng luật.

Làm gì trong 30 phút tới

1. Chạy /context trên project chính. Nếu CLAUDE.md không xuất hiện dưới Memory files, sửa vị trí file trước đã.
2. Đếm số dòng. Trên 200 thì cắt: chuyển thủ tục nhiều bước sang skills, chuyển luật theo thư mục sang .claude/rules/.
3. Rà từng dòng bằng câu hỏi "bỏ dòng này Claude có làm sai không"; dòng nào không trả lời được thì xóa.
4. Tìm trong chat tuần trước câu sửa bạn đã gõ từ hai lần trở lên, viết nó vào file.