TL;DR

Tháng 1/2026, Andrej Karpathy phàn nàn về 3 lỗi của Claude khi viết code: giả định thầm lặng, over-complication, và chỉnh sửa code không liên quan. Forrest Chang đóng gói thành 4 rules trong 1 file CLAUDE.md 65 dòng. Repo đó đạt 5,828 stars ngày đầu, 122,000 stars đến nay - single-file repo tăng trưởng nhanh nhất 2026.

Vấn đề: template được viết cho January 2026 - thời điểm Claude Code chủ yếu là autocomplete có giám sát. Tháng 5/2026, developers dùng agent-driven workflows, multi-step pipelines, monorepo nhiều service. 4 rules gốc không được thiết kế cho những thứ này.

Một developer test 6 tuần trên 30 codebase, 50 task đại diện, rồi thêm 8 rules. Tỷ lệ lỗi từ 41% xuống 3%.

4 Rules Gốc Làm Được Gì

Nếu chưa đọc repo của Forrest Chang, đây là nền tảng:

  • Rule 1 - Think Before Coding: Phát biểu giả định rõ ràng. Hỏi thay vì đoán. Đưa ra nhiều cách diễn giải khi có ambiguity.

  • Rule 2 - Simplicity First: Minimum code giải quyết vấn đề. Không feature suy đoán. Không abstraction cho single-use code.

  • Rule 3 - Surgical Changes: Chỉ chạm vào những gì cần thiết. Không "cải thiện" code lân cận. Không refactor những thứ đang chạy tốt.

  • Rule 4 - Goal-Driven Execution: Định nghĩa success criteria. Loop cho đến khi verify. Đừng nói Claude làm gì - hãy nói thành công trông như thế nào.

4 rules này đóng khoảng 40% failure modes trong các session Claude Code không có giám sát. Phần còn lại nằm ở các khoảng trống bên dưới.

4 Chỗ Template Gốc Âm Thầm Hỏng

Trước khi thêm rules mới, cần hiểu template gốc hỏng ở đâu:

  1. Long-running agent tasks: 4 rules target khoảnh khắc Claude viết code. Không có budget rule, không có checkpoint rule, không có "fail loud" rule. Pipeline dài dễ drift.

  2. Multi-codebase consistency: "Match existing style" giả định chỉ có 1 style. Trong monorepo 12 service, Claude phải chọn style nào - template gốc không nói. Kết quả: chọn ngẫu nhiên hoặc trộn lẫn.

  3. Test quality: Goal-Driven Execution coi "tests pass" là thành công. Không yêu cầu tests phải có ý nghĩa. Kết quả: tests kiểm tra không có gì hữu ích nhưng làm Claude tự tin.

  4. Production vs prototype: Simplicity First bắn nhầm vào early-stage code cần 100 dòng scaffolding để tìm ra hướng đi.

8 Rules Mới - Mỗi Cái Từ 1 Sự Cố Thực Tế

Robot developer đọc CLAUDE.md rulebook với 12 numbered rules

Rule 5 - Dùng model chỉ cho judgment calls: Dùng Claude cho: phân loại, soạn thảo, tóm tắt, trích xuất từ unstructured text. KHÔNG dùng cho: routing, retries, status-code handling, deterministic transforms. Sự cố: code dùng Claude để "quyết định có nên retry khi gặp 503 không" - retry policy trở nên random vì model đọc request body làm context.

Rule 6 - Token budget không phải advisory: 4,000 tokens/task, 30,000 tokens/session. Sự cố: debugging session chạy 90 phút, model đề xuất lại fix đã bị từ chối 40 messages trước đó.

Rule 7 - Surface conflicts, đừng average chúng: Khi 2 pattern trong codebase mâu thuẫn, chọn 1 cái (mới hơn / được test nhiều hơn), giải thích tại sao, flag cái kia để cleanup. Sự cố: codebase có 2 pattern xử lý error - Claude viết code mới làm cả hai. Error handler bị gọi 2 lần.

Rule 8 - Đọc trước khi viết: Trước khi thêm code vào file, đọc exports, immediate caller, và các shared utility rõ ràng. Sự cố: Claude thêm function bên cạnh function giống hệt đã có. Import order quyết định cái nào thắng. Function cũ đã là source of truth 6 tháng.

Rule 9 - Tests verify intent, không chỉ behavior: Mỗi test phải encode TẠI SAO behavior quan trọng, không chỉ NÓ LÀM GÌ. Sự cố: Claude viết 12 tests cho auth function. Tất cả pass. Auth broken trên production vì tests kiểm tra function trả về gì đó, không phải đúng thứ gì.

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

Rule 11 - Tuân thủ convention của codebase, dù bạn không đồng ý: Conformance > taste. Nếu thực sự nghĩ convention gây hại, hãy nêu ra. Đừng fork âm thầm. Sự cố: Claude inject React hooks vào class-component codebase. Chúng chạy được. Chúng cũng phá vỡ testing patterns vốn dựa vào componentDidMount.

Rule 12 - Fail loud: "Hoàn thành" là sai nếu có gì đó bị skip âm thầm. "Tests pass" là sai nếu có test bị bỏ qua. Surface uncertainty thay vì ẩn nó đi. Sự cố: database migration "hoàn thành thành công" nhưng âm thầm skip 14% records gặp constraint violation. Phát hiện sau 11 ngày khi báo cáo bắt đầu sai.

Con Số Sau 6 Tuần Test

3 cấu hình được test trên 50 task đại diện, 30 codebase:

  • 0 rules: Tỷ lệ lỗi 41%, compliance N/A

  • 4 rules gốc: Tỷ lệ lỗi 11%, compliance 78%

  • 12 rules: Tỷ lệ lỗi 3%, compliance 76%

Kết quả đáng chú ý: thêm 8 rules gần như không ảnh hưởng compliance (78% → 76%) nhưng cắt thêm 8 điểm phần trăm tỷ lệ lỗi. 8 rules mới cover failure modes mà 4 rules cũ không address - chúng không cạnh tranh cùng attention budget.

Ngưỡng quan trọng: past 200 dòng, compliance giảm mạnh. Test với 18 rules → compliance xuống 52%. CLAUDE.md phải compact. Anthropic cũng xác nhận: Claude tuân theo file này khoảng 80% thời gian, và instructions bị chôn trong noise sẽ bị deprioritize.

Khi Nào Không Cần Cả 12 Rules

Tác giả nói thẳng: "A 6-rule CLAUDE.md tuned to your real failure modes beats a 12-rule one with 6 rules you'll never need."

  • Không dùng multi-step pipelines → Rule 10 không có giá trị

  • Codebase một service với linting enforcement → Rule 11 thừa

  • Chủ yếu làm prototype nhanh → Rule 6 (token budget) có thể gây friction

Đọc 12 rules, giữ những cái map với lỗi bạn đã thực sự gặp, bỏ phần còn lại.

Cài Đặt Ngay

Hai bước:

# 1. Thêm 4 rules gốc của Karpathy vào CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

# 2. Paste rules 5-12 sau đó

Lưu ở root của repo. Thêm rules dự án cụ thể bên dưới 12 rules chung. Không vượt 200 dòng tổng cộng - past đó, compliance bắt đầu giảm.

Template gốc: forrestchang/andrej-karpathy-skills. Best practices bổ sung: HumanLayer - Writing a good CLAUDE.md. via @MnimiyD