CLAUDE.md giúp Claude Code bớt đoán mò, sửa quá tay và thiếu kiểm chứng

README của andrej-karpathy-skills đưa 4 nguyên tắc cho Claude Code: nêu giả định, ưu tiên đơn giản, sửa đúng phạm vi và xác minh kết quả. Phù hợp để bổ sung vào chỉ dẫn riêng của từng codebase.

Một ticket chỉ ghi “thêm validation” có thể khiến coding agent tự chọn format dữ liệu, dựng abstraction mới rồi tiện tay sửa cả những phần không liên quan. Đến lúc mở diff, phần thực sự cần thiết lại chỉ chiếm một góc nhỏ.

andrej-karpathy-skills đề xuất một cách đơn giản để giảm kiểu lệch hướng này: thêm bộ hướng dẫn vào CLAUDE.md cho Claude Code. Mục tiêu không phải thêm quy trình nặng nề, mà là buộc agent làm rõ điều chưa chắc, ưu tiên giải pháp tối giản và kiểm chứng kết quả.

Bốn nguyên tắc cho coding agent

README mô tả bộ hướng dẫn này lấy cảm hứng từ các quan sát của Andrej Karpathy về những điểm yếu thường gặp khi LLM viết code: tự đưa ra giả định, làm phức tạp hóa giải pháp và sửa những phần chưa hiểu đầy đủ.

Bốn nguyên tắc trong file gồm:

| Nguyên tắc | Vấn đề hướng tới | Hành vi mong đợi | |---|---|---| | Think Before Coding | Giả định ngầm, bỏ qua điều chưa rõ và đánh đổi | Nêu giả định, hỏi lại khi cần, trình bày các cách hiểu khác nhau | | Simplicity First | Abstraction và tính năng phình to | Chỉ viết lượng code cần thiết cho yêu cầu | | Surgical Changes | Chỉnh sửa lan sang phần không liên quan | Chỉ chạm vào phần cần sửa, giữ style hiện có | | Goal-Driven Execution | Làm theo mệnh lệnh nhưng không có tiêu chí kiểm chứng | Đặt tiêu chí thành công và xác minh bằng test hoặc kiểm tra phù hợp |

Điểm thực dụng nhất là Surgical Changes. Guideline yêu cầu agent không tự “cải thiện” code lân cận, comment hay định dạng; không refactor thứ không thuộc yêu cầu; và không xóa dead code có sẵn chỉ vì tình cờ phát hiện ra.

Ngược lại, nếu chính thay đổi của agent làm một import, biến hoặc hàm trở nên không dùng nữa, nó nên dọn phần đó. Mỗi dòng thay đổi, theo tinh thần README, cần truy ngược được về yêu cầu ban đầu.

Đổi ticket mơ hồ thành mục tiêu có thể kiểm tra

README khuyến nghị chuyển từ câu lệnh chung chung sang tiêu chí thành công rõ ràng.

Ví dụ:

| Yêu cầu ban đầu | Chuyển thành mục tiêu | |---|---| | “Add validation” | Viết test cho input không hợp lệ, rồi làm các test đó pass | | “Fix the bug” | Viết test tái hiện lỗi, rồi sửa để test pass | | “Refactor X” | Đảm bảo test pass trước và sau khi refactor |

Với tác vụ nhiều bước, agent được hướng dẫn nêu kế hoạch ngắn kèm cách xác minh:

text [Step] → verify: [check] [Step] → verify: [check] [Step] → verify: [check]

Cách giao việc này không đảm bảo agent luôn đúng, nhưng giúp reviewer có điểm bám rõ hơn: giả định nào đã được nêu, kết quả nào cần đạt và thay đổi nào thực sự phục vụ ticket.

Cài dưới dạng plugin hoặc CLAUDE.md theo project

README nêu hai cách dùng với Claude Code.

Cách 1: Cài plugin

Từ Claude Code, thêm marketplace:

text /plugin marketplace add forrestchang/andrej-karpathy-skills

Sau đó cài plugin:

text /plugin install andrej-karpathy-skills@karpathy-skills

Theo README, plugin giúp skill khả dụng trên các project. Đây có thể phù hợp khi bạn muốn dùng cùng một bộ nguyên tắc làm mặc định, nhưng vẫn nên kiểm tra xem chúng có xung đột với quy ước của từng repository hay không.

Cách 2: Thêm CLAUDE.md vào từng repository

Với project mới:

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

Với project đã có CLAUDE.md, README đề xuất nối nội dung vào file hiện tại:

bash echo "" >> CLAUDE.md curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

Lệnh thứ hai sẽ append toàn bộ guideline. Trước khi commit, nên đọc lại diff và xử lý các quy tắc trùng lặp hoặc mâu thuẫn với chỉ dẫn sẵn có của team.

README ghi dự án dùng giấy phép MIT.

Đừng chỉ copy file chung: thêm luật của codebase

Bốn nguyên tắc trên là luật hành xử chung. Chúng không thể tự biết codebase của bạn dùng TypeScript strict mode, endpoint nào phải có test hay error handling đang theo convention nào.

README gợi ý bổ sung phần hướng dẫn riêng cho project, chẳng hạn:

markdown ## Project-Specific Guidelines

Use TypeScript strict mode All API endpoints must have tests Follow the existing error handling patterns in src/utils/errors.ts

Với team, phần chỉ dẫn này thường quyết định agent có tạo ra thay đổi dễ review hay không. Có thể giữ bốn nguyên tắc làm lớp bảo vệ chung, rồi thêm các yêu cầu mà reviewer thực sự kiểm tra: phạm vi module, lệnh test, style, convention về lỗi và quy tắc API.

Repository cũng có rule cho Cursor tại .cursor/rules/karpathy-guidelines.mdc và dẫn đến CURSOR.md để xem cách dùng ở project khác.

Đây là thiên hướng thận trọng, không phải nghi thức bắt buộc

README lưu ý guideline này ưu tiên sự cẩn trọng hơn tốc độ. Với một lỗi chính tả hoặc thay đổi một dòng hiển nhiên, việc lập kế hoạch đầy đủ và trình bày mọi đánh đổi có thể tạo thêm ma sát.

Nên áp dụng chặt hơn với các task như:

Bug khó tái hiện. Thay đổi API hoặc validation. Công việc chạm nhiều module. Refactor có ràng buộc về test và tương thích. PR cần giữ diff nhỏ để dễ review hoặc cherry-pick.

Với việc rất nhỏ, giá trị cốt lõi vẫn là không sửa vượt phạm vi — không nhất thiết phải biến mọi yêu cầu thành một quy trình nhiều bước.

Checklist trước khi áp dụng

[ ] Chọn plugin dùng chung hay CLAUDE.md theo từng project. [ ] Nếu append vào file hiện có, kiểm tra quy tắc trùng lặp và mâu thuẫn. [ ] Bổ sung yêu cầu riêng về test, style, error handling và phạm vi module. [ ] Giao task bằng tiêu chí có thể xác minh, thay vì chỉ dùng mệnh lệnh chung chung. [ ] Review diff để bảo đảm mọi thay đổi đều phục vụ yêu cầu.

Một file hướng dẫn không thay thế review kỹ thuật. Nhưng nếu nó khiến agent hỏi trước khi đoán, viết ít hơn khi đã đủ và tự kiểm tra kết quả, đó là một thiết lập đáng thử cho những PR không được phép “sáng tạo” ngoài phạm vi.