Keep CLAUDE.md under 200 lines: what to write, what to cut, where the rest goes

Nhiều team coi CLAUDE.md như wiki: thêm mọi quy ước, mọi quy trình, mọi bài học, rồi thắc mắc vì sao Claude càng ngày càng "lơ" chỉ dẫn. Lý do nằm ở cơ chế: CLAUDE.md được nạp vào mọi phiên, nên mỗi dòng đều chiếm một chút sự chú ý của Claude ở mọi task, liên quan hay không. Tài liệu Claude Code khuyến nghị mỗi file dưới 200 dòng; file dài hơn vừa tốn context vừa làm giảm mức tuân thủ. Bài này hướng dẫn viết CLAUDE.md gọn và chỗ để đặt phần còn lại.

Phép thử trước khi thêm một dòng

1. Claude có tìm ra điều này bằng cách đọc code không?
2. Nó có thực sự đi tìm không?

Nếu cả hai đều "có", bỏ dòng đó. Model hiện nay đọc code rất giỏi: cấu trúc thư mục, framework test, quy ước đặt tên… nó tự thấy. Thứ nó không thấy là những gì chưa từng nằm trong repo: quyết định chốt trong cuộc họp, quy trình deploy nằm trong đầu một người, biến môi trường mà integration test cần.

CLAUDE.md nên có gì?

• Cách kiểm chứng: lệnh test, typecheck, lint chính xác; cách chạy một file test.
• Chỗ code gây hiểu lầm: pattern cũ có khắp nơi nhưng code mới không được bắt chước; thư mục trông như bỏ đi nhưng vẫn dùng.
• Quyết định không có trong repo: helper xử lý lỗi đã chọn, cách deploy, cái gì cần review migration.
• Điều đã phải sửa Claude hai lần.

# Commands
- Install: pnpm install
- Run one test file: pnpm vitest run path/to/file.test.ts
- Typecheck: pnpm tsc --noEmit

# Conventions
- Use the error helpers in src/lib/errors.ts, never throw raw strings
- src/legacy/ is still live but don't copy its patterns into new code

# Gotchas
- Integration tests need DATABASE_URL set, see .env.example

Phần còn lại để ở đâu?

Ví dụ rule theo đường dẫn:

---
paths:
  - "src/api/**/*.ts"
---
- Validate request bodies with the zod schemas in src/api/schemas/
- Every new endpoint needs an entry in openapi.yaml, CI fails without it

Một quy trình release dài nằm trong skill sẽ không làm nặng việc sửa bug không liên quan, như khi nó nằm trong CLAUDE.md. Với skill có tác dụng phụ (thật sự cắt release), thêm disable-model-invocation: true để chỉ chạy khi bạn tự gõ /release.

Cơ chế nạp cần biết

• CLAUDE.md ở thư mục làm việc và mọi thư mục cha được nạp khi khởi động, nối tiếp nhau chứ không ghi đè. Nếu hai chỉ dẫn mâu thuẫn, Claude có thể chọn tuỳ ý.
• Import file khác bằng @duong/dan, đệ quy tối đa 4 cấp. Import không làm giảm token: file được nhúng vẫn vào context.
• Auto memory (ghi chú Claude tự viết) lưu ở ~/.claude/projects/<project>/memory/; mỗi phiên chỉ nạp 200 dòng đầu hoặc 25KB của file chỉ mục.

Công cụ dọn dẹp

• /init: sinh bản đầu tiên từ codebase. Việc tiếp theo chủ yếu là xoá bớt.
• /doctor: gợi ý cắt những gì Claude tự suy ra được từ code.
• /doctor prompt-audit: tìm chỉ dẫn viết cho model đời cũ, trỏ tới file không còn tồn tại, hoặc mâu thuẫn nhau.
• /context: xác nhận file đã được nạp; /memory: xem và sửa.

Áp dụng thế nào?

• Dev: Đưa sở thích cá nhân (giọng trả lời, URL sandbox) vào CLAUDE.local.md, đừng commit vào file chung.
• Tech Lead: Rà CLAUDE.md hằng quý như dọn tech debt: xoá dòng lỗi thời, tách quy trình sang skill, quy tắc cục bộ sang .claude/rules/, quy tắc bắt buộc sang hook.
• PM: Quyết định sản phẩm ảnh hưởng đến code (ví dụ "không dùng thư viện X vì license") chính là loại thông tin đáng có trong CLAUDE.md.