CLAUDE.md là gì? Cách viết hướng dẫn dự án cho Claude Code

Khi làm việc trong một repository, Claude Code cần hiểu dự án dùng công nghệ gì, lệnh nào để chạy và những quy ước nào phải tuân theo. Tệp CLAUDE.md cho phép bạn lưu các chỉ dẫn đó để dùng lại giữa các phiên.

Theo tài liệu Anthropic, Claude Code đọc hướng dẫn bộ nhớ từ thư mục dự án và các vị trí liên quan; nội dung trong tệp có thể được dùng làm ngữ cảnh khi làm việc. Cấu trúc và hành vi chi tiết có thể thay đổi, vì vậy hãy đối chiếu tài liệu chính thức về bộ nhớ Claude Code trước khi thiết lập cho nhóm.

Nội dung nào nên đưa vào CLAUDE.md?

Ưu tiên thông tin dự án khó tự suy ra và có giá trị lặp lại:

• Lệnh cài đặt, chạy ứng dụng và kiểm tra.
• Sơ đồ thư mục hoặc nơi đặt từng loại logic.
• Quy ước đặt tên, định dạng và cách xử lý lỗi.
• Các ràng buộc quan trọng, ví dụ không sửa file sinh tự động.
• Cách xác nhận một thay đổi đã hoàn tất.

Tránh biến tệp thành bản sao toàn bộ tài liệu. Hướng dẫn dài, cũ hoặc mâu thuẫn khiến trợ lý khó tập trung; hãy liên kết tới tài liệu chuyên biệt khi có thể.

Mẫu tối giản

# Project guide

## Commands
- Install: `npm install`
- Dev: `npm run dev`
- Check: `npm run check`

## Conventions
- Keep API validation in `src/lib/contracts`.
- Prefer existing components before adding new dependencies.
- Explain any database migration in the change summary.

## Before finishing
- Review the diff for unrelated changes.
- Report commands that were run and any limitation.

Hãy thay các ví dụ bằng lệnh và kiến trúc thật của repository. Không chép máy móc tên thư mục trong mẫu.

Cách viết để hướng dẫn hữu ích

Viết mệnh lệnh cụ thể và có thể kiểm chứng. “Viết code tốt” quá mơ hồ; “dùng component hiện có, giữ type rõ ràng và chạy lệnh check sau khi sửa” giúp định hướng tốt hơn. Phân biệt quy tắc bắt buộc với gợi ý tùy tình huống.

Rà soát khi dự án thay đổi

Sau khi đổi package manager, cấu trúc thư mục hoặc lệnh kiểm tra, cập nhật hướng dẫn tương ứng. Xóa chỉ dẫn lỗi thời và giữ nội dung ngắn để người mới trong nhóm cũng hiểu được.

CLAUDE.md không thay thế review code hoặc kiểm thử. Nó giúp trợ lý bắt đầu đúng ngữ cảnh; bạn vẫn cần xác nhận mọi thay đổi bằng quy trình của dự án.