Bạn để Claude Code sửa repo, nhưng agent lại chạy npm test trong khi team dùng pnpm? Lỗi này thường không phải do model “dở” — mà do dự án chưa có CLAUDE.md ghi rõ quy tắc Claude cần nhớ mỗi phiên.
Đây là bài thứ ba trong series Claude Code. Nếu chưa cài tool, bạn đọc Claude Code là gì? Hướng dẫn cài đặt và chạy dự án đầu tiên. Nếu chưa quen slash command, đọc thêm 7 lệnh Claude Code cần biết. Còn bài này tập trung vào câu hỏi: CLAUDE.md là gì, đặt ở đâu, và viết sao để Claude Code làm đúng ngay từ prompt đầu tiên.
Tóm tắt nhanh
- CLAUDE.md là file markdown chứa quy tắc dự án mà Claude Code đọc ở đầu mỗi phiên.
- File này là context, không phải rào chắn bảo mật; quy tắc tuyệt đối cần hook, deny rule hoặc managed settings.
- Nên ghi lệnh build/test, convention, kiến trúc ngắn, ràng buộc cứng và lỗi team hay gặp.
- Giữ file ngắn, cụ thể và nhất quán; tài liệu khuyến nghị khoảng dưới 200 dòng cho mỗi file.
- Dùng
/initđể tạo bản đầu,/contextđể kiểm tra file đã load, và/doctor prompt-auditđể rà instruction cũ.
CLAUDE.md là gì?
CLAUDE.md là file markdown chứa hướng dẫn lâu dài cho Claude Code — ví dụ lệnh build, quy ước code, cấu trúc dự án và những điều agent không nên làm. Claude Code đọc file này ở đầu phiên để có context giống như một teammate mới được brief trước khi nhận việc. [1]
- CLAUDE.md
- File quy tắc dự án hoặc quy tắc cá nhân do bạn viết, được Claude Code load như context khi làm việc trong repo.
- Auto memory
- Ghi chú do Claude tự lưu từ các lần bạn chỉnh sửa, preference và pattern trong quá trình làm việc.
Điểm dễ nhầm: CLAUDE.md không phải “cấu hình ép buộc”. Anthropic mô tả đây là context chứ không phải enforcement — model thường làm theo, nhưng vẫn có thể diễn giải sai nếu quy tắc mơ hồ hoặc mâu thuẫn. Với điều tuyệt đối cấm, bạn cần hook, deny rule hoặc managed settings thay vì chỉ viết chữ hoa trong file. [1] [3]
Claude Code cũng có thể đọc AGENTS.md trong repo thay cho CLAUDE.md. Điều này hữu ích khi team đã chuẩn hóa một file instruction cho nhiều AI coding agent khác nhau, không muốn duy trì hai bản quy tắc gần giống nhau. [4]
Nếu bạn đang theo workflow vibe coding, CLAUDE.md chính là lớp “governance nhẹ” đầu tiên: nó giúp agent giữ đúng chuẩn repo trước khi bạn cần tới permission mode, checkpoint hay CI gate.
Claude Code đọc CLAUDE.md từ đâu?
Claude Code có thể load CLAUDE.md từ nhiều scope: policy toàn tổ chức, file cá nhân trong home directory, file project trong repo, file local riêng và file trong subdirectory. File ở thư mục hiện tại và các thư mục cha được load lúc mở phiên; file trong subdirectory được load khi Claude làm việc tới phần đó. [1]
| Scope | Vị trí | Dùng cho |
|---|---|---|
| Managed policy | Đường dẫn hệ thống theo OS | Quy tắc bảo mật, compliance, chuẩn toàn công ty |
| User instructions | ~/.claude/CLAUDE.md | Preference cá nhân áp dụng cho mọi dự án |
| Project instructions | ./CLAUDE.md hoặc ./.claude/CLAUDE.md | Quy tắc team chia sẻ qua git |
| Local instructions | ./CLAUDE.local.md | Ghi chú riêng của bạn trong project, nên gitignore |
| Subdirectory | src/api/ hoặc packages/web/ (file cùng tên trong thư mục) | Convention riêng cho module hoặc package |
Sau khi tạo file, bạn có thể chạy /context trong phiên để kiểm tra phần Memory files. Nếu file không xuất hiện, thường là đặt sai vị trí hoặc file nằm trong subdirectory chưa được Claude đọc tới. [1]
CLAUDE.md còn hỗ trợ import bằng cú pháp @path/to/file. Cách này giúp tách tài liệu, nhưng không giảm context cost — file import vẫn được load cùng CLAUDE.md. Mình khuyên chỉ dùng import khi thật sự cần giữ tài liệu dài ở nơi khác, còn quy tắc hằng ngày vẫn nên nằm gọn trong file chính. [1]
Nên ghi gì vào CLAUDE.md?
Chỉ ghi thứ Claude không tự suy ra nhanh từ repo, hoặc thứ nó phải rediscover lại mỗi phiên. Mục tiêu không phải viết một bản documentation đầy đủ, mà là một briefing ngắn giúp agent chọn đúng command, đúng convention và tránh đúng bẫy.
Theo hướng dẫn chính thức, CLAUDE.md nên có năm nhóm nội dung chính. [2]
- Commands: lệnh install, dev server, test, lint, typecheck và cách chạy một test cụ thể.
- Conventions: naming, error handling, file layout, thư viện team đã chọn và pattern không được copy.
- Architecture: 2-3 câu về các phần chính và cách chúng giao tiếp.
- Hard constraints: nơi cấm ghi, lệnh cấm chạy, secret không được đọc, migration phải review.
- Known gotchas: lỗi môi trường, file trông cũ nhưng vẫn production, test cần biến môi trường riêng.
Ví dụ một CLAUDE.md ngắn cho dự án Next.js:
# Commands - Install: pnpm install - Dev: pnpm dev - Test một file: pnpm vitest run path/to/file.test.ts - Typecheck: pnpm tsc --noEmit # Conventions - Dùng Server Actions cho mutation mới. - Không thêm dependency mới nếu chưa kiểm tra bundle size. - API route phải validate input bằng schema trong src/lib/schemas/. # Gotchas - Không sửa file trong src/generated/. Chạy pnpm codegen để tạo lại. - Test integration cần DATABASE_URL, xem .env.example.
Những thứ không nên đưa vào: tài liệu API dài, lịch sử quyết định, changelog, nội dung nhìn cây thư mục là thấy, hoặc quy tắc “đẹp” mà team không bao giờ làm. File càng nhiễu, tín hiệu càng yếu. [2]
Viết quy tắc thế nào để Claude Code làm đúng?
Viết quy tắc đủ cụ thể để kiểm tra được kết quả. “Format code properly” không giúp Claude biết bạn muốn gì; “dùng 2-space indentation” hoặc “chạy pnpm lint trước khi commit” thì kiểm tra được ngay.
| Quy tắc mơ hồ | Quy tắc dễ làm đúng |
|---|---|
| Viết code sạch | Ưu tiên function nhỏ, đặt helper dùng chung trong src/lib/ |
| Test kỹ | Chạy pnpm test và pnpm tsc –noEmit trước khi báo xong |
| Đừng phá database | Không chạy migration trên database production; mọi migration cần review |
| Dùng đúng UI | Component mới dùng Tailwind + component trong src/components/ui/ |
Anthropic cũng nhấn mạnh ba nguyên tắc: ngắn, có cấu trúc và nhất quán. File mỗi scope nên nhắm khoảng dưới 200 dòng; nhóm quy tắc theo heading; và rà file định kỳ để xóa instruction cũ hoặc mâu thuẫn. Nếu hai file ghi ngược nhau, Claude có thể chọn một cách tùy ngữ cảnh — đây là lỗi hệ thống, không phải lỗi prompt. [1]
Có một ranh giới quan trọng bạn cần nhớ: CLAUDE.md là non-deterministic instruction. Nó ảnh hưởng quyết định của model, không bắt buộc hành vi tuyệt đối. Khi bạn viết “không bao giờ sửa folder generated” mà vẫn sợ agent quên, rule đó nên chuyển thành deny rule hoặc hook. Cách phân biệt này được Anthropic giải thích rõ trong tài liệu best practices. [3]
Bạn có thể chạy /doctor prompt-audit để Claude rà CLAUDE.md, AGENTS.md, rules, skills, commands, subagents và output styles. Lệnh này báo instruction cũ, đường dẫn không còn tồn tại, hoặc file mâu thuẫn nhau; nó chỉ đề xuất sửa chứ không tự đổi file. [1]
Dự án lớn nên tổ chức CLAUDE.md ra sao?
Với monorepo hoặc codebase lớn, đừng nhồi toàn bộ convention vào một CLAUDE.md gốc. Cách tốt hơn là root file giữ quy tắc toàn repo, còn mỗi package hoặc subsystem có file riêng cho convention gần với code đang sửa. [5]
Ví dụ repo có packages/api và packages/web: root CLAUDE.md ghi commit convention và lệnh chung; file trong packages/api/ ghi rule database, migration và test backend; file trong packages/web/ ghi rule component, styling và accessibility. Khi bạn chạy Claude từ packages/api, agent nhận cả root và file cục bộ mà không phải tải convention frontend không liên quan. [5]
Nếu một quy tắc áp dụng cho nhiều path rải rác, bạn có thể dùng path-scoped rules trong .claude/rules/ thay vì lặp file ở nhiều thư mục. Ngược lại, nếu một package không bao giờ cần load, setting claudeMdExcludes giúp loại file instruction không liên quan khỏi context. [4] [5]
Điểm thực tế mình thấy hay quên: nơi bạn chạy lệnh claude quyết định file nào load lúc mở phiên. Chạy từ root sẽ phù hợp việc xuyên nhiều package; chạy từ package cụ thể sẽ gọn hơn khi task chỉ đụng một subsystem.
Quy trình tạo và bảo trì file quy tắc
Cách nhanh nhất là chạy /init, rồi biên tập lại bản Claude sinh như một onboarding document sống. Lệnh này phân tích repo và tạo draft gồm command, cấu trúc và convention nó phát hiện được; bạn cần xóa phần sai, thêm quyết định không nằm trong code, rồi commit file để team cùng dùng. [2]
Quy trình file quy tắc trong 5 bước
- Chạy /init. Mở Claude Code ở repo root và tạo bản draft đầu tiên.
- Rà chính xác. Kiểm tra lệnh thật, package manager, folder generated và convention team đang dùng.
- Rút ngắn file. Xóa nội dung hiển nhiên, giữ rule có tác động trực tiếp lên hành vi agent.
- Commit và kiểm tra load. Đưa file vào git nếu là quy tắc team, rồi dùng /context xác nhận file được đọc.
- Cập nhật khi có tín hiệu. Claude sai hai lần cùng một lỗi, reviewer phải nhắc lại, hoặc convention thay đổi — đó là lúc thêm hoặc xóa một dòng.
Bảo trì nên nhẹ nhưng đều. Anthropic gợi ý review sau /init, khi Claude lặp lại cùng lỗi, khi convention đổi, và skim định kỳ để xóa instruction cũ. Nếu làm trong team, hãy review thay đổi file này như một phần pull request — file này ảnh hưởng mọi phiên Claude Code sau đó. [2]
Nếu bạn đang lo agent có quyền quá rộng, File này chỉ là một phần của hệ thống an toàn. Bạn vẫn nên kết hợp review diff, checkpoint và permission mode; bài phân tích về bảo mật vibe coding có cùng nguyên tắc: càng cho agent nhiều quyền, càng cần ranh giới rõ.
Nguồn tham khảo
Các nguồn kiểm tra ngày 02/11/2026. Tính năng Claude Code thay đổi nhanh — bạn nên đối chiếu docs chính thức và lệnh /help trong phiên khi đọc lại bài.
- Claude Code Docs — How Claude remembers your project
- Claude Help Center — Give Claude context: project context and better prompts
- Claude Code Docs — Best practices for Claude Code
- Claude Code Docs — Explore the .claude directory
- Claude Code Docs — Set up Claude Code in a monorepo or large codebase
Câu hỏi thường gặp về file quy tắc
File này có bắt buộc không?
Không bắt buộc, nhưng rất nên có khi bạn dùng Claude Code thường xuyên trong cùng một repo. File này giúp agent không phải đoán lại command, convention và ràng buộc dự án mỗi phiên.
File instruction khác AGENTS.md thế nào?
Hai file cùng chứa instruction cho AI coding agent. File này là định dạng riêng của Claude Code, còn AGENTS.md là file dùng chung hơn cho nhiều agent; Claude Code có thể đọc AGENTS.md trong repo phù hợp.
Nên đặt file quy tắc ở đâu?
Với quy tắc team, đặt trong project root hoặc thư mục .claude/ và commit vào git. Với quy tắc cá nhân cho mọi dự án, đặt trong home directory dưới ~/.claude/. Với ghi chú riêng trong một repo, dùng CLAUDE.local.md và gitignore.
File này có làm Claude Code an toàn tuyệt đối không?
Không. File này là context chứ không phải enforcement. Quy tắc không được phá vỡ cần deny rule, hook, sandbox hoặc managed settings; File này chỉ nên dùng cho convention và hướng dẫn model.
File quy tắc nên dài bao nhiêu?
Nên giữ ngắn và signal-dense; tài liệu chính thức gợi ý khoảng dưới 200 dòng cho mỗi file. Nếu file dài hơn, hãy tách theo scope, rules hoặc subdirectory thay vì nhồi hết vào root.
Khi nào nên cập nhật file quy tắc?
Cập nhật khi Claude lặp lại cùng một lỗi, reviewer phải nhắc lại một convention, hoặc team đổi tool/lệnh/quy trình. Ngoài ra nên skim định kỳ để xóa instruction cũ hoặc mâu thuẫn.
File instruction không cần dài — nó cần đúng. Một file ngắn ghi chính xác lệnh test, package manager, folder cấm sửa và convention team sẽ tiết kiệm cho bạn nhiều lần sửa prompt hơn một tài liệu dài đầy khẩu hiệu. Nếu đã có Claude Code trong máy, bạn nên chạy /init hôm nay, rà file sinh ra trong 10 phút rồi commit bản đầu tiên.
Cần thiết kế workflow AI coding cho team? VietnamTutor hỗ trợ chuẩn hóa file quy tắc, permission, review và quy trình phát triển phù hợp quy mô doanh nghiệp. Bạn đang muốn Claude Code nhớ quy tắc nào nhất trong dự án của mình? Để lại bình luận nhé.
