原文标题: Tệp CLAUDE.md của Karpathy lên vị trí #1 trên GitHub với 82,000 sao. Hầu hết các nhà phát triển vẫn chưa đọc.

Tác giả bản dịch: Dep

Biên tập viên's chú: Khi nhiều người sử dụng Claude Code, vấn đề lớn nhất không phải là mô hình không mạnh mẽ đủ, mà là mỗi lần phải bắt đầu từ đầu.

Bạn cần lặp đi lặp lại cho nó lịch sử dự án, ngăn xếp công nghệ, quy tắc mã, những nơi không được phép chạm vào, những giải pháp đã thử trước đó. Miễn là thông tin này không được cố định, Claude sẽ phụ thuộc vào đoán, kết quả có thể là sửa các tệp không nên sửa, tái cấu trúc mã không yêu cầu, thậm chí đề xuất công cụ không phù hợp với dự án hiện tại.

CLAUDE.md mà bài viết này giới thiệu, chính là hướng dẫn sử dụng được viết cho Claude Code. Bạn chỉ cần đặt nó vào thư mục root của dự án, mỗi khi khởi động, Claude sẽ tự động đọc nó. Nó có thể thông báo cho Claude trước: cách trả lời, cách viết mã, khi nào phải hỏi trước, những thao tán không được tự ý thực hiện, dự án sử dụng ngăn xếp công nghệ gì, và những quyết định quan trọng đã được đưa ra trong quá khứ.

Đơn giản nói, vai trò của CLAUDE.md là: giảm sự lặp lại trong giải thích, hạn chế vùng biên của mô hình, khiến lập trình AI ổn định hơn, dễ kiểm soát hơn.

Nếu bạn đang sử dụng Claude Code, bạn có thể bắt đầu từ 4 quy tắc mà Karpathy đã tóm tắt: Hỏi nếu không rõ, thử cách đơn giản trước tiên, tránh mã không liên quan, định rõ sự không chắc chắn. Bạn hãy viết những quy tắc này vào CLAUDE.md trước, sau đó từ từ bổ sung theo dự án của riêng bạn, bạn sẽ thấy rõ sự cải thiện trong trải nghiệm sử dụng.

Dưới đây là nội dung gốc:

Một tệp có tên CLAUDE.md đã lên vị trí đầu tiên trên GitHub Trending.

82,000 sao, 7800 lượt fork.

Sự việc này bắt đầu từ Andrej Karpathy. Ông từng là trưởng nhóm AI của Tesla, cũng là một trong những thành viên sáng lập của OpenAI. Ông tóm tắt ra 4 hành vi làm cho Claude Code không hiệu quả, và viết chúng vào một tệp.

Sau đó, một nhà phát triển đã mở rộng dựa trên 4 quy tắc này và công khai phát hành tệp này. Kết quả là nó đã nhanh chóng trở nên phổ biến.

Lý do rất đơn giản: Chính xác mã hóa đã tăng từ 65% lên 94%.

Nhưng hầu hết các nhà phát triển hàng ngày sử dụng Claude Code thực ra chưa bao giờ thiết lập này. Họ bắt đầu mỗi phiên làm việc từ đầu: diễn giải lại ngữ cảnh giống nhau, dọn dẹp các thay đổi phạm vi không cần thiết, quay trở lại những cải tiến không ai yêu cầu.

Dưới đây là tệp đầy đủ.

Cài đặt mà hầu hết nhà phát triển đã bỏ lỡ

Mỗi khi bạn mở Claude Code, nó mặc định không biết gì cả.

Nó không biết ngăn xếp công nghệ của bạn, không biết quy tắc mã của bạn, không biết lịch sử dự án của bạn, cũng không biết bạn đã thử qua gì, và đặc biệt không biết trước ba phiên làm việc bạn đã quyết định không làm gì.

