Bộ nhớ với CLAUDE.md

Mỗi phiên Claude Code bắt đầu với một cửa sổ ngữ cảnh (context window) trống trơn — Claude không “nhớ” gì từ phiên trước, trừ khi thông tin đó được nạp lại. Có hai cơ chế giúp mang kiến thức xuyên suốt các phiên:

CLAUDE.md — chỉ dẫn do bạn viết tay.
Auto memory — ghi chú do Claude tự viết dựa trên những gì nó học được (lệnh build, mẹo debug, sở thích của bạn…) trong lúc làm việc.

Cả hai đều được nạp vào đầu mỗi phiên, và đều là ngữ cảnh — nghĩa là Claude cố gắng làm theo chứ không đảm bảo tuân thủ tuyệt đối 100% (khác với Hooks, vốn bắt buộc thực thi). Chỉ dẫn càng cụ thể, càng ngắn gọn, Claude càng làm theo nhất quán.

	`CLAUDE.md`	Auto memory
Ai viết	Bạn	Claude
Nội dung	Chỉ dẫn, quy tắc	Điều học được, pattern
Phạm vi	Dự án / cá nhân / tổ chức	Theo từng repo
Dùng cho	Coding standard, quy trình, kiến trúc dự án	Lệnh build, mẹo debug, sở thích Claude tự phát hiện

`CLAUDE.md` — chỉ dẫn bạn viết tay

CLAUDE.md là file markdown Claude Code đọc vào đầu mỗi phiên làm việc. Dùng file này để thiết lập:

Quy chuẩn code (coding standards)
Quyết định kiến trúc quan trọng
Thư viện/công cụ ưu tiên sử dụng
Checklist review trước khi commit

Khi nào nên thêm vào CLAUDE.md

Coi CLAUDE.md là nơi ghi lại những điều bạn phải giải thích lại nhiều lần. Nên thêm khi:

Claude mắc lại đúng lỗi cũ lần thứ hai.
Một lượt review phát hiện điều Claude lẽ ra phải biết về codebase này.
Bạn gõ lại đúng một lời sửa/làm rõ mà phiên trước đã từng gõ.
Một thành viên mới trong team cũng cần biết điều tương tự để làm việc hiệu quả.

Chỉ nên giữ những sự thật cần có mặt trong mọi phiên: lệnh build, quy ước, cấu trúc dự án, các quy tắc “luôn luôn làm X”. Nếu một chỉ dẫn là quy trình nhiều bước hoặc chỉ áp dụng cho một phần nhỏ của codebase, hãy tách ra thành skill hoặc rule theo đường dẫn cụ thể (.claude/rules/, xem bên dưới) thay vì nhét hết vào CLAUDE.md.

Ví dụ CLAUDE.md tối giản

# Project ABC

## Stack
- Backend: Node.js + TypeScript, Fastify framework
- Database: PostgreSQL, Prisma ORM
- Test: Vitest

## Conventions
- Always write tests for new business logic
- No `any` in TypeScript
- Commit messages follow Conventional Commits

## Common commands
- `npm run dev` — start the dev server
- `npm test` — run the full test suite
- `npm run lint` — run lint checks

Có thể tạo nhanh bằng lệnh /init trong phiên tương tác — Claude sẽ tự khám phá dự án và đề xuất nội dung phù hợp. Nếu đã có sẵn CLAUDE.md, /init sẽ đề xuất cải thiện thay vì ghi đè.

Đặt CLAUDE.md ở đâu

CLAUDE.md có thể đặt ở nhiều cấp, được nạp theo thứ tự từ phạm vi rộng đến hẹp (chỉ dẫn của dự án xuất hiện sau chỉ dẫn cá nhân trong ngữ cảnh):

Phạm vi	Vị trí	Dùng cho	Chia sẻ với
Cấp tổ chức (managed)	Do IT/DevOps triển khai qua MDM	Quy chuẩn công ty, chính sách bảo mật	Toàn bộ nhân viên
Cá nhân, mọi dự án	`~/.claude/CLAUDE.md`	Sở thích cá nhân áp dụng cho mọi dự án	Chỉ bạn
Dự án, dùng chung	`./CLAUDE.md` hoặc `./.claude/CLAUDE.md`	Kiến trúc, quy chuẩn, quy trình của dự án	Cả team (qua git)
Cá nhân, riêng dự án	`./CLAUDE.local.md`	URL sandbox riêng, test data riêng — nhớ thêm vào `.gitignore`	Chỉ bạn, chỉ dự án này

