CLAUDE.md: Tối ưu hóa ngữ cảnh (context) cho Claude Code

CLAUDE.md là một lớp ngữ cảnh (context layer) giúp triệt tiêu độ trễ thiết lập (setup latency) và tối ưu chi phí token (token economy) khi làm việc với Claude Code.

Thay vì phải tái định nghĩa môi trường trong mỗi phiên làm việc, file Markdown này cung cấp một "bộ nhớ vĩnh viễn" (persistent memory) nằm tại gốc dự án. Claude Code tự động nạp các chỉ dẫn này ngay sau system prompt để hiểu cấu trúc, quy tắc và phong cách lập trình của bạn mà không cần giải thích lại.

Vấn đề cốt lõi của các mô hình ngôn ngữ lớn (LLM) hiện nay là tính vô trạng thái (stateless) — chúng không học thêm từ các phiên hội thoại trừ khi thông tin được nạp trực tiếp vào cửa sổ ngữ cảnh (context window). CLAUDE.md giải quyết bài toán "mất trí nhớ" này, biến Claude từ một trợ lý mới tuyển dụng thành một cộng sự cấp cao am hiểu hệ thống chỉ trong vài mili giây khởi chạy.

Sơ đồ khái niệm: file CLAUDE.md nằm tại gốc dự án được Claude Code nạp vào mỗi phiên làm việc như một bộ nhớ thường trực, giúp AI nắm cấu trúc và quy tắc dự án ngay từ prompt đầu tiên.

Tại sao các dự án chuyên nghiệp cần CLAUDE.md?

Trong quy trình làm việc thực tế, một kỹ sư thường mất kha khá thời gian mỗi sáng để tái thiết lập ngữ cảnh cho AI. CLAUDE.md triệt tiêu khoản phí này bằng cách đóng vai tài liệu tóm tắt (briefing document) cho một đồng nghiệp đang bị mất trí nhớ tạm thời.

Lợi ích về mặt kỹ thuật bao gồm:

Tối ưu token: không lãng phí token để nhắc lại các lệnh build/test cơ bản.
Nhất quán kiến trúc: ngăn AI tự ý dùng npm khi dự án chạy pnpm, hoặc dùng default exports khi quy chuẩn là named exports.
Giảm sai sót hệ thống: cung cấp các rào chắn (guardrail) về bảo mật và tuân thủ (compliance) ngay từ đầu phiên làm việc.

Cơ chế xếp chồng (stacking) và thứ tự ưu tiên

Claude Code nạp các file chỉ dẫn theo thứ tự từ gốc hệ thống tệp (filesystem root) xuống thư mục làm việc hiện hành. Dữ liệu được nối tiếp (concatenated) thay vì ghi đè hoàn toàn:

Sơ đồ phân tầng cách Claude Code nạp file chỉ dẫn: bốn lớp xếp chồng từ Managed Policy đến User, Project rồi Local, đi từ gốc hệ thống xuống thư mục làm việc; lớp gần thư mục làm việc nhất có ưu tiên cao nhất.

Managed Policy: chính sách doanh nghiệp (ví dụ /etc/claude-code/CLAUDE.md). Không thể bị loại trừ bởi người dùng.
User Instructions: cấu hình cá nhân cho mọi dự án (~/.claude/CLAUDE.md).
Project Instructions: file tại gốc dự án (./CLAUDE.md hoặc ./.claude/CLAUDE.md). Thường được commit lên Git.
Local Instructions: ghi chú cá nhân, sandbox URL (./CLAUDE.local.md). Nên đưa vào .gitignore.

Lưu ý cho monorepo: trong các dự án lớn, bạn có thể dùng cấu hình claudeMdExcludes trong .claude/settings.local.json để loại bỏ các file CLAUDE.md không liên quan từ những team khác, tránh làm loãng ngữ cảnh.