Do đó, nó chỉ có thể đoán. Và khi nó bắt đầu đoán, có thể cải tiến mã không cần thiết mà bạn không yêu cầu, đề xuất khung của kiến trúc sẽ phá vỡ hiện có, xóa tệp mà không xác nhận và thậm chí đảo ngược quyết định bạn đã thực hiện trước đó.

CLAUDE.md là một tệp văn bản thuần túy đặt trong thư mục gốc của dự án. Claude Code sẽ tự động đọc nó mỗi khi bắt đầu một phiên làm việc.

Một lần cài đặt, không cần phải diễn giải lại và có thể sửa chữa ba loại lỗi chi phí cao.

Cài đặt mặc định: Bạn hàng tuần tiêu 375 đô la chỉ để lặp lại diễn giải bản thân

Nhà phát triển bình thường mỗi ngày mất khoảng 30 phút để giải thích lại ngữ cảnh cho Claude.

Ngăn xếp công nghệ, quy tắc mã, lịch sử dự án, phương pháp đã thử qua—nếu không viết thông tin này một lần và cho Claude đọc tự động vào mỗi lần, những thông tin đó sẽ không được giữ nguyên qua các phiên làm việc khác nhau.

Nếu tính theo giờ lương của nhà phát triển là 150 đô la:

· Mỗi ngày 30 phút, tương đương 75 đô la;

· Mỗi tuần đó là 375 đô la.

· Nếu là một nhóm 5 người, tức là 1875 đô la chi phí ẩn.

7 quy tắc dưới đây nên đặt ở đầu tệp CLAUDE.md.

→ Loại bỏ lời nói vô nghĩa

Không bắt đầu câu trả lời bằng các câu như "Câu hỏi hay", "Dĩ nhiên có thể", "Không vấn đề" hoặc tương tự. Hãy đưa ra câu trả lời trực tiếp. Không cần chào hỏi, không cần tái diễn câu hỏi.

→ Phù hợp chiều dài câu trả lời với nhiệm vụ

Chiều dài câu trả lời phải phù hợp với độ phức tạp của nhiệm vụ. Đối với câu hỏi đơn giản, trả lời trực tiếp và ngắn gọn; đối với nhiệm vụ phức tạp, cung cấp giải thích đầy đủ và chi tiết. Không dùng câu kết thúc có vẻ tái diễn câu hỏi hoặc kết luận để làm đầy trang.

→ Đề xuất giải pháp trước khi hành động

Trước khi bắt đầu bất kỳ nhiệm vụ quan trọng nào, đưa ra 2–3 lựa chọn đường dẫn khả thi, sau đó tiếp tục thực hiện khi tôi đã chọn.

→ Thừa nhận sự không chắc chắn trước khi gây thiệt hại

Nếu bạn không chắc chắn về bất kỳ sự thật, dữ liệu, ngày tháng hoặc thông tin kỹ thuật nào, hãy nêu rõ trước khi trích dẫn. Không dùng thông tin có vẻ hợp lý để lấp đầy khoảng trống kiến thức. Khi không chắc chắn, hãy nói trực tiếp là không chắc chắn.

→ Tôi là ai, tôi biết gì

Về tôi: [Tên] / Vai trò: [Vai trò của bạn] / Lĩnh vực: [Lĩnh vực].

Tôi giỏi về: [Nội dung bạn am hiểu].

Tôi đang học về: [Khoảng cách kiến thức].

Vui lòng điều chỉnh độ sâu của mỗi câu trả lời dựa trên thông tin này. Không giải thích quá mức về nội dung mà tôi đã biết, cũng đừng bỏ qua bối cảnh tôi cần.

→ Bối cảnh dự án hiện tại

Tôi đang làm: [Tên dự án] / Mục tiêu: [Kết quả cụ thể] / Đối tượng: [Ai sẽ sử dụng] / Nền công nghệ: [Ràng buộc liên quan] / Cần tránh: [Danh sách].

