CLAUDE.md là gì & cách viết chuẩn cho Claude Code (có mẫu 2026)

Jasmine (dev dùng Claude Code hằng ngày, tự viết & tinh chỉnh CLAUDE.md cho nhiều dự án thật).

CLAUDE.md là gì?

Nếu bạn từng bực vì Claude Code cứ "quên" là dự án dùng pnpm chứ không phải npm, hay tự ý tạo file mới thay vì sửa file cũ - thì CLAUDE.md chính là thứ bạn thiếu.

CLAUDE.md là một file Markdown đặt ở gốc dự án, được Claude Code tự động nạp vào ngữ cảnh ngay khi phiên bắt đầu, để làm "hướng dẫn hệ thống" bền vững cho toàn dự án. Nói cách khác, thay vì mỗi lần mở phiên mới bạn lại phải gõ lại "dự án này dùng TypeScript, chạy test bằng lệnh X, đừng đụng vào thư mục Y", bạn viết những quy ước đó một lần vào CLAUDE.md. Agent đọc nó như đọc phần dặn dò của một đồng nghiệp đã quen dự án.

Điểm quan trọng để phân biệt: CLAUDE.md không phải một prompt bạn phải nhớ dán mỗi lần, cũng không phải tài liệu cho người đọc. Nó là ngữ cảnh cho agent - viết ngắn gọn, mệnh lệnh, tập trung vào thứ giúp Claude ra quyết định đúng. Càng cụ thể và càng đúng trọng tâm, agent càng ít "chệch". Nếu bạn chưa rõ Claude Code là gì, hãy đọc trước bài Claude Code là gì rồi quay lại đây.

Một cách hình dung khác: khi làm việc với một dev mới, bạn không muốn giải thích lại mọi thứ mỗi buổi sáng. Bạn viết một trang onboarding, họ đọc, rồi tự vận hành. CLAUDE.md đúng là trang onboarding đó - nhưng cho agent, và được đọc lại tự động ở mỗi phiên. Đây cũng là lý do file này đáng đầu tư: một lần viết tốt, lợi ích cộng dồn qua hàng trăm phiên sau đó. Theo tài liệu best practices của Anthropic, việc tinh chỉnh CLAUDE.md dần theo thời gian (như một prompt sống) mang lại hiệu quả rõ hơn là cố viết hoàn hảo ngay từ đầu.

CLAUDE.md hoạt động thế nào? (vì sao agent tuân theo)

Cơ chế thực ra rất đơn giản: khi bạn mở một phiên trong thư mục dự án, Claude Code quét và nạp các file CLAUDE.md tìm được vào phần đầu ngữ cảnh, trước cả prompt đầu tiên của bạn. Có nhiều lớp được nạp cùng lúc:

• Gốc dự án - ./CLAUDE.md, quy ước chung cho cả repo (nạp cho mọi người làm dự án).
• Cá nhân bạn - ~/.claude/CLAUDE.md, sở thích riêng áp cho mọi dự án của bạn.
• Thư mục cha/con - Claude Code tìm ngược lên cây thư mục và cũng đọc CLAUDE.md trong thư mục con khi làm việc ở đó, nên quy ước riêng cho một module có thể đặt ngay cạnh module đó.

Vì nội dung này nằm ở phần đầu ngữ cảnh, nó chịu ảnh hưởng của primacy bias - mô hình có xu hướng "nghe" mạnh hơn với những gì xuất hiện sớm. Đây là lý do bạn nên đặt các ràng buộc quan trọng nhất (constraints, "KHÔNG làm") lên đầu file, đừng chôn chúng ở giữa một đoạn văn dài.

Một lưu ý trung thực: CLAUDE.md tạo ra ngữ cảnh Claude Code mạnh, nhưng không phải "luật bất khả xâm phạm". Khi context đầy hoặc file quá dài, tín hiệu bị pha loãng và agent vẫn có thể bỏ sót. Muốn kiểm chứng agent có đọc không, cách nhanh nhất là hỏi thẳng: "theo CLAUDE.md, lệnh chạy test là gì?" - nếu trả lời đúng nghĩa là bộ nhớ dự án đã vào ngữ cảnh.

