TL;DR

Hầu hết developer đang tìm cách cải thiện prompt trong khi vấn đề thực sự nằm ở CLAUDE.md - hoặc là không có, hoặc là dùng sai hoàn toàn. CLAUDE.md không phải nơi để dump mọi yêu cầu vào: đây là hệ thống phòng ngừa lỗi giúp Claude không phải đoán mò về codebase của bạn. Bài này giải thích tại sao, và cách xây dựng đúng.

Claude bắt đầu mỗi session không biết gì về dự án của bạn

Nhiều developer không nhận ra điều này: Claude context-blind hoàn toàn ở đầu mỗi phiên. Nó không biết:

  • Project của bạn có cấu trúc như thế nào
  • Bạn theo convention nào
  • Architecture decisions nào đã được đưa ra
  • Lỗi nào quan trọng nhất cần tránh
  • Workflow của bạn kỳ vọng gì

Kết quả: Claude ứng biến. Và ứng biến chính là nguồn gốc của output không nhất quán. Session này xuất sắc, session sau lại frustrating - không phải vì model kém hơn, mà vì environment thay đổi.

CLAUDE.md sửa điều này. Đây là file markdown Claude Code tự động đọc ở đầu mỗi session, cung cấp persistent context về project mà Claude không thể tự suy ra từ code. Kết quả của việc setup đúng: một developer cảm giác như đang "chiến đấu với model", developer còn lại cảm giác như vừa thuê một senior engineer đã hiểu rõ codebase. Cùng một model. Setup hoàn toàn khác nhau.

Mục đích thực sự của CLAUDE.md

Phần lớn mọi người nghĩ CLAUDE.md tồn tại để "đưa instructions". Đó là cách hiểu bề mặt.

Mục đích sâu hơn là: giảm decision ambiguity. Đó là toàn bộ cuộc chơi.

AI workflow tốt không được xây dựng bằng cách liên tục thêm prompts. Chúng được xây bằng cách loại bỏ uncertainty. CLAUDE.md tốt nhất không cố control mọi thứ - chúng đơn giản ngăn những lỗi tốn kém nhất xảy ra lặp đi lặp lại.

CLAUDE.md không phải wishlist. Đây là hệ thống phòng ngừa lỗi.

Tại sao CLAUDE.md của bạn đang thất bại thầm lặng

Ba sai lầm phổ biến nhất:

Sai lầm 1: File quá dài. Mọi dòng thêm vào đều cạnh tranh với nhau. Frontier models có thể theo ~150-200 instructions trước khi compliance giảm. Claude Code system prompt đã chiếm khoảng 50 slots - bạn chỉ còn 100-150 slots cho toàn bộ CLAUDE.md và task prompt. File càng dài, rule adherence càng yếu - kể cả những rule đã hoạt động tốt trước đó. Một session mới đã tốn ~20.000 tokens chỉ để load system prompt và CLAUDE.md trước khi bạn gõ chữ đầu tiên. Chuyên gia khuyến nghị giữ file dưới 300 dòng, HumanLayer - công ty tiêu hàng tỷ tokens mỗi tháng - giữ file của họ dưới 60 dòng.

Sai lầm 2: Generic instructions. Những câu như "Write clean code", "Be a senior engineer", "Think step by step" nghe có vẻ hữu ích nhưng hầu như không thay đổi behavior. Claude đã hiểu những khái niệm này. Điều thực sự quan trọng là project-specific constraints, ví dụ:

  • never modify deployment configs
  • always run type checks
  • use existing utilities only
  • ask before architecture changes

Sai lầm 3: Không có cấu trúc. Phần lớn developer dump mọi thứ vào một file lớn - workflow preferences, stack details, architecture notes, personal opinions - tất cả trộn lẫn. Advanced users tách context có chủ ý: global rules - project rules - personal workflow preferences.

5 thành phần của một CLAUDE.md chất lượng cao

5 thành phần của CLAUDE.md chất lượng cao

Sau khi phân tích nhiều Claude workflow thực tế, hầu hết setup hiệu quả đều bao gồm 5 phần này:

1. Commands - Cách run dev, test, lint, type-check. Không có phần này, Claude đoán mò và tạo ra back-and-forth không cần thiết.

2. Architecture Map - Business logic ở đâu, API routes ở đâu, UI components ở đâu, state management ở đâu. Không cần mọi chi tiết, chỉ cần đủ để ngăn bad placement decisions.

3. Hard Rules - Mỗi rule phải trả lời câu hỏi: "Nếu bỏ rule này đi, Claude có mắc lỗi tốn kém không?" Nếu có: giữ lại. Nếu không: xóa. Negative rules quan trọng không kém positive rules - nói với Claude những gì KHÔNG làm cực kỳ mạnh mẽ.

4. Workflow Behavior - Ask before major changes, make minimal edits only, explain tradeoffs first. Phần này control cách Claude tiếp cận task, không chỉ output cuối cùng.

5. Out-of-Scope Boundaries - Phần bị underrate nhất. Xác định rõ forbidden areas: do not modify deployment configs, do not touch manually maintained files, never alter production infrastructure automatically. Boundaries tạo ra stability, và stability tích lũy theo thời gian.

Ngoài ra, CLAUDE.md hỗ trợ lazy loading qua subdirectory files: đặt CLAUDE.md trong subfolder (ví dụ src/api/CLAUDE.md, supabase/CLAUDE.md) - Claude chỉ load khi đang làm việc trong folder đó. Instruction budget cho frontend work không bị tốn bởi database migration rules. Đây là cách các team lớn tiêu hàng tỷ tokens/tháng vẫn giữ được performance ổn định.

Một lưu ý quan trọng: CLAUDE.md instructions chỉ được tuân thủ khoảng 70% thời gian. Cho code style preferences thì ổn. Cho safety rules như "đừng push to main" hay "đừng xóa production data" thì không ổn - đó là lúc bạn cần hooks (shell scripts chạy deterministic tại specific points trong workflow) để đạt 100% enforcement.

CLAUDE.md là hệ thống tự cải thiện

Insight mạnh nhất và ít người nhận ra: CLAUDE.md tốt cải thiện theo thời gian.

Mỗi lần Claude mắc lỗi, bạn refine system. Sau nhiều tháng, file trở thành:

  • Institutional memory của team
  • Workflow documentation
  • Architecture guidance
  • Error prevention layer
  • Operational context

Đó là lúc Claude bắt đầu cảm thấy "thông minh hơn hẳn" - không phải vì model thay đổi, mà vì system của bạn đã tiến hóa.

Phần lớn developer vẫn đang cố "prompt tốt hơn". Trong khi đó advanced users đang: engineering context, refining workflows, reducing ambiguity, building reusable systems, designing operational environments. Prompting là tạm thời. Systems compound.

Bắt đầu như thế nào

Đừng bắt đầu bằng một template khổng lồ. Bắt đầu từ mức tối thiểu - 20 dòng: project description và key commands. Sau đó dùng Claude Code thực tế. Khi Claude mắc một lỗi lặp đi lặp lại, thêm 1 targeted instruction để fix. Commit thay đổi đó vào git để trace được sau này.

Cứ mỗi vài tuần, review và prune: xóa rule redundant, xóa workaround cho behavior model cũ đã được fix. CLAUDE.md nên shrink qua các phiên bản model, không grow mãi.

Chạy /init trong terminal để generate starter file dựa trên project structure hiện tại - đó là điểm xuất phát tốt, rồi xóa bớt những gì Claude đã biết không cần nhắc.

via Claude Code Best Practices | Using CLAUDE.md Files - Anthropic | How to Write a Good CLAUDE.md - Builder.io