TL;DR

Tháng 1/2026, Andrej Karpathy than thở về Claude Code trên X. Forrest Chang đọc thread đó, gói 3 vấn đề thành 4 rules trong một file CLAUDE.md, đẩy lên GitHub. 5.828 sao ngày đầu. 120.000 sao sau vài tháng. 220.000+ sao tổng cộng tính đến 5/2026.

Tháng 5/2026, developer @Mnilax test template đó trên 30 codebase trong 6 tuần, rồi bổ sung thêm 8 rules. Kết quả: tỷ lệ lỗi từ 41% xuống 3%, compliance rate chỉ giảm nhẹ từ 78% xuống 76%.

Bài này phân tích toàn bộ 12 rules, lý do từng rule tồn tại, và 4 điểm mà template gốc bể im lặng.

Bối cảnh: Từ than thở đến 220k sao

Ngày 26/1/2026, Karpathy - đồng sáng lập OpenAI, cựu AI Lead tại Tesla - đăng thread mô tả 3 failure modes anh thấy khi dùng Claude Code hàng ngày:

  • Silent assumptions: Model tự giả định, tự chạy, không hỏi gì cả

  • Over-complication: Giải pháp phức tạp hơn yêu cầu nhiều lần

  • Orthogonal damage: Sửa file A, tự ý đụng vào file B không liên quan

Hôm sau, Forrest Chang gói 3 vấn đề đó thành 4 behavioral rules trong một file CLAUDE.md 65 dòng. Repo đạt 5.828 sao ngày đầu tiên - trở thành file đơn lẻ tăng trưởng nhanh nhất lịch sử GitHub năm 2026.

Karpathy không viết file này, không officially endorse nó. Chang là tác giả.

4 Rules Nền Tảng (Karpathy - Chang)

Template gốc 65 dòng, 4 rules, giải quyết khoảng 40% failure modes trong Claude Code sessions không có giám sát:

  1. Think Before Coding - Nêu assumption rõ ràng. Nếu mơ hồ, hỏi trước khi đoán. Đề xuất nhiều cách tiếp cận khi có ambiguity.

  2. Simplicity First - Code tối thiểu giải quyết bài toán. Không feature speculative, không abstraction cho code dùng một lần.

  3. Surgical Changes - Chỉ đụng vào những gì cần đụng. Không "cải thiện" code lân cận, không refactor thứ chưa bể.

  4. Goal-Driven Execution - Định nghĩa success criteria trước, loop đến khi đạt được. Không cho Claude biết cần làm gì - cho nó biết thành công trông như thế nào.

4 rules này đóng được ~40% vấn đề phổ biến. 60% còn lại nằm ở những chỗ template không nhắc đến.

8 Rules Bổ Sung - Mnimiy, May 2026

Sơ đồ 4 rules gốc Karpathy + 8 rules mới của Mnimiy, tỷ lệ lỗi từ 41% xuống 3%

Sau 6 tuần test trên 30 codebase, @Mnimiy xác định 8 failure modes mà template gốc không cover - đặc biệt với agent-driven workflows tháng 5/2026 (agent fights, hook cascades, skill loading conflicts, multi-step workflows):

  • Rule 5 - Model chỉ làm việc ngôn ngữ: Không dùng Claude để quyết định retry/routing/status code. Nếu code đã có câu trả lời, để code xử lý. Lý do từ thực tế: một đoạn gọi Claude để "quyết định có retry 503 không" hoạt động ổn 2 tuần, rồi bắt đầu lỗi ngẫu nhiên vì model đọc request body làm context cho quyết định.

  • Rule 6 - Token budget là hard limit: 4.000 tokens/task, 30.000 tokens/session. Gần hết - summarize và bắt đầu lại. Không để model chạy quá. Thực tế: một session debug kéo 90 phút, model đề xuất lại fix đã bị reject từ 40 messages trước.

  • Rule 7 - Surface conflicts, không average: Nếu hai pattern trong codebase mâu thuẫn, chọn một, giải thích tại sao, flag cái kia để cleanup. Không "blend" cả hai. Thực tế: codebase có 2 error-handling pattern, Claude viết code dùng cả hai - lỗi bị swallow 2 lần.

  • Rule 8 - Đọc trước khi viết: Trước khi thêm code vào file, đọc exports, callers, shared utilities. Thực tế: Claude thêm function cạnh function có cùng logic mà nó chưa đọc - cả hai làm cùng việc, cái mới thắng vì import order.

  • Rule 9 - Tests verify intent, không phải chỉ behavior: Test phải encode tại sao behavior đó quan trọng. Thực tế: 12 tests cho auth function đều pass, nhưng auth bể trên production - tests chỉ kiểm tra function trả về gì đó, không kiểm tra đúng hay sai.

  • Rule 10 - Checkpoint sau mỗi bước quan trọng: Sau mỗi step trong multi-step task, tóm tắt đã làm gì, đã verify gì, còn gì. Thực tế: refactor 6 bước bể ở bước 4, Claude tiếp tục làm bước 5-6 trên nền bể - gỡ mất nhiều thời gian hơn làm lại từ đầu.

  • Rule 11 - Convention beats novelty: Codebase dùng snake_case? Dùng snake_case dù thích camelCase hơn. Thực tế: Claude đưa React hooks vào codebase class-component - hoạt động nhưng bể testing patterns, mất nửa ngày để revert.

  • Rule 12 - Fail loud: "Migration completed" là sai nếu 30 records bị skip im lặng. Thực tế: database migration "completed successfully" nhưng bỏ qua 14% records do constraint violation - phát hiện 11 ngày sau khi reports bắt đầu sai.

