Một CLAUDE.md nhỏ để Claude đừng sửa lung tung

TL;DR

• Ngăn Claude sửa lung tung bằng quy tắc ngắn gọn
• Bốn nguyên tắc: nghĩ trước, đơn giản, chỉnh gọn, mục tiêu rõ
• Cài plugin toàn cục hoặc thêm CLAUDE.md vào repo
• Tests-first: đổi yêu cầu thành tiêu chí kiểm thử
• Dành cho nhóm dùng Claude Code cần PR nhỏ, dễ xác minh

Tôi yêu cầu sửa một cái nhỏ. Claude trả lại một hộp đồ nghề đầy thứ lạ. Tôi đang ngồi nhìn diff dài mà tim nóng lên vì biết hậu quả của một API đã bị chạm lung tung. Câu chuyện này bắt đầu bằng một dòng lệnh không đủ ràng, và kết thúc bằng hóa đơn API cùng giờ trễ fix.

Hook - Một câu neo đơn giản

Repo này làm một việc rõ ràng: đóng bốn nguyên tắc Karpathy vào một CLAUDE.md để Claude Code (hoặc các assistant tôn trọng file này) hỏi trước, ưu tiên đơn giản, và chỉ thực hiện những chỉnh sửa có thể kiểm chứng bằng test. Nói ngắn: giúp Claude bớt hăng và sửa có trách nhiệm.

Tại sao cần cái này

Bạn biết cảm giác: bảo “refactor logging” rồi nhận về một PR xóa nửa repo. Lý do không hẳn vì Claude độc ác, mà vì yêu cầu mơ hồ. CLAUDE.md là tấm bảng kiểm nhỏ trước khi assistant rờ vào code. Nó giống bảng kiểm lúc đi phẫu thuật: kiểm tra tên bệnh nhân, vị trí mổ, và chỉ khi mọi thứ rõ ràng thì mới rạch dao.

Một tấm bảng kiểm ngắn gọn có tác dụng lớn: giảm scope, ép chu trình tests-first, buộc assistant hỏi câu rõ ràng nếu thiếu thông tin. Đây không phải một phép màu. Đây là một công cụ để đổi “tôi nghĩ nên làm vậy” thành “đây là tiêu chí chấp nhận”.

Show, Don’t Tell - Tình huống thực chiến

Tình huống 1 - Yêu cầu mơ hồ (input → output)

User: "Refactor logging across repo to new format."
Assistant: "Okay, I'll rewrite logging across src/, update formats, and remove dead code."
# Output: large diff, unrelated file changes, tests broken

Tình huống 1 - Với CLAUDE.md (input → output)

User: "Goal: tests/logging.test.js passes. Acceptance: change only src/logging, minimal diff."
Assistant: "I will add failing tests first, change src/logging to satisfy tests, keep diff minimal."
# Output: small diff, tests pass

Tình huống 2 - Cài plugin toàn cục (khi bạn quản nhiều repo)

/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills
# Output (ví dụ): Installed plugin "andrej-karpathy-skills@karpathy-skills"

Tình huống 3 - Thêm CLAUDE.md vào repo đơn lẻ

curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
# Inspect file before committing

Tình huống 4 - Workflow tests-first (Pattern: Surgical)

1. Viết test thể hiện mục tiêu.
2. Yêu cầu assistant “Make tests pass. Touch only file X.”
3. Lặp: chạy test → sửa → test pass → kết thúc.

Quan sát: tests-first ép assistant suy nghĩ theo tiêu chí đo lường. Một cú như vậy biến “thay đổi cảm tính” thành một chuỗi nhỏ, có thể review.

Visual: khi CLAUDE.md vào phòng

Markdy trên kia là một minh họa: developer ném yêu cầu, assistant muốn sửa ào ào, mediator (CLAUDE.md) xuất hiện, kéo quy trình về tests-first, rồi PR nhỏ được gửi. Metaphor: CLAUDE.md như tấm biển chỉ đường giữa hai người thợ, và như dây bảo hộ trước khi leo thang.

The Guts - Cài đặt và mẫu dùng

Cách 1 - Plugin toàn cục (khuyên dùng khi quản nhiều repo)

/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills

Cách 2 - Thêm CLAUDE.md vào repo (một repo)

curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md
# inspect CLAUDE.md then commit

Surgical workflow (mẫu ngắn):

1. Viết test thể hiện mục tiêu.
2. Giao nhiệm vụ cho assistant: “Make tests pass. Touch only file X.”
3. Review diff, run tests, lặp lại nếu cần.

• Key features:
  • Bốn nguyên tắc rõ ràng: Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution
  • Dual modes: plugin hoặc per-repo CLAUDE.md
  • Khuyến khích tests-first, tiêu chí thành công đo lường được

💡 Tip: Đừng để CLAUDE.md dài quá. Một checklist ngắn buộc assistant hỏi thay vì phán đoán. Một tờ giấy nhớ tốt hơn một cuốn sách hướng dẫn.

⚠️ Warning: Lệnh cURL từ raw.githubusercontent.com cần kiểm tra nội dung trước khi commit. Plugin marketplace cũng cần review metadata trước khi kích hoạt.

Where it fits

• Works with Claude Code và các assistant tôn trọng CLAUDE.md.
• Thay thế cách giao thông tin rời rạc trong PRs và chat bằng một nguồn truth ngắn gọn.
• Dùng tốt cho bug fixes, refactor có phạm vi xác định, và bất kỳ việc nào bạn muốn giữ diff nhỏ.

Alternatives: README repo đề cập đến Multica như dự án liên quan; dùng Multica khi bạn cần orchestration phức tạp hơn.

Reality check - Một số giới hạn

• Thiên về thận trọng: làm chậm chỉnh sửa tạm thời, nhất là với task rât nhỏ.
• Tốt nhất cho nhóm đã có test suite. Nếu repo không có test, cần chuẩn bị bước test trước.
• Snapshot workspace có vài file bị thiếu trong bản tải về; ví dụ CLAUDE.md hay EXAMPLES.md nên inspect từ remote trước khi dùng.

Kết - The Twist

Trở về cái cảnh ban đầu: tôi mở PR nhỏ, tim lặng trở lại khi thấy diff bé. CLAUDE.md không làm việc thay bạn. Nó chỉ như mảnh băng keo dán vết rách: nếu dán đúng chỗ, giữ được ghép; dán hờ hững thì cũng rách lại. Repo này có 54,909 sao; con số đó là tín hiệu có nhiều người thấy vấn đề này đáng giải quyết. CLAUDE.md là một cách khiêm nhường để giảm họa, không phải một lá bùa.

forrestchang/andrej-karpathy-skills · no license · 54909