Bạn ngồi viết một CLAUDE.md thật chỉn chu cho agent của mình: quy ước đặt tên, cách xử lý lỗi, mấy chỗ nguy hiểm phải tránh. Agent của bạn nuốt nó, và từ đó làm việc đúng ý — gọn gàng, nhất quán.
Vấn đề lộ ra ở pull request của người bên cạnh. Code họ chạy được, nhưng theo một bộ quy ước khác hẳn. Không phải họ ẩu. Là con agent của họ chưa từng đọc một chữ nào trong cái file bạn viết — vì cái file đó nằm trên máy bạn, trong thư mục của bạn, trong tầm với của riêng agent bạn. Bạn viết luật cho cả nhà, nhưng treo nó trong phòng riêng.
01Bộ luật chỉ chạm được những agent đọc được nó
Đây là điều dễ quên khi bạn quen làm một mình: một bộ luật không có quyền lực gì ngoài cái nó được đọc. Nó không phải một thông báo phát ra toàn đội. Nó là một file — và file thì chỉ những agent với tới được mới nạp.
Khi chỉ có bạn, ranh giới đó vô hình, vì bạn là agent-reader duy nhất. File của bạn, máy của bạn, agent của bạn — một vòng khép kín hoàn hảo. Thêm người thứ hai, cái vòng đó vỡ ra mà bạn không thấy: giờ có hai file luật trên hai máy, và mỗi agent chỉ đọc file của chủ nó. Hai bộ luật, không cái nào biết cái nào tồn tại, cùng định hình một codebase. Kết quả y hệt như không có luật nào — chỉ khác là rối theo kiểu khó lần ra hơn.
Nên cú lật rất gọn: một bộ luật hay mà nằm sai chỗ thì thua một bộ luật tầm thường mà nằm đúng chỗ chung. Vị trí của cái file quan trọng ngang nội dung của nó.
✕ File luật trên máy từng người
✓ Một file luật trong chỗ chung
Khác biệt không nằm ở chữ trong file. Nằm ở chỗ file ngồi: trong thư mục riêng (chỉ agent bạn đọc) hay trong chỗ chung được commit (mọi agent kéo về đều nạp).
02Cái gì thuộc về bộ luật chung, cái gì để riêng
Không phải mọi thứ trong file luật cá nhân đều nên đẩy lên chung. Trộn lẫn sở thích riêng vào luật đội thì người khác thấy gò bó, mà luật đội lẫn vào sở thích thì loãng. Tách rõ ba thứ này thuộc về bộ luật chung:
Cách đặt tên, cấu trúc, xử lý lỗi cho phần mọi người cùng đụng. Đây là cốt lõi: nếu hai agent làm khác nhau ở đây, cái chung rạn. Phải nằm trong luật chung.
"Đừng đụng chỗ này", "luôn chạy thử trước khi triển khai" — mấy cái chốt an toàn cả đội cần biết. Một người học bằng cách vấp; cả đội nên học bằng một dòng trong luật chung.
Sở thích cá nhân — giọng văn khi chat, cách bạn thích agent tóm tắt — giữ trong file riêng của bạn. Đừng ép cả đội theo gu của một người; luật chung chỉ giữ cái phải-chung.
Đường phân chia gọn trong một câu hỏi: "nếu agent của người khác làm khác tôi ở chỗ này, cái chung có hỏng không?" Có → luật chung. Không → để riêng. Bộ luật chung nên mỏng và chỉ chứa cái thật sự phải đồng nhất.
03Bộ luật chung là code, nên đối xử như code
Một khi bộ luật đã nằm trong chỗ chung và định hình cái mọi agent làm, nó không còn là ghi chú cá nhân — nó là một phần của hệ thống, ngang với code. Mà cái gì là code thì có vòng đời của code: nó được review trước khi đổi, có lịch sử để truy, và đổi nó là một quyết định của đội chứ không phải một người lặng lẽ sửa.
Điều này nghe nặng nề nhưng thực ra giải phóng: khi bộ luật được review như code, một quy ước mới phải thuyết phục được cả đội trước khi áp cho mọi agent — nên nó ít khi sai bậy, và khi đã chốt thì ai cũng biết vì sao. Ngược lại, một file luật cá nhân đổi tùy hứng là một nguồn loạn âm thầm: agent của bạn đổi hành vi giữa chừng mà hai người kia không hay.
Đây cũng là chỗ ý tưởng CLAUDE.md là bộ luật sống, không phải README lớn thêm một bậc — từ bộ luật cho agent của bạn thành bộ luật cho agent cả đội. Và nếu chưa biết một bộ khung như vậy gồm gì, có sẵn một bộ khung CLAUDE.md để bắt đầu — kéo về, cắt phần riêng, commit phần chung. Bộ luật bạn viết hay tới đâu cũng chỉ đáng giá bằng số agent thật sự đọc được nó — nên việc đầu tiên không phải viết cho hay, mà là đặt nó vào đúng cái chỗ mọi agent cùng nhìn thấy.