3.3 Path-Specific Rules for Conditional Convention Loading

Những gì cần nắm

Path-specific rules áp dụng convention có điều kiện, dựa trên file bạn đang edit. Chúng giải quyết thứ mà cả root CLAUDE.md lẫn CLAUDE.md cấp thư mục đều làm không tốt: convention phải áp cho một loại file nằm rải rác qua nhiều thư mục.

Path-specific rules hoạt động ra sao

File rule nằm trong thư mục .claude/rules/. Mỗi file mang YAML frontmatter với field paths chỉ định glob pattern. Rule bên trong chỉ load khi bạn đang edit file khớp pattern đó.

---
paths: ["terraform/**/*"]
---
# Terraform Conventions

- Use snake_case for all resource names
- Tag every resource with environment and team labels
- Never hardcode AMI IDs — use data sources
- All modules must have a variables.tf, outputs.tf, and README.md

Edit một file khớp terraform/**/* thì những rule này tự load. Edit một React component hay một API handler thì không. Rule ở ẩn cho tới khi chúng thật sự liên quan.

Glob pattern khớp trên toàn bộ codebase

Đây là chỗ chúng phát huy giá trị. Một glob như **/*.test.tsx bắt hết mọi file test trong codebase, nằm ở đâu cũng được. Lấy một cấu trúc project điển hình:

src/
  components/
    Button.tsx
    Button.test.tsx
  api/
    auth.ts
    auth.test.ts
  utils/
    format.ts
    format.test.ts
  pages/
    dashboard/
      Dashboard.tsx
      Dashboard.test.tsx

File test nằm cạnh file source qua bốn thư mục. Một path-specific rule với paths: ["**/*.test.tsx", "**/*.test.ts"] áp cùng bộ test convention cho từng file đó, tự động.

Vì sao không dùng CLAUDE.md cấp thư mục?

CLAUDE.md cấp thư mục chỉ áp cho file trong đúng một thư mục. Để phủ file test rải qua hơn 50 thư mục, bạn phải thả một CLAUDE.md vào từng thư mục có test. Nghĩa là:

Hơn 50 bản sao của cùng một bộ convention
Mỗi thư mục mới có test lại cần một bản sao mới
Mỗi lần đổi convention phải cập nhật cả 50+ file
Chắc chắn sẽ trôi dạt khi vài bản sao bị bỏ quên

Path-specific rules với glob pattern xoá sạch vấn đề này. Một file, một pattern, phủ toàn bộ.

Vì sao không dùng root CLAUDE.md?

Root CLAUDE.md load cho mọi session, bất kể bạn edit file nào. Nhét Terraform convention vào root CLAUDE.md thì chúng đốt token ngay cả khi bạn đang edit React component. Nhét test convention vào đó thì chúng load trong lúc bạn viết API handler.

Vài ví dụ file rule thực tế

Test convention cho toàn bộ codebase:

---
paths: ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts", "**/*.spec.tsx"]
---
# Test Conventions

- Use describe/it blocks with descriptive names that read as sentences
- Each test file must have at least one happy path and one error case
- Use factory functions for test data, not inline object literals
- Mock external services at the module boundary, not individual functions
- Assert behaviour, not implementation details

API convention cho mọi route handler:

---
paths: ["src/api/**/*", "**/routes/**/*", "**/*.controller.ts"]
---
# API Conventions

- All endpoints return { data, error, metadata } response shape
- Use Zod schemas for request validation at the handler boundary
- Log request ID on every error response
- Rate limiting configuration must be explicit, not inherited from defaults

Convention cho infrastructure-as-code:

---
paths: ["terraform/**/*", "**/*.tf", "infrastructure/**/*"]
---
# Infrastructure Conventions

- State files must reference remote backends, never local
- Use workspaces for environment separation
- Every module must be versioned with a CHANGELOG

Khi nào dùng cách nào

Tình huống	Cách phù hợp nhất
Chuẩn chung của team áp cho mọi code	Root CLAUDE.md
Convention cho đúng một thư mục package	CLAUDE.md cấp thư mục
Convention cho một loại file rải qua nhiều thư mục	Path-specific rules với glob pattern
Workflow riêng theo tác vụ, gọi theo nhu cầu	Skill trong .claude/skills/

Đề thi rất hay đưa ra tình huống file test nằm cạnh file source qua nhiều thư mục. Đáp án luôn là path-specific rules với glob pattern.

Bẫy thi

Tình huống luyện tập

Một codebase có file test nằm cạnh file source suốt hơn 50 thư mục (ví dụ Button.test.tsx cạnh Button.tsx). Team muốn mọi test tuân theo cùng bộ convention bất kể nằm ở đâu. Cách nào dễ bảo trì nhất?

