Skill CLAUDE.md của Andrej Karpathy: một file cải thiện Claude Code

CLAUDE.md của Andrej Karpathy là một file chỉ dẫn ngắn đặt ở gốc dự án, gói lại bốn nguyên tắc để Claude Code bớt mắc những lỗi cố hữu khi viết code: tự ý giả định, viết rối, và sửa lan sang code không liên quan. Nó không đổi mô hình — nó dựng sẵn các rào chắn hành vi mà Claude đọc ngay khi mở phiên làm việc.

Bộ quy tắc này đúc kết từ quan sát của Karpathy về những "con rắn hay cắn" — cách anh gọi các lỗi mà LLM cứ lặp đi lặp lại — khi anh chuyển phần lớn công việc từ viết tay sang code bằng tác nhân (agent). Gốc rễ không nằm ở chỗ mô hình yếu, mà ở chỗ nó quá tự tin: gặp một yêu cầu mơ hồ là tự chọn lấy một cách hiểu rồi lẳng lặng chạy theo, chẳng buồn hỏi lại. Cấu hình CLAUDE.md đúng cách, các bản diff (khác biệt giữa mã cũ và mới) sẽ sạch hơn, bám sát yêu cầu và bớt hẳn lỗi do AI tự biên tự diễn.

"andrej-karpathy-skills" là gì?

Đây là một repository GitHub (multica-ai/andrej-karpathy-skills, trước là forrestchang/andrej-karpathy-skills) biến các quan sát của Karpathy về những lỗi LLM hay mắc — tự ý giả định, viết code phức tạp quá mức (over-engineering), sửa lan sang code không liên quan — thành một bộ quy tắc cụ thể. Có một chỗ cần rạch ròi: Karpathy là người chỉ ra những "con rắn cắn mình", nhưng người biến chúng thành file CLAUDE.md và plugin cho Claude Code lại là cộng đồng (cụ thể là tổ chức Multica). Quan sát là của Karpathy; còn bốn quy tắc thì do cộng đồng viết ra.

Bộ kỹ năng này nhắm vào tình trạng AI không quản được sự mơ hồ, không trình bày các phương án đánh đổi (trade-off) và hay viết 1000 dòng cho việc chỉ cần 100 dòng. Thay vì để AI "chạy rông" trong repo, nó ép mô hình vào khuôn khổ kỹ thuật khắt khe của một kỹ sư senior. Giá trị được nhắc đến nhiều nhất là con số đo được từ cộng đồng: áp bộ quy tắc này có thể kéo tần suất lỗi khi code của Claude từ 41% xuống còn 11%.

Bốn nguyên tắc — và lỗi mà mỗi nguyên tắc chặn

Mỗi nguyên tắc trong file nhắm thẳng vào một "lỗ hổng" cụ thể trong cách AI làm việc:

1. Think Before Coding (Nghĩ trước khi code): Chặn việc AI tự chọn một cách hiểu sai mà không hỏi lại. Quy tắc này buộc AI trình bày giả định và phương án đánh đổi trước khi viết dòng code nào. Thấy mơ hồ thì phải dừng lại hỏi cho rõ, thay vì âm thầm "đoán" ý bạn.
2. Simplicity First (Ưu tiên đơn giản): Chặn việc lạm dụng trừu tượng hóa hoặc thêm các tính năng "dự phòng" không ai yêu cầu. AI hay có xu hướng viết code phức tạp quá mức; nguyên tắc này ép nó chỉ viết tối thiểu những gì cần để giải quyết vấn đề. 100 dòng là đủ thì không được viết 1000 dòng.
3. Surgical Changes (Thay đổi chính xác): Chặn việc sửa code "tiện tay" ở những phần không liên quan. AI chỉ được chạm vào đúng những dòng phục vụ tác vụ. Nhờ vậy bản diff sạch, dễ review và không gây tác dụng phụ lên các module đang chạy ổn.
4. Goal-Driven Execution (Thực thi theo mục tiêu): Thay vì ra lệnh từng bước (imperative), hãy đưa ra tiêu chí thành công (success criteria). AI sẽ tự lặp cho đến khi đạt mục tiêu — ví dụ: "Viết test case trước, rồi code cho đến khi mọi test đều pass". Cách này tận dụng đúng thế mạnh lặp lại đến cùng của LLM để cho ra kết quả kiểm chứng được.

CLAUDE.md và Skill hoạt động ra sao trong Claude Code?

Cơ chế cốt lõi ở đây là "Tiết lộ tăng dần" (progressive disclosure). Để bảo vệ context window (cửa sổ ngữ cảnh) không bị tràn bởi các chỉ dẫn thừa, Claude Code nạp dữ liệu theo ba cấp độ:

• Cấp 1 (Metadata): Khi mở phiên, tác nhân chỉ nạp phần YAML frontmatter — tên và mô tả ngắn của skill. AI biết skill đó tồn tại nhưng chưa đọc nội dung.
• Cấp 2 (Body): Khi thấy nhiệm vụ hiện tại (ví dụ refactor code) khớp với mô tả của skill, AI mới dùng Bash tool để đọc toàn bộ file SKILL.md vào ngữ cảnh.
• Cấp 3 (Linked files): Các tài liệu bổ sung (như reference.md) chỉ được nạp khi thật sự cần xử lý ca chuyên sâu.

