CLAUDE.md & bộ nhớ dự án

Bạn không muốn mỗi phiên lại phải nhắc “dự án này dùng pnpm”, “test bằng Vitest”, “đừng sửa thư mục legacy”. CLAUDE.md là một file Claude tự đọc khi mở phiên - nơi bạn ghi quy ước một lần để nó bám đúng mãi.

• ▸CLAUDE.md = trí nhớ dài hạn do BẠN viết cho dự án; Claude đọc tự động mỗi phiên.
• ▸Chứa: lệnh build/test, quy ước, cấu trúc, “luật” cần tuân thủ.
• ▸Được nạp lại sau khi ngữ cảnh bị nén (compact) - quy ước cốt lõi không bị quên giữa chừng.

Có nhiều tầng CLAUDE.md, gộp với nhau (tầng ngoài rộng, tầng trong cụ thể). Từ rộng đến hẹp:

• ▸Quy ước CẢ NHÓM → ./CLAUDE.md và commit vào git.
• ▸Sở thích RIÊNG → ~/.claude/CLAUDE.md (mọi dự án) hoặc CLAUDE.local.md (dự án này).
• ▸Gõ /init để Claude sinh CLAUDE.md ban đầu từ chính code của bạn.

Thử bật/tắt từng tầng để thấy tầng nào thắng khi có xung đột quy ước:

Bí quyết: ngắn, cụ thể, hành động được. Dưới đây là một ví dụ gọn cho dự án web:

# Dự án: Cửa hàng X (web)

## Lệnh
- Cài: pnpm install
- Chạy dev: pnpm dev
- Test: pnpm test   (LUÔN chạy trước khi commit)
- Build: pnpm build

## Quy ước
- TypeScript; thụt lề 2 dấu cách; dùng nháy đơn.
- Component đặt trong src/lib/components, đặt tên PascalCase.
- Không sửa thư mục legacy/ (mã cũ, chỉ tham khảo).

## Quy trình
- Làm trên nhánh; mở PR vào main; không commit thẳng main.

• ▸“Dùng thụt lề 2 dấu cách” thắng “format cho đẹp” - cụ thể luôn tốt hơn chung chung.
• ▸Ưu tiên: lệnh build/test, quy ước, cấu trúc, vài luật hay bị phá.
• ▸Giữ ngắn (thường < ~200 dòng): dài quá làm loãng ngữ cảnh, Claude bám kém.

Không cần mở file thủ công. Đang làm mà nghĩ ra một quy ước, gõ một dòng bắt đầu bằng # - Claude lưu vào bộ nhớ ngay:

• ▸# <ghi chú> - thêm nhanh một điều cần nhớ vào CLAUDE.md (Claude hỏi lưu ở tầng nào).
• ▸/memory - mở danh sách file nhớ đang nạp để xem & sửa trực tiếp.
• ▸@đường-dẫn trong CLAUDE.md - gộp nội dung file khác vào (vd @docs/quy-uoc.md).

Ngoài CLAUDE.md (do bạn viết), Claude Code còn có bộ nhớ tự động: nó tự ghi lại những điều học được qua các phiên - quyết định dự án, mẹo gỡ lỗi, thứ bạn từng chỉnh. Lần sau quay lại, nó “nhớ” mà không cần bạn nhắc.

• ▸CLAUDE.md = BẠN viết (chỉ dẫn). Bộ nhớ tự động = CLAUDE viết (ghi chú cho chính nó).
• ▸Lưu cục bộ trên máy bạn, là markdown thường - xem/sửa/xoá tuỳ ý (qua /memory).
• ▸Bật/tắt được; nếu thấy nó nhớ điều không nên, cứ mở file ra sửa hoặc xoá.