CLAUDE.md — Lớp bộ nhớ: "hiến pháp" của agent

Ở bài tổng quan, chúng ta ví một AI "trần" như nhân sự giỏi nhưng ngày nào cũng phải onboarding lại. CLAUDE.md chính là lời giải đầu tiên và nền tảng nhất cho vấn đề đó: một tài liệu mà Claude đọc ngay khi bắt đầu, để không bao giờ phải hỏi lại "dự án này làm gì, quy ước ra sao".

Đây là lớp móng của cả bộ công cụ. Làm tốt CLAUDE.md, mọi lớp phía sau (Skills, Hooks, Subagents...) đều mượt hơn. Làm ẩu, agent sẽ liên tục "đoán mò" bối cảnh.

CLAUDE.md là gì và hoạt động ra sao

Mỗi phiên Claude Code bắt đầu với một context window trống. CLAUDE.md là một file Markdown bạn viết; Claude đọc nó ở đầu mỗi phiên để có ngữ cảnh bền vững — chuẩn code, lệnh build, ghi chú kiến trúc — mà không cần bạn lặp lại trong từng cuộc trò chuyện (Claude Docs — Memory).

Cách hình dung đúng: nó giống bản "hiến pháp" hoặc tài liệu onboarding của dự án. Bạn viết một lần, Claude tuân theo mọi lần.

Một chi tiết kỹ thuật đáng lưu ý (và hay bị nói sai): nội dung CLAUDE.md không nằm trong system prompt — theo tài liệu chính thức, nó được đọc ở đầu phiên và đưa vào như một user message ngay sau system prompt (Anthropic Support — CLAUDE.md). Hệ quả thực tế: đây là chỉ dẫn có sức nặng cao nhưng không phải mệnh lệnh tuyệt đối — Claude cố tuân theo, không đảm bảo 100%. Muốn ràng buộc cứng, ta dùng Hooks (xem Bài 3).

Phân cấp bộ nhớ: 4 tầng, nạp từ rộng đến hẹp

Sức mạnh thật của CLAUDE.md nằm ở chỗ nó phân cấp. Claude Code nạp nhiều file theo thứ tự, và các file được nối lại (concatenate) chứ không ghi đè nhau (Claude Docs — Memory):

Quy tắc nạp: Claude đi ngược lên cây thư mục từ nơi bạn chạy, gom các file lại từ gốc filesystem xuống thư mục làm việc. Nội dung xuất hiện sau có xu hướng được "chú ý" hơn — nên chỉ dẫn hẹp/cụ thể (project, local) tự nhiên có trọng số cao hơn chỉ dẫn chung (user). File CLAUDE.md ở thư mục con được nạp theo yêu cầu khi Claude đọc file trong thư mục đó, không phải lúc khởi động.

Ý nghĩa với doanh nghiệp: IT có thể đặt một CLAUDE.md cấp tổ chức để áp chuẩn chung cho mọi máy, mọi repo — một cơ chế governance nhẹ nhàng nhưng hiệu quả.

@import: tổ chức file, không nhồi nhét

Bạn có thể kéo nội dung file khác vào CLAUDE.md bằng cú pháp @:

# Quy ước dự án
- Quy trình git: @docs/git-instructions.md
- Chuẩn API: @.claude/rules/api-style.md

@import hỗ trợ đường dẫn tương đối/tuyệt đối và cho phép import lồng nhau nhiều tầng — tài liệu có nêu giới hạn độ sâu (các nguồn ghi khoảng 4–5 hop tùy phiên bản), nên đừng lồng quá sâu (Claude Docs — Memory). Nếu chỉ muốn nhắc đường dẫn mà không import, bọc trong backtick: ` @README `.

Cạm bẫy quan trọng: @import giúp tổ chức file gọn gàng, nhưng không giảm token — file được import vẫn nạp đầy đủ lúc khởi động. Đừng tưởng tách file ra là tiết kiệm ngữ cảnh.

Hai lệnh bạn phải biết: /init và /memory

• /init — sinh một CLAUDE.md khởi đầu bằng cách quét dự án. Nó còn đọc các file quy ước có sẵn như AGENTS.md, .cursorrules, .windsurfrules nếu tồn tại. Nếu chọn tùy chọn cá nhân, nó tự thêm CLAUDE.local.md vào .gitignore.
• /memory — liệt kê các file bộ nhớ đang được nạp, cho bật/tắt auto memory, và mở thư mục bộ nhớ để chỉnh sửa.

Một mẹo tương thích: Claude Code đọc CLAUDE.md, không đọc AGENTS.md trực tiếp. Nếu dự án của bạn dùng AGENTS.md (chuẩn dùng chung nhiều công cụ), hãy tạo CLAUDE.md chỉ gồm một dòng @AGENTS.md để tái dùng.

Ghi chú nhỏ mà hữu ích: các khối HTML comment <!-- ... --> trong CLAUDE.md bị loại bỏ trước khi vào ngữ cảnh — dùng để ghi chú cho người đọc mà không tốn token.

"Auto memory": bộ nhớ thứ hai, do Claude tự viết

