Hôm nay mình sẽ hướng dẫn anh em thiết lập file CLAUDE.md để Claude Code tự nhớ kiến trúc và quy ước làm việc ngay từ đầu mỗi phiên chat.
Mỗi phiên mới Claude không nhớ gì về dự án của anh em, nên bước hướng dẫn Claude Code lưu ngữ cảnh này rất đáng làm.
Bài này mình dựa theo tài liệu chính thức của Claude Code, mình chưa tự chạy thử, nên anh em làm thấy khác thì cứ đối chiếu lại với tài liệu.
Mỗi phiên làm việc mới luôn bắt đầu với context window hoàn toàn trắng.
Tài liệu ghi rõ hai cơ chế chính giúp mang kiến thức xuyên suốt các phiên là những file cấu hình do anh em tự viết và hệ thống ghi nhớ tự động.
Anh em nên chủ động tạo file chỉ dẫn ngay từ đầu để Claude biết sẵn cấu trúc dự án và quy ước của nhóm, khỏi phải đoán.
Bước 1: Nắm rõ cách hướng dẫn Claude Code qua các vị trí file
Anh em có thể đặt file chỉ dẫn ở nhiều cấp thư mục.
Nếu muốn đặt quy tắc cá nhân áp dụng cho mọi dự án trên máy, anh em lưu vào ~/.claude/CLAUDE.md.
Với dự án làm chung cả nhóm, anh em để CLAUDE.md ở thư mục gốc của repo và commit cùng mã nguồn, đồng đội kéo về là dùng được luôn.
File này đặt ở ./CLAUDE.md hoặc ./.claude/CLAUDE.md, và nên có lệnh build, lệnh test, cách đặt tên.
Khi anh em cần ghi chú cá nhân mà không muốn đưa lên repo chung, hãy tạo file CLAUDE.local.md và thêm vào file .gitignore.
Thêm dòng CLAUDE.local.md vào file .gitignore thì git sẽ bỏ qua file này, nên nó không bị đưa lên repo.
Ghi chú riêng này chỉ nằm trên máy anh em, đồng đội không bị ảnh hưởng.
Mặc định, Claude Code nạp CLAUDE.md và CLAUDE.local.md từ thư mục anh em đang chạy và các thư mục cha phía trên; file trong thư mục con được nạp khi Claude đọc hay sửa file ở đó.
Nếu repo dùng AGENTS.md thì Claude Code có thể đọc file đó thay cho CLAUDE.md.
Bước 2: Tạo nhanh file bằng lệnh tự động
Anh em mở terminal trên máy rồi cd vào đúng thư mục dự án.
Mình khuyên anh em đứng đúng thư mục dự án trước khi gõ claude, để nó nạp đúng file CLAUDE.md của dự án.
cd your-project
claudeKhi claude đã mở, anh em gõ /init ngay trong khung chat (không gõ ở terminal ngoài) để Claude tự tạo CLAUDE.md.
Nếu dự án đã có CLAUDE.md, /init sẽ đề xuất chỉnh sửa chứ không ghi đè.
Nếu muốn /init hỏi anh em từng bước, hãy đặt biến môi trường CLAUDE_CODE_NEW_INIT bằng 1 trước khi chạy /init.
Biến môi trường này anh em khai báo trong shell hoặc trong khối env của file cấu hình, rồi chạy /init như bình thường.
Khi mở chế độ tương tác, /init sẽ hỏi anh em muốn tạo gì từ file CLAUDE.md, skill tới hook, rồi đưa bản đề xuất để duyệt trước khi ghi file.
Khi file đã được sinh ra, anh em chỉ việc đọc lại toàn bộ nội dung và bổ sung thêm những quy ước kiến trúc mà Claude không thể tự mình phát hiện.
Anh em có thể tham khảo một ví dụ file ngắn với tiêu đề "# Lệnh thường dùng" đi cùng dòng "- Chạy npm test trước khi commit".
Ngay bên dưới, anh em ghi tiêu đề cấu trúc cùng quy ước đặt các file xử lý API vào thư mục src/api/handlers/.
Bước 3: Viết quy tắc cụ thể và kiểm soát độ dài
Quy tắc viết càng cụ thể thì Claude làm theo càng sát.
Lệnh test phải chạy được.
Anh em hãy yêu cầu cụ thể thay vì viết mơ hồ.
Chẳng hạn, tài liệu đưa ra ví dụ nên viết Use 2-space indentation thay vì dặn chung chung là hãy định dạng code cho đẹp.
Lệnh test cụ thể và chỉ rõ file nằm ở đâu thì Claude làm sát ý hơn hẳn.
Anh em hãy gom các chỉ dẫn cùng chủ đề dưới một tiêu đề markdown (dòng bắt đầu bằng #), mỗi ý một gạch đầu dòng.
Tài liệu khuyên mỗi file CLAUDE.md nên dưới 200 dòng, vì file dài tốn context hơn và Claude làm theo kém hơn.
File quá dài sẽ làm tốn nhiều context window trong mỗi phiên chat.
Nếu có quy tắc chỉ dùng cho một phần dự án, anh em tách chúng thành các file rule riêng đặt trong thư mục .claude/rules/.
Mỗi rule gắn với một nhóm file hay thư mục nhất định, nên chỉ nạp khi Claude đụng tới đúng chỗ đó.
Bước 4: Ghép thêm tài liệu bằng cú pháp import
Anh em có thể nạp thêm tài liệu bằng cách gõ @ rồi đường dẫn file, ví dụ @docs/git-instructions.md, ngay trong CLAUDE.md.
Muốn nhắc tên đường dẫn mà không import, anh em bọc nó trong dấu backtick.
Đường dẫn tương đối hay tuyệt đối đều dùng được.
Đường dẫn tương đối tính từ chính file đang chứa dòng import.
File được import còn import tiếp được file khác, tối đa bốn cấp.
Nếu đường dẫn chứa khoảng trắng, anh em phải thêm một dấu gạch chéo ngược ngay trước mỗi dấu cách để hệ thống đọc đúng tên file.
Ví dụ import một file nằm trong thư mục tên Design Docs (có dấu cách):
- API conventions @Design\ Docs/api-conventions.mdImport chỉ giúp anh em chia file cho gọn, không giúp tiết kiệm context, vì file được import cũng nạp ngay khi mở phiên.
Lần đầu Claude Code gặp import trỏ ra ngoài thư mục làm việc, nó hiện hộp thoại xin phép (approval) liệt kê các file; nếu anh em từ chối thì các import đó bị tắt và hộp thoại không hiện lại.
Hộp thoại này có để tránh trường hợp anh em mở repo lạ mà trong đó có file import trỏ ra ngoài, nên mình thấy cứ đọc kỹ danh sách rồi hẵng đồng ý.
Bước 5: Rà soát xung đột bằng công cụ kiểm tra
Sau khi viết xong, anh em cần kiểm tra xem file đã được nạp chưa.
Trong phiên chat, anh em gõ /context rồi xem danh sách dưới mục Memory files.
/contextKhi nghi file có quy tắc mâu thuẫn hoặc đã cũ, anh em gõ /doctor prompt-audit trong phiên chat để Claude rà giúp.
Mặc định nó rà CLAUDE.md, CLAUDE.local.md, AGENTS.md cùng các quy tắc, skill, lệnh và subagent trong thư mục .claude/ và ~/.claude/, tìm chỉ dẫn viết cho model cũ, file hay lệnh không tồn tại, và các file mâu thuẫn nhau.
/doctor prompt-audit .claude/skills/deployAnh em chạy /doctor prompt-audit, đọc báo cáo, rồi nhắn Claude 'áp dụng các chỗ sửa' đối với những điểm anh em đồng ý.
Lệnh /doctor prompt-audit chạy qua skill /claude-api có sẵn, nên nếu skill này bị tắt thì lệnh không dùng được.
Lệnh này cần Claude Code v2.1.283 trở lên.
Anh em yên tâm, lệnh này chỉ đề xuất thôi, khi nào anh em bảo áp dụng thì file mới bị sửa.
Anh em nên dọn bớt những dòng thừa trong file, vì file càng gọn thì Claude càng làm theo đúng.
Lỗi hay gặp khi cấu hình file chỉ dẫn
Một lỗi dễ gặp là đặt hai quy tắc mâu thuẫn nhau trong cùng một file cấu hình hoặc giữa các cấp thư mục khác nhau trong dự án.
Hai quy tắc đá nhau thì Claude có thể chọn đại một cái, nên lúc nghe lời kiểu này lúc kiểu kia.
Anh em nên rà soát định kỳ để loại bỏ những quy tắc cũ.
Một sơ suất khác là quên dấu gạch chéo ngược khi import đường dẫn có dấu cách, làm cho hệ thống dừng đọc ngay tại khoảng trắng đầu tiên.
Nhồi quá nhiều hướng dẫn làm file dài quá 200 dòng thì Claude dễ bỏ sót những quy tắc quan trọng.
File càng ngắn và cụ thể thì Claude càng làm đúng ý anh em.
