Biên tập viên: Vào tháng 1 năm 2026, những lời phàn nàn của Andrej Karpathy về việc Claude viết mã đã làm nổi bật một tệp dường như nhỏ nhưng cực kỳ quan trọng trong quy trình lập trình AI: CLAUDE.md. Sau đó, Forrest Chang đã tổng hợp các vấn đề này thành 4 quy tắc hành vi nhằm hạn chế những lỗi phổ biến của Claude khi lập trình: giả định im lặng, thiết kế quá mức, làm tổn hại đến mã không liên quan và thiếu tiêu chuẩn thành công rõ ràng.

Nhưng vài tháng sau, các kịch bản sử dụng Claude Code đã không còn chỉ là “để mô hình viết một đoạn mã”. Khi các agent đa bước, hook kích hoạt chuỗi, tải kỹ năng và hợp tác giữa nhiều kho mã trở nên phổ biến, các mô hình thất bại mới也开始 xuất hiện: mô hình mất kiểm soát trong các nhiệm vụ dài, kiểm tra vượt qua nhưng không xác minh logic thực tế, di chuyển hoàn tất nhưng bỏ qua lỗi một cách im lặng, các phong cách mã khác nhau bị trộn lẫn sai cách.

Tác giả bài viết đã kiểm tra 30 kho mã trong vòng 6 tuần và bổ sung thêm 8 quy tắc dựa trên 4 quy tắc ban đầu của Karpathy, nhằm giải quyết các vấn đề mới phát sinh khi AI lập trình chuyển từ việc hoàn thành đơn lẻ sang hợp tác dưới dạng Agent.

Dưới đây là bản gốc:

Vào cuối tháng 1 năm 2026, Andrej Karpathy đã đăng một chuỗi tweet phàn nàn về cách Claude viết mã. Ông chỉ ra ba loại vấn đề điển hình: đưa ra giả định sai mà không giải thích, làm phức tạp hóa quá mức, và gây ra những tác động không liên quan đến mã mà vốn dĩ không nên thay đổi.

Forrest Chang đã xem chuỗi tweet này, tổng hợp các lời phàn nàn thành 4 quy tắc hành vi, ghi vào một tệp riêng biệt tên CLAUDE.md và đăng lên GitHub. Dự án này ngay ngày đầu tiên ra mắt đã nhận được 5.828 sao, trong vòng hai tuần được lưu lại 60.000 lần, hiện đã đạt 120.000 sao và trở thành kho mã nguồn một tệp tăng trưởng nhanh nhất năm 2026.

Sau đó, tôi đã thử nghiệm nó trên 30 kho mã trong vòng 6 tuần.

Bốn quy tắc này thực sự hiệu quả. Tỷ lệ lỗi từng xảy ra khoảng 40% trong quá khứ, nay đã giảm xuống dưới 3% trong các nhiệm vụ phù hợp để các quy tắc này phát huy tác dụng. Nhưng vấn đề là, mẫu này ban đầu được tạo ra để giải quyết các lỗi xảy ra khi Claude viết mã vào tháng Một.

Đến tháng 5 năm 2026, các vấn đề mà hệ sinh thái Claude Code đối mặt đã khác đi: xung đột giữa các Agent, kích hoạt chuỗi hook, xung đột tải skill, và gián đoạn luồng công việc đa bước xuyên phiên.

Vì vậy, tôi đã thêm 8 quy tắc nữa. Dưới đây là phiên bản đầy đủ 12 quy tắc của CLAUDE.md: Lý do từng quy tắc đáng để thêm vào và nơi bản gốc của mẫu Karpathy sẽ lặng lẽ không còn hiệu lực ở 4 vị trí.

Nếu bạn muốn bỏ qua phần giải thích và sao chép sử dụng ngay, tệp đầy đủ nằm ở cuối bài viết.

Tại sao điều này lại quan trọng

Tệp CLAUDE.md của Claude Code là tệp bị đánh giá thấp nhất trong toàn bộ hệ sinh thái lập trình AI. Hầu hết các nhà phát triển thường mắc ba lỗi sau:

Đầu tiên, hãy coi nó như một thùng rác ưa thích, nhét tất cả thói quen của bạn vào đó, đến khi nó phình to hơn 4.000 token và tỷ lệ tuân thủ quy tắc giảm xuống còn 30%.