A. Tạo một file rule trong .claude/rules/ với YAML frontmatter paths: [“/*.test.tsx”, “/*.test.ts”] chứa test convention của repo
B. Đặt một file CLAUDE.md vào mọi thư mục có file test, mỗi file mang một bản sao của test convention
C. Thêm toàn bộ test convention vào file root CLAUDE.md để chúng được load vào context ở mọi session
D. Tạo một skill trong .claude/skills/ chứa test convention và bảo developer gọi nó trước khi viết hay sửa bất kỳ test nào

Đáp án & giải thích

Đúng: A

A — Glob pattern trong .claude/rules/ khớp file theo pattern trên toàn bộ codebase. Convention tự load khi edit bất kỳ file test nào, bất kể thư mục. Một file phủ hết hơn 50 thư mục, không tốn công bảo trì khi có thêm file test mới.
B — Với hơn 50 thư mục, cách này tạo trùng lặp khổng lồ. Mỗi lần đổi convention phải cập nhật 50+ file. Thư mục mới lại cần bản sao mới. Trôi dạt là chắc chắn.
C — Root CLAUDE.md load cho mọi session. Test convention sẽ ăn token ngay cả khi edit file không phải test. Path-specific rules tiết kiệm token hơn.
D — Cách này dựa vào việc developer nhớ gọi skill ở mỗi lần sửa test — kỷ luật con người là mắt xích yếu. Skill cũng có thể tự kích hoạt qua frontmatter paths, nhưng kể cả vậy chúng vẫn load theo nhu cầu như workflow dạng tác vụ chứ không phải context luôn hiện diện. Test convention phải định hình mọi lần edit file khớp, và đó đúng là thứ .claude/rules/ với path scoping cung cấp — load vào context tự động, không cần bước thủ công nào.

Nguồn

Claude Code Memory and Rules Documentation — Anthropic
Claude Certified Architect Foundations Exam Guide — Task Statement 3.3 — Anthropic
Claude Certified Architect Foundations Exam Guide — Sample Question 6 — Anthropic

Exam Simulator

Năm câu trắc nghiệm theo format đề thi về Path-Specific Rules for Conditional Convention Loading. Chọn đáp án trước, rồi mở phần giải thích.

Câu 1

A. Tạo một skill trong .claude/skills/ chứa test convention và bảo developer gọi nó trước khi viết test
B. Đặt một file CLAUDE.md vào mọi thư mục có chứa file test
C. Thêm toàn bộ test convention vào file root CLAUDE.md
D. Một file rule trong .claude/rules/ với frontmatter paths: [“/*.test.tsx”, “/*.test.ts”]

Đáp án & giải thích

Đúng: D

A sai vì: Cách này dựa vào việc developer nhớ gọi skill ở mỗi lần sửa test — kỷ luật con người là mắt xích yếu. Skill có thể tự kích hoạt qua frontmatter paths, nhưng kể cả vậy chúng vẫn load theo nhu cầu như workflow dạng tác vụ chứ không phải context luôn hiện diện. Path-specific rules trong .claude/rules/ tự load vào context khi Claude đọc file khớp, không cần bước thủ công nào.
B sai vì: Với hơn 50 thư mục, cách này tạo trùng lặp khổng lồ. Mỗi lần đổi convention phải cập nhật 50+ file. Thư mục mới lại cần bản sao mới. Trôi dạt là chắc chắn.
C sai vì: Root CLAUDE.md load cho mọi session. Test convention sẽ ăn token ngay cả khi edit file không phải test như API handler hay database model.
D đúng vì: Glob pattern trong .claude/rules/ khớp file theo pattern trên toàn bộ codebase. Convention tự load khi edit bất kỳ file test nào, bất kể thư mục. Một file phủ hết hơn 50 thư mục, không tốn công bảo trì khi có thêm file test mới.

Câu 2

Một project có file hạ tầng Terraform trong terraform/ và code ứng dụng trong src/. Terraform convention gồm những quy tắc đặt tên resource không liên quan gì tới code ứng dụng. Nên cấu hình chúng ở đâu để tiết kiệm token tối đa?

A. Trong root CLAUDE.md để chúng luôn sẵn sàng
B. Trong .claude/rules/terraform.md với paths: [“terraform//*”, “/*.tf”] ở YAML frontmatter
C. Trong một CLAUDE.md cấp thư mục đặt bên trong terraform/ cạnh chính các module
D. Trong một skill tại .claude/skills/terraform/SKILL.md mà developer gọi trước khi sửa bất kỳ module nào

Đáp án & giải thích

Đúng: B

A sai vì: Root CLAUDE.md load cho mọi session. Quy tắc đặt tên Terraform sẽ ăn token khi bạn edit React component hay API handler — context lãng phí hoàn toàn.
B đúng vì: Path-specific rules với glob pattern phủ cả cây thư mục terraform/ lẫn mọi file .tf ở bất kỳ đâu trong codebase. Chúng chỉ load khi edit file khớp, cho hiệu quả token cao nhất.
C sai vì: CLAUDE.md cấp thư mục chỉ phủ thư mục terraform/. Nếu có file .tf nằm chỗ khác trong codebase (module infrastructure-as-code ở vị trí khác), chúng sẽ không được phủ.
D sai vì: Skill load theo nhu cầu như workflow dạng tác vụ chứ không phải context luôn hiện diện. Convention hạ tầng phải định hình mọi lần edit file hạ tầng, và đó đúng là thứ .claude/rules/ với path scoping cung cấp.

Câu 3

Một developer đang edit file src/api/auth.ts. Project có ba file rule: .claude/rules/testing.md (paths: [“/*.test.ts”]), .claude/rules/api-conventions.md (paths: [“src/api//”]), và .claude/rules/terraform.md (paths: [“terraform/**/”]). Những rule nào được load?

