Cách viết `CLAUDE.md` tốt

• LLM là hàm không trạng thái, vì vậy CLAUDE.md đóng vai trò là tài liệu cốt lõi để giới thiệu codebase cho Claude ở mỗi phiên
• Tệp này cần trình bày ngắn gọn WHAT (cấu trúc), WHY (mục đích) và HOW (cách vận hành) của dự án; việc nhồi nhét quá nhiều lệnh không cần thiết sẽ làm giảm hiệu năng
• Claude có thể bỏ qua nội dung trong CLAUDE.md nếu theo chỉ dẫn của system message, nó đánh giá nội dung đó ít liên quan
• Một tệp hiệu quả chỉ nên chứa thông tin ngắn gọn và có thể áp dụng rộng rãi; các hướng dẫn chi tiết nên được tách sang tài liệu riêng để quản lý theo cách Progressive Disclosure
• CLAUDE.md là điểm tác động mạnh nhất của agent harness, vì vậy nên được viết thủ công một cách cẩn trọng thay vì tạo tự động

---

Tính không trạng thái của LLM và vai trò của CLAUDE.md

• LLM sử dụng trọng số cố định tại thời điểm suy luận và không duy trì việc học hay ký ức giữa các phiên
  • Vì vậy, nếu muốn mô hình hiểu codebase thì mọi thông tin đều phải được cung cấp qua input token
• Các coding agent như Claude Code phải quản lý bộ nhớ một cách tường minh, và CLAUDE.md là tệp duy nhất được tự động đưa vào mọi cuộc hội thoại
• Vì thế, ba điều sau là bắt buộc
  1. Khi bắt đầu phiên, Claude không biết gì về codebase
  2. Mỗi phiên đều phải cung cấp lại thông tin cần thiết
  3. Phương tiện tiêu chuẩn cho việc này là CLAUDE.md

Onboarding codebase: WHAT, WHY, HOW

• CLAUDE.md đóng vai trò là tài liệu onboarding giúp Claude hiểu dự án
  • WHAT: cung cấp bản đồ code như tech stack, cấu trúc dự án, cách tổ chức monorepo
  • WHY: giải thích mục đích và chức năng của từng thành phần
  • HOW: nêu rõ cách thực hiện công việc thực tế như build, test, typecheck
• Tuy nhiên, liệt kê toàn bộ lệnh là không hiệu quả; chỉ nên bao gồm lượng thông tin tối thiểu cần thiết

Vì sao Claude bỏ qua CLAUDE.md

• Claude Code chèn vào user message một system reminder như sau

  IMPORTANT: this context may or may not be relevant...
  

  • Vì vậy Claude có thể bỏ qua ngữ cảnh đó nếu cho rằng nó không liên quan đến tác vụ hiện tại
• Tệp càng có nhiều chỉ dẫn không mang tính phổ quát thì khả năng bị bỏ qua càng cao
• Có thể suy đoán Anthropic thêm cơ chế này vì khi bỏ qua các chỉ dẫn không cần thiết, chất lượng kết quả được cải thiện

Nguyên tắc viết CLAUDE.md tốt

Less (instructions) is more

• LLM có thể tuân theo ổn định khoảng 150~200 chỉ dẫn
  • Mô hình càng nhỏ thì hiệu năng càng giảm mạnh, và không phù hợp với tác vụ nhiều bước
• System prompt của Claude Code đã chứa sẵn khoảng 50 chỉ dẫn
  • Vì vậy trong CLAUDE.md, chỉ nên giữ những chỉ dẫn phổ quát và thiết yếu nhất ở mức tối thiểu
• Càng nhiều chỉ dẫn thì chất lượng thực thi tổng thể của toàn bộ chỉ dẫn càng suy giảm đồng đều

Độ dài tệp và phạm vi áp dụng

• LLM hoạt động tốt hơn với ngữ cảnh tập trung và có mức liên quan cao
• Vì CLAUDE.md được đưa vào mọi phiên, nên chỉ nên giữ lại thông tin có thể áp dụng rộng rãi
• Thông thường, nên giữ ở mức dưới 300 dòng, và càng ngắn càng tốt
  • Tệp ví dụ của HumanLayer dưới 60 dòng

Progressive Disclosure

• Với các dự án lớn, rất khó nhồi mọi thông tin vào một tệp, nên khuyến nghị cách công khai dần thông tin (Progressive Disclosure)
  • Các hướng dẫn chi tiết được tách ra thành những tệp Markdown riêng trong thư mục agent_docs/
  • Ví dụ: building_the_project.md, running_tests.md, code_conventions.md
