Bạn mở Claude Code lên để làm việc, giải thích lại từ đầu dự án đang dùng framework gì, quy ước đặt tên ra sao, style code thế nào. Xong việc, đóng session lại. Hôm sau mở lên, y như hôm qua chưa từng xảy ra — Claude lại hỏi lại từ đầu. Nếu bạn thấy quen thuộc, đây chính là vấn đề mà file CLAUDE.md sinh ra để giải quyết.
Ý tưởng cốt lõi CLAUDE.md: coi Claude như nhân viên mới mất trí nhớ
Cứ hình dung Claude Code như một bạn dev mới vào công ty, cực kỳ giỏi, nhưng mỗi sáng đi làm là quên sạch mọi thứ hôm qua. Bạn không đời nào ngồi đào tạo lại từ đầu mỗi ngày — bạn viết hẳn một tài liệu onboarding, đưa cho người đó đọc trước khi bắt tay vào việc.
CLAUDE.md chính là tài liệu onboarding đó, nhưng dành cho AI. Claude Code tự động đọc file này vào đầu mỗi session, nên bạn không phải lặp lại những điều cơ bản mỗi lần mở chat mới.
Cách kiểm tra xem một điều gì đó có nên đưa vào file hay không cũng đơn giản: nếu một bạn dev mới cần biết điều này để làm việc hiệu quả, thì nó nên nằm trong CLAUDE.md.
Lưu ý: đây là tính năng riêng của Claude Code, dùng được trên mọi giao diện của nó — kể cả tab Code trong app Claude desktop. Bản Claude chat thông thường không đọc file này; ở đó thứ tương đương gần nhất là phần custom instructions của project.
Vài thuật ngữ cần nắm trước
Để đọc phần sau dễ hơn, bạn cầm sẵn vài khái niệm này:
- Session: một phiên trò chuyện — Claude quên sạch mọi thứ khi session kết thúc.
- Context window: “bàn làm việc” của Claude, không gian giới hạn để chứa thông tin đang xử lý.
- CLAUDE.md: tài liệu onboarding một trang, viết một lần, đọc mỗi session.
- Rules: các ghi chú theo chủ đề riêng, chỉ load khi liên quan đến việc đang làm.
- Skills: những playbook chi tiết, Claude chỉ mở ra khi cần làm đúng việc đó.
- “Context, không phải luật cưỡng chế”: file này giống một bản brief rõ ràng, không phải hợp đồng bắt buộc tuân theo tuyệt đối.
Cái gì nên đưa vào, cái gì nên để ngoài
Nhiệm vụ của CLAUDE.md là ghi lại những gì luôn đúng, và chỉ đường tới những chỗ khác khi cần chi tiết hơn.
Nên đưa vào:
- Những điều bạn phải lặp lại ở mọi session
- Quy tắc kiểu “luôn làm cái này” / “không bao giờ làm cái kia”
- Đường dẫn tới nơi mọi thứ nằm — để Claude biết đọc gì trước
- Quy ước đặt tên
Nên để ngoài:
- Toàn bộ design token hay dữ liệu chi tiết — chỉ trỏ đường dẫn, đừng dán nguyên vào
- Quy trình từng bước cho một việc cụ thể một lần — cái này nên thành một skill
- Những gì thay đổi liên tục theo tuần — đó là nội dung cho một prompt, không phải luật cố định
Viết mơ hồ vs viết cụ thể: khác biệt nằm ở đây
Đây là phần quyết định file có hữu ích hay không. Một dòng tốt phải mô tả điều Claude làm, kiểm chứng được bằng cách nhìn vào kết quả. Một dòng tệ chỉ mô tả cảm giác chung chung.
| Viết mơ hồ | Viết cụ thể, kiểm chứng được |
|---|---|
| “Bám theo thương hiệu” | “Luôn lấy đầy đủ design system từ file Figma trước khi tự nghĩ ra giá trị mới. Mọi giá trị phải bắt nguồn từ token đã có sẵn” |
| “Làm prototype cho tốt” | “Dựng prototype bằng React kèm thư viện Motion. Giao dưới dạng một artifact duy nhất, không viết inline” |
| “Giữ khoảng cách nhất quán” | “Spacing dùng thang cơ sở 4px. Không dùng giá trị pixel tùy tiện” |
| “Đây là toàn bộ token, kèm 300 dòng dán vào” | “Token nằm ở design-system/tokens.md. Luôn đọc file này trước khi bắt đầu build” |
Mẹo nhỏ: dòng cuối cùng trong bảng trên quan trọng vì lý do kỹ thuật. Viết đường dẫn dưới dạng text thường (
design-system/tokens.md) nghĩa là Claude chỉ mở file đó khi cần. Nếu bạn dùng cú pháp import (@design-system/tokens.md), Claude sẽ tải hết 300 dòng ngay từ đầu mỗi session — đúng thứ bạn đang muốn tránh. Đường dẫn thường cho việc đọc khi cần,@importchỉ dành cho file nhỏ mà bạn thực sự muốn load mỗi lần.
CLAUDE.md khác gì một file nội dung như design.md?
Cả hai đều là file markdown, nhưng nhiệm vụ ngược nhau hoàn toàn. CLAUDE.md là chỉ dẫn — Claude nên hành xử ra sao. Một file nội dung như design.md là thông tin — dữ liệu thực tế Claude dùng để làm việc.
| CLAUDE.md (chỉ dẫn) | File nội dung như design.md (thông tin) |
|---|---|
| Claude nên hành xử thế nào: mặc định, quy tắc, “luôn/không bao giờ” | Claude làm việc dựa trên gì: sản phẩm, người dùng, quyết định thiết kế |
| Tự động load ở mọi session | Không phải tên file đặc biệt — chỉ đọc khi được trỏ tới hoặc import |
| Luôn ngắn gọn, trỏ sang file khác | Chứa chi tiết, chỉ kéo vào khi cần |
Cần nói rõ một điều mang tính kỹ thuật: đặt tên file là design.md không tự động làm gì cả. Chỉ CLAUDE.md (cùng CLAUDE.local.md và thư mục .claude/rules/) mới tự load. Claude chỉ chạm tới design.md khi CLAUDE.md trỏ đường dẫn tới nó (đọc khi cần), hoặc khi bạn dùng import @design.md (load ngay lúc khởi động).
Nói cách khác, hai file này là đồng đội chứ không cạnh tranh nhau. CLAUDE.md là bản brief hướng dẫn Claude làm việc và biết tìm ở đâu; design.md là một trong những nơi nó tìm tới.
Vì sao file này nên ngắn: bàn làm việc, không phải kho chứa
Mọi thứ Claude đọc lúc đầu phải vừa trên “bàn làm việc” trước khi bắt tay vào. Nhồi nhét toàn bộ design system lên đó, Claude sẽ không tìm ra thứ thực sự quan trọng.
Mốc khoảng 200 dòng không phải giới hạn dung lượng cứng nhắc, mà là nguyên tắc “giữ bàn làm việc gọn gàng”. Mục tiêu là một file tinh gọn, nói rõ điều gì luôn đúng và những thứ nặng đô nằm ở đâu. Tài liệu tham khảo dày cộp thì để trên kệ, chỉ lấy xuống khi cần.
Ba lớp cấu trúc, giống hệt một design system trưởng thành
Đây là mô hình giúp mọi thứ dễ hiểu, vì nó có hình dạng y hệt một design system đã trưởng thành:
- CLAUDE.md là trang nền tảng — thứ ai cũng đọc đầu tiên, load đầy đủ ở mọi session.
- Rules là hướng dẫn cấp component — nằm thành file riêng theo chủ đề trong thư mục
.claude/rules/. Điểm hay là bạn có thể giới hạn một rule chỉ áp dụng cho đường dẫn file cụ thể, nên nó chỉ load khi Claude đang làm việc trên những file khớp điều kiện đó. Nhờ vậy trang nền tảng vẫn ngắn gọn mà vẫn có sẵn quy tắc chi tiết khi cần. Rule không giới hạn phạm vi thì load ở mọi session, giống file chính. - Skills là playbook quy trình — những hướng dẫn từng bước chi tiết, chỉ lấy ra khi cần cho một việc cụ thể. Đây chính xác là lý do một quy trình dựng prototype nên là một skill, chứ không phải mục trong CLAUDE.md.
Nếu bạn từng xây design system, bạn đã hiểu kiến trúc này rồi: nền tảng, tài liệu component, playbook quy trình.
Lớp “build”: điều biến một file thành file dành cho dân kỹ thuật
Mọi nguyên tắc ở trên áp dụng cho bất kỳ CLAUDE.md nào. Nhưng Claude Code là công cụ để build, không phải để chat suông. Muốn nó ra code chạy được thật sự, file phải mang theo cách dự án của bạn được build, không chỉ giao diện trông ra sao. Bốn phần dưới đây làm phần lớn công việc:
Commands — các lệnh chính xác để cài đặt, chạy, test, lint. Claude chạy y nguyên các lệnh này, nên đây là thứ giúp nó tự kiểm tra kết quả thay vì đưa cho bạn thứ chưa test.
Stack và quy ước — framework, ngôn ngữ, cách style, viết cụ thể. “Style bằng biến CSS token trong tokens.css, không dùng mã hex thô” hiệu quả hơn hẳn “dùng design system”. Nêu rõ mẫu, trỏ đúng file.
Guardrails — những gì tuyệt đối không được đụng vào. “Không thêm dependency mà không hỏi trước.” “Không sửa tay file tokens tự sinh, nó sẽ bị ghi đè khi sync.” Đây là thứ ngăn Claude làm một việc về kỹ thuật thì ổn nhưng lại âm thầm gây rối dự án.
Định nghĩa hoàn thành (definition of done) — phần biến một file dev thường thành file dành cho dân thiết kế kiêm kỹ thuật. Hoàn thành không chỉ là “test pass”. Hoàn thành nghĩa là: khớp với ảnh chụp Figma, dùng token và component có sẵn chứ không tự bịa ra, và mọi kiểm tra đều qua. Bạn đang coi độ trung thực về mặt hình ảnh như một bài test — đúng tiêu chuẩn mà công việc của chính bạn phải đạt.
Mẹo nhỏ: thay vì chỉ nói “không bao giờ”, hãy đưa luôn phương án an toàn thay thế. Không phải “không bao giờ hard-code màu”, mà là “dùng biến CSS token trong
tokens.css“. Chỉ ra đáp án đúng, thay vì chỉ rào chắn cái sai.
Đặt file ở đâu: cá nhân, chung nhóm, hay riêng tư
Phạm vi chỉ là chuyện bạn ghim ghi chú ở đâu. Tên file mới là thứ khiến Claude load nó — một file tên project-instructions.md sẽ không tự động làm gì cả. Bắt buộc phải đặt tên là CLAUDE.md.
| Ghim ở đâu | Phạm vi áp dụng | Tên file |
|---|---|---|
| Máy tính cá nhân, theo bạn mọi nơi | Mặc định cá nhân, áp dụng cho mọi dự án | ~/.claude/CLAUDE.md |
| Bảng chung của dự án | Chuẩn của cả nhóm, chia sẻ qua repo | ./CLAUDE.md |
| Ngăn kéo riêng, chỉ dự án này | Ghi chú riêng tư, không đưa vào repo | CLAUDE.local.md |
Còn một phạm vi thứ tư bạn sẽ không tự thiết lập: file CLAUDE.md do bộ phận IT/DevOps quản lý và đẩy xuống mọi máy trong công ty. Biết nó tồn tại cũng tốt, vì đôi khi đồng nghiệp đang tuân theo một quy tắc mà chẳng ai trong nhóm viết ra.
Đừng viết từ đầu — để Claude tự soạn bản nháp
Hai cách nhanh gọn:
- Chạy lệnh
/inittrong Claude Code. Claude sẽ đọc dự án và tự soạn CLAUDE.md dựa trên các quy ước tìm thấy được. Nếu file đã tồn tại, nó đề xuất cải thiện thay vì ghi đè. - Nói “thêm cái này vào CLAUDE.md” ngay giữa lúc làm việc. Mỗi khi bạn sửa Claude về một điều nó nên luôn nhớ, cứ bảo nó viết thẳng vào file. Tài liệu lớn dần từ những lần sửa thực tế của bạn — đây chính là nguồn gốc của những mục hay nhất.
Lưu ý: một câu “nhớ giúp mình cái này” thông thường sẽ lưu vào bộ nhớ tự động riêng của Claude, không phải vào CLAUDE.md. Muốn nó vào file thật, phải nói rõ tên file.
Đây là bản brief, không phải hợp đồng
CLAUDE.md định hình cách Claude hành xử giống như một bản brief rõ ràng định hình cách một nhân viên mới làm việc — nó không ép buộc về mặt vật lý. Vì vậy chỉ dẫn cụ thể, có thứ tự ưu tiên, không mâu thuẫn nhau mới thực sự quan trọng. Mục nào mơ hồ hoặc chồng chéo sẽ bị làm theo hời hợt hoặc bị bỏ qua, y như một bản brief mập mờ cho ra kết quả mập mờ.
Nếu bạn cần một điều thực sự bị chặn cứng, không cho Claude tùy ý quyết định, đó là việc của hook, không phải CLAUDE.md. Nói gọn: CLAUDE.md định hướng, hook cưỡng chế.
Đang dùng AGENTS.md? Đây là file chỉ dẫn trung lập giữa các nhà cung cấp mà nhiều công cụ AI coding khác đọc. Claude Code đọc CLAUDE.md, không đọc AGENTS.md. Trỏ file này sang file kia bằng import
@AGENTS.md(hoặc tạo symlink) để hai công cụ dùng chung một bộ chỉ dẫn, tránh lệch nhau theo thời gian.
Mẫu CLAUDE.md để bạn copy dùng luôn
# CLAUDE.md
## Project
- Đang xây gì: [một dòng]
- Dành cho ai: [đối tượng người dùng chính]
- Nền tảng: [web / iOS / Android / ...]
## Stack & tools
- [Framework + ngôn ngữ, ví dụ React + TypeScript]
- Style: [ví dụ biến CSS token trong src/styles/tokens.css]
- Nguồn thiết kế: [Figma + MCP nào, nếu có]
- Làm prototype: [ví dụ React + thư viện Motion], giao dưới dạng một artifact duy nhất
## Commands
- Cài đặt: [lệnh]
- Chạy dev: [lệnh]
- Test: [lệnh]
- Lint + typecheck: [lệnh]
- Chạy [lệnh kiểm tra] trước mỗi lần commit.
## Luôn
- Luôn [lấy đầy đủ design system trước khi tự bịa ra giá trị mới]
- Luôn [style bằng biến token trong [file], không dùng hex thô hay inline style]
- Luôn [tái sử dụng component có sẵn trước khi tạo mới]
## Không bao giờ
- Không bao giờ [thêm dependency mà không hỏi trước]
- Không bao giờ [refactor code không liên quan đến việc đang làm]
- Không bao giờ [sửa tay file tokens tự sinh; nó bị ghi đè khi sync]
## Mọi thứ nằm ở đâu (trỏ đường dẫn, đừng dán nội dung)
- Design tokens: [src/styles/tokens.css]
- Components: [src/components]
- Ghi chú sản phẩm/UX: [docs/product.md]
## Định nghĩa hoàn thành
- Khớp với ảnh chụp Figma, không chỉ gần giống
- Dùng token và component có sẵn, không tự bịa
- [Lint, type, test] đều pass
## Quy ước đặt tên
- Token: [category/role/variant, ví dụ color/text/primary]
- File/component: [quy ước của bạn]
## Cần biết thêm
- [Một lỗi hay gặp mà Claude từng làm sai trước đây]
- [Một file hoặc ràng buộc dễ bị bỏ sót]
Việc còn lại là xóa hết phần hướng dẫn trong ngoặc, điền thông tin dự án thật của bạn vào, và bạn đã có một CLAUDE.md sẵn sàng dùng — không cần chờ đến khi mọi thứ hoàn hảo, cứ viết bản đầu tiên rồi để nó lớn dần theo mỗi lần bạn sửa Claude nhé.
Để lại một bình luận