Viết CLAUDE.md tốt nhất: Hướng dẫn đầy đủ cho Claude Code

Lời nhắc hệ thống của Claude Code vốn đã chiếm khoảng 50 chỉ dẫn trước khi phiên của bạn bắt đầu. Nghiên cứu về các LLM tiên phong cho thấy khả năng tuân thủ chỉ dẫn bắt đầu suy giảm ở mức khoảng 150 đến 200 chỉ dẫn tổng, nghĩa là bạn còn khoảng 100 đến 150 chỗ cho mọi thứ bạn muốn Claude biết về dự án của mình. 

CLAUDE.md là tệp lấp đầy những chỗ đó. Đây là một tệp markdown mà Claude Code đọc ở đầu mỗi phiên, cung cấp cho nó ngữ cảnh bền vững về codebase của bạn mà không cần bạn lặp lại. Nhưng Claude sẽ chủ động lọc nội dung mà nó cho là không liên quan đến tác vụ hiện tại. Một tệp cồng kềnh không chỉ lãng phí dung lượng; nó còn cạnh tranh với các quy tắc thực sự của bạn.

Hướng dẫn này đề cập cách xây dựng một CLAUDE.md xứng đáng với từng dòng: nên đưa gì vào, loại gì ra, cách cấu trúc cho nhóm, và cách giữ cho nó hữu ích theo thời gian.

Tôi cũng khuyên bạn nên xem các hướng dẫn Claude Code gần đây khác của chúng tôi:

• Chế độ Lập kế hoạch của Claude Code
• Claude Code trong Docker
• Cách xây dựng plugin cho Claude Code
• Sử dụng Claude Code với các mô hình cục bộ Ollama

CLAUDE.md là gì?

CLAUDE.md là tệp markdown mà Claude Code tự động tải ở đầu mỗi cuộc trò chuyện. Nó nằm tại thư mục gốc dự án và cung cấp cho Claude các chỉ dẫn thường trực về nhiều thông tin liên quan: 

• Ngăn xếp công nghệ bạn sử dụng
• Cách bạn chạy kiểm thử
• Những quy ước nào là quan trọng
• Những gì không được đụng tới

Nếu không có nó, mỗi phiên sẽ bắt đầu từ con số không. Bạn giải thích cùng ngữ cảnh, sửa cùng giả định, và chứng kiến Claude lặp lại những sai lầm như hôm qua. CLAUDE.md khắc phục điều đó bằng cách mã hóa kiến thức dự án của bạn một lần.

Đây là một trong vài hệ thống ngữ cảnh mà Claude Code sử dụng, và mỗi hệ thống xử lý công việc khác nhau:

Chạy /init sẽ tạo một CLAUDE.md khởi đầu bằng cách phân tích codebase của bạn, phát hiện hệ thống build, framework kiểm thử và các mẫu mã. Nếu đã có tệp, nó sẽ gợi ý cải tiến thay vì ghi đè. Đây là điểm khởi đầu hợp lý, nhưng tệp này quá quan trọng để phó mặc cho tự động.

Một điểm quan trọng khác là nội dung CLAUDE.md cũng tồn tại qua /compact. Khi ngữ cảnh bị nén giữa phiên, Claude sẽ đọc lại tệp từ đĩa và nạp lại từ đầu.

Vị trí tệp và mức độ ưu tiên

Tệp CLAUDE.md có thể nằm ở bốn nơi, liệt kê từ phạm vi rộng nhất đến cụ thể nhất:

• Chính sách quản lý (toàn tổ chức): /Library/Application Support/ClaudeCode/CLAUDE.md trên macOS. Áp dụng cho mọi người dùng trên máy và không thể loại trừ bằng bất kỳ cài đặt nào. Trên Linux/WSL là /etc/claude-code/CLAUDE.md, và trên Windows là C:\Program Files\ClaudeCode\CLAUDE.md.

• Cấp người dùng: ~/.claude/CLAUDE.md. Chỉ dẫn cá nhân áp dụng cho mọi dự án trên máy của bạn.

• Cấp dự án: ./CLAUDE.md hoặc ./.claude/CLAUDE.md tại thư mục gốc repo. Đây là tệp bạn commit vào git và chia sẻ với nhóm.

• Thư mục con: ./subdir/CLAUDE.md. Phạm vi trong thư mục đó và được nạp theo yêu cầu khi Claude đọc tệp ở đó, không phải lúc bắt đầu phiên.