Hãy áp dụng bối cảnh này vào mỗi nhiệm vụ. Nếu yêu cầu nào không phù hợp với bối cảnh, xin vui lòng chỉ ra trước khi thực hiện.

→ Cố định phong cách biểu đạt của bạn

Phong cách viết của tôi là: [Mô tả phong cách biểu đạt của bạn].

Độ dài câu: [Ưu tiên].

Các từ thường sử dụng: [Ví dụ].

Những từ tôi không bao giờ sử dụng: [Ví dụ].

Định dạng: [Văn xuôi hoặc có cấu trúc].

Khi bạn viết bất kỳ nội dung nào thay mặt cho tôi, hãy tuân thủ chặt chẽ phong cách này, không được sử dụng phong cách biểu đạt riêng của bạn mặc định.

Thời gian hàng ngày dành cho việc giải thích bối cảnh: 30 phút

Theo giờ công của nhà phát triển là 150 Mỹ kim: 75 Mỹ kim / ngày

Hàng tuần: Mỗi nhà phát triển 375 Mỹ kim

Nhóm 5 người: Hàng tuần 1875 Mỹ kim

Cài đặt thời gian CLAUDE.md cho phần này: Tổng cộng 45 phút

Lỗi cần tránh: Không viết CLAUDE.md từ đầu. Hãy sử dụng mẫu dưới đây trước, sau đó chỉnh sửa kết quả đầu ra:

Dựa trên những gì tôi đã nói cho bạn về bản thân tôi, dự án của tôi, và cách làm việc của tôi mong muốn, hãy viết một tệp CLAUDE.md hoàn chỉnh cho tôi. Nội dung bao gồm: Ai tôi là, lịch sử kỹ thuật của tôi, sở thích giao tiếp của tôi, và hành vi mặc định mà mỗi phiên nên tuân theo. Yêu cầu cụ thể, văn bản thuần túy, dưới 500 từ.

Hành vi Ràng Buộc: Bạn không có quyền sửa đổi với "150 Mỹ kim mỗi giờ" kia

Bạn yêu cầu Claude sửa một hàm.

Kết quả là anh ấy tái cấu trúc ba tệp, đổi tên biến, sắp xếp lại các import, và thậm chí viết lại phần chú thích mà bạn đã bỏ thời gian để viết.

Và tất cả điều này đều không qua sự xác nhận của bạn.

Đánh giá và quay trở lại những thay đổi không cần thiết này có thể mất 1 giờ, tức là 150 Mỹ kim. Điều này xảy ra ba lần mỗi tuần, tức là 450 Mỹ kim. Với nhóm 5 người, điều này có nghĩa là 2250 Mỹ kim mỗi tuần để dọn dẹp các thay đổi không được ủy quyền.

7 quy tắc sau đây nên được đưa vào phần Hành vi Ràng Buộc của CLAUDE.md.

→ Kiểm soát phạm vi chặt chẽ

Chỉ chỉnh sửa các tệp, hàm và dòng mã trực tiếp liên quan đến nhiệm vụ hiện tại. Không tái cấu trúc, đổi tên, sắp xếp lại, định dạng lại hoặc "tối ưu hóa" nội dung nào mà tôi chưa chính thức yêu cầu bạn sửa đổi.

Nếu bạn tìm thấy nơi khác cần sửa, hãy chú thích ở cuối. Đừng chạm vào nó, bao giờ cũng không được.

→ Hỏi trước khi thực hiện thay đổi lớn

Trước khi thay đổi lớn vào nội dung mà tôi đã tạo, bao gồm việc viết lại phần, xoá phần, tái cấu trúc cấu trúc, thay đổi ngôn ngữ, v.v., bạn phải dừng lại, rõ ràng nêu rõ bạn chuẩn bị thay đổi gì và tại sao. Chờ tôi xác nhận trước khi tiếp tục.

→ Xác nhận trước mọi hành động phá hoại

