Cách tạo file CLAUDE.md cho Claude Code: Hướng dẫn và template

Một file CLAUDE.md hiệu quả không thay thế cho tư duy của bạn. Nó giúp loại bỏ việc phải lặp lại các thông tin kỹ thuật, giới hạn và quy trình kiểm tra giống nhau trong mỗi phiên làm việc.

Nó phát huy hiệu quả tốt nhất khi không phải là một danh sách các mong muốn chung chung. file này nên chỉ dẫn cho Claude Code biết những lệnh nào hoạt động tốt, vị trí các code quan trọng, những phần không được phép thay đổi và cách nhận biết khi nào một tác vụ đã hoàn tất.

Chức năng của CLAUDE.md

CLAUDE.md là một file Markdown thông thường. Claude Code nạp file này vào bộ nhớ dự án và sử dụng nội dung của nó như các hướng dẫn bổ sung cho quá trình làm việc. Do đó, đây là nơi lý tưởng để lưu trữ các chi tiết áp dụng cho nhiều tác vụ khác nhau:

• Các lệnh đáng tin cậy để phát triển, kiểm thử (test) và build ứng dụng
• Sơ lược về các thư mục quan trọng và những điểm truy cập (entry point) chính
• Các quy tắc kiến ​​trúc và những dependency
• Các giới hạn nghiêm ngặt, chẳng hạn như "không chạy lệnh di chuyển cơ sở dữ liệu khi chưa được phê duyệt"
• Các tiêu chí rõ ràng để Claude xác minh kết quả hoàn thành tác vụ

Nó không thay thế cho bản mô tả tác vụ chi tiết. Kết quả cụ thể, phạm vi công việc và tiêu chí nghiệm thu vẫn cần được nêu trong câu lệnh (prompt) hiện tại. Các cuộc trò chuyện có thể bị rút gọn hoặc làm mất đi những chi tiết quan trọng từ trước đó. Hãy đưa các quy tắc dự án quan trọng và có tính lâu dài vào file này, thay vì chỉ để chúng trong nội dung trò chuyện.

Cấu trúc phân cấp: Toàn hệ thống, dự án và thư mục con

Claude Code kết hợp các file cấu hình dựa trên đường dẫn làm việc của bạn. Khi khởi chạy, nó tổng hợp nội dung từ thư mục ngoài cùng vào sâu bên trong. File CLAUDE.local.md sẽ được nạp sau file CLAUDE.md trong cùng thư mục. Một file CLAUDE.md khác nằm trong thư mục con sẽ được thêm vào ngữ cảnh khi Claude đọc các file trong khu vực đó.

Ví dụ về cấu trúc phân cấp thực tế

~/.claude/CLAUDE.md
  Các quy tắc cá nhân áp dụng cho mọi dự án

~/projects/shop/CLAUDE.md
  Các quy tắc chung cho shop

~/projects/shop/apps/admin/CLAUDE.md
  Các quy tắc dành riêng cho giao diện quản trị (admin frontend)

~/projects/shop/apps/admin/src/payments/CLAUDE.md
  Các biện pháp bảo vệ bổ sung cho phần xử lý thanh toán

Hãy đặt thông tin dự án dùng chung vào file CLAUDE.md hoặc .claude/CLAUDE.md tại thư mục gốc của dự án. Hãy chọn một quy ước và duy trì sự nhất quán trong toàn bộ kho lưu trữ (repository). Hãy viết những quy tắc sao cho chúng không xung đột lẫn nhau; Claude Code sẽ gộp nội dung của các file lại thay vì áp dụng hệ thống ưu tiên để xử lý những hướng dẫn mâu thuẫn.

Anthropic trình bày chi tiết về các file bộ nhớ cấp dự án, cấp người dùng và cục bộ trong tài liệu chính thức về Bộ nhớ (Memory). Các giao diện và thuật ngữ cụ thể có thể thay đổi, vì vậy hãy tham khảo lại tài liệu này khi thực hiện những thay đổi lớn đối với cấu hình.

