# CLAUDE.md là gì? Viết file hướng dẫn để AI hiểu dự án của bạn

URL: https://opcaios.org/blog/claude-md-la-gi
Ngày: 2026-11-18
Cập nhật: 2026-11-04
Tác giả: Lê Quốc Nghĩa
Chuyên mục: Hướng dẫn

CLAUDE.md là gì? CLAUDE.md là một file Markdown chứa hướng dẫn lâu dài mà bạn tự viết cho [Claude Code](/tien-ich/claude-code): cách chạy dự án, quy ước đặt tên, việc luôn phải làm, việc không được làm. Theo trang "How Claude remembers your project" trong tài liệu Claude Code tại code.claude.com (đọc ngày 03/11/2026), mỗi phiên Claude Code bắt đầu với một ngữ cảnh trống, và CLAUDE.md được nạp ngay đầu phiên để Claude không phải hỏi lại những điều bạn đã giải thích. Bài này không hứa CLAUDE.md khiến AI luôn làm đúng, vì chính tài liệu nói Claude coi CLAUDE.md là ngữ cảnh, không phải cấu hình bắt buộc; OPCAIOS cũng không có số đo về mức cải thiện. Nội dung gồm các cấp của CLAUDE.md, cách import file khác, nên ghi gì và không nên ghi gì, khác biệt với bộ nhớ tự động và AGENTS.md, lệnh /init, một mẫu ngắn cho người làm một mình, và cách OPCAIOS đang tổ chức file hướng dẫn thật. Nếu chưa biết Claude Code là gì, đọc trước bài [Claude Code là gì](/blog/claude-code-la-gi).