Thứ hai, hoàn toàn không sử dụng, mỗi lần đều phải prompt lại. Điều này sẽ gây lãng phí 5 lần token và thiếu tính nhất quán giữa các phiên khác nhau.

Thứ ba, sao chép một mẫu rồi bỏ quên không quan tâm nữa. Nó có thể hoạt động trong hai tuần, nhưng khi kho mã thay đổi, nó sẽ ngừng hoạt động mà bạn không hề hay biết.

Tài liệu chính thức của Anthropic nêu rõ: CLAUDE.md về cơ bản chỉ mang tính chất gợi ý. Claude sẽ tuân theo nó khoảng 80% thời gian. Khi vượt quá 200 dòng, tỷ lệ tuân thủ sẽ giảm rõ rệt vì các quy tắc quan trọng sẽ bị chìm trong tiếng ồn.

Mẫu của Karpathy giải quyết vấn đề này: một tệp, 65 dòng, 4 quy tắc. Đây là mức cơ sở tối thiểu.

Nhưng giới hạn có thể còn cao hơn nữa. Sau khi thêm 8 quy tắc dưới đây, nó không chỉ bao quát các vấn đề về viết mã mà Karpathy đã phàn nàn vào tháng 1 năm 2026, mà còn bao gồm cả các vấn đề về sắp xếp Agent mới xuất hiện vào tháng 5 năm 2026—những vấn đề này chưa tồn tại khi mẫu ban đầu được tạo ra.

4 quy tắc ban đầu

Nếu bạn chưa xem kho của Forrest Chang, hãy xem phiên bản cơ bản này:

Quy tắc 1: Suy nghĩ trước khi mã hóa.

Đừng đưa ra giả định một cách im lặng. Hãy nêu rõ các giả định của bạn và phơi bày các điểm đánh đổi. Hãy đặt câu hỏi trước khi phỏng đoán. Khi có phương án đơn giản hơn, hãy chủ động phản đối.

Quy tắc 2: Ưu tiên sự đơn giản.
Sử dụng mã ít nhất có thể để giải quyết vấn đề. Không thêm các tính năng tưởng tượng. Không thiết kế lớp trừu tượng cho mã dùng một lần. Nếu một kỹ sư giàu kinh nghiệm cho rằng nó quá phức tạp, thì nên đơn giản hóa.

Quy tắc 3: Sửa đổi chính xác như phẫu thuật.
Chỉ sửa những phần bắt buộc phải sửa. Đừng tự ý “tối ưu” mã, chú thích hoặc định dạng liền kề. Đừng tái cấu trúc những thứ không có vấn đề. Giữ nguyên phong cách hiện có.

Quy tắc 4: Thực hiện có mục tiêu.
Xác định tiêu chí thành công trước, sau đó lặp lại cho đến khi hoàn tất xác minh. Đừng nói với Claude phải làm gì ở từng bước, mà hãy cho nó biết kết quả thành công nên như thế nào, để nó tự lặp lại.

Bốn quy tắc này có thể giải quyết khoảng 40% các mẫu thất bại mà tôi thấy trong các phiên Claude Code không có người giám sát. Khoảng 60% vấn đề còn lại nằm ẩn trong những khoảng trống dưới đây.

Tám quy tắc tôi thêm vào, cùng với lý do

Mỗi quy tắc đều xuất phát từ một khoảnh khắc thực tế: Bốn quy tắc ban đầu của Karpathy đã không còn đủ. Dưới đây, tôi sẽ mô tả bối cảnh trước, sau đó đưa ra quy tắc tương ứng.

Quy tắc của Karpathy không bao quát điểm này. Do đó, mô hình bắt đầu tự quyết định những vấn đề vốn nên được xử lý bởi mã xác định: có nên thử lại một lần gọi API hay không, cách định tuyến một tin nhắn, và khi nào nên nâng cấp xử lý. Kết quả là, các quyết định mỗi tuần đều khác nhau. Bạn nhận được một hệ thống if-else không ổn định, tính phí 0,003 USD mỗi token.

