Viết CLAUDE.md: bộ nhớ dài hạn cho dự án

CLAUDE.md giải quyết vấn đề gì

Mỗi phiên Claude Code bắt đầu từ con số 0 — nó không nhớ phiên trước. CLAUDE.md là cách bạn "onboard" Claude như onboard một đồng nghiệp mới: một lần, dùng mãi.

Nội dung file được nạp thẳng vào context mỗi phiên, nên mọi dòng đều có chi phí. Nguyên tắc: ngắn như một README tốt.

Nên có gì trong file

Ví dụ một khối gọn:

• Lệnh hay dùng: build, test, lint, chạy dev server
• Quy ước code: đặt tên, cấu trúc thư mục, thư viện ưu tiên
• Điều cấm: file không được đụng, API không được gọi trực tiếp
• Bối cảnh nghiệp vụ: một hai câu về sản phẩm và người dùng

# CLAUDE.md
## Lệnh
- npm run dev — chạy local
- npm test — chạy test (bắt buộc trước khi commit)

## Quy ước
- Component đặt trong src/components, PascalCase
- Dùng CSS modules, không styled-components

## Cấm
- Không sửa src/legacy/** (đang migrate)

Không nên có gì

Đừng dán tài liệu API dài, đừng liệt kê toàn bộ cấu trúc thư mục (Claude tự đọc được), đừng viết mô tả chung chung kiểu "hãy viết code sạch". Mỗi dòng không giúp Claude ra quyết định tốt hơn là một dòng nên xóa.

Ba cấp CLAUDE.md

Quy tắc chọn cấp: quy ước của cả team để ở repo; thói quen riêng của bạn để ở global; chi tiết chỉ liên quan một module để sâu trong thư mục đó.

• ~/.claude/CLAUDE.md — toàn cục, áp dụng mọi dự án: sở thích cá nhân của bạn
• <repo>/CLAUDE.md — cấp dự án, commit vào git để cả team dùng chung
• <repo>/<thư-mục>/CLAUDE.md — cấp module, chỉ nạp khi Claude làm việc trong thư mục đó

Cập nhật nhanh bằng phím #

Đang làm việc mà phát hiện một quy ước cần ghi nhớ? Gõ # theo sau là nội dung — Claude Code sẽ đề nghị thêm dòng đó vào CLAUDE.md phù hợp. Đây là cách file lớn lên tự nhiên theo dự án thay vì phải ngồi viết một lần cho hoàn hảo.

Dấu hiệu file đang phản tác dụng

• Claude lặp lại một lỗi dù đã ghi trong file: dòng đó viết mơ hồ, hãy viết lại thành quy tắc kiểm tra được
• File dài hơn ~150 dòng: tách phần chi tiết sang tài liệu riêng và chỉ trỏ link
• Có nội dung hết hạn: sai còn tệ hơn thiếu — hãy dọn định kỳ như dọn README