Cách viết CLAUDE.md: phân cấp, @import và .claude/rules

Exam guide nêu ba tầng:

Claude Code đọc tất cả các file áp dụng cùng lúc. Không file nào ghi đè file nào; nội dung được gộp lại, file cụ thể hơn được đọc sau. Docs hiện tại còn có file managed policy cho quy định toàn tổ chức và CLAUDE.local.md (để trong .gitignore) cho ghi chú cá nhân theo project. Cả hai đều hữu ích khi làm thật, nhưng đề thi xoay quanh ba tầng ở trên.

Chẩn đoán kinh điển: thành viên mới không nhận được rule

Tình huống nên chờ sẵn: một dev senior đã tinh chỉnh hành vi của Claude suốt mấy tháng. Thành viên mới vào, clone repo, và Claude bỏ qua hết convention về test và đặt tên mà cả team vẫn dùng.

Các convention đó nằm trong ~/.claude/CLAUDE.md của dev senior. Chỉ dẫn tầng user chỉ áp dụng cho chính người đó và không bao giờ được chia sẻ qua version control. Cách sửa: chuyển convention của team vào CLAUDE.md tầng project (hoặc .claude/rules/) rồi commit, chỉ giữ sở thích cá nhân ở tầng user.

Để kiểm tra file nào đang được nạp, guide chỉ đến lệnh /memory: nó liệt kê các memory file Claude Code dùng ở cả scope user và project, và mở chúng để sửa. Ở bản Claude Code hiện tại, /context cũng cho thấy các file CLAUDE.md và rules đã nạp lúc khởi động.

Một CLAUDE.md ôm hết mọi package trong monorepo sẽ rất dài, và chỉ dẫn càng dài thì càng ít được tuân thủ đều. Cú pháp @import kéo file khác vào theo đường dẫn:

# packages/billing/CLAUDE.md
@../../docs/standards/api-conventions.md
@../../docs/standards/money-handling.md

Ghi chú riêng cho billing đặt ở đây.

Đường dẫn tương đối tính từ file chứa lệnh import. Import có thể lồng nhau (docs cho tối đa bốn tầng). Kỹ năng đề thi muốn ở đây là chọn lọc: CLAUDE.md của mỗi package chỉ import những file chuẩn mà người maintain biết là liên quan, nên package billing có rule xử lý tiền còn trang docs thì không.

Lưu ý: import giúp tổ chức chứ không tiết kiệm token. File được import vẫn nạp cùng CLAUDE.md tham chiếu nó.

Thư mục .claude/rules/ thay một CLAUDE.md khổng lồ bằng các file theo chủ đề:

repo/
├── CLAUDE.md                 # ngắn: tổng quan project, lệnh build
├── .claude/
│   └── rules/
│       ├── api-conventions.md
│       ├── deployment.md
│       └── testing.md        # paths: ["**/*.test.tsx"]
└── src/
    ├── checkout/Cart.test.tsx
    └── profile/Avatar.test.tsx

File rule không có frontmatter thì nạp ở mọi session, giống CLAUDE.md. Thêm field paths với glob pattern thì rule chỉ nạp khi Claude làm việc với file khớp:

---
paths:
  - "**/*.test.tsx"
---

# Component test conventions

- Use React Testing Library queries by role, not by test ID.
- One behaviour per test; name tests "does X when Y".
- Mock network calls with the shared handlers in test/msw.

Guide nêu hai lợi ích: convention không liên quan không chiếm context (ít token, ít nhiễu), và rule đi theo loại file thay vì theo thư mục.

Vì sao rule theo đường dẫn tốt hơn CLAUDE.md thư mục con trong trường hợp này

CLAUDE.md thư mục con gắn với đúng một thư mục. Trong repo này, file test nằm cạnh component ở checkout/, profile/ và hàng chục thư mục khác. Muốn phủ hết bằng file tầng thư mục, bạn phải chép cùng một bộ convention vào từng thư mục rồi giữ chúng đồng bộ. Một file testing.md với paths: ["**/*.test.tsx"] áp dụng cho mọi file test ở bất cứ đâu. Convention cho terraform/**/* hay **/*.sql cũng vậy.

Chỉ dùng CLAUDE.md thư mục con khi rule thật sự thuộc về một thư mục, ví dụ một module legacy có cách build riêng.

Một phân biệt liên quan từ task statement 3.2: CLAUDE.md chứa chuẩn chung áp dụng mọi session, nên luôn được nạp. Skills (.claude/skills/<name>/SKILL.md) chứa workflow cho từng loại việc, như checklist release hay quy trình migration, và chỉ nạp khi được gọi. Chỉ dẫn chỉ cần cho một loại việc thì là skill. Chỉ cần cho một loại file thì là rule theo đường dẫn. Cần ở mọi nơi thì đặt trong CLAUDE.md.

So sánh skills, commands và subagents xem ở skills, commands và subagents.

Một team đặt test của React component ngay cạnh component, rải trong khoảng 40 thư mục tính năng. Họ muốn Claude Code theo đúng convention test mỗi khi sửa file test, nhưng không nạp convention đó khi sửa code khác. Nên làm gì?

A. Thêm một CLAUDE.md chứa convention test vào từng thư mục trong 40 thư mục. B. Đặt convention vào ~/.claude/CLAUDE.md của từng dev. C. Tạo .claude/rules/testing.md với frontmatter paths: ["**/*.test.tsx"] rồi commit. D. Thêm convention vào CLAUDE.md ở gốc dưới mục "Testing".

Đáp án: C. Rule theo glob khớp file test theo loại ở mọi thư mục, chỉ nạp khi có file khớp, và được chia sẻ qua version control.

• A chạy được nhưng nhân bản cùng nội dung 40 lần và lệch dần khi có thư mục mới.
• B là tầng user nên không được chia sẻ, thành viên mới sẽ không có.
• D có chia sẻ, nhưng convention bị nạp ở mọi session, kể cả session không đụng đến file test nào.

• ~/.claude/CLAUDE.md tầng user là cá nhân, không chia sẻ. Rule của team đặt ở CLAUDE.md project hoặc .claude/rules/, commit vào repo.
• "Thành viên mới không nhận được rule" thường có nghĩa rule đang ở tầng user.
• @import giữ CLAUDE.md gọn và cho mỗi package chỉ include chuẩn mình cần.
• File trong .claude/rules/ có glob paths chỉ nạp với file khớp, tốt hơn CLAUDE.md thư mục con khi convention rải khắp codebase.
• Dùng /memory để kiểm tra memory file nào đang nạp khi hành vi khác nhau giữa các session.