Các tệp cụ thể hơn có ưu tiên cao hơn tệp phạm vi rộng. Nếu CLAUDE.md của dự án nói "dùng tab" còn tệp cấp người dùng nói "dùng dấu cách", thì tệp của dự án sẽ được ưu tiên.

Đối với sở thích cá nhân không nên đưa vào hệ thống kiểm soát phiên bản, hãy tạo CLAUDE.local.md và thêm vào .gitignore. Những khác biệt về trình soạn thảo, kiểu commit ưa thích, hoặc ghi đè tạm thời nên đặt ở đây để không làm lộn xộn tệp dùng chung.

Biết tệp nằm ở đâu và cạnh tranh với gì, câu hỏi tiếp theo là thực sự nên chứa gì bên trong.

Nên đưa gì vào CLAUDE.md

Một CLAUDE.md chia thành ba lớp: 

1. Dự án là gì
2. Vì sao nó hoạt động theo cách như vậy
3. Claude nên vận hành trong đó như thế nào

Nếu bạn đã đọc Thực hành tốt nhất cho Claude Code, bạn sẽ nhận ra đây là cùng một nguyên tắc áp dụng cho một bề mặt hẹp hơn. (Nếu chưa, bạn nên đọc ngay sau bài này!)

Tổng quan dự án giàu thông tin

Mở đầu bằng mô tả một đến hai dòng về dự án và ngăn xếp công nghệ kèm phiên bản. Claude có thể suy ra nhiều điều từ việc đọc mã, nhưng nó sẽ không đoán được bạn đang dùng Next.js 15 thay vì 14, hay bạn chọn Drizzle thay vì Prisma.

Bao gồm sơ đồ cấu trúc thư mục. Không cần mọi tệp, chỉ bố cục cấp cao với mô tả ngắn:

src/
  data/        # Data loading and preprocessing pipelines
  models/      # Model definitions and training loops
  evaluation/  # Metrics, validation, experiment tracking
  api/         # FastAPI endpoints for model serving
  tests/       # Co-located with source, test_*.py

Đưa các lệnh thường dùng vào khối mã. Build, test, lint và khởi động dev server. Một lệnh nằm trong khung mã là thứ Claude sẽ chạy nguyên văn. Một lệnh viết trong câu chỉ là gợi ý mà nó có thể ứng biến.

Mục đích và ràng buộc

Các quyết định kiến trúc cần có trong tệp vì nếu không, Claude sẽ tự đưa ra quyết định. Nếu bạn chọn SQLite thay vì Postgres vì một lý do nào đó, hãy nói rõ. Nếu lớp API của bạn tuân theo một mẫu cụ thể, hãy giải thích lý do.

Lý giải đóng vai trò thực tế ở đây. "Không bao giờ force push" là một chỉ dẫn phẳng mà Claude có thể bỏ qua khi bị thúc ép. "Không bao giờ force push. Việc này ghi lại lịch sử chia sẻ và không thể khôi phục cho cộng tác viên," cho Claude đủ ngữ cảnh để khái quát. Nó sẽ không chỉ tránh git push --force. Nó cũng sẽ chần chừ trước khi git reset --hard trên một nhánh chia sẻ.

Chỉ dẫn làm việc cho Claude

Phần này bao gồm các quy ước mà Claude không thể nắm bắt chỉ bằng cách đọc mã. Nếu bạn dùng Conventional Commits (feat:, fix:, docs:), hãy nói rõ. Nếu nhánh theo mẫu đặt tên như initials/description, hãy ghi lại.

Những điểm lắt léo và bẫy cũng nên có ở đây. Codebase nào cũng có: script migration phải chạy trước khi build, biến môi trường cần giá trị cụ thể để kiểm thử qua, module sẽ hỏng nếu import sai thứ tự. Claude là thành viên mới mỗi phiên, và đây là những thứ mà người mới hay vấp ngay ngày đầu.

Những gì có thể bỏ qua: bất cứ thứ gì Claude đã biết từ chính ngôn ngữ. Bạn không cần bảo nó dùng async/await trong JavaScript hiện đại hay ưu tiên pathlib trong Python 3. Nếu một quy ước là mặc định của ngôn ngữ, viết ra chỉ tạo nhiễu làm lu mờ những chỉ dẫn thực sự quan trọng.

Cách viết tệp CLAUDE.md

