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ì

Là một file Markdown đặt ở gốc dự án, Claude Code tự đọc mỗi khi khởi động phiên làm việc trong thư mục đó. Nội dung file đóng vai trò như bản hướng dẫn nhập môn cho một người mới vào dự án, chỉ khác là người đọc ở đây là Claude.

📌 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.

Cấu trúc một file đủ dùng

• 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.

Lỗi thường gặp: viết quá dài hoặc quá chung chung

File dài hàng nghìn dòng chép hết tài liệu công ty vào không giúp ích gì. Claude vẫn phải lọc ra phần liên quan, tốn ngữ cảnh cho phần không cần. Ngược lại, viết "code sạch, dễ đọc" quá chung chung thì không đưa ra được chỉ dẫn cụ thể nào. Viết đúng mức: đủ chi tiết để không phải đoán, đủ ngắn để đọc lại nhanh.

Nếu dự án có nhiều quy trình lặp lại cố định ngoài phạm vi CLAUDE.md, cân nhắc thêm Skill riêng cho từng quy trình cụ thể thay vì nhồi hết vào một file.