Rule theo đường dẫn trong .claude/rules

Ở bài 3.1, bạn đã biết thư mục .claude/rules/ dùng để chia một CLAUDE.md dài thành nhiều file theo chủ đề. Mặc định, mọi file trong đó được nạp ngay khi mở Claude Code. Nhưng quy ước viết migration thì chỉ cần khi sửa migration, đâu cần lúc sửa giao diện.

Bài này giúp bạn trả lời: làm sao để một quy ước chỉ được nạp khi Claude làm việc với đúng loại file cần nó?

Ví dụ xuyên suốt: nền tảng học trực tuyến

Nhóm bạn làm một nền tảng học trực tuyến. Repo có cấu trúc:

learn-app/
  apps/web/src/components/VideoPlayer.tsx
  apps/web/src/components/VideoPlayer.spec.tsx
  apps/web/src/pages/khoa-hoc/ChiTiet.spec.tsx
  packages/billing/src/invoice.spec.ts
  packages/billing/migrations/0007_them_coupon.sql
  packages/courses/migrations/0012_them_chuong.sql
  infra/k8s/web.yaml

CLAUDE.md ở gốc đã dài hơn 400 dòng, gồm ba phần lớn: cách viết test, cách viết migration SQL, cách sửa file hạ tầng trong infra/. Hai vấn đề:

1. Khi bạn chỉ sửa màu một nút bấm, Claude vẫn nạp cả phần migration và hạ tầng. Context đầy những thứ không liên quan.
2. File test (*.spec.ts, *.spec.tsx) nằm cạnh code ở khắp nơi, migration nằm trong nhiều package. Không có một thư mục nào chứa hết chúng.

Rule chỉ nạp khi đụng tới file khớp mẫu

Thêm trường paths vào frontmatter của một file trong .claude/rules/. File đó trở thành rule theo đường dẫn (path-specific rule): nó chỉ được nạp khi Claude làm việc với file có đường dẫn khớp mẫu.

Tách phần viết test ra .claude/rules/testing.md:

---
paths:
  - "**/*.spec.ts"
  - "**/*.spec.tsx"
---

# Viết test

- Dùng Vitest, đặt file test cạnh file code.
- Mỗi test chỉ kiểm một hành vi, tên test viết bằng câu.

Theo tài liệu Claude Code:

• Rule theo đường dẫn được nạp khi Claude dùng Read, Write hoặc Edit với một file khớp mẫu. Đọc một file bằng cat hay head qua Bash cũng tính.
• File rule không có paths thì được nạp ngay khi mở Claude Code, như CLAUDE.md ở gốc.
• paths là trường duy nhất Claude Code đọc trong file rule; trường khác bị bỏ qua.
• Mẫu được tính từ thư mục chứa thư mục .claude của dự án, tức gốc repo.

Viết mẫu glob

Mẫu glob là cách mô tả một nhóm đường dẫn bằng ký tự đại diện: * khớp một phần tên trong một tầng thư mục, ** khớp bao nhiêu tầng thư mục cũng được.

Ba file rule của ví dụ:

Giờ khi bạn sửa VideoPlayer.tsx, không rule nào trong ba rule trên được nạp. Khi Claude mở VideoPlayer.spec.tsx, chỉ testing.md được nạp. Đó là điểm mạnh của rule theo đường dẫn: áp quy ước theo loại file, bất kể file nằm ở thư mục nào.

Context gọn hơn, đỡ tốn token

Quay lại vấn đề 1. Sau khi tách, CLAUDE.md ở gốc chỉ còn những quy ước đúng ở mọi lúc. Phần test, migration, hạ tầng chỉ vào context khi cần.

Tài liệu Claude Code nói rõ ích lợi này: rule theo đường dẫn chỉ vào context khi Claude làm việc với file khớp mẫu, nên bớt nhiễu và tiết kiệm chỗ trong context. Tài liệu cũng lưu ý file CLAUDE.md càng dài thì càng tốn context và Claude càng khó làm theo đầy đủ.

So với các cách giữ CLAUDE.md gọn ở bài 3.1:

Rule theo đường dẫn hay CLAUDE.md ở thư mục con

Bài 3.1 có nói CLAUDE.md đặt trong thư mục con cũng chỉ được đọc khi Claude đụng tới file trong thư mục đó. Vậy sao không đặt CLAUDE.md vào từng thư mục?

Vì CLAUDE.md gắn với một thư mục. File test của nhóm bạn nằm ở components/, pages/khoa-hoc/, packages/billing/src/ và còn nhiều chỗ nữa. Muốn quy ước test có mặt ở mọi nơi, bạn phải chép cùng một nội dung vào hàng chục file CLAUDE.md, rồi sửa một chỗ là phải sửa hết. Một file rule với **/*.spec.tsx làm được việc đó ở một chỗ.

1. Quy ước áp cho một loại file nằm rải rác nhiều thư mục?Rule trong .claude/rules/ có paths
2. Quy ước chỉ đúng cho đúng một thư mục?CLAUDE.md trong thư mục đó
3. Quy ước đúng ở mọi lúc, mọi file?CLAUDE.md ở gốc, hoặc rule không có paths
4. Còn lạiQuy trình chỉ dùng khi được gọi: viết thành skill (bài 3.2)