Thời điểm đó, có một đoạn mã gọi Claude để “xác định liệu có nên thử lại khi gặp lỗi 503 hay không”. Ban đầu nó hoạt động tốt, duy trì trong hai tuần, sau đó đột ngột trở nên không ổn định vì mô hình bắt đầu coi thân yêu cầu là bối cảnh để đưa ra quyết định. Chiến lược thử lại trở nên ngẫu nhiên vì prompt cũng ngẫu nhiên.

CLAUDE.md không có ràng buộc ngân sách giống như một tờ séc trống. Mỗi vòng lặp đều có thể mất kiểm soát, trở thành một lần trút đầy ngữ cảnh 50.000 token. Mô hình sẽ không tự dừng lại.

Thời điểm đó diễn ra như sau: một phiên gỡ lỗi kéo dài 90 phút. Mô hình liên tục lặp lại quanh cùng một đoạn thông báo lỗi 8KB và dần quên những giải pháp đã thử trước đó. Cuối cùng, nó bắt đầu đề xuất những phương án mà tôi đã từ chối cách đây 40 tin nhắn. Nếu có ngân sách token, quá trình này nên được dừng lại ở phút thứ 12.

Khi hai phần trong kho mã mâu thuẫn với nhau, Claude sẽ cố gắng chiều cả hai bên, dẫn đến việc tạo ra một đoạn mã không nhất quán.

Thời điểm đó, trong kho mã có hai mô hình xử lý lỗi: một là async/await kết hợp với try/catch rõ ràng, và một là biên giới lỗi toàn cục. Mã mới do Claude viết đã sử dụng cả hai. Kết quả là xử lý lỗi được thực hiện hai lần. Tôi đã mất 30 phút mới hiểu được tại sao lỗi lại bị bỏ qua hai lần.

Sự sửa đổi "kiểu phẫu thuật" của Karpathy đã nói với Claude không được thay đổi mã lân cận. Nhưng nó chưa từng nói với Claude: hãy hiểu trước mã lân cận. Nếu không có điều này, Claude sẽ viết mã mới xung đột với mã đã tồn tại cách đó 30 dòng.

Thời điểm đó xảy ra như sau: Claude đã thêm một hàm mới có chức năng hoàn toàn giống với hàm đã tồn tại, vì nó không đọc hàm gốc trước. Hai hàm này thực hiện cùng một việc. Tuy nhiên, do thứ tự import, hàm mới đã ghi đè lên hàm cũ, trong khi hàm cũ đã là tiêu chuẩn duy nhất thực tế trong 6 tháng.

Việc Karpathy đề cập đến "thực thi hướng mục tiêu" ngụ ý rằng bài kiểm tra có thể đóng vai trò là tiêu chuẩn thành công. Tuy nhiên, trong thực tế, Claude sẽ coi "đi qua bài kiểm tra" là mục tiêu duy nhất, từ đó viết ra những đoạn mã chỉ có thể vượt qua các bài kiểm tra bề ngoài nhưng lại phá hủy các thành phần khác.

Thời điểm đó là như vậy: Claude đã viết 12 bài kiểm tra cho hàm xác thực, tất cả đều vượt qua. Nhưng logic xác thực trong môi trường sản xuất đã bị hỏng. Những bài kiểm tra đó chỉ xác minh rằng hàm “trả về một cái gì đó”, chứ không xác minh rằng nó trả về đúng thứ cần thiết. Hàm có thể vượt qua bài kiểm tra vì nó trả về một hằng số.

Mẫu của Karpathy có tương tác mặc định là một lần duy nhất. Tuy nhiên, các công việc thực tế của Claude Code thường nhiều bước:重构 qua 20 tệp, xây dựng tính năng trong một phiên làm việc, gỡ lỗi qua nhiều commit. Nếu không có điểm kiểm tra, chỉ một bước sai cũng có thể khiến toàn bộ tiến độ trước đó bị mất.

Thời điểm đó diễn ra như sau: một nhiệm vụ tái cấu trúc 6 bước đã gặp lỗi ở bước thứ 4. Khi tôi phát hiện ra, Claude đã tiếp tục thực hiện bước thứ 5 và bước thứ 6 trên nền lỗi đó. Thời gian dành để phân tích và sửa lỗi còn lâu hơn so với việc thực hiện lại toàn bộ nhiệm vụ. Nếu có điểm kiểm tra, lỗi ở bước thứ 4 đã có thể được phát hiện ngay.