3 loại CLAUDE.md & đặt ở đâu

Nhiều người nhầm tưởng chỉ có một file duy nhất. Thực tế có ba phạm vi, và biết đặt đúng chỗ giúp bạn tránh nhồi mọi thứ vào một file:

Còn CLAUDE.local.md (bản riêng không commit) trước đây dùng để ghi ghi chú cá nhân theo dự án, nhưng nay đã deprecated. Thay vào đó, hãy dùng cú pháp import (xem bên dưới) hoặc đặt phần cá nhân vào ~/.claude/CLAUDE.md. Nếu bạn muốn "đặt CLAUDE.md ở đâu" cho gọn: quy ước nhóm vào gốc repo, sở thích riêng vào file user, ngoại lệ theo module vào thư mục con.

Nên bỏ gì vào CLAUDE.md? (6 phần cốt lõi)

Đây là câu hỏi quan trọng nhất - và đa số file kém là vì nhồi sai thứ. Sắp theo ROI từ cao xuống thấp, sáu phần đáng có là:

1. Lệnh (ROI cao nhất). Cách test, build, lint, chạy dev. Agent thường đoán sai lệnh nhất, nên đây là phần tiết kiệm thời gian nhiều nhất. Ví dụ: pnpm test, pnpm build, pnpm lint.
2. Tech stack + version. Ngôn ngữ, framework, package manager, DB. Ví dụ: "Next.js 15 (App Router), TypeScript strict, pnpm, PostgreSQL + Prisma". Giúp agent không dùng API lỗi thời.
3. Cấu trúc thư mục - mỗi mục một dòng. Ví dụ: "app/ routes; components/ UI; lib/ helpers dùng chung". Đủ để agent biết đặt file mới vào đâu.
4. Quy ước code. Naming, import order, cách xử lý lỗi, style test. Nêu những thứ dễ sai, đừng chép lại toàn bộ style guide.
5. Ranh giới "KHÔNG làm". Đây là phần tạo khác biệt lớn nhất và nên đặt gần đầu. Ví dụ: "KHÔNG tạo file mới khi sửa được file cũ", "KHÔNG commit khi chưa được yêu cầu", "KHÔNG đụng thư mục migrations/ đã chạy".
6. Import @path tới doc chi tiết. Thay vì dán cả tài liệu dài, trỏ tới nó: @docs/architecture.md. Giữ file chính gọn mà vẫn cho agent lối vào chi tiết khi cần (progressive disclosure).

Nguyên tắc lọc: nếu một dòng không giúp agent ra quyết định khác đi, hãy bỏ nó. CLAUDE.md không phải README. README giải thích dự án cho người đọc; CLAUDE.md dặn agent cách hành xử. Hai mục đích khác nhau, đừng gộp làm một - nếu không file sẽ phình to bằng nội dung mà agent chẳng bao giờ cần đến khi ra quyết định.

Mẫu CLAUDE.md chuẩn (copy-paste)

Dưới đây là một mẫu hoàn chỉnh, chạy được cho dự án Next.js + TypeScript điển hình. Đây chính là thứ hầu hết trang hướng dẫn tiếng Việt còn thiếu: một file bạn dán vào là dùng được ngay, rồi tỉa theo dự án của mình.

Copy mẫu này rồi sửa theo dự án bạn: đổi phần tech stack, lệnh và cấu trúc thư mục cho khớp. Giữ mục "KHÔNG làm" lên đầu.

# CLAUDE.md

Web app quản lý đặt lịch cho phòng khám. Ưu tiên: đúng nghiệp vụ > tốc độ code.

## KHÔNG làm (đọc trước)
- KHÔNG tạo file mới nếu sửa được file sẵn có.
- KHÔNG commit/push khi chưa được yêu cầu.
- KHÔNG sửa file trong `prisma/migrations/` đã chạy - tạo migration mới.
- KHÔNG dùng `any` trong TypeScript. Không tắt lint để cho qua.

