CLAUDE.md không phải tài liệu — đó là bộ luật sống của agent trên hệ thống bạn

TL;DR

CLAUDE.md không phải chỗ để giải thích cấu trúc dự án cho agent hiểu. Đó là bộ luật định nghĩa agent được làm gì và không được làm gì trên hệ thống của bạn — một forcing function sống trong context, không phải một tài liệu bị bỏ quên. Viết sai nó, bạn vẫn phải nhắc lại mỗi session. Viết đúng, nó tự vận hành.

Bạn đã từng thêm một dòng vào prompt: "Đừng sửa gì ngoài file tôi chỉ định."

Lần sau, agent vẫn sửa file khác.

Bạn thêm lại. Lần sau nó lại sửa. Bạn bắt đầu để dòng đó ở đầu mỗi prompt. Rồi bạn tự hỏi: sao phải nhắc mãi một thứ không thay đổi?

Câu trả lời là bạn đang nhét một quy tắc vào chỗ sai. Prompt nhắc nhở bị agent coi là ngữ cảnh của task đó, không phải nguyên tắc hoạt động. Nó có thể lãng quên giữa session. CLAUDE.md thì không — nó được load vào system context và đứng đó xuyên suốt.

Nhưng chỉ khi bạn viết nó đúng.

01Hai kiểu CLAUDE.md — và tại sao một kiểu không hoạt động

✕ CLAUDE.md như README

Mô tả cấu trúc thư mục, stack, mục đích project

▼

Agent đọc → hiểu ngữ cảnh → vẫn tự ra quyết định không kiểm soát được

▼

Bạn vẫn nhắc nhở lặp lại những gì đáng lẽ không cần nhắc

✓ CLAUDE.md như forcing function

Định nghĩa rõ được và không được — điều kiện, ngoại lệ, khi nào dừng hỏi bạn

▼

Agent không cần suy đoán → hành vi dự đoán được và nhất quán xuyên session

▼

Bạn chỉ sửa CLAUDE.md khi quy tắc thật sự thay đổi, không phải mỗi lần nhắc

Cùng một file, hai vai trò hoàn toàn khác nhau. Phần lớn CLAUDE.md hiện tại của mọi người trông giống cột trái hơn cột phải — đủ để agent hiểu context, nhưng không đủ để định hình hành vi.

Sự khác biệt không phải ở độ dài hay chi tiết. Là ở loại thông tin. README giải thích cấu trúc hiện tại. Forcing function đặt ra quy tắc cho tương lai.

Câu hỏi để phân biệt: "Nếu tôi bỏ dòng này, agent có làm gì khác không?" Nếu không — đó là mô tả, không phải quy tắc. Và mô tả không thay đổi hành vi.

02Ba thứ phải có để CLAUDE.md thực sự vận hành

Không phải tất cả mọi thứ đều cần ghi. Ba loại sau là xương sống:

Quy tắc hành vi cứng — "never" và "always"

Những thứ không có ngoại lệ: "Never edit files outside the directory I specify." / "Always ask before deleting anything." / "If unsure about scope, stop and ask — do not guess." Câu này phải là câu lệnh, không phải câu gợi ý. "Bạn nên hỏi khi…" yếu hơn "Stop and ask when…" rất nhiều.

Điều kiện rõ ràng cho việc dừng lại hỏi

Agent thường hoặc hỏi quá nhiều (mỗi bước đều confirm) hoặc không hỏi gì (đến khi sai rồi mới biết). Định nghĩa rõ điều kiện kích hoạt: "If the change touches shared config or anything outside the current module — stop and ask first."

Chuẩn output bạn cần — format, độ chi tiết, ngôn ngữ

Nếu bạn muốn nó báo cáo theo format nhất định, viết commit message theo convention cụ thể, hay giữ nguyên một ngôn ngữ — định nghĩa một lần ở đây. Mỗi lần bạn phải nhắc lại format là một lần bạn lẽ ra không cần nhắc.

Ngữ cảnh về vùng nguy hiểm trong hệ thống

"Thư mục infra/prod/ — chỉ đọc, không ghi." / "File config.json là source of truth — không tự sửa." / "Service A và B share state — thay đổi một sẽ ảnh hưởng kia." Agent không biết lịch sử hệ thống của bạn. Bạn phải nói với nó những chỗ nào đặc biệt nguy hiểm.

Bốn mảnh này là đủ cho một CLAUDE.md hoạt động được. Không phải đủ dài, không phải đủ chi tiết — đủ loại. Thêm vào khi bạn phát hiện pattern mới cần tốt nhất hóa, không phải viết đầy đủ từ đầu.

03Dấu hiệu setup đang cản bạn thay vì giúp bạn

Setup đang làm vậy với bạn

Bạn copy-paste một đoạn chỉ dẫn vào đầu mỗi sessionnếu thứ đó không thay đổi theo task, nó thuộc về CLAUDE.md — không phải prompt

Agent hỏi những câu bạn đã trả lời nhiều lần trướcthông tin bất biến — ngôn ngữ, convention, ai cần notify — phải ở context file, không ở prompt

Cùng một lỗi, khác session, khác tasknếu agent cứ lặp một pattern sai bạn không muốn, đó là tín hiệu cần thêm một quy tắc vào CLAUDE.md, không phải sửa lại prompt lần nữa

Bạn không nhớ CLAUDE.md của mình nói gìquá dài, quá mô tả, không có quy tắc hành động — đọc lại và hỏi: "dòng này thay đổi hành vi gì?"

Mỗi dấu hiệu trên là một rò rỉ năng lượng mà bạn đang bỏ qua — vì nó xảy ra từng chút một và không có gì gọi tên nó.

04CLAUDE.md như culture document của một người

Cách nhìn hữu ích nhất với CLAUDE.md không phải là nhìn nó như configuration file. Mà là nhìn nó như một bộ nguyên tắc làm việc — kiểu như onboarding document bạn sẽ đưa cho một đồng nghiệp mới trước khi giao việc đầu tiên.

Đồng nghiệp mới cần biết những gì bạn không nói là hiển nhiên — vì với người ngoài, không có gì hiển nhiên cả. Họ cần biết vùng nào dễ vỡ. Họ cần biết khi nào dừng lại hỏi thay vì tự quyết. Và họ cần biết format bạn muốn khi họ báo cáo lại.

Bạn có thể nói mọi thứ đó mỗi lần giao task — hoặc bạn có thể viết nó một lần, đúng chỗ, và không phải nói lại. CLAUDE.md là cái một lần đó.

Khác biệt duy nhất với đồng nghiệp thật: agent đọc CLAUDE.md mỗi session và nó nhất quán y hệt lần đầu. Đồng nghiệp thật có thể quên. Agent thì không — nhưng chỉ khi bạn đã viết đúng thứ cần nhớ vào đó.