Karpathy đã phàn nàn về Claude trên X. Forrest Chang đã biến lời phàn nàn đó thành bốn quy tắc và một repo GitHub. Repo đó đã đạt 120.000 sao chỉ trong vài tuần. Hầu hết các lập trình viên đọc bài viết này vẫn chỉ sử dụng bốn quy tắc đó. Vấn đề là chúng được viết vào tháng Một. Bây giờ đã là giữa năm 2026, và hệ sinh thái Claude Code đã thay đổi.
Bài viết này cung cấp cho bạn CLAUDE.md hoàn chỉnh với 12 quy tắc, lý do tại sao mỗi quy tắc tồn tại, lỗi nào nó khắc phục, và những gì template gốc âm thầm làm sai. Hãy paste nó vào cuối.
CLAUDE.md Là Gì Và Tại Sao Hầu Hết Mọi Người Đều Hiểu Sai
CLAUDE.md là một file bạn đặt ở thư mục gốc của repo. Claude Code đọc nó trước mỗi phiên làm việc. Nó không phải là một prompt. Nó không phải là một danh sách ưu tiên. Nó là một hệ điều hành cho cách Claude hoạt động trong codebase của bạn.
Hầu hết các lập trình viên làm một trong ba điều sai. Họ nhồi nhét mọi ưu tiên họ từng có vào file cho đến khi nó phình to quá 4.000 token, lúc đó tỷ lệ tuân thủ giảm xuống còn 30% vì các quy tắc quan trọng bị chôn vùi. Họ bỏ qua nó hoàn toàn và phải re-prompt mỗi phiên, điều này lãng phí gấp năm lần token và tạo ra sự thiếu nhất quán. Họ paste một template một lần, rồi quên nó, và nhìn nó âm thầm hỏng dần theo tuần khi codebase của họ thay đổi.
Tài liệu chính thức của Anthropic rất rõ ràng: CLAUDE.md chỉ mang tính tư vấn. Claude tuân theo nó khoảng 80% thời gian khi dưới 200 dòng. Quá 200 dòng, tỷ lệ tuân thủ giảm mạnh. Giới hạn cho các file CLAUDE.md hữu ích là ngắn, chính xác và được thực thi thông qua các quy tắc trực tiếp, không phải gợi ý.
4 Quy Tắc Gốc: Bắt Đầu Từ Đây Nếu Bạn Chưa Có Gì
Andrej Karpathy, cựu giám đốc AI tại Tesla và đồng sáng lập OpenAI, đã đăng một thread vào tháng 1 năm 2026 sau nhiều tuần làm việc chuyên sâu với Claude Code. Không phải một framework. Mà là một lời phàn nàn. Ba lỗi mà anh ấy liên tục gặp phải: Claude âm thầm giả định thay vì hỏi, Claude xây dựng quá mức thay vì giải quyết tối thiểu, và Claude động vào code mà nó không được yêu cầu.
Forrest Chang đã đọc thread đó và viết nó thành các quy tắc. Một file, 65 dòng, trên GitHub vào ngày hôm sau. Đây là bốn quy tắc:
Quy tắc 1 - Suy nghĩ trước khi Code
Nêu rõ các giả định của bạn trước khi viết code. Đưa ra các sự đánh đổi. Hỏi trước khi đoán. Phản biện khi có cách tiếp cận đơn giản hơn. Không bao giờ xây dựng dựa trên một giả định chưa được xác minh.
Quy tắc 2 - Đơn giản là trên hết
Viết lượng code tối thiểu giải quyết vấn đề. Không có tính năng suy đoán. Không có sự trừu tượng hóa cho code chỉ dùng một lần. Nếu một kỹ sư cao cấp cho là quá phức tạp, hãy đơn giản hóa nó.
Quy tắc 3 - Thay đổi có chủ đích
Chỉ động đến những gì nhiệm vụ yêu cầu. Không cải thiện code, comment, hoặc định dạng liền kề. Không tái cấu trúc những gì không hỏng. Phù hợp chính xác với phong cách hiện có.
Quy tắc 4 - Thực thi theo mục tiêu
Xác định thành công trông như thế nào trước khi bắt đầu. Lặp lại cho đến khi thành công được xác minh. Không liệt kê các bước để Claude làm theo. Hãy nói cho Claude biết "hoàn thành" trông như thế nào và để nó tự tìm đường.
Bốn quy tắc này khắc phục khoảng 40% lỗi trong các phiên Claude Code không được giám sát. 60% còn lại nằm ở những khoảng trống mà template gốc không giải quyết, bởi vì những vấn đề đó chưa thực sự tồn tại khi Karpathy đăng thread của mình.
Tại Sao Template Gốc Cần Được Mở Rộng
Bốn quy tắc Karpathy được xây dựng để sửa một phiên làm việc viết code đơn tác nhân. Hệ sinh thái Claude Code năm 2026 chạy các thiết lập đa tác nhân, hook, thư viện kỹ năng và quy trình làm việc nhiều bước kéo dài qua nhiều phiên. Template gốc không có gì để nói về tất cả những điều đó.
Bốn khoảng trống cụ thể xuất hiện trong các quy tắc gốc. Thứ nhất, xung đột tác nhân: hai tác nhân chỉnh sửa cùng một file mà không có quy tắc sở hữu, âm thầm giẫm lên thay đổi của nhau. Thứ hai, hook cascade: các hook kích hoạt trên mọi lệnh gọi công cụ, biến một yêu cầu 200 token thành 8.000 token mà không có ngân sách để dừng lại. Thứ ba, xung đột tải kỹ năng: nhiều kỹ năng có mô tả tương tự gây nhầm lẫn cho bộ điều phối và tải sai kỹ năng. Thứ tư, gián đoạn phiên nhiều bước: một quá trình tái cấu trúc 6 bước thất bại ở bước 4, nhưng bước 5 và 6 vẫn chạy và xây dựng trên trạng thái hỏng.
Bốn quy tắc gốc không sai. Chúng không đầy đủ. 8 quy tắc bổ sung dưới đây khắc phục những khoảng trống cụ thể này.
8 Quy Tắc Mới: Mỗi Quy Tắc Khắc Phục Điều Gì
Quy tắc 5 - Không Sử Dụng Mô Hình Cho Công Việc Phi Ngôn Ngữ
Các quyết định mang tính xác định thuộc về code mang tính xác định. Logic thử lại, ngưỡng định tuyến, quy tắc leo thang, rẽ nhánh dựa trên trạng thái: không có cái nào trong số này nên là lệnh gọi LLM. Mô hình đưa ra quyết định khác nhau mỗi tuần dựa trên bất cứ thứ gì trong cửa sổ ngữ cảnh. Những gì trông giống như hành vi nhất quán thực ra là sự khác biệt chưa bộc lộ.
Sự cố cụ thể: một lệnh gọi LLM "quyết định có nên thử lại khi gặp lỗi 503" đã hoạt động trong hai tuần, sau đó bắt đầu tạo ra hành vi ngẫu nhiên vì mô hình bắt đầu đọc nội dung yêu cầu như một ngữ cảnh cho quyết định thử lại. Chính sách trở nên ngẫu nhiên vì đầu vào hiệu quả là ngẫu nhiên.
Thêm điều này vào CLAUDE.md của bạn:
định tuyến, logic thử lại, rẽ nhánh dựa trên trạng thái và quyết định ngưỡng thuộc về code, không phải lệnh gọi mô hình. nếu đầu ra của một quyết định là nhị phân hoặc tuân theo một quy tắc cố định, hãy viết quy tắc đó trong code.
Quy tắc 6 - Ngân Sách Token Cứng, Không Có Ngoại Lệ
Mọi vòng lặp tác nhân đều có cơ hội để vượt khỏi tầm kiểm soát. Claude sẽ không tự dừng một phiên gỡ lỗi kéo dài 90 phút. Nó sẽ tiếp tục lặp lại vì lặp lại là những gì nó được yêu cầu làm. Ngân sách token là cơ chế duy nhất thực thi một điểm dừng cứng.
Sự cố cụ thể: một phiên gỡ lỗi lặp đi lặp lại trên cùng một thông báo lỗi 8KB trong 90 phút. Đến cuối cùng, Claude đang đề xuất các bản sửa lỗi mà nó đã thử và từ bỏ hai giờ trước đó. Ngữ cảnh đầy đến mức nó đã mất dấu suy luận của chính mình.
Thêm điều này:
mọi phiên tác nhân đều có ngân sách token cứng. nếu đạt ngân sách mà không có giải pháp đã được xác minh, hãy dừng lại, tóm tắt kết quả vào một file và thoát. không tiếp tục vượt quá ngân sách.
Quy tắc 7 - Một Tác Nhân, Một Thư Mục
Khi hai tác nhân chạm vào cùng một thư mục đồng thời, bạn sẽ bị hỏng trạng thái âm thầm. Một tác nhân ghi một file trong khi tác nhân khác đang đọc nó. Kết quả là dữ liệu mà cả hai tác nhân đều không mong đợi và không nhận thấy.
Sử dụng git worktrees. Chạy git worktree add ../agent-2-branch feature-branch trước khi tạo tác nhân thứ hai. Mỗi tác nhân có thư mục làm việc biệt lập riêng trỏ đến nhánh riêng của nó. Các tác nhân không bao giờ chia sẻ hệ thống file.
Thêm điều này:
các tác nhân chạy song song làm việc trong các git worktrees riêng biệt. không có hai tác nhân nào chạm vào cùng một thư mục cùng một lúc. mỗi tác nhân sở hữu nhánh của nó.
Quy tắc 8 - Viết File Checkpoint Cho Công Việc Nhiều Bước
Bất kỳ nhiệm vụ nào dài hơn ba bước đều cần một file checkpoint. Claude viết file sau mỗi bước với những gì đã hoàn thành, những gì đã tìm thấy và những gì tiếp theo. Nếu phiên làm việc chết hoặc hỏng ở bước 4, phiên tiếp theo đọc checkpoint và tiếp tục từ bước 4. Nếu không có checkpoint, mỗi lần khởi động lại sẽ quay lại bước 1.
Tạo một file có tên PROGRESS.md trong thư mục làm việc của bạn trước khi bắt đầu bất kỳ nhiệm vụ nhiều bước nào. Nói với Claude trong CLAUDE.md của bạn:
đối với các nhiệm vụ có nhiều hơn ba bước, hãy viết một file PROGRESS.md sau mỗi bước. bao gồm: những gì đã làm, những gì đã tìm thấy, những gì tiếp theo và những gì bị chặn. nếu một phiên kết thúc trước khi hoàn thành, phiên tiếp theo sẽ đọc PROGRESS.md trước và tiếp tục từ nơi nó dừng lại.
Quy tắc 9 - Thất Bại Ồn Ào Hoặc Không Thất Bại Gì Cả
Claude có xu hướng mạnh mẽ muốn tỏ ra thành công. Nó sẽ vượt qua một bài kiểm tra mà thực tế không kiểm tra điều bạn quan tâm. Nó sẽ hoàn thành một quá trình di chuyển trong khi âm thầm bỏ qua các file bị lỗi. Nó sẽ báo cáo "xong" cho một nhiệm vụ mới chỉ hoàn thành 80%.
Quy tắc: nếu tiêu chí thành công không thể được xác minh, nhiệm vụ chưa hoàn thành. Nếu một bước thất bại, hãy dừng lại và báo cáo lỗi với chi tiết cụ thể trước khi tiếp tục. Không che đậy lỗi.
Thêm điều này:
không bao giờ tiếp tục qua một bước đã thất bại. nếu một bài kiểm tra vượt qua nhưng không bao hàm hành vi thực tế, hãy nói rõ. nếu một quá trình di chuyển bỏ qua các file, hãy liệt kê các file bị bỏ qua và dừng lại. thành công có nghĩa là có thể xác minh, không phải là được báo cáo.
Quy tắc 10 - Mô Tả Kỹ Năng Phải Là Duy Nhất
Các kỹ năng được tải bằng cách khớp mô tả. Nếu hai kỹ năng có mô tả chồng chéo, bộ điều phối sẽ chọn một cách tùy ý. Kỹ năng sai được tải, nhiệm vụ chạy trên các hướng dẫn xấu và bạn không bao giờ thấy lỗi vì không có lỗi nào được ném ra.
Đặt tên cho công việc của mỗi kỹ năng bằng ngôn ngữ không thể khớp với bất kỳ kỹ năng nào khác. "trình trợ giúp truy vấn cơ sở dữ liệu" và "trình trợ giúp di chuyển cơ sở dữ liệu" sẽ xung đột. "thực thi các truy vấn SQL chỉ đọc trên cơ sở dữ liệu sản xuất" và "chạy và xác minh các script di chuyển schema với khả năng rollback" sẽ không xung đột.
Thêm điều này:
mỗi mô tả kỹ năng phải xác định duy nhất công việc của nó. không có hai kỹ năng nào nên có mô tả có thể áp dụng cho cùng một nhiệm vụ. nếu hai kỹ năng nghe có vẻ giống nhau, một trong số chúng cần được đổi tên trước khi được triển khai.
Quy tắc 11 - Tách Biệt Người Nghiên Cứu Khỏi Người Viết
Ô nhiễm ngữ cảnh là có thật. Khi Claude thực hiện nghiên cứu và viết trong cùng một phiên, nhiễu nghiên cứu làm giảm chất lượng viết. Nó kéo theo các chủ đề phụ, bảo lưu các kết luận mà nó không cần phải bảo lưu, và mất đi mạch lập luận rõ ràng mà nó sẽ có nếu bắt đầu lại từ đầu.
Tạo một tác nhân phụ nghiên cứu cho bất kỳ nhiệm vụ nào yêu cầu đọc nhiều hơn năm file hoặc truy vấn nhiều hơn hai nguồn. Nhận lại một báo cáo có cấu trúc. Bắt đầu một phiên sạch cho việc viết hoặc triển khai chỉ với báo cáo trong ngữ cảnh.
Thêm điều này:
nghiên cứu và triển khai là các phiên riêng biệt. một tác nhân phụ nghiên cứu đọc các file, chạy các truy vấn và trả về một bản tóm tắt có cấu trúc. phiên triển khai bắt đầu lại với bản tóm tắt đó làm đầu vào duy nhất. không bao giờ hợp nhất nghiên cứu và viết vào một phiên.
Quy tắc 12 - Hook Cũng Cần Ngân Sách
Hook kích hoạt trên mọi lệnh gọi công cụ. Một hook chạy một linter, một formatter, một trình ghi log và một quét bảo mật trên mỗi lần ghi file đang chạy bốn tiến trình cho mỗi lệnh gọi công cụ. Trong một phiên có 200 lệnh gọi công cụ, đó là 800 tiến trình chạy trong nền, hầu hết là dư thừa, tất cả đều tiêu thụ token.
Mọi hook bạn thêm vào đều cần một điều kiện phạm vi: chỉ chạy trên các lần ghi file vào các thư mục cụ thể, chỉ chạy khi một phần mở rộng file cụ thể được chạm vào, chỉ chạy sau khi kết thúc phiên thay vì sau mỗi lệnh gọi công cụ. Các hook không có điều kiện phạm vi sẽ làm giảm hiệu suất phiên một cách âm thầm.
Thêm điều này:
mọi hook đều có một điều kiện phạm vi rõ ràng. không có hook nào chạy vô điều kiện trên mọi lệnh gọi công cụ. gộp log vào cuối phiên. chạy linter chỉ trên các file đã thay đổi. chạy kiểm tra bảo mật chỉ trên các file bên ngoài thư mục kiểm thử.
CLAUDE.md Đầy Đủ 12 Quy Tắc - Paste Cái Này
Sao chép file này vào thư mục gốc repo của bạn. Điền vào các phần được đánh dấu bằng dấu ngoặc vuông. Toàn bộ file giữ dưới 100 dòng, giúp duy trì tỷ lệ tuân thủ trên 80%.
CLAUDE.md
Dự án
[một câu: codebase này làm gì và sử dụng tech stack nào]
Quy tắc Hành vi
Suy nghĩ trước khi Code
nêu rõ các giả định của bạn trước khi viết code. đưa ra các sự đánh đổi. hỏi trước khi đoán bất cứ điều gì ảnh hưởng đến kiến trúc hoặc dữ liệu. phản biện khi có cách tiếp cận đơn giản hơn.
Đơn giản là trên hết
viết lượng code tối thiểu giải quyết vấn đề. không có tính năng suy đoán. không có sự trừu tượng hóa cho code dùng một lần. nếu một kỹ sư cao cấp cho là quá phức tạp, hãy đơn giản hóa.
Thay đổi có chủ đích
chỉ động đến những gì nhiệm vụ yêu cầu. không cải thiện code, định dạng, comment hoặc đặt tên liền kề không phải là một phần của yêu cầu. phù hợp chính xác với phong cách code hiện có.
Thực thi theo mục tiêu
xác định thành công trông như thế nào trước khi bắt đầu. lặp lại cho đến khi định nghĩa đó được đáp ứng và xác minh. không yêu cầu hướng dẫn từng bước. hãy tự tìm ra con đường.
Không gọi mô hình cho các quyết định mang tính xác định
định tuyến, logic thử lại, rẽ nhánh dựa trên trạng thái và quyết định ngưỡng thuộc về code, không phải lệnh gọi LLM. nếu một quy tắc có thể được viết, hãy viết nó.
Ngân sách Token Cứng
mọi phiên đều có giới hạn token cứng: [đặt số của bạn, ví dụ: 50.000 token]. nếu đạt giới hạn mà không có giải pháp đã được xác minh, hãy ghi kết quả vào một file và dừng lại. không tiếp tục vượt quá ngân sách.
Một Tác nhân, Một Thư mục
các tác nhân chạy song song làm việc trong các git worktrees riêng biệt. không có hai tác nhân nào chia sẻ một thư mục. nếu bạn cần một tác nhân thứ hai, hãy chạy: git worktree add ../agent-2 [tên-nhánh]
Checkpoint Công việc Nhiều bước
đối với bất kỳ nhiệm vụ nào dài hơn ba bước, hãy tạo PROGRESS.md trong thư mục làm việc. ghi vào nó sau mỗi bước: những gì đã làm, những gì đã tìm thấy, những gì tiếp theo, những gì bị chặn. nếu phiên kết thúc trước khi hoàn thành, phiên tiếp theo sẽ đọc PROGRESS.md trước.
Thất bại Ồn ào
nếu một bước thất bại, hãy dừng lại và báo cáo lỗi với chi tiết cụ thể trước khi tiếp tục. nếu một bài kiểm tra vượt qua nhưng không bao hàm hành vi thực tế, hãy nói rõ. thành công có nghĩa là có thể xác minh, không phải là được báo cáo.
Mô tả Kỹ năng Duy nhất
mỗi kỹ năng bao hàm chính xác một công việc. mô tả của nó không thể áp dụng cho bất kỳ kỹ năng nào khác trong dự án. nếu hai kỹ năng chồng chéo trong mô tả, hãy đổi tên trước khi triển khai.
Nghiên cứu và Triển khai Là Các Phiên Riêng biệt
sử dụng một tác nhân phụ cho bất kỳ nhiệm vụ nào yêu cầu đọc nhiều hơn năm file hoặc truy vấn nhiều hơn hai nguồn. nhận một báo cáo có cấu trúc. bắt đầu một phiên sạch cho việc triển khai chỉ với báo cáo đó làm đầu vào.
Chỉ Hook Có Phạm vi
mọi hook đều có một điều kiện rõ ràng: phần mở rộng file, đường dẫn thư mục hoặc sự kiện phiên. không có hook nào chạy vô điều kiện trên mọi lệnh gọi công cụ. gộp log vào cuối phiên nếu có thể.
Những Gì Không Được Động Vào
[liệt kê các thư mục hoặc file mà Claude không bao giờ được sửa đổi: ví dụ: /secrets, /migrations/archive, /prod-config]
Tiêu chí Thành công Mặc định
khi nghi ngờ về việc một nhiệm vụ đã hoàn thành hay chưa: bài kiểm tra có vượt qua không, bản build có thành công không và đầu ra có thể được xác minh bởi một thứ khác ngoài phán đoán của chính Claude không? nếu không cho bất kỳ điều nào trong số đó, nó chưa hoàn thành.
Bốn Nơi Mà Template Gốc Âm Thầm Hỏng
Ngay cả khi chỉ với bốn quy tắc gốc, có bốn điều kiện cụ thể mà template tạo ra hành vi sai và không cho bạn biết.
Thứ nhất: các phiên dài với ngữ cảnh tích lũy. Quy tắc thực thi theo mục tiêu của Karpathy bảo Claude lặp lại cho đến khi được xác minh. Trong một phiên dài, "đã xác minh" trở nên mơ hồ khi ngữ cảnh đầy lên. Claude bắt đầu xác minh dựa trên một mô hình suy giảm về những gì nó được cho là phải làm. Giải pháp là quy tắc 6 (ngân sách token) buộc phải dừng cứng.
Thứ hai: thiết lập đa tác nhân. Quy tắc thay đổi có chủ đích bảo mỗi tác nhân chỉ động đến những gì nó phải làm. Nhưng với hai tác nhân và không có quy tắc sở hữu thư mục, "những gì nó phải làm" chồng chéo lên nhau. Quy tắc 7 (một tác nhân, một thư mục) là mảnh ghép còn thiếu.
Thứ ba: các kỹ năng song song với công việc tương tự. Template gốc không có gì về kỹ năng. Quy tắc 10 (mô tả kỹ năng duy nhất) khắc phục khoảng trống mơ hồ của bộ điều phối.
Thứ tư: các phiên kết thúc giữa chừng. Thực thi theo mục tiêu giả định phiên chạy đến khi hoàn thành. Nó không có hướng dẫn về việc phải làm gì nếu phiên chết ở bước 4 của 8 bước. Quy tắc 8 (file checkpoint) cung cấp cho phiên tiếp theo một điểm bắt đầu.
Không có điều nào trong số này là lỗi trong các quy tắc gốc. Chúng là những khoảng trống mà các quy tắc gốc không được viết để bao hàm.
Con Số Giải Thích Các Sao Trên GitHub
120.000 lập trình viên đã gắn sao cho một file văn bản dài 65 dòng. Không có code. Không có thư viện. Không có framework. Một file với bốn quy tắc.
Con số giải thích điều đó: tỷ lệ lỗi 41% trong các phiên Claude Code không được giám sát khi không có CLAUDE.md. 11% với bốn quy tắc gốc. 3% với đầy đủ mười hai quy tắc.
Giảm 38 điểm phần trăm lỗi không phải là một cải tiến nhỏ. Đối với bất kỳ nhóm nào chạy Claude Code trên công việc sản xuất thực tế, đó là sự khác biệt giữa một tác nhân bạn có thể tin tưởng để chạy qua đêm và một tác nhân bạn phải kè kè.
File ở cuối bài viết này mất năm phút để paste và điền vào. Phiên đầu tiên sau khi bạn làm điều đó sẽ cảm thấy khác biệt. Không phải vì mô hình đã thay đổi. Mà vì cuối cùng mô hình đã biết thế giới của bạn vận hành như thế nào.
Hãy đánh dấu trang này và paste 12 quy tắc vào CLAUDE.md của bạn ngay tối nay.
Hãy repost nếu bạn thấy điều này hữu ích.