Nội dung của từng file CLAUDE.md

File CLAUDE.md toàn hệ thống

File ~/.claude/CLAUDE.md dành cho các quy tắc cá nhân áp dụng cho nhiều dự án. File này có thể bao gồm các tùy chọn định dạng, ngôn ngữ ưu tiên cho code và comment, hoặc quy trình xác thực cá nhân. Nó không nên chứa các giả định liên quan đến một repository cụ thể nào.

Project CLAUDE.md

File này nằm trong kho lưu trữ (repository) và mô tả trạng thái chung của dự án. Hãy duy trì việc quản lý phiên bản cho file này khi cả nhóm cần nắm rõ các lệnh và quy tắc chung. Chỉ đưa vào các thông tin thực tế dựa trên code, cấu hình hoặc quyết định đã được cả nhóm thống nhất.

CLAUDE.local.md

Sử dụng CLAUDE.local.md cho các bổ sung cá nhân tại cùng vị trí, chẳng hạn như dữ liệu thử nghiệm cục bộ hoặc quy trình làm việc riêng. Hãy thêm file này vào .gitignore. Mật khẩu, API key, dữ liệu khách hàng và các thông tin nhạy cảm khác không được phép xuất hiện trong bất kỳ file CLAUDE.md nào.

Các quy tắc cho thư mục con

Việc tạo file trong thư mục con rất hữu ích khi một khu vực cụ thể có các rủi ro hoặc quy ước riêng. Những ví dụ điển hình bao gồm: Xử lý thanh toán, di chuyển dữ liệu và ứng dụng di động. Đừng sao chép lại toàn bộ nội dung của file root (ở thư mục chính) vào đây; chỉ thêm những quy tắc đặc thù cho khu vực đó.

File CLAUDE.md toàn hệ thống cho phong cách làm việc của bạn

File toàn hệ thống tại `~/.claude/CLAUDE.md` nên độc lập với kho lưu trữ cụ thể. Đây là nơi thích hợp để quy định cách Claude làm việc với bạn nói chung. File này không nên chứa các giả định gắn liền với một framework hay dự án cụ thể nào.

Ví dụ về nội dung file ~/.claude/CLAUDE.md

# Quy tắc làm việc cá nhân

## Cộng tác
- Giải thích kế hoạch và các bước kiểm chứng trước khi thực hiện những thay đổi lớn.
- Đặt câu hỏi khi kết quả mong đợi hoặc phạm vi công việc chưa rõ ràng.

## Code
- Ưu tiên sử dụng TypeScript nếu dự án đã áp dụng ngôn ngữ này.
- Sử dụng các công cụ định dạng và kiểm thử sẵn có của dự án.

## Trước khi hoàn tất
- Liệt kê các file đã thay đổi và những bước kiểm tra đã thực hiện.
- Nêu rõ các rủi ro còn tồn tại.

Template tinh gọn cho thư mục gốc của dự án

Tạo file trực tiếp tại thư mục gốc của dự án hoặc để Claude Code tạo bản nháp ban đầu bằng lệnh /init. Bản nháp được tạo tự động không thể hiểu tường tận về dự án của bạn. Hãy xem xét lại, loại bỏ các giả định không phù hợp và chỉ thêm vào những quy tắc thực sự được áp dụng.

Template CLAUDE.md cho dự án

# Tên dự án

Một câu mô tả ngắn gọn về sản phẩm và người dùng của sản phẩm đó. 

## Các khu vực quan trọng
- src/app/: các tuyến (routes) và trang (pages)
- src/lib/: logic nghiệp vụ và các tích hợp
- tests/: các bài kiểm tra tự động

## Chạy và xác minh
```bash
npm run lint
npm run test
npm run build
```