Khác biệt nằm ở chỗ: CLAUDE.md là các chỉ dẫn chung nạp vào mọi phiên của một dự án, còn Skill là một thư mục quy tắc dùng chung được cho nhiều dự án, chỉ được nạp khi AI thấy cần đến. Đây cũng là lý do bộ quy tắc Karpathy tồn tại ở cả hai dạng: một file CLAUDE.md để chép thẳng, và một skill karpathy-guidelines để cài một lần rồi dùng ở mọi nơi.

Cài đặt: plugin, file CLAUDE.md hay rule cho Cursor?

Có ba cách triển khai, tùy bạn muốn gọn hay linh hoạt:

Cách 1: Cài Plugin (khuyên dùng cho Claude Code). Biến bộ quy tắc thành một "kỹ năng" hệ thống, dùng được ở mọi dự án:

/plugin marketplace add multica-ai/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

Cách 2: Tải thẳng file cho một dự án. Không muốn cài plugin thì dùng curl kéo file vào gốc dự án:

curl -o CLAUDE.md https://raw.githubusercontent.com/multica-ai/andrej-karpathy-skills/main/CLAUDE.md

Cách 3: Dùng với Cursor. Bộ quy tắc này chạy tốt cả trên Cursor — chỉ cần lưu nội dung vào file .cursor/rules/karpathy-guidelines.mdc, thế là mọi phiên chat hay soạn thảo trong Cursor đều bị ràng buộc theo các nguyên tắc trên. Muốn kiểm tra file nào đã nạp vào ngữ cảnh hiện tại, chạy lệnh /memory.

Khi nào nên dùng — và các lỗ hổng cần lưu ý

Bộ quy tắc này rất hợp với dự án phức tạp, nhiều file, nơi một giả định sai nhỏ của AI có thể kéo theo hàng giờ debug. Nhưng nó không hoàn hảo, và cộng đồng đã chỉ ra vài điểm cần vá.

Rủi ro lớn nhất trên Reddit: Claude có thể trở nên quá thận trọng, mất khả năng góp ý về một kiến trúc tốt hơn vì sợ phạm luật "Surgical Changes" — biến cộng sự lập trình thành kẻ ghi chép thụ động. Cách vá phổ biến là thêm một điều khoản thứ 5: "Tôi luôn sẵn sàng nghe ý tưởng tốt hơn. Đừng ngại đề xuất một phương án có tác động lâu dài thay vì chỉ sửa mang tính tình thế." Nhưng nhớ giới hạn nó lại — chỉ lên tiếng khi phương án thay thế tránh được rủi ro thật hoặc công sức bỏ phí, kẻo mọi tác vụ nhỏ đều thành một cuộc họp chiến lược.

Hai lỗ hổng khác cũng đáng bổ sung. Một là quy tắc "Read before Write": bắt AI đọc kỹ các hàm export và những nơi gọi trực tiếp trước khi viết mới, để khỏi tạo ra hàm trùng lặp vì thiếu bối cảnh. Hai là chốt mỗi tác vụ bằng việc liệt kê những gì đã KHÔNG làm (trường hợp biên bị bỏ qua, phần dọn dẹp còn nợ) — chính cái ca lặng lẽ bị bỏ sót mới là thứ khiến bạn khổ lúc 1 giờ sáng, chứ không phải đoạn code nó đã viết. Cuối cùng, các quy tắc dài dễ "phai" khi phiên kéo dài và bị đẩy ra khỏi ngữ cảnh, nên bộ quy tắc càng ngắn gọn càng bám lâu.

Chọn quy tắc hợp với repo, đừng chép mù cả file

Hãy coi bộ quy tắc Karpathy như một "thực đơn" (menu) chứ đừng coi là khuôn mẫu cứng nhắc để chép mù. Giá trị thật nằm ở chỗ bạn nhặt ra những quy tắc hợp với repo của mình và tinh chỉnh chúng dựa trên chính những lỗi AI mắc phải trong dự án đó. Một bộ chỉ dẫn tốt là bộ ngắn gọn, cụ thể và đổi được hành vi của AI ngay từ những bản diff đầu tiên — ví dụ thay "hãy viết đơn giản" bằng "không thêm lớp trừu tượng mới trừ khi nó gỡ trùng lặp ở ít nhất hai nơi gọi".

Tài liệu tham khảo

• GitHub — multica-ai/andrej-karpathy-skills
• How Claude remembers your project — Claude Code Docs
• Equipping agents for the real world with Agent Skills — Anthropic
• Karpathy CLAUDE.md Rules: Cut Claude Errors 41% to 11% — AI Builder Club
• r/ClaudeAI — Adding a clause to Karpathy's 4 CLAUDE.md rules
• Karpathy CLAUDE.md Skills: Use the Viral Rules as a Menu, Not a Template — Developers Digest
• Karpathy Claude Code Skills — Nic's notes