Claude Code đọc CLAUDE.md/CLAUDE.local.md bằng cách đi ngược từ thư mục làm việc hiện tại lên thư mục gốc — vì vậy chạy Claude Code ở foo/bar/ sẽ nạp cả foo/CLAUDE.md lẫn foo/bar/CLAUDE.md. Các file CLAUDE.md trong thư mục con (bên dưới nơi bạn chạy Claude Code) chỉ được nạp khi Claude thực sự đọc file trong thư mục con đó, không nạp ngay từ đầu.

Chạy /context trong phiên để kiểm tra chính xác file nào đã được nạp vào mục Memory files.

Dự án dùng chung đã có sẵn AGENTS.md cho các coding agent khác? Tạo CLAUDE.md import lại file đó thay vì viết trùng nội dung:

@AGENTS.md

## Claude Code
Dùng plan mode cho các thay đổi trong src/billing/.

Viết chỉ dẫn hiệu quả

Vì CLAUDE.md là ngữ cảnh chứ không phải cấu hình bắt buộc, cách viết ảnh hưởng trực tiếp đến việc Claude có làm đúng theo hay không:

Độ dài: nên dưới 200 dòng mỗi file. File càng dài càng tốn ngữ cảnh và càng giảm độ tuân thủ.
Cấu trúc: dùng heading và bullet để nhóm chỉ dẫn liên quan — dễ quét hơn đoạn văn dài.
Cụ thể, kiểm chứng được: “Dùng thụt lề 2 dấu cách” tốt hơn “format code cho đẹp”; “Chạy npm test trước khi commit” tốt hơn “nhớ test code”.
Nhất quán: hai chỉ dẫn mâu thuẫn nhau khiến Claude chọn bừa một trong hai — rà soát định kỳ để loại bỏ chỉ dẫn lỗi thời.

Có thể chia nhỏ nội dung bằng cú pháp import @đường-dẫn (ví dụ @docs/git-instructions.md) — file được import vẫn tính vào ngữ cảnh nạp lúc khởi động, chỉ giúp tổ chức nội dung gọn hơn, không giảm dung lượng.

Tổ chức theo chủ đề với `.claude/rules/`

Với dự án lớn, có thể tách chỉ dẫn thành nhiều file trong .claude/rules/, mỗi file một chủ đề (testing.md, security.md…). Đặc biệt hữu ích: có thể giới hạn một rule chỉ áp dụng cho một số loại file bằng paths trong frontmatter — tránh nạp chỉ dẫn không liên quan mỗi phiên:

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules
- All API endpoints must include input validation
- Use the standard error response format

Rule không có paths được nạp ngay từ đầu như CLAUDE.md; rule có paths chỉ nạp khi Claude đọc đến file khớp pattern.

Auto memory — Claude tự ghi chú

Ngoài CLAUDE.md, Claude Code còn tự xây dựng “auto memory” trong quá trình làm việc: lệnh build, mẹo debug, quyết định kiến trúc, sở thích code style… được ghi lại mà không cần bạn chủ động viết. Claude không lưu mọi thứ mỗi phiên — nó tự đánh giá điều gì đáng nhớ cho những lần sau.

Bộ nhớ này được lưu trong ~/.claude/projects/<project>/memory/, gồm một file MEMORY.md (mục lục ngắn gọn, được nạp mỗi phiên) và các file chủ đề chi tiết hơn (chỉ đọc khi cần). Chạy /memory trong phiên để xem/sửa toàn bộ, hoặc tự sửa trực tiếp bằng tay vì đây chỉ là file markdown thường.

Muốn Claude nhớ điều gì đó ngay, chỉ cần nói thẳng: “luôn dùng pnpm, không dùng npm” hay “nhớ rằng test API cần Redis chạy sẵn ở local” — Claude sẽ tự lưu vào auto memory. Muốn thêm hẳn vào CLAUDE.md (chia sẻ với cả team) thì nói rõ “thêm điều này vào CLAUDE.md”.

Auto memory bật mặc định; tắt bằng cách vào /memory chọn tắt, hoặc đặt "autoMemoryEnabled": false trong settings.json.

Xử lý khi Claude không làm theo CLAUDE.md

Chạy /context, kiểm tra file có nằm trong Memory files không — nếu không thấy, Claude không đọc được file đó.
Kiểm tra chỉ dẫn có đủ cụ thể không (“dùng thụt lề 2 dấu cách” thay vì “format cho đẹp”).
Rà soát các CLAUDE.md/rule khác xem có mâu thuẫn nhau không.
Nếu chỉ dẫn cần chạy bắt buộc tại một thời điểm cố định (trước mỗi commit, sau mỗi lần sửa file…), dùng Hooks thay vì CLAUDE.md — hooks thực thi bằng shell script, không phụ thuộc việc Claude có “nhớ” hay không.