4 nguyên tắc CLAUDE.md theo Karpathy: hỏi trước, viết ít, sửa đúng chỗ, có phép thử

Andrej Karpathy từng mô tả các lỗi quen thuộc khi để LLM viết code: model tự giả định thay bạn rồi cứ thế làm, không hỏi lại khi bối rối, thích làm phức tạp hoá với abstraction thừa, và tiện tay sửa luôn code hay comment không liên quan. Repo andrej-karpathy-skills (khoảng 226 nghìn sao trên GitHub tại thời điểm viết) biến các nhận xét đó thành một file CLAUDE.md với 4 nguyên tắc. Đây là một trong những cách rẻ nhất để cải thiện hành vi Claude Code: vài chục dòng, không cài gì phức tạp. Bài này phân tích từng nguyên tắc, cách cài và khi nào không nên áp dụng máy móc.

Bốn nguyên tắc

1. Nghĩ trước khi code

• Nói rõ giả định; không chắc thì hỏi thay vì đoán.
• Yêu cầu có nhiều cách hiểu thì liệt kê ra, không lặng lẽ chọn một.
• Có cách đơn giản hơn thì phản biện; bối rối thì gọi tên chỗ chưa rõ.

2. Đơn giản là trên hết

• Không thêm tính năng ngoài yêu cầu, không "linh hoạt", "cấu hình được" khi chưa ai cần.
• Không abstraction cho code dùng một lần, không xử lý lỗi cho tình huống không thể xảy ra.
• 200 dòng mà 50 dòng làm được thì viết lại.

3. Sửa như phẫu thuật

• Không "tiện tay cải thiện" code, comment, format bên cạnh; không refactor thứ không hỏng.
• Theo đúng style hiện có, kể cả khi bạn sẽ viết khác.
• Gặp code chết không liên quan thì nhắc, không xoá. Chỉ dọn import, biến mà chính thay đổi của mình làm thừa.

4. Làm theo mục tiêu kiểm chứng được

Biến mệnh lệnh thành mục tiêu có phép thử: "Sửa bug" thành "viết test tái hiện bug rồi làm nó pass"; "Refactor X" thành "test pass trước và sau". Việc nhiều bước thì nêu kế hoạch ngắn, mỗi bước kèm cách kiểm tra. Tiêu chí rõ giúp Claude tự lặp tới khi đạt, thay vì hỏi bạn liên tục.

Cách cài

• Plugin (khuyến nghị trong README): thêm marketplace của repo bằng /plugin marketplace add rồi /plugin install theo hướng dẫn, áp dụng cho mọi dự án.
• CLAUDE.md theo dự án: tải file CLAUDE.md của repo vào gốc dự án, hoặc nối thêm vào cuối CLAUDE.md đang có, sau đó viết quy tắc riêng của dự án ở các mục khác.
• Cursor: repo có sẵn rule trong .cursor/rules/.

Vì chỉ là vài chục dòng, cách này hợp với khuyến nghị giữ CLAUDE.md ngắn: nó mô tả hành vi, thứ Claude không tự đọc ra được từ code.

Dấu hiệu đang có tác dụng

• Diff nhỏ hơn, chỉ chứa thay đổi được yêu cầu.
• Ít phải viết lại vì làm phức tạp quá.
• Câu hỏi làm rõ đến trước khi code, không phải sau khi sai.
• PR gọn, không có refactor "tiện thể".

Đánh đổi và lưu ý

• Bộ nguyên tắc nghiêng về thận trọng hơn tốc độ. Việc vặt (sửa typo, một dòng hiển nhiên) không cần cả quy trình; README cũng nói vậy.
• "Hỏi trước" có thể thành hỏi quá nhiều; nếu khó chịu, thêm câu "với việc nhỏ, cứ làm rồi báo".
• Không thay được test và review. Nó giảm lỗi, không loại bỏ lỗi.

Áp dụng thế nào?

• Dev: Nối 4 nguyên tắc vào CLAUDE.md, làm một tuần rồi so diff và số lần phải sửa lại.
• Tech Lead: Đưa "Surgical Changes" vào tiêu chí review PR do AI tạo: mọi dòng phải truy được về ticket.
• PM: "Goal-Driven" áp dụng cho cả yêu cầu bạn viết: kèm tiêu chí chấp nhận kiểm chứng được, Claude và dev đều làm đúng hơn.