Trong một thư viện mã đã có mô hình chín muồi, Claude thích đưa vào cách viết của riêng mình. Dù cách viết của nó “tốt hơn”, việc引入 một mô hình thứ hai bản thân nó còn tệ hơn bất kỳ mô hình đơn lẻ nào.

Thời điểm đó là như vậy: Claude đã引入 hooks vào một mã nguồn React dựa trên class component. Nó thực sự hoạt động được. Nhưng đồng thời nó làm phá vỡ mô hình kiểm thử vốn có của mã nguồn, vì những bài kiểm thử đó phụ thuộc vào componentDidMount. Cuối cùng, phải mất nửa ngày để xóa bỏ và viết lại.

Sự thất bại đắt giá nhất của Claude thường là những thất bại trông giống như thành công. Một hàm “chạy được”, nhưng trả về dữ liệu sai; một lần di chuyển “đã hoàn thành”, nhưng bỏ qua 30 bản ghi; một bài kiểm tra “đã vượt qua”, nhưng chỉ vì khẳng định đó vốn đã sai.

Thời điểm đó diễn ra như sau: Claude nói rằng việc di chuyển cơ sở dữ liệu đã “hoàn thành thành công”. Nhưng thực tế, nó đã lặng lẽ bỏ qua 14% bản ghi gây xung đột ràng buộc kích hoạt. Hành vi bỏ qua đã được ghi vào nhật ký, nhưng không được công khai rõ ràng. 11 ngày sau, khi dữ liệu báo cáo bắt đầu bất thường, chúng tôi mới phát hiện ra vấn đề.

Trong 6 tuần, tôi đã theo dõi cùng một nhóm 50 tác vụ đại diện, bao gồm 30 kho mã, và kiểm tra ba cấu hình.

Tỷ lệ lỗi đề cập đến: nhiệm vụ cần được sửa đổi hoặc viết lại để phù hợp với ý định ban đầu. Các lỗi được tính bao gồm: giả định lỗi im lặng, thiết kế quá mức, phá hoại không liên quan, thất bại im lặng, vi phạm quy ước, thỏa hiệp xung đột, bỏ sót các điểm kiểm tra.

Tỷ lệ tuân thủ là xác suất mà Claude sẽ áp dụng rõ ràng quy tắc đó khi quy tắc đó có hiệu lực.

Kết quả thực sự thú vị không chỉ là tỷ lệ lỗi giảm từ 41% xuống 3%. Quan trọng hơn, khi mở rộng từ 4 quy tắc lên 12 quy tắc, gánh nặng tuân thủ gần như không tăng lên, tỷ lệ tuân thủ chỉ giảm từ 78% xuống 76%, nhưng tỷ lệ lỗi lại giảm thêm 8 điểm phần trăm. Các quy tắc mới bổ sung này phủ sóng các mô hình thất bại mà 4 quy tắc ban đầu không xử lý, và chúng không cạnh tranh cùng một ngân sách chú ý.

Karpathy template sẽ lặng lẽ thất bại ở những đâu

Ngay cả khi không thêm quy tắc mới, 4 mẫu quy tắc ban đầu cũng không đủ ở ít nhất 4 vị trí.

Đầu tiên, các tác vụ Agent chạy trong thời gian dài.
Các quy tắc của Karpathy chủ yếu nhắm vào thời điểm Claude đang viết mã. Nhưng điều gì xảy ra khi Claude đang chạy một pipeline nhiều bước? Mẫu ban đầu không có quy tắc về ngân sách, không có quy tắc về điểm kiểm tra, cũng không có quy tắc “thất bại một cách lớn tiếng”. Do đó, pipeline sẽ dần dần trôi dạt.

Thứ hai, tính nhất quán giữa nhiều kho mã nguồn.
「Phù hợp với phong cách hiện có」 mặc định chỉ có một phong cách. Nhưng trong một monorepo có 12 dịch vụ, Claude phải chọn xem nên phù hợp với phong cách nào. Quy tắc ban đầu không hướng dẫn nó cách chọn. Do đó, nó ли chọn ngẫu nhiên, ли trộn đều vài phong cách.