Trước khi xóa bất kỳ tệp nào, ghi đè mã hiện có, xóa bản ghi trong cơ sở dữ liệu, hoặc gỡ bỏ phụ thuộc, bạn phải dừng lại, liệt kê rõ ràng các nội dung sẽ bị ảnh hưởng và yêu cầu tôi xác nhận một cách rõ ràng. Chỉ khi tôi nói "Đồng ý" trong tin nhắn hiện tại, bạn mới được tiếp tục.

"Bạn trước đó đã đề cập" không có nghĩa là đồng ý.

→ Hoạt động trên môi trường sản xuất phải tạm dừng

Các hoạt động sau đây phải nhận được sự xác nhận rõ ràng trong phiên trò chuyện hiện tại, không có ngoại lệ:

· Triển khai hoặc đẩy vào bất kỳ môi trường nào;

· Chạy di chuyển hoặc thay đổi cấu trúc cơ sở dữ liệu;

· Gửi bất kỳ cuộc gọi API ngoại vi nào;

· Thực thi bất kỳ lệnh nào có tác động không thể đảo ngược.

· Tôi phải nói "Đồng ý" trong tin nhắn hiện tại.

→ Luôn hiển thị những thay đổi đã được thực hiện

Sau mỗi nhiệm vụ mã hóa, phần kết thúc phải bao gồm:

Tệp đã chỉnh sửa: Liệt kê tất cả các tệp đã chỉnh sửa;

Nội dung chỉnh sửa: Mô tả mỗi tệp bằng một câu;

Tệp không được chỉnh sửa cố ý;

Công việc cần xử lý tiếp theo.

→ Không được thực hiện hành động thay mặt tôi mà không có sự xác nhận rõ ràng

Không được thay mặt tôi gửi, xuất bản, chia sẻ hoặc sắp xếp bất kỳ nội dung nào mà không có sự xác nhận rõ ràng từ tôi trong tin nhắn hiện tại. Bao gồm email, lời mời lịch, chia sẻ tài liệu, hoặc bất kỳ hoạt động nào ngoài cuộc trò chuyện hiện tại. Tôi phải nói "Đồng ý" trong tin nhắn hiện tại.

→ Hãy suy nghĩ trước khi viết mã

Đối với các nhiệm vụ liên quan đến quyết định kiến trúc, gỡ lỗi vấn đề phức tạp, hoặc phát triển tính năng không đơn giản, hãy phân tích từng bước để hiểu vấn đề trước khi viết mã. Trình bày quá trình suy luận của bạn, chỉ ra những điểm chưa chắc chắn, sau đó thực thi.

Hoa hồng hàng tuần về việc lăn ngược các thay đổi không cần thiết: 150 đô la

Đánh giá cặp tay hàng tuần: 75 đô la

Chi phí phát sinh do hành động của mỗi nhà phát triển: 225 đô la/tuần

Nhóm 5 người: 1125 đô la/tuần

Thiết lập thời gian bộ phận hành vi CLAUDE.md: 30 phút

Memory and Tech Stack: Đặt Claude Code thật đáng tin cậy

Claude sẽ quên mọi thứ giữa các phiên trò chuyện.

Mỗi quyết định bạn đã đưa ra, mỗi kế hoạch bạn đã thất bại, tại sao bạn đã chọn Prisma thay vì Drizzle sáu tháng trước, và tại sao một ràng buộc nào đó đến từ yêu cầu cụ thể của khách hàng — tất cả sẽ bị quên.

Sau đó, nó sẽ đề xuất lại những kế hoạch bạn đã loại bỏ từ lâu.

Phần này tương đương với việc cung cấp cơ chế "bộ nhớ thực sự" hiện tại nhất cho Claude, đồng thời khóa công nghệ stack của bạn, ngăn nó tiếp tục đề xuất các công cụ có thể phá hỏng kiến trúc hiện có.

→ MEMORY.md Bản nhật ký Quyết định

