Trả lời nhanh: CLAUDE.md là file văn bản đặt trong dự án, được Claude Code tự đọc vào đầu mỗi phiên làm việc. Nó trả lời giúp bạn ba câu mà agent luôn cần: dự án này chạy bằng lệnh gì, code viết theo quy ước nào, và tuyệt đối không được đụng vào đâu. Viết đúng file này là cách rẻ nhất để agent làm đúng ngay từ lượt đầu, thay vì bạn phải nhắc lại mỗi lần mở phiên mới.
Ai dùng Claude Code vài ngày cũng gặp cảnh này: sáng bảo agent chạy test bằng pnpm, chiều mở phiên mới nó lại gõ npm; hôm qua dặn đừng sửa thư mục migration, hôm nay nó sửa. Không phải agent đãng trí, mà vì mỗi phiên là một trang giấy trắng. CLAUDE.md chính là trang giấy bạn để sẵn trên bàn cho nó đọc trước khi bắt tay vào việc. Bài này chỉ cách viết file đó sao cho ngắn mà hiệu quả, kèm những lỗi khiến file dài ra nhưng agent lại càng làm sai.
Claude Code đọc file này lúc nào và vì sao nó quan trọng
Khi bạn mở Claude Code trong một thư mục, nó tìm CLAUDE.md ở gốc dự án và nạp nội dung vào ngữ cảnh trước khi nghe yêu cầu đầu tiên của bạn. Nói cách khác, file này là phần duy nhất trong dự án mà agent chắc chắn đọc, kể cả khi repo có hàng nghìn file mà nó chưa mở tới.
Hệ quả rất thực tế: những gì bạn phải nhắc đi nhắc lại mỗi phiên đều nên nằm trong đó. Đội nào cũng có một danh sách như vậy, thường là dùng trình quản lý gói nào, lệnh test là gì, thư mục nào do máy sinh ra nên đừng sửa tay, quy ước đặt tên ra sao. Không có file, bạn trả tiền hai lần cho cùng một thông tin: một lần bằng thời gian gõ lại, một lần bằng những lượt agent làm sai rồi phải sửa.
Nếu bạn chưa từng chạy Claude Code, đọc trước bài Claude Code là gì rồi quay lại, vì phần dưới đây giả định bạn đã mở được phiên đầu tiên.
Ba phần bắt buộc, kèm mẫu dùng được ngay
Một CLAUDE.md tốt hiếm khi dài quá một trang. Mẫu dưới đây là bộ khung tối thiểu, sửa lại theo dự án của bạn:
# Dự án: cửa hàng bán lẻ, Next.js + Postgres ## Lệnh hay dùng- Cài gói: pnpm install (KHÔNG dùng npm hay yarn)- Chạy dev: pnpm dev- Chạy test: pnpm test, chạy một file: pnpm test path/to/file- Kiểm kiểu: pnpm typecheck ## Quy ước code- TypeScript strict, không dùng any- Component đặt trong src/components, tên PascalCase- Truy vấn database chỉ qua src/db, không gọi SQL trực tiếp trong route- Mọi thay đổi schema phải kèm file migration ## Tuyệt đối không- Không sửa thư mục src/generated (do máy sinh)- Không commit file .env- Không chạy lệnh xóa dữ liệu trên database thật- Không tự đổi phiên bản thư viện lớn nếu chưa hỏiBa khối này giải quyết ba loại lỗi khác nhau. Khối lệnh chặn việc agent đoán sai công cụ, thứ gây lãng phí nhiều nhất vì nó thất bại rồi thử lại vòng vòng. Khối quy ước giữ code mới giống code cũ, để bạn không phải sửa phong cách sau mỗi lần agent viết. Khối điều cấm là cái quan trọng nhất, vì nó chặn những hành động khó hoàn tác.
Viết ngắn và cụ thể, đó là kỹ thuật thật sự
Điều nhiều người làm sai là biến CLAUDE.md thành tài liệu dự án. Nhớ rằng file này được nạp vào mọi lượt gọi, nên mỗi dòng thừa là tiền trả thêm suốt vòng đời dự án, và tệ hơn, nó pha loãng những dòng thật sự quan trọng.
Nguyên tắc viết: mỗi dòng phải là một câu lệnh hành vi mà agent kiểm chứng được, không phải một lời khuyên chung chung. So sánh nhanh:
- Kém: viết code sạch, dễ bảo trì. Agent không biết bạn muốn gì.
- Tốt: hàm dài quá 50 dòng thì tách, mỗi file export tối đa một component.
- Kém: cẩn thận với database.
- Tốt: không chạy lệnh nào ghi vào database production, chỉ dùng file .env.local.
Mẹo giữ file gọn theo thời gian: mỗi khi bạn phải sửa lại việc agent làm sai, hãy hỏi liệu có dòng nào ngăn được lỗi đó không, rồi thêm đúng một dòng. Ngược lại, mỗi tháng đọc lại và xóa những dòng không còn đúng. File sống là file được cắt tỉa, không phải file chỉ dày lên.
Phân tầng file cho dự án lớn và cho cá nhân
Với monorepo hoặc dự án có nhiều phần rất khác nhau, đặt CLAUDE.md ở gốc cho luật chung, rồi đặt file riêng trong từng thư mục con cho luật cục bộ. Khi agent làm việc trong thư mục con, luật cục bộ được nạp thêm, nên bạn không phải nhồi mọi thứ vào một chỗ:
CLAUDE.md # luật chung cả repoapps/web/CLAUDE.md # quy ước riêng cho frontendapps/api/CLAUDE.md # quy ước riêng cho backendpackages/ui/CLAUDE.md # quy tắc đặt tên componentCòn những thứ chỉ là sở thích của riêng bạn, ví dụ muốn agent trả lời bằng tiếng Việt hay luôn giải thích trước khi sửa, thì đừng nhét vào file chung của repo. Đội của bạn không nhất thiết muốn như vậy, và commit những dòng đó vào Git chỉ tạo tranh cãi vô ích. Claude Code có chỗ cho cấu hình cá nhân nằm ngoài repo, dùng đúng chỗ đó.
Một điểm hay bị quên: CLAUDE.md nên được commit vào Git như mọi file mã nguồn khác. Nó là tài sản chung, người mới vào dự án đọc file này cũng nắm được quy ước nhanh hơn đọc wiki, và mọi thay đổi luật đều có lịch sử.
Khi luật đã chuẩn thì việc tiếp theo là cho agent chỗ chạy
File luật tốt mở ra một khả năng mà nhiều người chưa tận dụng: giao việc dài cho agent rồi đi làm chuyện khác. Khi agent đã biết lệnh test, biết quy ước và biết vùng cấm, bạn có thể để nó tự chạy trọn một nhiệm vụ nhiều bước mà không cần ngồi canh từng lượt.
Lúc đó vấn đề chuyển từ chất lượng sang chỗ chạy. Việc dài mà chạy trên laptop thì gập máy là đứt, mạng rớt là mất phiên, và quạt gào suốt buổi. Cách nhiều dev Việt đang dùng là để agent chạy trên một VPS luôn bật, giữ phiên bằng tmux theo bài tmux, hoặc chạy hẳn chế độ không giao diện như bài chạy Claude Code headless. Cần nhiều agent làm song song trên cùng một repo thì tách bằng git worktree. Muốn đi xa hơn nữa, hãy biến luôn máy chủ đó thành máy dev từ xa để vừa gõ code vừa để agent chạy trên cùng một chỗ. Một ví dụ áp dụng file luật vào dự án thật nằm ở bài tùy biến WooCommerce bằng Claude Code.
Thứ tự đúng vẫn là luật trước, hạ tầng sau. Một agent chưa có CLAUDE.md mà cho chạy tự do cả đêm thì sáng ra bạn nhận về một đống thay đổi phải soát lại từ đầu.
Luật tốt và luật vô dụng, đặt cạnh nhau
# Luat TOT: cu the, kiem chung duoc- Moi ham xu ly tien dung so nguyen don vi dong, khong dung so thuc- Truy van co so du lieu phai dung tham so, khong noi chuoi- Khong tao file moi khi co the sua file san co trong cung thu muc- Truoc khi sua, doc file lien quan de theo dung quy uoc hien co- Comment viet bang tieng Viet khong dau, khong tron tieng Anh # Luat KEM: chung chung, khong kiem chung duoc- Viet code sach- Tuan thu best practice- Toi uu hieu nangNguyên tắc kiểm: một luật tốt là luật mà bạn đọc một đoạn mã và nói được ngay là có tuân thủ hay không. Luật không kiểm chứng được thì trợ lý cũng không áp dụng được, và nó chỉ chiếm chỗ.
Ba lỗi hay gặp
| Lỗi | Hậu quả | Cách sửa |
|---|---|---|
| Viết quá dài, hàng trăm dòng | Trợ lý bỏ qua phần lớn | Giữ dưới khoảng 30 dòng cho phần dùng chung |
| Các luật mâu thuẫn nhau | Trợ lý chọn ngẫu nhiên | Rà lại mỗi khi thêm luật mới |
| Chép luật từ dự án khác | Không khớp với thực tế dự án này | Xây từ chính các lỗi lặp lại của bạn |
| Ghi khóa hoặc mật khẩu vào tệp | Tệp này nằm trong kho mã nguồn | Không bao giờ ghi bí mật vào đây |
Cách xây bộ luật thật sự hữu ích
- Bắt đầu bằng tệp trống. Đừng chép mẫu từ nơi khác.
- Mỗi lần bạn phải sửa cùng một loại lỗi lần thứ ba, viết nó thành một luật. Bộ luật xây theo cách này luôn hữu ích hơn bộ luật chép sẵn.
- Sau một tháng, rà lại: luật nào không còn đúng thì xóa.
- Với dự án của khách hàng, thêm phần ràng buộc: tệp nào không được đụng, thư mục nào không được đọc.
Giới hạn: nó không phải phép màu
- Không thay được việc kiểm tự động. Thứ bắt buộc phải nằm trong công cụ kiểm định dạng và kiểm kiểu, không nằm trong tệp luật.
- Không thay được việc đọc mã trước khi ghép vào nhánh chính.
- Không bảo đảm trợ lý tuân thủ 100%. Nó giảm số lần phải sửa, không loại bỏ hoàn toàn.
Câu hỏi thường gặp
CLAUDE.md có làm tốn thêm token không?
Có, vì nội dung file được nạp vào ngữ cảnh ở mọi lượt. Nhưng đây là khoản chi rẻ hơn nhiều so với việc agent đoán sai rồi thử lại: một file nửa trang thường tốn vài trăm token, trong khi một lần chạy sai lệnh cài gói có thể đốt gấp hàng chục lần con số đó.
Nên viết CLAUDE.md bằng tiếng Việt hay tiếng Anh?
Cả hai đều được vì model hiểu tốt tiếng Việt. Kinh nghiệm thực dụng là viết tên lệnh, tên thư mục và tên quy ước bằng nguyên văn tiếng Anh, còn phần giải thích thì tiếng Việt cho cả đội dễ đọc. Quan trọng hơn ngôn ngữ là mức độ cụ thể.
Có nên nhờ chính Claude Code viết file này không?
Nên dùng nó để dựng bản nháp đầu tiên bằng cách yêu cầu đọc repo rồi tóm tắt lệnh và quy ước phát hiện được. Nhưng phải tự đọc lại và cắt, vì bản nháp máy sinh thường dài và chứa những điều hiển nhiên. Phần điều cấm thì bắt buộc bạn tự viết.
Sửa CLAUDE.md xong có cần khởi động lại phiên không?
Phiên đang chạy đã nạp bản cũ vào ngữ cảnh, nên cách chắc chắn nhất là mở phiên mới cho lần làm việc kế tiếp. Với thay đổi quan trọng như thêm một điều cấm, đừng tin phiên cũ sẽ tự cập nhật.