Thứ ba, chất lượng kiểm thử.
Thực hiện “theo mục tiêu” coi “kiểm tra qua” là thành công, nhưng không nêu rõ rằng bản thân bài kiểm tra phải có ý nghĩa. Kết quả là, Claude viết ra những bài kiểm tra gần như không xác minh điều gì, nhưng những bài kiểm tra này khiến nó lầm tưởng rằng mình rất tự tin.

Thứ tư, sự khác biệt giữa môi trường sản xuất và giai đoạn nguyên mẫu.
Cùng 4 quy tắc này có thể ngăn chặn mã sản xuất bị thiết kế quá mức, nhưng cũng có thể làm chậm quá trình phát triển bản mẫu. Vì giai đoạn bản mẫu đôi khi thực sự cần 100 dòng mã thử nghiệm để xác định hướng đi. Nguyên tắc “ưu tiên đơn giản” của Karpathy dễ dàng bị kích hoạt quá mức trong mã giai đoạn đầu.

Tám quy tắc mới này không nhằm thay thế bốn quy tắc gốc của Karpathy, mà nhằm lấp đầy những khoảng trống của chúng: mẫu gốc được thiết kế cho bối cảnh viết mã mang tính tự động hoàn thành vào tháng 1 năm 2026; nhưng đến tháng 5 năm 2026, Claude Code đã bước vào môi trường do Agent điều khiển, với nhiều bước và hợp tác giữa nhiều kho mã nguồn, hai bối cảnh này đối mặt với những vấn đề khác nhau.

Những phương pháp nào không hiệu quả

Trước khi xác định cuối cùng 12 quy tắc này, tôi cũng đã thử một số phương án khác.

Thêm quy tắc mà tôi thấy trên Reddit / X.
Hầu hết trong số đó либо chỉ lặp lại bốn quy tắc ban đầu của Karpathy bằng cách diễn đạt khác đi, либо là các quy tắc đặc thù lĩnh vực không thể khái quát hóa, chẳng hạn như “luôn sử dụng Tailwind class”. Cuối cùng, tất cả đều bị xóa bỏ.

Hơn 12 quy tắc.
Tôi đã thử tối đa 18 dòng. Sau 14 dòng, tỷ lệ tuân thủ giảm từ 76% xuống 52%. Giới hạn 200 dòng là có thật. Sau khi vượt quá độ dài này, Claude sẽ bắt đầu khớp mẫu thành “ở đây có quy tắc” thay vì đọc từng quy tắc một cách thực sự.

Các quy tắc phụ thuộc vào một số công cụ.
Ví dụ như “luôn luôn sử dụng eslint”, nếu dự án không cài đặt eslint, quy tắc này sẽ vô hiệu hóa và vô hiệu hóa một cách lặng lẽ. Sau đó, tôi đã sửa nó thành cách diễn đạt không phụ thuộc vào công cụ cụ thể, ví dụ thay “sử dụng eslint” bằng “tuân thủ phong cách đã được áp đặt trong kho mã nguồn”.

Đưa ví dụ vào CLAUDE.md, thay vì quy tắc.
Ví dụ chiếm nhiều ngữ cảnh hơn quy tắc. Ba ví dụ tiêu tốn ngữ cảnh tương đương khoảng 10 quy tắc, và Claude rất dễ bị quá khớp với các ví dụ. Quy tắc là trừu tượng, ví dụ là cụ thể. Do đó, nên sử dụng quy tắc.

Hãy cẩn thận, suy nghĩ kỹ lưỡng và tập trung hơn.
Đây đều là những tiếng ồn. Tỷ lệ tuân thủ các lệnh này đã giảm xuống khoảng 30% vì chúng không thể được kiểm tra. Sau đó, tôi đã thay thế chúng bằng các quy tắc mệnh lệnh cụ thể hơn, chẳng hạn như “nêu rõ các giả định”.

Hãy nói với Claude hãy hành xử như một kỹ sư giàu kinh nghiệm.
Điều này không có tác dụng. Claude vốn đã tự cho mình là kỹ sư kỳ cựu. Vấn đề thực sự không phải ở chỗ nó có nghĩ như vậy hay không, mà là nó có thực hiện như vậy hay không. Các quy tắc mệnh lệnh có thể thu hẹp khoảng cách này, còn các lời nhắc về danh tính thì không.

Bản đầy đủ 12 quy tắc của CLAUDE.md