![Sơ đồ CLAUDE.md: file cấp tổ chức, file cấp người dùng, file cấp dự án và CLAUDE.local.md được nạp theo thứ tự từ rộng đến hẹp khi bắt đầu phiên; file trong thư mục con nạp khi Claude đọc tới thư mục đó; import bằng @đường-dẫn kéo thêm file; bộ nhớ tự động nằm riêng do Claude tự ghi](https://opcaios.org/images/blog/claude-md-la-gi/so-do.webp)
*Các cấp CLAUDE.md, thứ tự nạp và vị trí của bộ nhớ tự động. Sơ đồ: OPCAIOS.*

## CLAUDE.md dùng để làm gì trong Claude Code?

CLAUDE.md dùng để ghi lại những điều bạn sẽ phải giải thích lại cho Claude Code ở mỗi phiên mới. Tài liệu Claude Code (đọc ngày 03/11/2026) gợi ý bốn dấu hiệu nên thêm một dòng vào CLAUDE.md: Claude mắc cùng một lỗi lần thứ hai, một lần duyệt mã phát hiện điều Claude lẽ ra phải biết về dự án, bạn gõ lại đúng lời nhắc đã gõ ở phiên trước, hoặc một người mới vào dự án cũng cần đúng thông tin đó. Nội dung phù hợp là sự thật cần có trong mọi phiên: lệnh build, lệnh chạy thử, quy ước, bố cục thư mục, quy tắc kiểu "luôn làm X". Một quy trình nhiều bước hoặc chỉ dùng cho một phần mã nên chuyển sang skill hoặc rule theo đường dẫn. Điểm quan trọng nhất cần nhớ: CLAUDE.md định hướng hành vi, không cưỡng chế. Muốn chặn chắc chắn một hành động bất kể Claude quyết định gì, tài liệu khuyên dùng hook PreToolUse, xem bài [hooks trong Claude Code](/blog/hooks-trong-claude-code).

## CLAUDE.md có những cấp nào và nạp theo thứ tự nào?

CLAUDE.md có bốn cấp chính, nạp từ phạm vi rộng nhất đến hẹp nhất, nên hướng dẫn của dự án xuất hiện sau hướng dẫn của người dùng trong ngữ cảnh. Theo bảng trong tài liệu chính thức (đọc ngày 03/11/2026):

| Cấp | Vị trí | Dùng cho | Ai thấy |
|---|---|---|---|
| Chính sách tổ chức | Thư mục hệ thống do IT quản lý (khác nhau trên macOS, Linux, Windows) | Chuẩn mã, bảo mật, tuân thủ của công ty | Mọi người dùng trên máy |
| Người dùng | `~/.claude/CLAUDE.md` | Thói quen cá nhân cho mọi dự án | Chỉ bạn |
| Dự án | `./CLAUDE.md` hoặc `./.claude/CLAUDE.md` | Kiến trúc, lệnh, quy trình chung của dự án | Cả nhóm, qua git |
| Cục bộ | `./CLAUDE.local.md` | Ghi chú riêng cho một dự án, nên đưa vào `.gitignore` | Chỉ bạn |

Claude Code đọc CLAUDE.md ở thư mục đang làm việc và mọi thư mục phía trên khi khởi động. Các file được nối với nhau, không file nào ghi đè file nào; file gần thư mục bạn mở nhất được đọc cuối. File CLAUDE.md trong thư mục con không nạp ngay mà nạp khi Claude đọc, ghi hoặc sửa một file trong thư mục con đó. Để xem file nào đã nạp, chạy `/context` và nhìn mục Memory files.

### Import file khác vào CLAUDE.md như thế nào?

Import là cách kéo nội dung một file khác vào CLAUDE.md bằng cú pháp `@đường/dẫn`. Theo tài liệu (đọc ngày 03/11/2026), đường dẫn tương đối được tính từ chính file chứa lệnh import, file được import có thể import tiếp, tối đa bốn tầng. Import giúp chia file cho gọn nhưng không làm giảm ngữ cảnh, vì file được import nạp cùng lúc với CLAUDE.md. Import trỏ ra ngoài thư mục dự án sẽ hiện hộp thoại xin duyệt ở lần đầu.

## Nên ghi gì và không nên ghi gì trong CLAUDE.md?

Nên ghi trong CLAUDE.md những câu đủ cụ thể để kiểm tra được, vì câu chung chung thì Claude không biết đã làm đúng hay chưa. Tài liệu Claude Code (đọc ngày 03/11/2026) đưa ví dụ: viết "chạy npm test trước khi commit" thay cho "hãy kiểm tra thay đổi", viết "API nằm trong src/api/handlers/" thay cho "giữ file gọn gàng". Danh sách thực dụng:

1. Lệnh chạy, build, kiểm tra mà dự án thật sự dùng.
2. Quy ước khác với mặc định của công cụ (ví dụ chỉ dùng một trình quản lý gói).
3. Việc cấm: không sửa file bí mật, không đẩy thẳng lên nhánh chính.
4. Bẫy đã gặp và lý do của một quyết định kiến trúc.
5. Thứ tự đọc tài liệu khi bắt đầu một loại việc.

Không nên ghi:

1. Khoá API, mật khẩu, địa chỉ máy chủ nội bộ (file dự án đi theo git).
2. Danh sách thư mục, danh sách thư viện mà Claude tự đọc được từ mã.
3. Quy trình dài chỉ dùng thỉnh thoảng: chuyển sang [skill](/blog/skill-la-gi-cach-dung-skill).
4. Hai quy tắc mâu thuẫn nhau: tài liệu cảnh báo Claude có thể chọn tuỳ ý một trong hai.

## CLAUDE.md nên dài bao nhiêu?

CLAUDE.md nên ngắn, mục tiêu dưới 200 dòng mỗi file theo khuyến nghị trong tài liệu Claude Code (đọc ngày 03/11/2026), vì file càng dài càng tốn ngữ cảnh và càng giảm mức tuân thủ. Cách giữ file ngắn có ba hướng. Thứ nhất, chuyển hướng dẫn chỉ áp dụng cho một phần mã vào thư mục `.claude/rules/`, nơi mỗi file rule có thể khai báo trường `paths` trong frontmatter để chỉ nạp khi Claude làm việc với file khớp mẫu, ví dụ chỉ file trong src/api. Thứ hai, chuyển quy trình nhiều bước thành skill, vì skill chỉ nạp khi được gọi hoặc khi liên quan. Thứ ba, định kỳ xoá dòng lỗi thời; tài liệu có nhắc lệnh `/doctor prompt-audit` để Claude tìm hướng dẫn cũ, mâu thuẫn hoặc trỏ tới file không tồn tại, yêu cầu Claude Code từ v2.1.283. Chú thích HTML dạng khối trong CLAUDE.md bị bỏ đi trước khi vào ngữ cảnh, nên có thể để ghi chú cho người mà không tốn token.

## CLAUDE.md khác bộ nhớ tự động (auto memory) thế nào?

CLAUDE.md do bạn viết, còn bộ nhớ tự động (auto memory) do Claude tự ghi dựa trên lời sửa và sở thích của bạn. Tài liệu Claude Code (đọc ngày 03/11/2026) so sánh như sau:

| | CLAUDE.md | Bộ nhớ tự động |
|---|---|---|
| Ai viết | Bạn | Claude |
| Nội dung | Hướng dẫn, quy tắc | Điều học được, lời sửa, bối cảnh không suy ra từ mã |
| Phạm vi | Tổ chức, người dùng, dự án | Theo từng repo, dùng chung giữa các worktree |
| Nạp vào phiên | Toàn bộ file | 200 dòng đầu hoặc 25KB đầu của file mục lục MEMORY.md |

Bộ nhớ tự động nằm trong thư mục riêng của từng dự án trên máy, gồm một file mục lục MEMORY.md và nhiều file ghi chú theo chủ đề; file chủ đề chỉ được đọc khi cần. Bộ nhớ chỉ ở trên máy, không đồng bộ sang máy khác. Bật tắt và xem lại bằng lệnh `/memory`; muốn Claude ghi vào CLAUDE.md thay vì bộ nhớ thì nói rõ "thêm vào CLAUDE.md".

## CLAUDE.md khác AGENTS.md thế nào?

AGENTS.md là file hướng dẫn dùng chung cho nhiều tác tử lập trình, còn CLAUDE.md là file riêng của Claude Code. Theo tài liệu (đọc ngày 03/11/2026), từ Claude Code v2.1.277, nếu thư mục làm việc và các thư mục cha không có CLAUDE.md hay CLAUDE.local.md, Claude đọc AGENTS.md thay thế; nếu có CLAUDE.md thì mặc định chỉ đọc CLAUDE.md. File `~/.claude/CLAUDE.md` cấp người dùng không tính vào phép kiểm tra này, nên vẫn nạp song song với AGENTS.md. Muốn đọc cả hai, đổi mục Project instructions trong `/config`. Cách an toàn cho mọi phiên bản là đặt dòng import ở đầu CLAUDE.md:

```markdown
@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.
```

Ví dụ trên lấy từ tài liệu chính thức: Claude đọc AGENTS.md trước, rồi đến phần riêng cho Claude.

## Lệnh /init giúp tạo CLAUDE.md ra sao?

Lệnh `/init` tạo một CLAUDE.md khởi đầu: Claude phân tích mã nguồn rồi ghi lệnh build, cách chạy thử và quy ước tìm được. Theo tài liệu (đọc ngày 03/11/2026), nếu đã có CLAUDE.md thì `/init` đề xuất cải thiện thay vì ghi đè. Đặt biến môi trường `CLAUDE_CODE_NEW_INIT=1` thì `/init` chuyển sang luồng hỏi đáp nhiều bước, hỏi muốn dựng CLAUDE.md, skill hay hook, và cho xem đề xuất trước khi ghi file. Sau `/init`, việc của bạn là cắt bớt phần Claude tự đọc được và thêm những điều Claude không thể tự biết.

## Mẫu CLAUDE.md ngắn cho người làm một mình

Đây là MẪU minh hoạ cho một dự án giả định (website bán khoá học nhỏ), không phải file thật của OPCAIOS. Thay lệnh và đường dẫn bằng của bạn:

```markdown
# Dự án: website khoá học (mẫu)

## Lệnh
- Cài: npm install
- Chạy thử: npm run dev
- Kiểm tra trước khi commit: npm run lint && npm test

## Quy ước
- Trả lời bằng tiếng Việt, ngắn gọn.
- Chỉ dùng npm, không dùng yarn.
- Mã giao diện nằm trong src/app/, mã gọi API nằm trong src/lib/.

## Không được làm
- Không đọc hay sửa file .env.
- Không đẩy thẳng lên nhánh main; tạo nhánh và báo lại.
- Không xoá dữ liệu thật; hỏi trước mọi lệnh xoá.
```

Khoảng 20 dòng là đủ để bắt đầu; mỗi lần phải dặn lại một điều thì thêm một dòng.

## Kinh nghiệm của OPCAIOS

OPCAIOS là website do một người vận hành cùng nhiều tác tử AI (Claude Code, Codex CLI, [Google Antigravity](/tien-ich/google-antigravity)), nên cách tổ chức file hướng dẫn được chọn để các tác tử khác nhau đọc chung một nguồn. Những gì chúng tôi đang làm thật (kiểm tra ngày 03/11/2026):

1. Một file hướng dẫn chung kiểu AGENTS.md cho mọi tác tử: thứ tự đọc tài liệu đầu phiên, cuối phiên phải ghi nhật ký vào một file trạng thái chung và nhật ký ngày, không để file rác.
2. Một file CLAUDE.md cấp người dùng, khoảng 30 dòng: bắt buộc trả lời tiếng Việt, trỏ về file hướng dẫn chung, nhắc rằng cổng và kết quả deploy ghi trong file chỉ để tham khảo, phải kiểm tra thực tế.
3. Repo website KHÔNG có CLAUDE.md riêng ở gốc. Quy tắc của website nằm trong bộ nhớ tự động: khoảng 40 ghi chú nhỏ cùng một file mục lục, ghi cả quy tắc như "chỉ commit đúng đường dẫn của mình" (vì nhiều phiên dùng chung chỉ mục git, xem [nhiều phiên AI cùng sửa một dự án](/blog/nhieu-phien-ai-cung-sua-mot-du-an)) và "deploy xong mới báo".
4. Quy trình dài như viết blog được gói thành skill thay vì nhét vào CLAUDE.md.

Điều chưa làm tốt: chúng tôi chưa đo được việc tuân thủ tăng hay giảm theo độ dài file; quy tắc quan trọng như "không xoá" vẫn chỉ là hướng dẫn, chưa có hook chặn.

## Câu hỏi thường gặp

### CLAUDE.md có bắt buộc phải có không?

Không bắt buộc. Claude Code vẫn chạy khi không có CLAUDE.md, và từ v2.1.277 sẽ đọc AGENTS.md nếu repo chỉ có file đó. Tuy vậy, nếu bạn thấy mình gõ lại cùng một lời dặn ở nhiều phiên, đó là dấu hiệu nên tạo CLAUDE.md. Người làm một mình có thể bắt đầu bằng file cấp người dùng cho thói quen chung, rồi thêm file cấp dự án khi một dự án có lệnh và quy ước riêng.

### Claude có luôn làm đúng theo CLAUDE.md không?

Không có bảo đảm. Tài liệu Claude Code nói rõ CLAUDE.md là ngữ cảnh, không phải cấu hình bắt buộc; câu càng cụ thể và file càng ngắn thì Claude làm theo càng đều. Với quy tắc không được phép vi phạm, như chặn sửa file bí mật hay chặn lệnh xoá, hãy dùng quy tắc quyền (permissions) hoặc hook PreToolUse, vì hai cơ chế này được Claude Code thực thi bất kể mô hình quyết định gì.

### Nên để CLAUDE.md ở gốc dự án hay trong thư mục .claude?

Cả `./CLAUDE.md` và `./.claude/CLAUDE.md` đều được tài liệu chính thức chấp nhận làm file cấp dự án. Chọn vị trí nào là tuỳ thói quen: đặt trong `.claude/` giúp gốc repo gọn hơn, đặt ở gốc thì người mới dễ thấy. Ghi chú riêng không muốn commit thì để trong `CLAUDE.local.md` và thêm file đó vào `.gitignore`. Chạy `/context` trong phiên để chắc file đã được nạp.

### Bộ nhớ tự động có thay được CLAUDE.md không?

Không nên coi là thay thế. Bộ nhớ tự động do Claude tự quyết định ghi gì, chỉ nạp 200 dòng hoặc 25KB đầu của file mục lục, và chỉ nằm trên một máy. CLAUDE.md do bạn kiểm soát, đi theo git và dùng chung cho cả nhóm. Cách hợp lý là để quy tắc quan trọng trong CLAUDE.md hoặc file hướng dẫn chung, còn bộ nhớ tự động giữ lời sửa vặt và bối cảnh làm việc. Định kỳ mở `/memory` đọc lại xem Claude đã ghi gì.

### Làm sao để một file hướng dẫn dùng chung cho Claude Code, Codex và công cụ khác?

Viết hướng dẫn chung trong AGENTS.md, rồi tạo CLAUDE.md chỉ có dòng `@AGENTS.md` ở đầu và phần riêng cho Claude phía dưới. Cách này chạy được cả với phiên bản Claude Code chưa tự đọc AGENTS.md. Nếu muốn có người hướng dẫn dựng bộ file này theo dự án thật của bạn, xem [khoá đào tạo ứng dụng AI](/services/dao-tao-ung-dung-ai) của OPCAIOS.

*Nguồn: tài liệu Claude Code của Anthropic, trang "How Claude remembers your project" (code.claude.com/docs/en/memory) và trang hooks guide, đọc ngày 03/11/2026; số phiên bản, giới hạn 200 dòng/25KB và tên lệnh có thể thay đổi theo bản cập nhật; chưa kiểm chứng mức cải thiện tuân thủ theo độ dài file. Kinh nghiệm là của OPCAIOS.*