Duy trì một tệp có tên MEMORY.md trong dự án. Mỗi khi đưa ra một quyết định quan trọng, thêm một bản ghi mới:

· Quyết định gì;

· Tại sao quyết định như vậy;

· Loại trừ điều gì, và tại sao bị loại trừ.

Mỗi khi bắt đầu phiên làm việc, hãy đọc MEMORY.md trước. Không được xung đột với bất kỳ quyết định nào đã được ghi lại mà không cần nhắc nhở.

→ Tóm tắt Kết thúc Phiên

Khi tôi nói "kết thúc phiên", "kết thúc" hoặc "hãy dừng lại ở đây", vui lòng ghi lại một tóm tắt phiên vào MEMORY.md, bao gồm:

· Đã xử lý điều gì trong phiên này;

· Đã hoàn thành điều gì;

· Đang tiếp tục làm gì;

· Đã đưa ra những quyết định nào;

· Ưu tiên cho phiên tiếp theo.

→ ERRORS.md Bản nhật ký Thất bại

Giữ một tệp có tên ERRORS.md trong dự án. Khi một kế hoạch đã thử nghiệm quá hai lần mà vẫn không thành công, hãy ghi lại:

· Điều gì không thành công;

· Cuối cùng làm thế nào để thành công;

· Cần chú ý vào lần tới điều gì.

Trước khi đề xuất kế hoạch cho một nhiệm vụ tương tự, hãy kiểm tra ERRORS.md trước.

→ Danh sách Sự thật Vĩnh cửu

Các sự thật sau đây luôn đúng cho dự án này và phải được áp dụng mà không được miễn trừ trong mỗi phiên làm việc:

[Ràng buộc vĩnh viễn, Quyết định kiến trúc và Quy tắc]

Nếu một nhiệm vụ xung đột với những sự thật này, xin vui lòng chỉ ra trước khi thực hiện.

→ Bộ công cụ kỹ thuật đã khóa

Bộ công nghệ của dự án này như sau, luôn sử dụng những công cụ này. Đừng gợi ý các giải pháp thay thế trừ khi được yêu cầu rõ ràng:

Ngôn ngữ: [ví dụ TypeScript]

Khung: [ví dụ Next.js 14]

Quản lý gói: [ví dụ pnpm]

Cơ sở dữ liệu: [ví dụ PostgreSQL với Prisma]

Kiểm thử: [ví dụ Vitest]

Phong cách: [ví dụ Tailwind CSS]

Nếu một công cụ nào đó không phù hợp, bạn có thể chỉ ra. Nhưng trừ khi được nêu rõ, bạn phải sử dụng bộ công nghệ đã xác định.

→ Khuyến khích suy nghĩ mở rộng với các quyết định phức tạp

Đối với các vấn đề liên quan đến kiến trúc hệ thống, cân nhắc hiệu suất, thiết kế cơ sở dữ liệu, hoặc các quyết định công nghệ dài hạn, xin vui lòng sử dụng chế độ suy nghĩ mở rộng.

Phân tích vấn đề từng bước, đề xuất các sự hy sinh mà tôi có thể chưa xem xét, chỉ ra giả định có thể không đúng sau khi mở rộng quy mô, sau đó đưa ra lời khuyên của bạn.

→ 4 Nguyên tắc cơ bản để tránh lỗi

Karpathy đã rút ra 4 loại hành vi khiến Claude Code thất bại. Một nhà phát triển đã tóm tắt chúng thành các nguyên tắc sau đây. Độ chính xác mã hóa sau đó từ 65% tăng lên 94%.

Hỏi trước, không giả định.
Nếu có bất kỳ điểm nào không rõ ràng, hãy hỏi trước khi viết dòng code đầu tiên. Đừng giả định về ý định, kiến trúc hoặc yêu cầu mà không nói ra.