Làm đúng nội dung là phần dễ hơn. Phần khó là viết các chỉ dẫn mà Claude thực sự sẽ tuân theo, và biết nên cắt bỏ gì.

Viết chỉ dẫn hiệu quả

Cụ thể luôn thắng ý định. "Định dạng mã cho đúng" không nói gì với Claude. "Thụt lề 2 dấu cách, không dùng dấu chấm phẩy, dùng dấu nháy đơn" nói chính xác phải làm gì và cho nó thứ có thể kiểm chứng.

Áp dụng bài kiểm tra này cho từng dòng: "Gỡ dòng này đi có khiến Claude mắc lỗi không?" Nếu câu trả lời là không, hãy bỏ. Khuyến nghị chính thức là dưới 200 dòng mỗi tệp, và một số đội giàu kinh nghiệm chỉ dùng dưới 60 dòng. Không phải chủ nghĩa tối giản cho đẹp: tệp ngắn hơn đồng nghĩa nhiều nội dung trong đó được đọc hơn.

Giữ mức tiêu đề tối đa ba cấp. Dùng tên mục mà agent quen thuộc theo chuẩn README: Commands, Structure, Conventions, Testing. Sáng tạo tên mục sẽ tạo ma sát vì Claude đã thấy hàng triệu README và có kỳ vọng rõ về nội dung ở từng mục.

Khi một quy tắc bị phớt lờ dù đã có trong tệp, đừng thêm lời bao quanh. Hãy tiền tố bằng IMPORTANT: hoặc YOU MUST. Nhưng dùng dè dặt, vì nhấn mạnh tỷ lệ kém. Nếu mọi quy tắc đều quan trọng, thì nhấn mạnh trở nên vô hình.

Nên loại bỏ gì

Cưỡng chế kiểu mã là cái bẫy lớn nhất. Định dạng, thụt lề, sắp xếp import: đây là các vấn đề xác định với lời giải xác định. Các linter và formatter như Biome, ESLint, hoặc Ruff xử lý nhanh hơn, rẻ hơn và nhất quán 100%. Tiêu tốn ngân sách chỉ dẫn cho quy tắc style là gánh nặng: cùng công việc mà pre-commit hook làm miễn phí.

Các quy ước ngôn ngữ chuẩn cũng nên loại trừ, vì Claude đã biết các mẫu TypeScript và lối viết Python. Tài liệu API đầy đủ nên được dẫn link thay vì dán vào. Các chỉ dẫn theo tác vụ chỉ áp dụng cho một số quy trình nên đặt trong skills, nơi chúng được nạp theo yêu cầu thay vì chiếm chỗ trong mọi phiên.

Một mẫu đáng lưu ý: ràng buộc chỉ có phủ định. "Không bao giờ dùng --legacy-peer-deps" sẽ khiến Claude mắc kẹt khi gặp xung đột phụ thuộc. Hãy ghép mọi cấm đoán với chỉ dẫn: "Không bao giờ dùng --legacy-peer-deps; hãy giải quyết xung đột bằng cách cập nhật gói lên phiên bản tương thích." Nếu bạn từng làm việc với Cursor Rules hay các tệp cấu hình AI tương tự, bạn sẽ thấy nguyên tắc này áp dụng xuyên công cụ.

Trước và sau: ví dụ thực tế tối giản

Đây là sự khác biệt trong thực tế. Bên trái là một mục CLAUDE.md tự sinh điển hình đầy lời khuyên chung mà Claude đã biết. Bên phải là cùng mục sau khi áp dụng bài kiểm tra tính cụ thể: chỉ còn các sự thật đặc thù dự án.

Phiên bản thứ hai ngắn hơn và nói với Claude những điều nó không thể suy ra từ codebase.

Xây tệp từ số không

Chạy /init ở thư mục gốc dự án để có điểm khởi đầu sinh tự động. Đọc từng dòng, cắt điều hiển nhiên, và thêm điều còn thiếu so với cách nhóm bạn thực sự làm việc. Bắt đầu từ đầu ra /init nhanh hơn so với tệp trống, nhưng nội dung tự sinh không bao giờ nên đưa vào mà không rà soát.

Nếu bạn thích viết từ đầu, hãy bắt đầu với năm mục: 

1. Tổng quan dự án
2. Bản đồ thư mục
3. Lệnh
4. Quy ước
5. Điểm lắt léo