Con Số Kiểm Chứng

@Mnimiy theo dõi 50 tasks đại diện trên 30 codebase trong 6 tuần, 3 cấu hình:

  • Không có CLAUDE.md: 41% tỷ lệ lỗi

  • 4 rules Karpathy: 11% tỷ lệ lỗi (compliance 78%)

  • 12 rules đầy đủ: 3% tỷ lệ lỗi (compliance 76%)

Điều đáng chú ý: từ 4 rules lên 12 rules chỉ tốn thêm 2% compliance overhead, nhưng cắt thêm 8 điểm phần trăm tỷ lệ lỗi. 8 rules mới xử lý failure modes khác hoàn toàn, không cạnh tranh attention budget với 4 rules gốc.

Giới hạn 200 dòng là thật: Anthropic docs xác nhận - vượt 200 dòng, Claude bắt đầu pattern-match "có rules" thay vì đọc từng rule. Test đến 18 rules: compliance rớt từ 76% xuống 52% khi vượt 14 rules.

4 Điểm Bể của Template Gốc

4 rules gốc không sai - chúng được viết để giải quyết vấn đề tháng 1/2026 (autocomplete-style coding). Chúng không đủ với May 2026:

  1. Long-running agent tasks: Không có budget rule, checkpoint rule, hay fail-loud rule. Pipeline drift dần.

  2. Monorepo consistency: "Match existing style" giả định một style duy nhất. Monorepo 12 services? Claude chọn ngẫu nhiên hoặc average.

  3. Test quality: Goal-Driven Execution treat "tests pass" là thành công. Không yêu cầu tests có ý nghĩa.

  4. Production vs prototype: "Simplicity First" overfires trên code early-stage - prototyping hợp lý cần 100 dòng scaffolding để tìm hướng.

Cách Cài Đặt

MIT license. Miễn phí. Dưới 30 giây để thêm vào project hiện tại:

# Thêm vào CLAUDE.md hiện tại (không overwrite)
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

Chỉ download từ repo official: forrestchang/andrej-karpathy-skills hoặc multica-ai/andrej-karpathy-skills trên GitHub. Lý do: security researchers đã record trường hợp CLAUDE.md độc hại trong repo bị clone có thể exfiltrate SSH keys và API credentials.

Sau khi thêm 4 rules gốc, paste tiếp 8 rules mới bên dưới. Tổng file giữ dưới 200 dòng.

Lời khuyên quan trọng nhất từ @Mnimiy: Đừng paste tất cả 12 rules chỉ vì có người trên X nói vậy. Đọc từng rule, giữ những rule map với lỗi bạn thực sự đã gặp, bỏ cái còn lại. CLAUDE.md 6 rules tinh chỉnh theo failure modes thật của bạn tốt hơn 12 rules với 6 cái bạn không bao giờ cần.

via forrestchang/andrej-karpathy-skills - AgentPedia 12-Rule Analysis - TechTimes