CLAUDE.md và cách viết prompt hiệu quả cho Claude Code

CLAUDE.md là gì?

CLAUDE.md là một file văn bản thuần (định dạng Markdown) mà Claude Code tự đọc khi bắt đầu mỗi phiên trong thư mục đó. Hãy hình dung nó như bản bàn giao bạn đưa cho một đồng nghiệp mới: nhóm làm việc ra sao, điều gì tuyệt đối tránh, phần quan trọng nằm ở đâu.

Bạn không cần nhắc đến file này trong prompt hay đính kèm nó. Lưu ý: CLAUDE.md là chỉ dẫn, không phải cơ chế cưỡng chế. Với quy tắc bắt buộc tuyệt đối, tài liệu chính thức khuyên dùng hook hoặc cài đặt quyền.

Đặt CLAUDE.md ở đâu?

Claude Code tìm file ở nhiều nơi và ghép nội dung lại với nhau, từ phạm vi rộng nhất đến cụ thể nhất:

Đa số nhóm chỉ cần file ở gốc repo, và nên commit nó vào git để cả nhóm cùng dùng. Nếu có ghi chú riêng không muốn chia sẻ (như URL môi trường thử nghiệm của bạn), tài liệu Claude Code gợi ý tạo CLAUDE.local.md ở gốc dự án và thêm nó vào .gitignore.

Bắt đầu nhanh với /init

1. Mở Claude Code trong thư mục dự án.
2. Gõ /init. Claude sẽ khám phá codebase và soạn sẵn một bản CLAUDE.md gồm lệnh build, lệnh test, tổng quan cấu trúc và các quy ước nó phát hiện.
3. Đọc lại bản nháp, xóa những gì sai hoặc thừa.
4. Commit file vào repo. Theo Help Center, toàn bộ việc này mất khoảng năm phút.

Nên và không nên ghi gì?

Mỗi dòng trong CLAUDE.md đều được nạp vào mọi yêu cầu, nên hãy giữ file dưới khoảng 200 dòng và viết cụ thể, kiểm chứng được.

# Lệnh
- Cài đặt: pnpm install
- Chạy test: pnpm test (phải pass trước khi commit)

# Quy ước
- Dùng pnpm, không dùng npm
- Mọi route API phải đi qua auth middleware
- Không sửa tay thư mục generated/

# Lưu ý
- Test không bao giờ ghi vào database production

Cập nhật CLAUDE.md khi nào?

• Khi Claude sai cùng một chỗ hai lần: đó là dấu hiệu thiếu quy tắc, thêm một dòng.
• Khi quy ước đổi: framework mới, công cụ test mới, quy tắc lint mới.
• Định kỳ mỗi quý: xóa nội dung cũ, vì chỉ dẫn lỗi thời còn tệ hơn không có.

Giữa phiên, bạn có thể gõ /memory để mở và sửa file, hoặc chỉ cần bảo Claude “hãy nhớ quy tắc này”, nó sẽ tự thêm vào đúng file. Lưu ý: sửa file giữa phiên thì thay đổi chỉ có hiệu lực sau khi bạn chạy /compact, mở file qua /memory, hoặc ở phiên sau.

7 thói quen viết prompt cho Claude Code

1. Nói kết quả mong muốn, không liệt kê từng bước. Mô tả bạn cần gì và vì sao, để Claude tự tìm chỗ cần sửa.
2. Dán nguyên văn thông báo lỗi. Stack trace đầy đủ có tên file, số dòng giúp Claude tìm đúng chỗ nhanh hơn một câu tóm tắt.
3. Việc lớn thì lập kế hoạch trước. Nếu thay đổi chạm tới nhiều file, nhấn Shift+Tab hai lần để vào plan mode, duyệt kế hoạch rồi mới cho làm từng bước.
4. Chỉ thẳng file bạn đã biết. Gõ @ kèm đường dẫn, ví dụ @src/auth/login.ts, vừa nhanh vừa tốn ít token.
5. Định nghĩa thế nào là “xong”. Ví dụ: test phải pass, code theo phong cách các handler khác, không thêm thư viện mới.
6. Mỗi cuộc trò chuyện một việc. Chuyển sang việc khác thì gõ /clear; CLAUDE.md đã giữ phần ngữ cảnh lâu dài.
7. Góp ý như với đồng nghiệp. Khi kết quả lệch, nói rõ chỗ sai thay vì viết lại cả yêu cầu. Claude sẽ giữ phần đúng và chỉ sửa điểm đó.

Những điều bạn học được trong bài này

• CLAUDE.md là bộ nhớ dự án, được Claude Code tự đọc đầu mỗi phiên
• Ba cấp đặt file và lý do nên commit file ở gốc repo vào git
• Dùng /init để tạo bản nháp, rồi tự rà lại
• Giữ file dưới khoảng 200 dòng, chỉ ghi điều Claude không tự suy ra được
• Bảy thói quen prompt: nêu kết quả, dán lỗi nguyên văn, plan mode, dùng @, định nghĩa “xong”, /clear, góp ý cụ thể

Nguồn tham khảo: Give Claude context: CLAUDE.md and better prompts – Claude Help Center · How Claude remembers your project – Claude Code Docs

Câu hỏi thường gặp