CLAUDE.md: Viết project instructions để Claude Code nhớ mãi không quên

Định nghĩa

CLAUDE.md là file markdown đặt tại thư mục gốc project (hoặc trong .claude/), đóng vai trò "bộ não dài hạn" cho Claude Code — nơi lưu trữ các quy tắc lập trình, quy ước team, và kiến trúc hệ thống mà AI sẽ tự động đọc lại ở mỗi phiên làm việc, ngay cả khi context window bị compaction.

Giải thích chi tiết

Vì sao CLAUDE.md giải cứu bạn khỏi "bức tường 20 phút"?

LLM agents là "vàng cá" với trí nhớ tuyệt vời cho 5 giây cuối cùng — chúng không có "hồi hải mã" (hippocampus). Khi bạn nói chuyện với Claude Code, mỗi turn là một inference mới trên chuỗi text. Sau khoảng 20 phút (hoặc khi context window đạt ~200K tokens), hệ thống kích hoạt "compaction" — nén lịch sử hội thoại một cách lossy để nhường chỗ cho tool output mới.

Điều gì xảy ra? Câu nhắc nhở quan trọng như "Đừng bao giờ xóa email mà không có approve" bị nén thành "xử lý email cẩn thận" — sắc thái biến mất, rào cản an toàn tan biến. Đây là lý do agents "điên loạn" sau 20 phút: instruction tokens bị đẩy ra để nhường chỗ, và bản tóm tắt không giữ lại ràng buộc.

CLAUDE.md là giải pháp kiến trúc: Nó tồn tại ngoài context window, được re-inject tươi mới mỗi turn như một "disk storage" trong khi chat history chỉ là "RAM volatile". Chat dùng để trò chuyện, file dùng để lưu trạng thái.

Ba tầng Memory: Hiểu đúng vị trí CLAUDE.md

Claude Code tổ chức memory theo ba scope — CLAUDE.md nằm ở tầng Project:

User scope (~/.claude/memory/): Cross-project, lưu coding style cá nhân, sở thích (bạn thích tab hay spaces, thói quen đặt tên biến). Loaded mỗi khi mở session bất kỳ project nào.

Project scope (.claude/memory/ hoặc CLAUDE.md ở root): Repository-specific — architectural decisions (vì sao chọn Repository pattern thay vì Active Record), team conventions, lịch sử feature. Sống sót qua các session nhưng cô lập per codebase.

Local scope: Session-only, không lưu file — dùng cho data sensitive hoặc task một lần mà persistence là rủi ro.

CLAUDE.md thuộc Project scope — nó là "bộ nhớ ngữ nghĩa" (semantic memory) của dự án, tồn tại xuyên suốt các phiên làm việc nhưng không lẫn sang dự án khác.

CLAUDE.md khác gì với việc nhắc nhở trong chat?

Nói cách khác: Chat là "làm việc bộ nhớ" (working memory), CLAUDE.md là "bộ nhớ dài hạn" (long-term storage). Bạn không thể giữ toàn bộ handbook công ty trong đầu khi code — bạn tra cứu khi cần. Claude cũng vậy: nó không cần nhớ tất cả, chỉ cần biết tra CLAUDE.md khi cần quyết định kiến trúc.

Cấu trúc file tối ưu

Một CLAUDE.md hiệu quả không phải là file dài 5000 dòng. Nó là progressive disclosure:

• Phần 1 — Metadata & Constraints (đọc trước): Tech stack, ngôn ngữ, framework, các quy tắc bất biến (immutable rules).
• Phần 2 — Architectural Decisions (ADR): Tại sao dùng Microservice thay vì Monolith, tại sao database sharding theo region Việt Nam.
• Phần 3 — Common Patterns: Cách xử lý lỗi chuẩn, format response API, quy ước đặt tên file.
• Phần 4 — Context dự án đặc thù: Bảng màu brand, business logic lạ (ví dụ: "trong hệ thống này, user.deleted không có nghĩa xóa hard, chỉ là soft delete").

Ví dụ thực tế

Dự án React + TypeScript cho startup Việt Nam

File CLAUDE.md đặt tại root:

# Project Instructions: E-commerce Platform

## Stack & Tools
- React 18 + TypeScript (strict mode)
- Tailwind CSS (không dùng CSS modules)
- React Query cho data fetching
- Zod cho schema validation

## Architectural Rules
1. Luôn dùng functional components, không class components
2. API calls chỉ được thực hiện trong `hooks/useApi.ts`, không gọi trực tiếp axios trong component
3. Error handling: Hiển thị toast tiếng Việt cho user, log tiếng Anh cho developer
4. Form validation: Dùng react-hook-form + zod, không dùng formik