Ngoài CLAUDE.md (bạn viết), Claude Code còn có hệ thống auto memory — nơi Claude tự ghi lại những bài học và pattern nó khám phá trong lúc làm việc (lệnh build hay dùng, insight khi debug, sở thích của bạn). Theo tài liệu hiện tại, nó lưu ở thư mục bộ nhớ cục bộ của dự án, có file MEMORY.md làm chỉ mục, và chỉ phần đầu của chỉ mục được nạp mỗi phiên (phần còn lại nạp theo yêu cầu) (Claude Docs — Memory).

Phân biệt rõ hai thứ:

Bốn thứ tên "memory" rất dễ nhầm

Đây là điểm gây rối nhất cho người mới, cần tách bạch:

1. CLAUDE.md (Claude Code) — file chỉ dẫn bạn viết, nạp vào ngữ cảnh phiên.
2. Auto memory (Claude Code) — Claude tự ghi note cục bộ trên máy.
3. Memory tool (Claude Developer Platform / API) — một công cụ để Claude tự tạo/đọc/sửa/xóa file trong một thư mục bộ nhớ đặt trên hạ tầng của bạn, bền vững qua nhiều cuộc hội thoại, giúp giảm áp lực context window (Anthropic — Context management). Đây là API tool, không phải cơ chế nạp chỉ dẫn của Claude Code.
4. Managed Agents memory store (Claude Developer Platform, beta) — kho tài liệu text theo workspace, khi gắn vào phiên sẽ được mount thành thư mục trong sandbox; có audit log, versioning, rollback (Claude Platform Docs).

Khi đọc tài liệu hay bài viết khác, luôn hỏi: "memory" ở đây là cái nào trong bốn cái trên?

Best practices: viết CLAUDE.md cho đúng

Từ tài liệu gốc và khung "steering" của Anthropic (Claude Docs — Memory; Steering Claude Code):

• Ngắn gọn. Nhắm dưới ~200 dòng. File dài tốn ngữ cảnh và làm giảm mức tuân thủ.
• Cụ thể hơn mơ hồ. "Dùng thụt lề 2 space" tốt hơn "format code cho đẹp"; "Chạy npm test trước khi commit" tốt hơn "nhớ test".
• Tránh mâu thuẫn. Hai quy tắc chọi nhau khiến Claude chọn tùy tiện. Rà soát định kỳ.
• Đặt đúng chỗ. Đây là nguyên tắc quan trọng nhất:
• Quy tắc kiểu "Mỗi khi X luôn làm Y" → nên là Hook (tất định), không phải câu chữ trong CLAUDE.md.
• Ràng buộc bắt buộc kiểu "Tuyệt đối không..." → Hook/permission, không phải CLAUDE.md.
• Một thủ tục dài ~30 dòng → nên tách thành Skill.
• Quy tắc chỉ áp cho src/api/** → nên là rule có paths: (nạp theo phạm vi file).
• Sở thích cá nhân → file user/local, đừng nhét vào CLAUDE.md của dự án dùng chung.
• Governance tổ chức. Managed CLAUDE.md (và managed settings) áp cho mọi phiên trên máy và không thể loại trừ — dùng cho chuẩn bắt buộc cấp công ty.

Ví dụ tối giản

Một CLAUDE.md dự án tốt không cần dài:

# Dự án: izzi-web (Next.js 16, TypeScript)

## Quy ước
- Dùng TypeScript strict; không dùng `any`.
- Test bằng vitest; chạy `npm run verify` trước khi commit.
- Component đặt trong `src/components/`, đặt tên PascalCase.

## Kiến trúc
- Backend gọi qua `src/lib/api.ts` (Bearer JWT), không fetch trực tiếp.
- Chi tiết quy trình git: @docs/git-instructions.md

Ngắn, cụ thể, đúng chỗ — Claude có thể tuân theo mà không tốn nhiều ngữ cảnh.

Tóm tắt & bước tiếp theo

CLAUDE.md là lớp bộ nhớ nền tảng: nó cho Claude bối cảnh bền vững qua phân cấp 4 tầng, tổ chức bằng @import, khởi tạo bằng /init, kiểm tra bằng /memory. Nhớ hai điều: (1) nó là chỉ dẫn, không phải guardrail tuyệt đối; (2) đừng nhầm nó với ba loại "memory" khác.

Nhưng có những kiến thức/quy trình quá dài hoặc quá chuyên biệt để nhét vào CLAUDE.md. Đó là lúc cần Agent Skills — đóng gói chuyên môn thành module nạp theo yêu cầu. Đó là nội dung Bài 2.

Nguồn tham khảo

• Claude Docs — Memory (CLAUDE.md): https://docs.claude.com/en/docs/claude-code/memory
• Anthropic Support — Give Claude context: CLAUDE.md (user message sau system prompt): https://support.claude.com/en/articles/14553240-give-claude-context-claude-md-and-better-prompts
• Anthropic — Steering Claude Code: https://claude.com/blog/steering-claude-code-skills-hooks-rules-subagents-and-more
• Anthropic — Context management (memory tool API): https://www.anthropic.com/news/context-management
• Claude Platform Docs — Managed Agents memory: https://platform.claude.com/docs/en/managed-agents/memory
• AZDIGI — chuỗi Claude Code tiếng Việt: https://azdigi.com/blog

Bài 1/7 trong chuỗi "Bộ công cụ phát triển Agent với Claude". Nội dung diễn giải lại từ tài liệu gốc của Anthropic. Trước ← Bài 0: Tổng quan · Tiếp theo → Bài 2: Agent Skills.