Viết CLAUDE.md Chuẩn Để AI Hiểu Đúng Dự Án

Không có CLAUDE.md, mỗi phiên mới Claude lại đoán lại từ đầu cấu trúc dự án của mình, đôi khi đoán sai và sửa nhầm chỗ không nên đụng vào. Từ lúc viết một file CLAUDE.md tử tế, số lần phải sửa lại vì Claude hiểu sai ngữ cảnh giảm hẳn.

CLAUDE.md là gì và được đọc khi nào?

CLAUDE.md là file Markdown đặt ở gốc dự án, được Claude Code tự nạp vào ngữ cảnh mỗi khi khởi động phiên làm việc trong thư mục đó, trước cả khi bạn gõ câu đầu tiên. Nội dung file giống bản hướng dẫn nhập môn cho người mới vào team, chỉ khác người đọc là Claude và nó đọc lại từ đầu ở mọi phiên.

📌 Chưa chắc nên chọn gì? Đọc trước Học AI: Dùng Claude, ChatGPT, Gemini Đúng Việc — hướng dẫn tổng hợp của Kudomax về học ai.

Ngoài file ở gốc dự án còn hai vị trí nữa: file ~/.claude/CLAUDE.md áp dụng cho mọi dự án trên máy bạn, và file CLAUDE.md đặt trong thư mục con, được nạp thêm khi Claude làm việc với file thuộc nhánh đó. Ba cấp này cộng dồn chứ không thay thế nhau, nên quy tắc chung để cấp cao, quy tắc riêng để đúng chỗ cần.

Một file đủ dùng gồm những mục nào?

Năm mục dưới đây đủ cho phần lớn dự án; thiếu mục nào thì Claude sẽ phải đoán đúng mục đó.

• Mô tả dự án ngắn gọn: làm gì, dùng công nghệ nào, ai là người dùng cuối.
• Quy tắc code cụ thể: quy ước đặt tên, cách xử lý lỗi, thư viện ưu tiên dùng và thư viện tránh dùng.
• Lệnh thường dùng: cách chạy test, cách build, cách khởi động server dev, để Claude không phải đoán mò từng lần.
• Việc không được tự ý làm: ví dụ không tự động commit, không xoá migration cũ, không đổi schema database mà chưa hỏi.
• Bối cảnh nghiệp vụ riêng: quy định đặc thù ngành hoặc công ty mà một AI thông thường không đoán được.

Một khung xương mình rút gọn từ file thật của dự án này, bạn thay nội dung là dùng được:

# Dự án: kudomax-nextjs
Site tiếng Việt, Next.js App Router, bài viết là JSON trong content/posts/.

## Lệnh thường dùng
- npm run dev: chạy server dev
- npm run build: build production, phải chạy trước khi báo hoàn thành

## Quy tắc
- Bài viết giữ định dạng wp:block, không đổi sang Markdown
- seo_title 40-65 ký tự, seo_description 140-160 ký tự

## Không được tự ý
- Không git commit khi chưa được yêu cầu
- Không sửa file trong public/images/

Để ý cách viết: toàn gạch đầu dòng ngắn, mỗi dòng một quy tắc kiểm chứng được. Câu kiểu viết code sạch không giúp gì vì không ai đo được thế nào là sạch; câu seo_title 40-65 ký tự thì Claude làm đúng hoặc sai rõ ràng, không có khoảng mờ để đoán.

Ba cấp CLAUDE.md khác nhau ở điểm gì?

Khác nhau ở phạm vi áp dụng và loại nội dung nên chứa, đặt sai cấp là quy tắc bị nạp thừa hoặc thiếu.

Hai tiện ích đi kèm đáng biết: một file có thể nhúng file khác bằng ký tự @ theo sau là đường dẫn, ví dụ @docs/quy-tac-api.md, để tách tài liệu dài ra ngoài mà vẫn được nạp; và bản CLAUDE.local.md không commit dành cho ghi chú riêng của bạn trong dự án chung, như đường dẫn máy cá nhân hay tài khoản test.

Cập nhật file này bằng cách nào cho tiện?

Ba đường tắt ngay trong Claude Code: lệnh /init quét cấu trúc dự án và sinh bản khởi đầu; gõ ký tự # ở đầu tin nhắn để thêm nhanh một ghi nhớ giữa phiên mà không phải mở file; lệnh /memory mở các file đang được nạp để sửa trực tiếp. Danh sách lệnh đầy đủ có trong bài 60+ slash command hữu ích cho Claude Code.

Thói quen giúp file của mình tốt lên từng tuần: mỗi lần Claude làm sai vì thiếu ngữ cảnh, sửa xong việc là thêm ngay một dòng quy tắc chặn đúng lỗi đó. File lớn dần từ lỗi thật, hiệu quả hơn hẳn ngồi tưởng tượng trước mọi tình huống ngay ngày đầu.

Ví dụ thật: một dòng quy tắc đáng giá thế nào?

Dự án này có quy tắc bài viết phải giữ định dạng wp:block trong file JSON. Trước khi ghi dòng đó vào CLAUDE.md, một lần mình nhờ Claude sửa lỗi chính tả hàng loạt, nó tiện tay chuyển hết nội dung sang Markdown cho gọn, và mình mất nguyên buổi chiều khôi phục từng bài. Từ khi có đúng một dòng quy tắc, lỗi này chưa tái diễn lần nào.

Bài học rút ra: quy tắc đáng ghi nhất không phải quy tắc nghe hay, mà là quy tắc mà vi phạm gây tốn công khôi phục. Rà lại các lần bạn từng phải sửa tay sau lưng AI, mỗi lần như vậy là một dòng nên có trong file.

Lỗi hay gặp khi viết CLAUDE.md là gì?

Hai thái cực cùng gây hại: file dài hàng nghìn dòng chép hết tài liệu công ty vào khiến Claude tốn ngữ cảnh lọc phần không liên quan, còn file toàn câu chung chung thì không đưa ra được chỉ dẫn nào dùng được. Viết đúng mức: đủ chi tiết để không phải đoán, đủ ngắn để đọc lại nhanh. File này được nạp ở mọi phiên nên độ dài của nó cũng là chi phí, mỗi dòng phải trả tiền token cho chính nó.

• Nhét bí mật vào file: API key, mật khẩu tuyệt đối không để đây, nội dung file được gửi kèm mọi request lên mô hình.
• Để file lỗi thời: quy tắc cũ chưa xoá khiến Claude làm theo cách đã bỏ, lỗi loại này rất khó truy vì ai cũng quên file có dòng đó.
• Trùng việc với linter: quy tắc format code để linter và hook lo, CLAUDE.md chỉ giữ phần công cụ máy không kiểm được.
• Nhồi quy trình nhiều bước: chuỗi thao tác cố định hợp với Skill hơn, file này chỉ nên giữ quy tắc nền.

Ranh giới đơn giản để chọn chỗ đặt: dùng CLAUDE.md nếu quy tắc cần áp dụng ở mọi phiên; dùng Skill riêng nếu là quy trình nhiều bước chỉ thỉnh thoảng mới chạy.

Bước tiếp theo cho bạn: mở dự án đang làm, chạy /init nếu chưa có file, rồi cắt bản tự sinh xuống còn khoảng 30 dòng theo năm mục ở trên. Sau đó cứ mỗi lần Claude làm sai vì thiếu ngữ cảnh, thêm một dòng. Một tháng sau bạn sẽ có file chuẩn hơn bất kỳ mẫu nào chép trên mạng.