• Trong CLAUDE.md, chỉ nên chứa danh sách và mô tả ngắn gọn của các tệp này, cùng chỉ dẫn để Claude đọc chúng khi cần
• Thay vì code snippet, nên dùng tham chiếu file:line để giữ tính cập nhật
• Cách này tương tự khái niệm Claude Skills, nhưng tập trung vào quản lý chỉ dẫn hơn là sử dụng công cụ

Claude không phải là linter

• Đưa guideline về code style vào CLAUDE.md là không hiệu quả
  • LLM tốn kém, chậm và không mang tính quyết định, kém phù hợp hơn linter
• Các quy tắc style vốn đã được học một cách tự nhiên từ pattern của code hiện có, nên không cần chỉ dẫn riêng
• Với formatting, hãy dùng linter có thể tự động sửa (như Biome) và chỉ đưa kết quả sửa cho Claude
• Khi cần, có thể dùng Stop Hook hoặc Slash Command để tự động hóa formatting và kiểm chứng

Không tạo tự động

• Không khuyến nghị CLAUDE.md được tạo bằng lệnh /init hay các tính năng sinh tự động
  • Vì đây là điểm đòn bẩy cao ảnh hưởng đến mọi phiên và mọi đầu ra
• Chỉ một dòng chỉ dẫn sai cũng có thể gây hiệu ứng dây chuyền làm giảm chất lượng toàn bộ mã nguồn
• Vì vậy, mọi câu chữ cần được rà soát kỹ và viết thủ công cẩn trọng

Kết luận

• CLAUDE.md là tài liệu để onboarding Claude vào codebase, và cần định nghĩa rõ WHY·WHAT·HOW
• Giảm thiểu chỉ dẫn và chỉ giữ nội dung phổ quát, ngắn gọn
• Dùng Progressive Disclosure để cung cấp thông tin cần thiết theo từng bước
• Không dùng Claude như linter; hãy kết hợp công cụ chuyên dụng cùng hook và command
• Thay vì tạo tự động, cần viết thủ công một cách cẩn trọng để tối đa hóa chất lượng tổng thể của harness

[GN⁺]

Ý kiến trên Hacker News

• Claude thường có xu hướng bỏ qua các chỉ dẫn trong CLAUDE.md
  Càng có nhiều thông tin không liên quan đến tác vụ cụ thể trong file, Claude càng ít tuân theo các chỉ dẫn đó
  Một người bạn đã bảo Claude gọi mình là “Mr Tinkleberry”, và mỗi lần Claude quên điều đó thì có thể biết là nó đang bỏ qua file

• Tôi đã dùng cách tiếp cận Table-of-Contents từ lâu
  Tách hướng dẫn theo từng tác vụ thành các file markdown riêng, rồi trong CLAUDE.md chỉ để danh sách và mô tả ngắn gọn của chúng
  Làm vậy sẽ giữ cho context window gọn gàng
  Có thể xem file ví dụ của tôi tại đây

  • Tôi cũng đã thử cách này nhưng kết quả khá thất thường
    Claude hầu như không thực sự đọc các file tài liệu khác

• Tôi cảm thấy nếu đưa cho Claude quá nhiều context thì chất lượng lại giảm đi
  Vì vậy tôi luôn duy trì hai phiên bản mã

  1. Mã gốc không có chú thích và khoảng trắng
  2. Mã có kèm chú thích
     Tôi chỉ đưa phiên bản đầu tiên cho LLM
     Tôi nghĩ tỷ lệ compute trên thông tin là mấu chốt. Năng lực tính toán thì có hạn
  • Tôi cũng có trải nghiệm tương tự, nhưng khi đưa nội dung lặp lại vào file ghi chú của Claude thì hiệu quả tăng lên
    Không cần nhét mọi thứ vào, nhưng đưa thông tin cốt lõi vào thì ROI rất cao
    Claude hoạt động tốt trong các dự án thông thường nhưng thường bị rối với framework hoặc công cụ mới
  • Bạn nói là duy trì hai phiên bản mã, tôi tò mò không biết bạn quản lý tính nhất quán đó thế nào
    Tôi muốn hỏi liệu bạn có dùng script để xóa chú thích và khoảng trắng sau khi chỉnh sửa không
  • Tôi nghĩ trong các file tài liệu nên giữ mật độ thông tin ở mức cao
  • Bạn nói không đưa cho LLM phiên bản có chú thích, tôi tò mò không biết trên thực tế bạn triển khai việc đó như thế nào
  • Rốt cuộc thì attention là hữu hạn. Nhồi quá nhiều context sẽ làm phân tán sự tập trung