Bạn luôn có thể mở rộng tệp sau này, và khởi đầu tối giản nghĩa là mọi dòng bạn thêm đều xuất phát từ một sai lầm thực tế thay vì phỏng đoán.

Hai tín hiệu cho thấy tệp cần bảo trì: 

• Claude xin lỗi vì bỏ sót một chỉ dẫn đã có: Cách diễn đạt mơ hồ, hãy viết lại cho rõ.
• Cùng một quy tắc bị vi phạm ở nhiều phiên: Tệp quá dài và Claude đang lọc bỏ, hãy rút ngắn.

Cả hai cùng dẫn tới một cách khắc phục: ít chữ hơn, cấu trúc rõ hơn.

Mở rộng CLAUDE.md cho nhóm

Một tệp cho một nhà phát triển có thể giữ gọn như vậy vô thời hạn. Khi cả nhóm tham gia, tệp cần kiểu cấu trúc khác.

Kiểm soát phiên bản và quyền sở hữu chung

Tệp CLAUDE.md cấp dự án nên nằm trong git. Đây là tài liệu dùng chung tốt lên khi đồng đội đóng góp quy tắc từ chính sai lầm của họ. Hãy xử lý thay đổi với tệp này như với PR mã: rà soát, chất vấn liệu mỗi dòng mới có xứng đáng chỗ đứng.

Khi các quy ước chất đống vượt quá sức chứa của một tệp, hãy chuyển chúng vào .claude/rules/. Mỗi tệp Markdown bao phủ một chủ đề với tên mô tả: testing.md, api-design.md, database-migrations.md. Claude phát hiện các tệp này đệ quy và nạp chúng với cùng mức ưu tiên như CLAUDE.md chính.

Quy tắc theo phạm vi đường dẫn còn giúp nhắm mục tiêu hơn. Thêm frontmatter YAML, và quy tắc chỉ nạp khi Claude làm việc với tệp khớp:

---
paths:
  - "src/api/**/*.ts"
---
# API conventions go here

Quy ước frontend sẽ không tiêu tốn ngân sách chỉ dẫn trong lúc làm backend, và ngược lại.

Trong monorepo nơi các nhóm có quy ước xung đột, claudeMdExcludes chặn nạp các tệp cụ thể:

{
  "claudeMdExcludes": [
    "**/other-team/.claude/rules/**"
  ]
}

Đặt mục này trong .claude/settings.local.json để giữ ngoài hệ thống kiểm soát phiên bản.

Tiết lộ dần và mô-đun hóa

Mở rộng một CLAUDE.md thường kích hoạt thôi thúc tập trung hóa: một tệp lớn chứa mọi thứ. Đó là hướng sai. Chia nhỏ CLAUDE.md của monorepo thành các tệp cấp dịch vụ có thể giảm tổng số từ đến 80% đồng thời cải thiện mức độ Claude tuân thủ quy tắc; ít thứ để đọc hơn mỗi phiên nghĩa là ít phải lọc hơn.

Nguyên tắc: dẫn chiếu, không nhúng. Thay vì @path/to/big-doc.md (tải toàn bộ tệp vào mọi phiên), hãy viết "Về quy trình migration, xem docs/migrations.md." Claude sẽ đọc khi cần thông tin. Cú pháp nhập @ hữu ích cho tệp nhỏ, nhưng bất kỳ thứ gì đáng kể đều nên được tham chiếu thay vì nhúng.

Các tệp CLAUDE.md trong thư mục con hoàn thiện mẫu này. Một frontend/CLAUDE.md với quy ước React chỉ được nạp khi Claude chạm vào tệp trong thư mục đó. Quy tắc backend sẽ không cản trở trong lúc làm việc frontend.

Bảo trì tệp CLAUDE.md của bạn

Mở rộng cấu trúc phần lớn là vấn đề đã có lời giải khi bạn nắm các thành phần cơ bản. Nhưng dự án thay đổi và quy ước tiến hóa. Những quy tắc hợp lý sáu tháng trước có thể trở thành nhiễu, che lấp các quy tắc quan trọng lúc này. Thách thức liên tục là giữ cho tệp trung thực theo thời gian.

Giữ tệp luôn cập nhật

Thêm quy tắc chậm hơn bạn nghĩ. Một dòng mới chỉ thuộc về tệp khi Claude mắc một lỗi thực sự mà dòng đó sẽ ngăn được. Mỗi quy tắc nên lần theo một sự cố thực, không phải một giả định.