## Quy tắc ràng buộc
- Kiểm tra các thành phần hiện có trước khi tạo mới.
- Xác thực dữ liệu đầu vào tại các điểm giao tiếp API.
- Ghi lại tài liệu về các thay đổi đối với giao diện công khai.

## Các giới hạn
- Không ghi thông tin nhạy cảm vào file hoặc đầu ra (output).
- Không thực hiện di chuyển dữ liệu khi chưa có kế hoạch được xác nhận.
- Hỏi ý kiến ​​trước khi thực hiện nếu yêu cầu sản phẩm chưa rõ ràng.

## Hoàn thành khi
- Các bước kiểm tra đã thống nhất đều đạt yêu cầu.
- Tài liệu và các bài kiểm tra liên quan phản ánh đúng hành vi thực tế.

Sử dụng cú pháp @ imports để trỏ đến các tài liệu dài và ổn định. Một mục như @docs/architecture.md sẽ load file đó khi khởi động. Việc nhập (import) chỉ hỗ trợ tham chiếu đến các file khác ở độ sâu giới hạn, vì vậy không nên nhập toàn bộ tập hợp tài liệu theo mặc định.

Sự khác biệt giữa CLAUDE.md và Auto Memory

Auto Memory lưu trữ các bài học có thể tái sử dụng một cách riêng biệt và cục bộ. Tính năng này hữu ích khi Claude Code phát hiện ra một đặc điểm ổn định của dự án trong quá trình làm việc. Nó khác với các hướng dẫn đã được xem xét và chia sẻ trong kho lưu trữ (repository).

CLAUDE.md vẫn là nguồn thông tin đáng tin cậy cho các tiêu chuẩn, giới hạn bảo mật, lệnh và quyết định về kiến ​​trúc. Hãy coi Auto Memory là một công cụ bổ trợ. Lệnh /memory cho phép bạn xem và quản lý các mục đã được lưu.

Phải làm sao khi Claude Code không tuân thủ quy tắc?

1. Chạy lệnh pwd để xác nhận rằng Claude Code đã khởi chạy trong thư mục dự án mong muốn.
2. Mở /context và kiểm tra nội dung trong phiên làm việc hiện tại.
3. Sử dụng /memory để đảm bảo Auto Memory không bị nhầm lẫn với một quy tắc dự án cụ thể nào đó.
4. Chạy claude --version và claude doctor nếu việc cài đặt hoặc cấu hình có dấu hiệu bất thường.
5. Thử dùng claude --safe-mode nếu gặp lỗi do tùy chỉnh. Chế độ này không load các file CLAUDE.md, skill, plugin, hook, MCP server hoặc Auto Memory. Các tính năng xác thực, chọn mô hình, công cụ tích hợp và quyền hạn vẫn hoạt động bình thường. Những chính sách quản lý vẫn được áp dụng.

Nếu file đã được load nhưng Claude vẫn hoạt động không đúng ý, hãy thu hẹp phạm vi quy tắc và đặt tên cụ thể cho bước kiểm tra đó. Thay vì viết "hãy cẩn thận với email", hãy viết "hiển thị người nhận, tiêu đề và nội dung để xác nhận trước khi gửi email".

Làm việc với các công cụ lập trình khác

Một số nhóm cũng sử dụng file AGENTS.md. Hãy tránh sao chép các quy tắc vào nhiều file khác nhau nếu có thể. Claude Code có thể bao gồm một file dùng chung thông qua lệnh import như @AGENTS.md. Khi đó, file CLAUDE.md (với nội dung ngắn gọn) có thể giải thích lý do file kia đóng vai trò chủ đạo và nêu rõ các bổ sung dành riêng cho Claude Code được áp dụng.

Hãy kiểm tra lại các lệnh thực tế và những quy tắc quan trọng nhất sau mỗi thay đổi lớn. Một file nhỏ gọn nhưng chính xác sẽ hữu ích hơn nhiều so với một tập hợp dài dòng các hướng dẫn đã lỗi thời.