A. Chỉ api-conventions.md, vì file khớp src/api/**/*
B. Cả ba, vì chúng đều nằm trong thư mục .claude/rules/
C. api-conventions.md và testing.md, vì file nằm trong src/
D. Không cái nào, vì path-specific rules cần được gọi tường minh

Đáp án & giải thích

Đúng: A

A đúng vì: src/api/auth.ts khớp pattern src/api/**/* trong api-conventions.md. Nó không khớp /*.test.ts (không phải file test) hay terraform//* (không nằm trong thư mục terraform).
B sai vì: Path-specific rules chỉ load khi file đang edit khớp glob pattern trong frontmatter. Nằm trong .claude/rules/ không có nghĩa là tự load cho mọi file.
C sai vì: testing.md đòi file khớp **/*.test.ts. auth.ts không phải file test, nên rule testing không load.
D sai vì: Path-specific rules tự load vào context khi Claude đọc file khớp. Chúng không cần gọi tường minh. Skill thì ngược lại, load theo nhu cầu như workflow dạng tác vụ.

Câu 4

Một team chuyển toàn bộ convention từ root CLAUDE.md sang path-specific rules trong .claude/rules/. Khi một developer edit hàm tiện ích trong src/utils/format.ts, họ nhận ra chuẩn code chung (naming, xử lý lỗi) không còn áp dụng nữa. Sai ở đâu?

A. Path-specific rules không thể chứa chuẩn code chung
B. Developer cần chạy /memory để load lại cấu hình
C. Glob bỏ sót file utility, hoặc chúng vốn thuộc về root
D. File .claude/rules/ chỉ hoạt động với file test và file hạ tầng

Đáp án & giải thích

Đúng: C

A sai vì: Path-specific rules chứa được mọi loại convention. Vấn đề nằm ở cách định nghĩa glob pattern.
B sai vì: /memory là công cụ chẩn đoán, cho biết file nào đã load. Nó không load lại hay kích hoạt việc load.
C đúng vì: Nếu chuẩn code chung áp cho TẤT CẢ file, chúng hoặc cần glob pattern kiểu [“**/*”] hoặc nên ở lại root CLAUDE.md. Chuyển chuẩn phổ quát sang rule path-scoped mà không có pattern bắt-tất-cả sẽ phá vỡ tính phổ quát của chúng.
D sai vì: File .claude/rules/ hoạt động với mọi loại file. Glob pattern quyết định file nào kích hoạt việc load, không phải nội dung của rule.

Câu 5

Đâu là lợi thế chính của path-specific rules so với root CLAUDE.md khi áp convention riêng cho một loại file?

A. Path-specific rules được version-control còn root CLAUDE.md thì không
B. Chúng chỉ load khi edit file khớp, tiết kiệm token context
C. Path-specific rules hỗ trợ YAML frontmatter còn root CLAUDE.md thì không
D. Path-specific rules chia sẻ được qua git còn root CLAUDE.md thì không

Đáp án & giải thích

Đúng: B

A sai vì: Cả path-specific rules lẫn root CLAUDE.md đều được version-control khi đặt trong repository.
B đúng vì: Hiệu quả token là lợi thế chính. Path-specific rules chỉ load cho file khớp, nên Terraform convention không ăn token khi bạn edit React component. Root CLAUDE.md load tất cả cho mọi session.
C sai vì: Path-specific rules có dùng YAML frontmatter cho path scoping, nhưng đó là cơ chế, không phải lợi thế chính. Lợi thế là việc load có điều kiện mà frontmatter cho phép.
D sai vì: Cả root CLAUDE.md lẫn file .claude/rules/ đều nằm trong repository và chia sẻ qua git.