CLAUDE.md là gì? Nội dung file cấu hình AI lập trình nhiều sao nhất trên GitHub

Trong kỷ nguyên lập trình cùng AI, CLAUDE.md đã trở thành một hiện tượng công nghệ, nhận được hàng chục nghìn lượt star trên GitHub. Tệp tin này được thiết lập như một “Management Contract” (Bản cam kết vận hành) giúp định hình và kiểm soát hành vi của các trợ lý AI (đặc biệt là Claude Code), ngăn ngừa các lỗi lập trình phổ biến do AI tự ý suy diễn hoặc viết mã quá phức tạp.

Dưới đây là nội dung chi tiết của tệp tin CLAUDE.md nổi tiếng nhất trên GitHub (thuộc kho lưu trữ của multica-ai/andrej-karpathy-skills) được dịch nghĩa chi tiết phục vụ cộng đồng lập trình viên Việt Nam.

Nội dung nguyên bản CLAUDE.md (Original Content)

# CLAUDE.md

Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.

**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.

## 1. Think Before Coding

**Don't assume. Don't hide confusion. Surface tradeoffs.**

Before implementing:
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them - don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.

## 2. Simplicity First

**Minimum code that solves the problem. Nothing speculative.**

- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

## 3. Surgical Changes

**Touch only what you must. Clean up only your own mess.**

When editing existing code:
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

## 4. Goal-Driven Execution

**Define success criteria. Loop until verified.**

Transform tasks into verifiable goals:
- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure tests pass before and after"

For multi-step tasks, state a brief plan:
```
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]
```

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

---

**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

Bản Dịch Nghĩa Chi Tiết & Giải Thích Hành Vi AI

1. Think Before Coding (Suy nghĩ trước khi viết mã)

Nguyên tắc: Không tự ý giả định. Không che giấu sự mơ hồ. Đưa các giải pháp đánh đổi ra ánh sáng.

Trước khi bắt tay vào sửa code, AI bắt buộc phải:

• Nêu rõ các giả định của mình một cách rõ ràng. Nếu chưa chắc chắn, phải hỏi lại lập trình viên.
• Nếu có nhiều hướng diễn giải cho yêu cầu, phải trình bày tất cả các phương án — tuyệt đối không được tự ý chọn âm thầm.
• Nếu có giải pháp đơn giản hơn, phải đề xuất. Có quyền phản biện lại yêu cầu nếu thấy cần thiết.
• Nếu có điểm nào không rõ ràng, phải dừng lại ngay. Chỉ rõ điểm gây bối rối và đặt câu hỏi làm rõ.

2. Simplicity First (Ưu tiên sự đơn giản)

Nguyên tắc: Lượng code tối thiểu để giải quyết vấn đề. Không viết mã phỏng đoán tương lai.

• Không thêm bất kỳ tính năng nào ngoài những gì được yêu cầu.
• Không trừu tượng hóa (tạo Class/Interface) cho các đoạn mã chỉ sử dụng một lần.
• Không thêm tính năng “linh hoạt” hoặc “cấu hình nâng cao” nếu không được yêu cầu cụ thể.
• Không viết xử lý lỗi (try-catch) cho những tình huống không thể xảy ra.
• Nếu bạn viết 200 dòng code trong khi có thể giải quyết bằng 50 dòng, hãy viết lại.

3. Surgical Changes (Can thiệp ngoại khoa / Chỉ sửa đúng chỗ)

Nguyên tắc: Chỉ chạm vào những gì bắt buộc. Chỉ dọn dẹp đống lộn xộn của chính mình tạo ra.

Khi chỉnh sửa mã nguồn có sẵn:

• Không tự ý “cải tiến” các đoạn code lân cận, comment hoặc định dạng căn lề của file.
• Không tái cấu trúc (refactor) những thứ đang chạy bình thường.
• Tuân thủ tuyệt đối phong cách viết code (coding style) hiện tại của dự án, ngay cả khi bạn không thích phong cách đó.

4. Goal-Driven Execution (Thực thi theo mục tiêu rõ ràng)

Nguyên tắc: Chuyển đổi yêu cầu thành các mục tiêu có thể kiểm chứng. Thực hiện kiểm tra từng bước.

• Xác định tiêu chí thành công rõ ràng trước khi sửa code.
• Sau khi thực hiện, phải chạy các bộ kiểm thử (test suite) để tự đánh giá mức độ hoàn thành.

Hy vọng bài viết này giúp bạn áp dụng thành công tệp tin CLAUDE.md vào dự án của mình để tối ưu hóa quy trình làm việc cùng trợ lý lập trình AI!