• Thật ra vẫn có cách giải quyết mà không cần thiết lập phức tạp như vậy
  Đó là viết tài liệu(documenting) cho mã thật rõ ràng
  Chỉ cần mô tả ngắn gọn mỗi file làm gì thì bản thân nó đã đóng vai trò như một prompt
  Có thể tận dụng README.md một cách tích cực
  LLM đã được huấn luyện trên thông tin công khai sẵn có, nên không cần phát minh gì mới

  • Nhưng khi viết tài liệu cho AI thì cần một cách khác với tài liệu dành cho người đọc
    Lời khuyên kiểu “hãy tài liệu hóa mã cho tốt” đơn thuần không phù hợp với ngữ cảnh này
  • Tôi cũng nghĩ cộng đồng AI đôi khi phát minh lại bánh xe một cách không cần thiết
    README thì tốt, nhưng CLAUDE.md có mục đích khác
    Ví dụ Claude/agents.md có tính năng được tự động chèn vào context khi truy cập thư mục cụ thể
    Với các codebase phức tạp thì quản lý context quan trọng hơn nhiều
  • CLAUDE.md không chỉ là tài liệu đơn thuần mà còn có vai trò tùy biến prompt khởi tạo của mô hình
    Vì vậy lời khuyên kiểu “hãy viết prompt cho đúng” là bỏ lỡ trọng tâm
  • Ví dụ, quy tắc như “truy vấn cơ sở dữ liệu phải luôn dùng index” thì nên viết ở đâu?
    Nếu đưa vào README thì cuối cùng nó cũng sẽ đóng vai trò giống CLAUDE.md
    Mục đích của CLAUDE.md là đưa trước thông tin cốt lõi để Claude không phải đọc lại toàn bộ tài liệu mỗi lần
    Con người thì nhớ, còn Claude lại quên sau mỗi tác vụ, nên cần một cấu trúc để giảm việc onboard lại

• Thành thật mà nói, nếu phải thiết lập hạ tầng AI đến mức này thì tôi thà tự viết mã còn hơn

  • Nhưng các thiết lập liên quan đến style chỉ cần làm một lần rồi tái sử dụng được
    Tôi quản lý riêng các quy tắc chung và các quy tắc theo từng dự án
  • Phần thiết lập được nói trong bài chỉ mất vài giờ
    Không dùng AI đơn giản là mất năng suất
  • Phần lớn thiết lập ban đầu thậm chí có thể giao cho LLM làm
  • Thực ra không tốn nhiều công sức đến thế. Vấn đề là cố tối ưu công cụ quá mức
  • Điều quan trọng là chi phí đó lặp lại hay chỉ một lần
    Nếu phần thiết lập chỉ cần làm một lần thì hoàn toàn đáng để đầu tư
    Lý do kiểu “ngại thiết lập” cũng giống như cái cớ của những người né cấu hình debugger

• Tôi chỉ cần sao chép đoạn mã cần thiết rồi dán vào cửa sổ chat và dùng như đang trò chuyện
  Dạo này mô hình đã cải thiện rất nhiều nên ngay cả không có file .md vẫn cho kết quả khá ổn
  Những file này có thể mang lại một chút cải thiện, nhưng tôi không nghĩ đó là phép màu tăng năng suất gấp 100 lần

  • Nhưng đây là một trường hợp sử dụng khác
    Điều đang được bàn ở đây là khi Claude tự mình thực hiện toàn bộ tính năng hoặc sửa lỗi
  • Tôi cũng có trải nghiệm tương tự. Tôi từng tạo CLAUDE.md một lần nhưng giờ không dùng nữa
    Chỉ cần đưa context cần thiết là nó hoạt động đủ tốt rồi. Hơi giống bikeshedding
  • Dù vậy, nếu sắp sẵn danh sách bảng hoặc cột trong cơ sở dữ liệu thì cũng giúp giảm lặp lại

• Tôi để Claude tự viết CLAUDE.md
  Nếu nói với nó “README.md là cho người dùng, còn CLAUDE.md là cho bạn”
  thì các chỉ dẫn như “hãy luôn kiểm tra tài liệu API” cũng sẽ được nó tự cập nhật
  Không cần biết prompt thần kỳ nào, miễn kết quả tốt là được

  • Nhưng tôi nghi ngờ liệu có bằng chứng nào cho thấy chỉ dẫn do AI tự viết tốt hơn chỉ dẫn do con người viết hay không
    Có vẻ chẳng có lý do gì để AI lại là bên biết cách prompt chính nó tốt nhất