Phân cấp CLAUDE.md, @import và .claude/rules

CLAUDE.md là file chứa hướng dẫn cho Claude Code: dự án dùng công cụ gì, viết test ra sao, đặt tên thế nào. Mỗi lần bạn mở Claude Code, nó đọc file này trước khi làm việc.

Vấn đề là một máy có thể có nhiều file CLAUDE.md ở nhiều chỗ. Bài này giúp bạn trả lời: đặt file ở đâu thì ai nhận được, và làm sao giữ nó gọn khi dự án ngày càng lớn?

Ví dụ xuyên suốt: monorepo của một app giao đồ ăn

Nhóm bạn làm một app giao đồ ăn, code để chung trong một repo:

food-app/
  CLAUDE.md
  apps/
    web/
    api/
      CLAUDE.md
  packages/
    ui/
  docs/
    standards/

Tuấn làm ở dự án từ đầu. Mỗi lần Tuấn nhờ Claude Code, Claude đều dùng pnpm, viết test bằng Vitest, đặt tên file migration đúng mẫu của nhóm.

Tuần này Hà vào nhóm. Hà clone repo về, nhờ Claude Code thêm một tính năng, và Claude lại chạy npm install, viết test bằng Jest. Cùng một repo, sao Claude trên hai máy làm khác nhau?

Rà một lúc, nhóm phát hiện mấy quy ước đó Tuấn viết trong ~/.claude/CLAUDE.md trên máy mình, chứ không nằm trong repo.

Ba cấp CLAUDE.md

Quay lại ví dụ: quy ước của Tuấn nằm ở cấp user, nên chỉ máy Tuấn có. Cách sửa là chuyển những dòng cả nhóm cần sang food-app/CLAUDE.md rồi commit. Trong ~/.claude/CLAUDE.md Tuấn chỉ nên giữ thói quen riêng, như "trả lời ngắn gọn" hay "giải thích bằng tiếng Việt".

Ngoài ba cấp trên, Claude Code còn có CLAUDE.local.md cho ghi chú riêng của bạn trong một dự án (nhớ thêm vào .gitignore), và file do bộ phận IT đặt cho cả công ty. Đề thi tập trung vào ba cấp trong bảng.

File nào được đọc, và đọc lúc nào

Không phải file CLAUDE.md nào cũng được đọc ngay từ đầu:

• Khi mở Claude Code, nó đọc CLAUDE.md ở thư mục bạn đang mở và ở tất cả thư mục cha. Mở ở food-app/ thì food-app/CLAUDE.md được đọc ngay.
• CLAUDE.md trong thư mục con chỉ được đọc khi Claude bắt đầu đụng tới file trong thư mục đó. apps/api/CLAUDE.md được đọc khi Claude mở, sửa hoặc tạo một file trong apps/api/.

Khi có nhiều file cùng được đọc, chúng được nối lại với nhau, không file nào xoá file nào. File ở gần thư mục bạn đang làm nhất nằm cuối. Nếu hai file dặn ngược nhau, ví dụ file gốc bảo dùng Vitest còn apps/api/CLAUDE.md bảo dùng Jest, thì theo tài liệu của Anthropic, Claude có thể làm theo bên nào cũng được.

Thêm hai điều nên biết:

• Khi cuộc trò chuyện dài quá và bạn chạy /compact để thu gọn, CLAUDE.md ở gốc dự án được đọc lại từ đầu, nên hướng dẫn trong đó không bị mất. Hướng dẫn bạn chỉ nói miệng trong cuộc trò chuyện thì có thể mất.
• CLAUDE.md là lời dặn, Claude cố làm theo nhưng không có gì bảo đảm tuyệt đối. Việc nào nhất định phải xảy ra thì dùng hook (đoạn script Claude Code tự chạy ở những thời điểm nhất định).

Giữ CLAUDE.md gọn bằng @import

Tài liệu của Anthropic khuyên mỗi file CLAUDE.md nên dưới khoảng 200 dòng. Khi quy ước nhiều lên, bạn có thể để chúng ở file riêng, rồi kéo vào CLAUDE.md bằng cách viết @ trước đường dẫn.

Nhóm bạn có ba tài liệu chuẩn trong docs/standards/: api-errors.md, database.md và react.md. Package api chỉ cần hai file đầu, nên người phụ trách API viết apps/api/CLAUDE.md như sau:

# API

Mọi endpoint trả lỗi theo chuẩn chung.

@../../docs/standards/api-errors.md
@../../docs/standards/database.md

Còn apps/web thì chỉ import react.md. Mỗi package kéo đúng thứ nó cần, không ai phải đọc quy ước của phần khác.

Mấy điều cần nhớ khi dùng @:

• Đường dẫn tương đối được tính từ file đang chứa dòng @, không phải từ thư mục bạn mở Claude Code. Vì vậy ở trên phải viết ../../docs/....
• File được import có thể import tiếp file khác, sâu tối đa 4 tầng.
• Lần đầu gặp một import trỏ ra ngoài thư mục đang làm việc, Claude Code sẽ hỏi bạn có cho phép không.
• Import giúp chia file cho dễ sửa, chứ không giúp tiết kiệm: nội dung file được import vẫn được đọc đầy đủ.

Tách theo chủ đề bằng thư mục .claude/rules/

Cách thứ hai là chia một CLAUDE.md dài thành nhiều file nhỏ, mỗi file một chủ đề, để trong thư mục .claude/rules/:

food-app/
  .claude/
    rules/
      testing.md
      migrations.md
      ui.md

Mỗi file là Markdown bình thường. Mặc định chúng được đọc ngay khi mở Claude Code, giống như CLAUDE.md ở gốc. Nhóm muốn sửa quy ước viết test thì chỉ cần mở testing.md, không phải lục trong một file dài.

File trong .claude/rules/ còn có thể chỉ được đọc khi Claude đụng tới những file nhất định, ví dụ chỉ khi sửa file test. Phần đó nằm ở bài 3.3.

Kiểm xem file nào đang được nạp

Khi Claude làm khác nhau giữa hai máy, hoặc hôm nay khác hôm qua, việc đầu tiên là xem những file hướng dẫn nào đang được nạp. Có hai lệnh liên quan:

Muốn biết chắc file nào thật sự đã được nạp, /context cho câu trả lời trực tiếp nhất. Đề thi thì dùng /memory cho việc kiểm file hướng dẫn đang được nạp, nên nếu câu hỏi về việc này chỉ có /memory trong các đáp án, hãy chọn /memory.

Sau khi biết file nào đang được nạp, dò lỗi theo thứ tự:

1. Chỉ một người không nhận được hướng dẫn?Hướng dẫn đang nằm ở ~/.claude/CLAUDE.md của người khác: chuyển vào CLAUDE.md của dự án
2. Chỉ làm sai trong một thư mục?Xem CLAUDE.md của thư mục đó đã được đọc chưa, có dặn khác file gốc không
3. Hai file dặn ngược nhau?Bỏ một bên, đừng trông vào chuyện file nào thắng
4. Còn lạiMở /context xem file nào đã nạp, rồi dùng /memory mở từng file ra đọc