## Tech stack
- Next.js 15 (App Router) + TypeScript (strict)
- pnpm (KHÔNG dùng npm/yarn)
- PostgreSQL + Prisma
- Tailwind CSS + shadcn/ui
- Vitest (unit) + Playwright (e2e)

## Lệnh
- Dev: `pnpm dev`
- Test: `pnpm test` # chạy 1 file: `pnpm test path/to/file`
- Build: `pnpm build`
- Lint: `pnpm lint`
- DB: `pnpm prisma migrate dev`

## Cấu trúc thư mục
- `app/` - routes (App Router)
- `components/` - UI tái sử dụng
- `lib/` - helper dùng chung, không có JSX
- `server/` - logic phía server, truy vấn DB
- `prisma/` - schema + migrations

## Quy ước code
- Component: PascalCase; hàm/biến: camelCase; hằng: UPPER_SNAKE.
- Ưu tiên named export; import tuyệt đối qua alias `@/`.
- Xử lý lỗi: throw `AppError` (xem `lib/errors.ts`), không nuốt lỗi im lặng.
- Mỗi tính năng mới phải kèm test.

## Quy trình
- Trước khi coi là xong: chạy `pnpm lint` và `pnpm test`, sửa hết lỗi.
- Thay đổi lớn: mô tả kế hoạch ngắn trước khi sửa nhiều file.

## Tài liệu chi tiết (import khi cần)
@docs/architecture.md
@docs/api-conventions.md

Do & Don't - ví dụ SAI → ĐÚNG

Khác biệt giữa file khiến agent làm đúng và file bị bỏ qua thường nằm ở cách diễn đạt, không phải độ dài. Vài cặp before/after thật:

Quy tắc vàng: viết như đang dặn một dev mới thông minh nhưng chưa biết gì về dự án - cụ thể, mệnh lệnh, ngắn. Mỗi câu mơ hồ ("viết code sạch", "theo best practice") gần như vô dụng vì agent không đo được. Thay "viết code sạch" bằng "hàm tối đa 40 dòng, tách khi dài hơn"; thay "xử lý lỗi cẩn thận" bằng "throw AppError, không dùng try/catch rỗng". Thứ đo được thì agent tuân được. Muốn xem toàn bộ lệnh Claude Code để đưa vào file, tham khảo cheat sheet lệnh Claude Code.

Giữ CLAUDE.md gọn & tối ưu token

Có một hiểu lầm phổ biến: file càng dài, agent càng "hiểu" dự án. Thực tế ngược lại. CLAUDE.md ngốn context window của mọi phiên, và khi nó phình to, mỗi dòng quan trọng lại bị lẫn giữa hàng chục dòng nhiễu - tín hiệu loãng đi, agent dễ bỏ sót đúng thứ bạn cần nhất.

Kinh nghiệm thực tế: nhắm khoảng ~200 dòng, trần khoảng 300-500 dòng cho dự án lớn. Vượt xa mức đó là dấu hiệu bạn nên tách. Cách tối ưu CLAUDE.md:

• Progressive disclosure qua import. Giữ file chính là "mục lục quyết định"; đẩy chi tiết dài (kiến trúc, quy ước API) sang file riêng và trỏ tới bằng @docs/....
• Cắt phần không đổi hành vi. Lịch sử dự án, mô tả marketing, giải thích dài dòng - bỏ hết.
• Gộp trùng lặp. Nếu đã nói "dùng pnpm" ở tech stack thì không cần lặp ở ba chỗ khác.
• Ưu tiên theo ROI. Lệnh và ranh giới lên đầu; thứ "biết thì tốt" xuống cuối hoặc chuyển sang import.

Mẹo nhanh: /init và phím #

Không cần viết CLAUDE.md từ con số 0. Hai công cụ tích hợp giúp bạn nhanh hơn nhiều:

• /init - chạy lệnh này trong dự án, Claude Code sẽ quét repo và sinh sẵn một CLAUDE.md khởi tạo (đoán tech stack, lệnh, cấu trúc). Bạn không lấy nguyên xi, mà dùng nó làm bản nháp rồi tỉa lại theo 6 phần cốt lõi ở trên.
• Phím # - trong lúc làm việc, gõ # rồi nhập một ghi chú, Claude Code sẽ đề nghị lưu nó vào CLAUDE.md (bạn chọn file dự án hay file user). Đây là cách thêm bộ nhớ dự án ngay giữa phiên khi bạn phát hiện một quy ước cần ghi lại - không phải dừng lại mở editor.