## Naming Conventions
- Components: PascalCase (ProductCard.tsx)
- Hooks: camelCase bắt đầu bằng `use` (useCart.ts)
- Utils: camelCase (formatCurrency.ts)
- Types: PascalCase + suffix (ProductType.ts)

## Business Context
- Đơn vị tiền tệ mặc định là VND, format: "100.000 ₫" (dùng dấu chấm phân cách hàng nghìn)
- Thời gian hiển thị theo múi giờ Asia/Ho_Chi_Minh
- "Hủy đơn" là soft delete, không xóa record trong DB
- Tích hợp thanh toán: Ưu tiên VietQR và MoMo, ít dùng credit card quốc tế

Kết quả: Sau 3 ngày nghỉ, bạn mở lại project, gõ "Thêm chức năng giảm giá" — Claude vẫn nhớ phải dùng Zod validate input, nhớ format tiền VND có dấu chấm, và không bao giờ gợi ý class component.

API Backend Node.js với quy tắc bảo mật nghiêm ngặt

File .claude/SECURITY.md (hoặc trong CLAUDE.md):

## Security Constraints (Critical - Never Violate)
- Không bao giờ log `password`, `token`, `credit_card` fields
- Mọi API endpoint phải có `authenticate` middleware trừ `/health` và `/login`
- SQL queries chỉ được thực hiện qua parameterized queries (knex.raw), không string concatenation
- Khi xóa user, phải gọi `AuditLog.create()` ghi lại action và lý do

Đặt trong Project scope. Khi Claude viết code xử lý user deletion, dù context đã đầy sau 50 lượt chat về feature khác, file này vẫn được re-inject — đảm bảo audit log không bao giờ bị quên.

Ứng dụng

Developer cá nhân

Giữ nhất quán coding style giữa các session. Bạn không còn phải nhắc "nhớ dùng Prettier với single quote" mỗi lần mở Claude. Viết một lần trong ~/.claude/CLAUDE.md (User scope) để áp dụng cho mọi project cá nhân, hoặc CLAUDE.md riêng cho từng repo nếu style khác nhau.

Team Lead và Tech Lead

Truyền architectural decisions cho toàn team qua file version control. Thay vì onboard member mới bằng cách kể "chúng ta dùng Repository pattern vì...", bạn commit CLAUDE.md vào git. Member mới clone repo, chạy Claude Code — AI tự động biết codebase structure và conventions, rút ngắn thời gian làm quen từ 2 tuần xuống 2 ngày.

Product Manager kỹ thuật

Lưu business logic phức tạp mà không phải giải thích lại. Ví dụ: "Trong hệ thống ERP này, lương tháng 13 tính theo công thức 3P khác với lương tháng thường". Viết vào CLAUDE.md, Claude sẽ nhớ áp dụng đúng công thức khi generate code báo cáo lương.

Non-coder (Vibe Coding)

Người không biết code có thể dùng CLAUDE.md để "đóng gói" intent. Thay vì mô tả lại "Tôi muốn app có màu xanh dương như logo công ty" mỗi lần sửa UI, họ viết một lần vào CLAUDE.md: "Brand color: #1E40AF, Font chữ tiếng Việt: Be Vietnam Pro". Sau đó chỉ cần nói "Làm đẹp trang login" — Claude tự áp dụng brand guidelines.

So sánh: CLAUDE.md vs các phương pháp khác

Kết luận: CLAUDE.md là sự kết hợp giữa tính bền vững của documentation và tính tự động của system prompt. Nó không thay thế việc học cách viết prompt tốt, nhưng loại bỏ gánh nặng "phải nhắc lại từ đầu" mỗi khi bắt đầu session mới.

Bài viết liên quan

Cùng cụm (Core Concepts)

• Vòng lặp Agent: Claude Code hoạt động thế nào? — Hiểu cơ chế compaction và tại sao cần external memory
• Hệ thống Tools và Permission — Cách Claude đọc file và thực thi lệnh an toàn
• Context Window 1 triệu token: Hiểu và tận dụng — Tại sao 200K tokens vẫn không đủ nếu không có CLAUDE.md
• Hệ thống Settings: Global, Project, Local — Cấu hình đa tầng trong Claude Code
• 6 chế độ Permission — Khi nào cần plan mode để review CLAUDE.md changes

Đọc tiếp (Level 1 — Sử dụng thực chiến)

• Hệ thống Memory: User, Project, Local scope — Đi sâu vào ba tầng memory và cách tối ưu cho workflow cá nhân
• Slash Commands cơ bản — Tận dụng CLAUDE.md kết hợp với /plan và /memory để quản lý project hiệu quả