CLAUDE.md là bộ nhớ hướng dẫn có chủ đích của dự án: kiến trúc, lệnh thường dùng, quy ước và giới hạn. Nó không phải cơ chế cưỡng chế bảo mật, nhưng giúp Claude Code nhận đúng bối cảnh ngay từ đầu. Tài liệu chính thức khuyến nghị viết cụ thể, có cấu trúc và thường giữ dưới khoảng 200 dòng.
Kết quả sau bài học: Bạn sẽ tạo CLAUDE.md dùng chung, phân biệt CLAUDE.local.md cá nhân và biết dùng /memory để kiểm tra tệp nào đang được nạp.
Tư duy quan trọng trước khi bắt đầu
AI coding agent là cộng sự có khả năng thao tác, không phải nguồn chân lý. Bạn vẫn chịu trách nhiệm về mã được đưa vào dự án. Hãy giữ nhiệm vụ nhỏ, cung cấp bối cảnh vừa đủ, yêu cầu bằng chứng và không phê duyệt điều mình chưa hiểu.
Hướng dẫn từng bước
Bước 1: Chọn đúng loại tệp
Đặt ./CLAUDE.md hoặc ./.claude/CLAUDE.md cho quy tắc chia sẻ qua Git. Dùng ./CLAUDE.local.md cho URL sandbox hoặc ghi chú riêng và thêm vào .gitignore. Tùy chọn người dùng ~/.claude/CLAUDE.md áp dụng rộng hơn.
Bước 2: Tạo khung bằng /init rồi biên tập
Lệnh /init có thể phân tích repository và tạo điểm bắt đầu. Đừng giữ nguyên một cách máy móc: kiểm tra lệnh, loại bỏ mô tả hiển nhiên và bổ sung quyết định kiến trúc mà công cụ không thể suy ra.
Bước 3: Viết hướng dẫn ngắn và đo được
Chia thành Project map, Commands, Code style, Testing, Do not và Definition of done. “Chạy npm test trước commit” tốt hơn “hãy kiểm tra kỹ”. Không đặt token, mật khẩu hoặc dữ liệu cá nhân.
Bước 4: Tổ chức dự án lớn
Tệp ở thư mục cha được nạp khi khởi động; tệp trong thư mục con có thể được nạp khi Claude đọc khu vực đó. Có thể dùng cú pháp @path để import tài liệu, nhưng import vẫn tiêu thụ context; chỉ đưa nội dung cần ở mỗi phiên.
Bước 5: Kiểm tra khi Claude không tuân thủ
Chạy /memory để xem tệp đã nạp. Tìm quy tắc mâu thuẫn, rút câu mơ hồ thành chỉ dẫn cụ thể và kiểm tra đường dẫn. Điều bắt buộc phải chặn nên cấu hình bằng permissions/hooks, không chỉ viết lời nhắc.
Bài thực hành có đầu ra rõ ràng
Bài tập: viết CLAUDE.md cho ứng dụng Express dùng npm, có lệnh npm test, quy tắc validate đầu vào ở route boundary, cấm sửa migrations cũ và định nghĩa hoàn thành gồm test + lint.
Tiêu chuẩn nộp bài: lưu prompt đã dùng, ảnh hoặc log kết quả trước/sau, diff cuối cùng, lệnh kiểm tra và ba điều bạn tự học được từ mã. Nếu test không chạy được, ghi lý do thay vì coi như đã đạt.
Prompt mẫu có thể sao chép
Đọc các tệp hướng dẫn hiện được nạp và tóm tắt theo Project map, Commands, Conventions, Do-not. Chưa sửa code.
Review CLAUDE.md này theo tiêu chí: cụ thể, không mâu thuẫn, dưới 200 dòng và mọi lệnh có thể chạy.
Đề xuất phần nào nên chuyển sang CLAUDE.local.md hoặc permission rule vì không phù hợp chia sẻ trong repository.
Lỗi người mới thường gặp
- Đưa toàn bộ README và kiến trúc dài vào context mọi phiên
- Dùng CLAUDE.md như hàng rào bảo mật cứng
- Quy tắc cá nhân được commit cho cả đội
- Không cập nhật lệnh sau khi đổi package manager
Checklist hoàn thành
- Đúng loại tệp và phạm vi
- Không chứa bí mật
- Lệnh chính xác
- Quy tắc cụ thể, không mâu thuẫn
- Đã xác nhận bằng /memory
Cách tự học để không phụ thuộc AI
- Trước khi hỏi, tự dự đoán tệp và nguyên nhân trong năm phút.
- Sau câu trả lời, yêu cầu giải thích một khái niệm bạn chưa hiểu bằng ví dụ nhỏ.
- Tự viết lại phần cốt lõi hoặc test mà không nhìn câu trả lời.
- Lưu lỗi và bài học vào ghi chú dự án, không lưu bí mật.
- Một tuần sau, làm lại bài tập với yêu cầu hơi khác.
Kết luận: dùng tác nhân AI tốt không nằm ở việc tạo nhiều code, mà ở khả năng đặt mục tiêu rõ, kiểm soát phạm vi và chứng minh kết quả. Nếu giữ được vòng lặp đọc → kế hoạch → thay đổi nhỏ → test → review, người mới vừa đi nhanh hơn vừa thực sự tiến bộ.
Nguồn tham khảo chính thức: tài liệu sản phẩm dành cho nhà phát triển. Giao diện và tính năng có thể thay đổi; hãy đối chiếu tài liệu hiện hành khi cài đặt.
