todo-api có thêm hai đồng nghiệp. Một người lo phần route, một người viết test. Chỉ sau hai tuần, CLAUDE.md đã dài gấp ba: quy tắc trả lỗi của route, quy ước đặt tên test, các bước release, một dòng viết hoa "NEVER push to main". Ai cũng thêm vào nhưng chẳng ai dám xóa. Claude bắt đầu bỏ sót những dòng quan trọng, đúng như bài 2.1 đã cảnh báo. Bài này bàn về cách tổ chức quy tắc khi cả team cùng dùng Claude Code.
File nào chung, file nào riêng
Bước đầu tiên là tách cái chung khỏi cái riêng:
- Chung, được commit:
CLAUDE.mdcủa dự án và thư mục.claude/rules/. Đây là chuẩn của dự án: lệnh test, quy ước, cạm bẫy. Vì cả team cùng đọc, chỉ đưa vào những gì đúng với mọi người. - Riêng, không commit:
CLAUDE.local.md(thêm vào.gitignore) cho sở thích của bạn trong dự án này;~/.claude/CLAUDE.mdvà~/.claude/rules/cho sở thích ở mọi dự án.
Rule cá nhân trong ~/.claude/rules/ được nạp trước rule của dự án. Nhưng như với CLAUDE.md, không bên nào ghi đè bên nào: nếu rule cá nhân và rule dự án nói ngược nhau, Claude có thể theo một trong hai. Cách duy nhất là giữ chúng nhất quán.
Chia quy tắc theo chủ đề
Khi một file CLAUDE.md bắt đầu dài, hãy tách nó vào thư mục .claude/rules/, mỗi file một chủ đề với tên dễ hiểu:
todo-api/
├── CLAUDE.md
└── .claude/
└── rules/
├── testing.md
├── routes.md
└── security.mdClaude Code tìm mọi file .md trong thư mục này, kể cả trong thư mục con, nên bạn có thể chia tiếp thành backend/, frontend/. Một rule không có trường paths được nạp ngay lúc khởi động, cùng mức với .claude/CLAUDE.md. Lợi ích chính ở đây là dễ quản lý: mỗi người sửa file thuộc phần mình, review gọn hơn, ít đụng nhau hơn.
Quy tắc cho một phần code
Lợi ích lớn hơn đến từ rule theo đường dẫn. Thêm frontmatter paths với mẫu glob ở đầu file:
---
paths:
- "src/routes/**/*.js"
---
- Return errors as { error: "..." } with the right status code
- Deletes stay soft: set deletedAt, never remove rowsRule này chỉ được nạp khi Claude dùng công cụ đọc, ghi hoặc sửa trên một file khớp mẫu. Khi Claude sửa test hay README, nó không chiếm chút bối cảnh nào. Vài mẫu glob hay dùng: **/*.ts cho mọi file .ts, src/**/* cho mọi file trong src/, src/**/*.{ts,tsx} cho hai đuôi file cùng lúc.
Lưu ý: paths là trường duy nhất Claude Code đọc trong frontmatter của rule. Bạn có thêm priority: high hay owner: team-api thì chúng bị bỏ qua mà không báo lỗi. Muốn biết rule dành cho ai, ghi bằng comment HTML trong thân file.
Hướng dẫn, quy trình hay luật cứng
Mỗi dòng trong file quá dài của đầu bài thật ra thuộc về một chỗ khác nhau. Docs chia mọi chỉ dẫn làm hai loại:
- Hướng dẫn, Claude quyết định: prompt,
CLAUDE.md, rule, skill. Claude đọc và thường làm theo, nhưng có thể quyết định khác khi thấy tình huống không hợp. - Bắt buộc, Claude Code thực thi: hook, deny rule trong settings, managed settings. Được áp dụng mọi lần, bất kể Claude nghĩ gì.
Từ đó, chọn chỗ cho từng thứ:
- Chuẩn code và cạm bẫy chung →
CLAUDE.md. - Quy tắc chỉ cho một phần code →
.claude/rules/cópaths. - Quy trình nhiều bước như các bước release → skill ở
.claude/skills/<tên>/SKILL.md. Trong mọi phiên, Claude chỉ thấy tên và mô tả của skill, và chỉ đọc toàn bộ khi việc cần tới. Cấp 3 sẽ dạy cách viết. - Điều không được phép xảy ra, như push thẳng lên main → hook hoặc deny rule. Dòng "NEVER push to main" viết hoa trong
CLAUDE.mdchỉ là lời nhắc, dù viết to tới đâu.
Cả công ty và các công cụ khác
Ở quy mô tổ chức, có thêm hai lớp.
Managed CLAUDE.md và managed settings. IT có thể đặt một CLAUDE.md chung cho mọi máy, hoặc dùng khóa claudeMd trong file managed settings. Nhà phát triển không loại trừ được file này. Docs phân vai rõ: settings để cưỡng chế kỹ thuật (chặn công cụ hay lệnh bằng permissions.deny, bật sandbox, biến môi trường), còn CLAUDE.md để hướng dẫn hành vi (chuẩn code, nhắc về xử lý dữ liệu). Muốn chặn một lệnh cho cả công ty thì dùng settings, không dùng CLAUDE.md.
Trong monorepo lớn, CLAUDE.md của nhóm khác ở thư mục cha có thể lọt vào phiên của bạn. Setting claudeMdExcludes cho phép bỏ qua chúng; đặt nó trong .claude/settings.local.json để chỉ ảnh hưởng máy bạn.
AGENTS.md. Nhiều team dùng AGENTS.md cho các agent viết code khác. Claude Code đọc AGENTS.md khi thư mục làm việc và các thư mục phía trên không có CLAUDE.md hay CLAUDE.local.md. Nếu đã có CLAUDE.md, mặc định Claude chỉ đọc CLAUDE.md. Cách giữ một nguồn duy nhất cho mọi công cụ là thêm một dòng vào CLAUDE.md:
@AGENTS.mdGiữ quy tắc luôn đúng
Quy tắc của team cũng cũ đi như code. Một file từng đúng có thể trỏ tới thư mục đã đổi tên, hay mâu thuẫn với một rule mới thêm. Hãy coi các file quy tắc như code: thay đổi qua pull request, có người review, và rà lại định kỳ.
Công cụ cho việc rà là /doctor prompt-audit. Nó đọc CLAUDE.md, CLAUDE.local.md, AGENTS.md cùng các rule, skill, lệnh và subagent trong .claude/ và ~/.claude/, rồi báo những chỉ dẫn viết cho model đời cũ, trỏ tới file hay lệnh không còn tồn tại, hoặc mâu thuẫn nhau. Báo cáo kèm đề xuất sửa, và không file nào đổi cho tới khi bạn bảo áp dụng. Muốn rà một phần thôi, truyền đường dẫn, ví dụ /doctor prompt-audit .claude/rules.
Với file dài ở đầu bài, kết quả sau khi sắp xếp lại sẽ là: CLAUDE.md ngắn chỉ còn lệnh và cạm bẫy chung, rules/routes.md cho người làm route, rules/testing.md cho người viết test, một skill release, và một hook chặn push lên main.
Hết cấp 2. Cấp 3 đi vào lệnh slash và Agent Skills: biến những quy trình bạn hay lặp lại thành thứ Claude gọi được bằng một lệnh.