Nếu bạn mới bắt đầu, luồng gọn nhất là: chạy /init → tỉa file theo mẫu bên trên → dùng phím # để bồi đắp dần. Bài 10 bước bắt đầu Claude Code cho người mới đi qua toàn bộ luồng này.

Chuẩn CLAUDE.md dựng sẵn từ bộ kit (AgentKit)

Tự viết CLAUDE.md tốt cần vài vòng thử-sai. Nếu muốn đi tắt, một số bộ kit như bộ kit AgentKit (ship sẵn chuẩn CLAUDE.md) đóng gói sẵn quy ước CLAUDE.md cùng rules/skills theo chuẩn, để bạn khỏi bắt đầu từ trang trắng. Nó không thay việc bạn khai báo lệnh và ranh giới riêng của dự án, nhưng tiết kiệm được phần khung và các quy ước lặp lại giữa nhiều dự án - bạn có thể dùng thử AgentKit (giảm 20% qua link) để xem cấu trúc mẫu của họ rồi giữ lại phần hợp với mình.

Câu hỏi thường gặp (FAQ)

Tên file CLAUDE.md có phân biệt hoa/thường không?

Có. Hãy đặt đúng CLAUDE.md viết hoa toàn bộ phần tên. Trên hệ thống phân biệt hoa/thường (Linux, thường gặp ở CI), đặt sai như claude.md có thể khiến Claude Code không nhận ra file.

Có nên commit CLAUDE.md vào git không?

Nên, với file gốc dự án - vì đó là quy ước chung, commit để cả nhóm dùng chung một ngữ cảnh. Ngược lại, ~/.claude/CLAUDE.md là cá nhân, không nằm trong repo. Ghi chú riêng theo dự án thì để trong file user hoặc import, không commit.

Claude không tuân CLAUDE.md thì sao?

Thường do một trong ba nguyên nhân: file quá dài nên tín hiệu loãng, quy ước quan trọng bị chôn ở giữa, hoặc context đã đầy. Cách khắc phục: rút gọn file, đẩy ràng buộc "KHÔNG làm" lên đầu, và kiểm chứng bằng cách hỏi agent một quy ước cụ thể xem nó trả lời đúng không.

CLAUDE.md dùng được với Cursor hay công cụ khác không?

CLAUDE.md là quy ước của Claude Code. Các công cụ khác dùng file ngữ cảnh riêng (ví dụ AGENTS.md hoặc file rules của công cụ đó). Nội dung bạn viết có thể tái sử dụng, nhưng tên file và cơ chế nạp thì khác nhau tùy công cụ.

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

Nhắm khoảng 200 dòng, trần 300-500 dòng cho dự án lớn. Ưu tiên chất lượng tín hiệu hơn số dòng: chỉ giữ những gì thay đổi được quyết định của agent, phần còn lại đẩy sang file import.

File dự án khác ~/.claude/CLAUDE.md chỗ nào?

File dự án (./CLAUDE.md) chứa quy ước áp cho cả repo và cả nhóm, commit vào git. File user (~/.claude/CLAUDE.md) chứa sở thích cá nhân của bạn, áp cho mọi dự án và không nằm trong repo. Claude Code nạp cả hai cùng lúc khi hai file cùng tồn tại.

Kết luận + bước tiếp theo

CLAUDE.md là khoản đầu tư nhỏ nhưng lời nhất khi dùng Claude Code: viết một lần, agent tuân quy ước ở mọi phiên. Hãy copy mẫu bên trên, tỉa theo dự án, đặt ràng buộc "KHÔNG làm" lên đầu và giữ file gọn. Nếu bạn mới bắt đầu, đọc 10 bước bắt đầu cho người mới; muốn tra lệnh nhanh thì lưu cheat sheet lệnh Claude Code cạnh bàn phím.