Chiều ngược lại cũng quan trọng: nếu Claude đã tự tuân thủ một quy ước mà không cần dặn, quy tắc đó là gánh nặng. Hãy gỡ bỏ để giải phóng ngân sách chỉ dẫn cho những quy tắc thực sự thay đổi hành vi.

Một thói quen bảo trì ít tốn công là bảo Claude: "Rà soát CLAUDE.md này và đề xuất cải tiến" vài tuần một lần. Nó phát hiện mâu thuẫn giữa các quy tắc, gắn cờ chỉ dẫn chồng chéo, và xác định chỗ diễn đạt có thể gọn hơn. 

Bạn cũng có thể thêm một chỉ dẫn thường trực ngay trong tệp: "Khi gặp giả định sai trong phiên, hãy đề xuất chỉnh sửa CLAUDE.md." Điều này tạo vòng lặp phản hồi, trong đó tệp được cải thiện qua quá trình sử dụng bình thường.

Những phản mẫu cần tránh

Dạng thất bại phổ biến nhất là tích tụ. Quy tắc chồng chất sau mỗi phiên bực bội, không ai gỡ những thứ đã hết ý nghĩa, và cuối cùng tệp dài đến mức Claude lọc bỏ nửa số nội dung. Khi Claude cứ phớt lờ một quy tắc, thêm nhấn mạnh trên một tệp cồng kềnh sẽ không sửa được. Cắt tỉa mới là giải pháp.

Nếu bạn dùng nhập @ cho tệp lớn, đó là vấn đề thứ hai cần kiểm tra. Một tài liệu kiến trúc 500 dòng được nhập bằng @ sẽ nhúng toàn bộ vào mọi phiên, đốt sạch ngân sách chỉ dẫn trước khi Claude xử lý quy tắc đầu tiên của bạn. Hãy tham chiếu thay vì nhúng.

Tự sinh bằng /init và không bao giờ biên tập là cách chắc chắn dẫn đến hành vi kém trên diện rộng. Một chỉ dẫn sai trong CLAUDE.md không chỉ ảnh hưởng một phản hồi. Nó định hình quá trình nghiên cứu, lập kế hoạch, và triển khai của Claude trong mọi phiên cho đến khi có người phát hiện.

Các quy tắc mâu thuẫn giữa nhiều tệp dẫn tới hành vi khó lường. Khi hai quy tắc xung đột, Claude sẽ chọn một mà không nói cho bạn biết là cái nào. Điều này tệ hơn trong dự án kết hợp CLAUDE.md gốc với vài tệp .claude/rules/. Rà soát định kỳ trên tất cả tệp chỉ dẫn là cách phòng ngừa duy nhất.

Không phải mọi sai lầm đều xứng đáng có quy tắc mới. Một số thất bại là cá biệt. Thêm quy tắc cho mọi trường hợp biên sẽ tạo ra một tệp đầy chỉ dẫn điều kiện, hữu ích trong tình huống hẹp nhưng gây hại trong phần lớn phiên. Mục tiêu suốt từ đầu đến cuối vẫn vậy: một tệp ngắn nơi mỗi dòng đều thay đổi hành vi.

Kết luận

CLAUDE.md có lẽ là tệp chịu tải lớn nhất trong một dự án Claude Code. Nó định hình mọi phiên trước khi bạn gõ dòng nhắc đầu tiên, và một tệp được bảo trì tốt sẽ cộng dồn hiệu quả qua nhiều tuần làm việc.

Nếu bạn chưa có, hãy chạy /init, đọc đầu ra, và cắt mọi dòng sẽ không ngăn được một lỗi thực sự. Nếu bạn đã có, hãy mở ngay và áp dụng cùng bài kiểm tra. Nếu CLAUDE.md của bạn buộc phải khổng lồ để giải thích dự án, đó là tín hiệu cho thấy công cụ của dự án quá phức tạp, không phải bạn cần tệp to hơn.

Bước tiếp theo đúng đắn: kiểm toán repo của bạn và phác thảo một bản nền tảng hôm nay. Bắt đầu với năm mục, giữ dưới 60 dòng, và để các sai lầm thực tế dẫn dắt mọi bổ sung về sau.

Nếu bạn muốn xây dựng công cụ sử dụng Anthropic API, khóa học Giới thiệu về các mô hình Claude của chúng tôi bao quát toàn bộ họ mô hình và dạy bạn cách sử dụng hiệu quả.