CLAUDE.md 220 nghìn sao: bài học thật là chuẩn hoá cách agent được phép sửa code

Một bài đang lên trong r/ClaudeCode nhắc lại một điều khá đáng chú ý: file CLAUDE.md nhỏ, nếu viết đúng, có thể tạo khác biệt lớn hơn cả việc đổi sang model mới hơn.

Câu chuyện được cộng đồng bàn nhiều là một CLAUDE.md lấy cảm hứng từ các failure mode mà Andrej Karpathy từng nêu: AI coding agent hay tự đoán ý, làm quá tay, sửa code không liên quan, và tỏ ra chắc chắn khi thật ra đang thiếu thông tin. Bài đăng cho rằng chỉ vài nguyên tắc rõ ràng trong file khởi động phiên làm việc đã đủ giúp Claude Code bớt “đi lạc”.

Điểm đáng chú ý không nằm ở con số sao GitHub, mà ở hướng dịch chuyển: anh em đang dần coi prompt vận hành như một phần của engineering system, không còn là vài dòng nhắc nhở tuỳ hứng.

Vì sao CLAUDE.md lại có tác dụng

Claude Code thường bắt đầu mỗi phiên trong trạng thái thiếu ngữ cảnh. Nó có thể đọc repo, nhưng không tự biết đầy đủ:

• quyết định kiến trúc nào đã được chốt;
• cách tiếp cận nào đã bị loại bỏ;
• phần nào của codebase không được đụng vào;
• mức độ “làm tối thiểu” mà team mong muốn;
• khi nào nên hỏi lại thay vì tự suy diễn.

Nếu không có rào chắn, agent rất dễ làm điều mà người dùng không hề muốn: refactor thêm, đổi abstraction, sửa test phụ, hoặc “giúp” bằng cách mở rộng phạm vi task. Với project nhỏ thì có thể chỉ hơi phiền. Với project thật, đặc biệt có pipeline phức tạp, chi phí review và rollback sẽ tăng rất nhanh.

Một CLAUDE.md tốt đóng vai trò như checklist vận hành đầu phiên: không thay thế hiểu biết của developer, nhưng ép agent phải đi theo vài quy tắc tối thiểu trước khi viết code.

Bốn nguyên tắc nên có trong file khởi động

Từ bài thảo luận, mình thấy bốn nguyên tắc này đáng để anh em đưa vào workflow:

1. Hỏi khi chưa rõ, đừng tự đoán
   
   Nếu yêu cầu, kiến trúc hoặc mục tiêu chưa đủ rõ, agent phải hỏi trước khi sửa code.

2. Giải pháp đơn giản trước
   
   Ưu tiên thay đổi nhỏ nhất chạy được. Không tự tạo abstraction, framework, helper hoặc pattern mới nếu task không cần.

3. Không đụng phần ngoài phạm vi
   
   File nào không liên quan trực tiếp thì để nguyên. Đây là nguyên tắc rất quan trọng để giảm diff nhiễu.

4. Nói rõ khi thiếu chắc chắn
   
   Nếu agent không tự tin, nó phải nêu ra điểm chưa chắc thay vì tiếp tục với giọng khẳng định.

Điểm hay là các rule này không quá “prompt engineering”. Nó giống quy định làm việc trong team hơn: rõ phạm vi, rõ mức can thiệp, rõ cách xử lý khi thiếu thông tin.

Bài học vận hành cho team dùng AI coding

Nếu team đang dùng Claude Code thường xuyên, mình nghĩ CLAUDE.md nên được quản lý như tài liệu kỹ thuật sống, không phải một file prompt bị bỏ quên.

Một cách làm thực tế:

• bắt đầu với file ngắn, dưới 100 dòng;
• chia thành rule bắt buộc và preference mềm;
• thêm phần “không được làm” cụ thể theo repo;
• sau mỗi incident, bổ sung một rule ngắn thay vì viết lại cả file;
• định kỳ xoá rule cũ không còn đúng;
• yêu cầu agent tóm tắt phạm vi trước khi sửa task rủi ro cao.

Ví dụ, với repo production, mình sẽ thêm các dòng kiểu:

- Before editing, state the exact files you plan to modify.
- Do not change public APIs unless the task explicitly asks for it.
- Prefer small diffs and preserve existing style.
- If tests fail for reasons outside the current task, report them instead of fixing unrelated code.

Những rule này không làm agent thông minh hơn, nhưng làm hành vi của nó đoán được hơn. Với AI coding, tính “đoán được” thường quan trọng ngang tốc độ.

Đừng biến CLAUDE.md thành bãi rác ngữ cảnh

Một rủi ro khác là anh em nhồi mọi thứ vào CLAUDE.md: kiến trúc, roadmap, bug cũ, quy ước, todo, ghi chú họp. File càng dài, khả năng rule quan trọng bị loãng càng cao.

Mình sẽ tách như sau:

• CLAUDE.md: nguyên tắc làm việc, guardrail, style code;
• docs/architecture.md: quyết định kiến trúc dài hạn;
• docs/decisions/: ADR hoặc ghi chú quyết định;
• issue/task hiện tại: yêu cầu cụ thể của lần làm việc.

Nói cách khác, CLAUDE.md không nên là trí nhớ duy nhất của project. Nó nên là “luật giao thông” để agent biết cách di chuyển qua codebase.

Kết luận

Tin đáng chú ý ở đây không phải là một file prompt đạt nhiều sao, mà là cộng đồng Claude Code đang hội tụ quanh một thực hành rất engineering: chuẩn hoá cách agent được phép hành động.

Nếu anh em từng bị Claude sửa lan, đoán sai intent, hoặc tự tin làm điều chưa được hỏi, đừng vội đổi model trước. Hãy kiểm tra lại file khởi động phiên làm việc. Một bộ rule ngắn, rõ, dễ bảo trì có thể giảm rất nhiều chi phí vận hành hàng ngày.