Thực hiện giải pháp đơn giản nhất trước.
Luôn thực hiện giải pháp đơn giản nhất có thể hoạt động trước hết. Đừng thêm lớp trừu tượng hoặc linh hoạt không được yêu cầu một cách rõ ràng.

Không chạm vào mã không liên quan.
Nếu một tập tin hoặc hàm nào đó không liên quan trực tiếp đến nhiệm vụ hiện tại, xin đừng sửa đổi. Ngay cả khi bạn nghĩ rằng có thể tối ưu hóa, xin đừng chạm vào.

Chỉ ra một cách rõ ràng sự không chắc chắn.
Nếu bạn không chắc chắn về một giải pháp hoặc chi tiết công nghệ nào đó, xin vui lòng chỉ ra trước khi tiếp tục. Việc tỏ ra chắc chắn mà không có căn cứ sẽ gây hại nhiều hơn việc thừa nhận sự thiếu hiểu biết.

· Chi phí phục hồi hàng tuần do quyết định bị quên và khuyến nghị sai lầm: 300 đô la Mỹ mỗi nhà phát triển

· Khuyến nghị ngăn xếp công nghệ sai lầm và công cụ không tương thích: 75 đô la Mỹ hàng tuần

· Lãng phí liên quan đến trí nhớ mỗi nhà phát triển: 375 đô la Mỹ / tuần

· Đội 5 người: 1875 đô la Mỹ / tuần

· MEMORY.md + ERRORS.md + Thời gian cài đặt ngăn xếp công nghệ: 20 phút

Kết luận

Tổng cộng chi phí như sau:

· Mỗi tuần phải giải thích ngữ cảnh lặp đi lặp lại: 375 đô la Mỹ

· Mỗi tuần phải hoàn tác sự thay đổi không được ủy quyền: 225 đô la Mỹ

· Mỗi tuần phải xử lý vấn đề do quyết định bị quên gây ra: 375 đô la Mỹ

· Tổng lãng phí mỗi nhà phát triển mỗi tuần: 975 đô la Mỹ.

Nếu là đội phát triển 5 người: mỗi tuần 4875 đô la Mỹ. Một năm 253,500 đô la Mỹ.

Và việc thiết lập CLAUDE.md chỉ mất tổng cộng 2 giờ.

Chỉ với 4 quy tắc của Karpathy, tỷ lệ lập trình chính xác đã tăng từ 65% lên 94%.

Một tệp văn bản thuần túy, 21 quy tắc, và 2 giờ làm việc.

Người phát triển thực hiện việc thiết lập này thực tế đang sử dụng một Claude đáng tin cậy hơn: nó có thể nhớ quyết định, kiểm soát phạm vi công việc, yêu cầu xác nhận trước các hoạt động phá hoại và không khuyến nghị bất kỳ khung công nghệ nào có thể phá hủy kiến ​​trúc hiện tại.

Và những người chưa thiết lập vẫn đang chi 975 đô la Mỹ hàng tuần để lặp lại giải thích cho chính mình.

Ghi chú: Bắt đầu bằng 4 quy tắc của Karpathy. Chỉ cần 4 quy tắc này. Bây giờ hãy sao chép và dán chúng vào một tệp mới tên là CLAUDE.md trong thư mục gốc dự án của bạn, chỉ mất 2 phút. Tiếp theo, hàng tuần bổ sung dần dần theo những khoảng trống bạn phát hiện.

Trước khi bị cuốn trôi trong dòng thông tin, hãy đánh dấu lại. Nếu bạn cảm thấy hữu ích, bạn cũng có thể chia sẻ với người thực sự cần nó.

[Liên kết gốc]

Chào mừng bạn tham gia cộng đồng chính thức của BlockBeats:

Nhóm Telegram đăng ký: https://t.me/theblockbeats

Nhóm Telegram thảo luận: https://t.me/BlockBeats_App

Tài khoản Twitter chính thức: https://twitter.com/BlockBeatsAsia