Dạy AI luật riêng: CLAUDE.md

Tới giờ mèo con đã có app Next.js, dữ liệu trong PostgreSQL và một lớp cache Redis. Nhưng mỗi lần mở phiên vibe mới, Claude lại như người mới vào việc: nó không nhớ luật riêng của business mèo con. Thế là mèo con phải gõ lại "nhớ là số dư không cache nhé", "tiền lưu số nguyên thôi", "route admin phải kiểm quyền"... mỗi phiên một lần.

Nhắc đi nhắc lại vừa mệt vừa dễ quên - quên một câu là Claude đoán mò, và đoán sai chỗ tiền bạc thì trả giá đắt. Cần một chỗ ghi luật một lần, để mọi phiên sau tự bám.

Chỗ đó là một file tên CLAUDE.md đặt ở gốc repo. Đầu mỗi phiên, Claude Code tự đọc nó - coi như cuốn "nội quy dự án" luôn để sẵn trên bàn. Mèo con ghi vào đây ngữ cảnh sản phẩm, quy ước và những luật đã chốt; từ đó Claude làm theo thay vì đoán.

• ▸Là file Markdown ở gốc repo, tên đúng CLAUDE.md.
• ▸Claude tự nạp vào ngữ cảnh đầu mỗi phiên - không cần nhắc.
• ▸Khác câu chat (chỉ sống trong một phiên): CLAUDE.md là bộ nhớ lâu dài.

Vì Claude đọc CLAUDE.md ở đầu mỗi phiên, luật mèo con ghi một lần sẽ áp cho tất cả các lần vibe sau - trên máy, trên web hay trên điện thoại đều như nhau:

Đây chính là cách biến những điều mèo con phải dặn lặp đi lặp lại thành một bộ nhớ chung, ổn định theo dự án.

Bốn nhóm đáng ghi cho web bán hàng: ngữ cảnh sản phẩm (bán gì, có ví, ai dùng), quy ước code (đặt tên, cấu trúc thư mục), chuẩn chất lượng (a11y, bảo mật, format) và ràng buộc đã chốt. Một file mở đầu có thể trông như sau:

# Web bán hàng - Mèo Shop

## Sản phẩm
Web bán hàng online có ví điện tử. Khách tạo tài khoản,
nạp tiền qua QR (SePay), mua hàng thì trừ số dư. Có trang
quản trị (admin) quản lý hàng, kho, giao dịch và số dư.

## Stack
Next.js + PostgreSQL + Redis. Đăng nhập: Better-auth.
Giao diện: shadcn-react + Tailwind. Deploy: VPS riêng.

## Quy ước
- Code chạy qua Prettier trước khi commit.
- Chuỗi bí mật để trong .env, không hardcode.
- Tên bảng/cột tiếng Việt không dấu, snake_case.

Quan trọng nhất là phần ràng buộc bất biến - những luật mà sai một cái là hỏng sản phẩm hoặc thất thoát tiền. Ghi rõ để Claude không "tối ưu" lại theo ý nó:

## Đã chốt - đừng phá
- Tiền lưu bằng SỐ NGUYÊN, đơn vị đồng. KHÔNG dùng float.
- Số dư ví KHÔNG cache - đọc thẳng từ database mỗi lần.
- Mọi route /admin phải kiểm quyền trước khi chạy.
- Nạp tiền phải idempotent: một lần chuyển khoản chỉ
  cộng số dư đúng một lần dù webhook gửi lại.

CLAUDE.md càng phình thì Claude càng loãng và mèo con càng lười đọc lại. Giữ nó gọn: chỉ luật quan trọng và ngữ cảnh cần thiết. Khi chốt quyết định mới (đổi cách đăng nhập, thêm quy ước), cập nhật rồi commit - để lần vibe sau bám đúng ngay.

• ▸Ngắn gọn, đúng trọng tâm - đừng nhồi mọi thứ.
• ▸Commit CLAUDE.md lên GitHub để đồng bộ khi vibe trên web/điện thoại.
• ▸KHÔNG để bí mật (mật khẩu, khoá API) trong CLAUDE.md - thứ đó thuộc .env.