Đây là phiên bản đầy đủ có thể sao chép và dán trực tiếp.

Hiện không thể hiển thị nội dung này ngoài tài liệu Feishu

Lưu nó dưới tên CLAUDE.md tại thư mục gốc của kho lưu trữ. Dưới 12 quy tắc này, thêm các quy tắc riêng của dự án, ví dụ: công nghệ, lệnh kiểm thử, mẫu lỗi, v.v. Tổng thể không vượt quá 200 dòng, nếu vượt quá, tỷ lệ tuân thủ quy tắc sẽ giảm rõ rệt.

Làm thế nào để cài đặt

Chỉ cần hai bước:

1. Thêm 4 quy tắc cơ bản của Karpathy vào tệp CLAUDE.md của bạn
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

2. Dán quy tắc 5–12 trong bài viết này vào bên dưới

Lưu tệp vào thư mục gốc của kho lưu trữ. Dấu >> ở đây rất quan trọng, vì nó có tác dụng thêm vào tệp CLAUDE.md đã có, thay vì ghi đè lên các quy tắc dự án mà bạn đã viết trước đó.

CLAUDE.md không phải là danh sách ước muốn, mà là một hợp đồng hành vi nhằm ngăn chặn các mô hình thất bại cụ thể mà bạn đã quan sát thấy.

Mỗi quy tắc đều nên trả lời một câu hỏi: Nó ngăn chặn lỗi gì?

Bốn quy tắc của Karpathy nhằm phòng tránh các mô hình thất bại mà ông thấy vào tháng 1 năm 2026: giả định im lặng, kỹ thuật hóa quá mức, phá hoại không liên quan, tiêu chuẩn thành công yếu kém. Đây là những nền tảng, đừng bỏ qua.

Tám quy tắc mới tôi thêm vào nhằm phòng ngừa các mô hình thất bại mới xuất hiện sau tháng 5 năm 2026: vòng lặp Agent không có ràng buộc ngân sách, nhiệm vụ đa bước không có điểm kiểm tra, các bài kiểm tra dường như đã thực hiện nhưng thực tế không kiểm tra được logic quan trọng, và vấn đề che giấu thất bại im lặng dưới dạng thành công im lặng. Chúng là các bản vá tăng dần.

Tất nhiên, hiệu quả cụ thể sẽ khác nhau tùy người. Nếu bạn không sử dụng pipeline nhiều bước, quy tắc 10 sẽ không quá quan trọng với bạn. Nếu kho mã của bạn chỉ có một phong cách thống nhất và đã được lint thực thi, thì quy tắc 11 là dư thừa. Sau khi đọc xong 12 quy tắc này, hãy giữ lại những quy tắc thực sự liên quan đến những lỗi bạn từng mắc phải và xóa đi phần còn lại.

Một phiên bản CLAUDE.md với 6 quy tắc được tùy chỉnh cho các mô hình thất bại thực tế, vượt trội hơn một phiên bản có 12 quy tắc trong đó 6 quy tắc bạn sẽ không bao giờ sử dụng.

Kết luận

Bài tweet của Karpathy vào tháng 1 năm 2026 về cơ bản là một lời phàn nàn. Forrest Chang đã biến nó thành 4 quy tắc. Cuối cùng, 120.000 nhà phát triển đã dành cho kết quả này một lượt Star. Và phần lớn trong số họ, cho đến hôm nay, vẫn chỉ đang sử dụng 4 quy tắc đó.

Mô hình đã tiến bộ, hệ sinh thái cũng đã thay đổi. Agent đa bước, hook kích hoạt chuỗi, tải skill, hợp tác nhiều kho mã nguồn—những điều này đều chưa tồn tại khi Karpathy đăng dòng tweet đó. Bốn quy tắc ban đầu không giải quyết được những vấn đề này. Chúng không sai, mà chỉ chưa đầy đủ.

Thêm 8 quy tắc mới. Trong 6 tuần, kiểm thử trên 30 kho mã. Tỷ lệ lỗi giảm từ 41% xuống còn 3%.

Hãy lưu bài viết này tối nay và dán 12 quy tắc này vào file CLAUDE.md của bạn. Nếu nó giúp bạn tiết kiệm một tuần tìm hiểu về Claude, hãy chia sẻ.