Viết file CLAUDE.md cho Claude Code: ghi lệnh build, test, commit để phiên nào cũng có sẵn

Tóm tắt nhanh
File hướng dẫn dự án của Claude Code là CLAUDE.md, đặt ở thư mục gốc. Bạn ghi vào đó lệnh build, lệnh chạy test và quy ước commit thật của dự án, để mỗi phiên mới có sẵn bối cảnh mà không phải nhắc lại. Có thể gõ /init để tạo bản đầu, nhưng phải kiểm tra và thay lệnh sai bằng lệnh thật.
Có. Một dự án thực tế nên có một file hướng dẫn riêng cho Claude Code, tên là CLAUDE.md, đặt ở thư mục gốc của dự án. Trong đó bạn ghi ba thứ cốt lõi: cách build, cách chạy test và quy ước commit. Theo mô tả của tập này, mỗi phiên mới sẽ đọc file đó trước khi bắt đầu làm việc, nên bạn không phải gõ lại cùng một đoạn dặn dò mỗi lần.
Vì sao đáng quan tâm? Vì Claude Code giống một đồng nghiệp mới vào dự án mỗi sáng. Nó giỏi, nhưng nó không nhớ hôm qua bạn dặn gì. Nếu bạn không nói dự án chạy test bằng lệnh nào, nó sẽ đoán. Đoán đúng thì may, đoán sai thì bạn mất công sửa, hoặc tệ hơn là nó báo “đã test xong” bằng một lệnh không phải lệnh thật của dự án.
Bài này đi sâu hơn video ngắn bên dưới: file này hoạt động thế nào, nên ghi dòng nào và không nên ghi dòng nào, cách kiểm tra bản tự sinh, ba tình huống dùng thật, cái giá phải trả và những lỗi người mới hay mắc. Bài nằm trong series giao việc rõ, kiểm tra kỹ với Claude Code. Các tập khác đã nói về cách giao việc và cách đọc lại thay đổi trước khi commit. Ở đây mình chỉ tập trung vào chuyện “bối cảnh có sẵn”.
I.Bản chất của file hướng dẫn dự án
A.Nó là gì và chạy thế nào
CLAUDE.md là một file văn bản thường, viết bằng Markdown, nằm trong thư mục gốc dự án. Bạn mở bằng trình soạn thảo nào cũng được. Không có cú pháp đặc biệt nào bắt buộc: bạn viết như viết ghi chú cho người mới vào nhóm.
Điểm quan trọng là cách nó được dùng. Khi bạn mở một phiên mới trong thư mục dự án (gõ claude), Claude Code nạp nội dung file này vào bối cảnh của phiên đó. Nghĩa là những dòng bạn viết trở thành thứ Claude “đã biết” ngay từ câu đầu tiên, trước cả khi bạn giao việc.
Hãy hình dung một cuốn sổ tay nhận việc đặt sẵn trên bàn. Người mới đến, đọc sổ, rồi mới hỏi bạn. Cuốn sổ không làm người đó giỏi hơn, nhưng nó tránh cho bạn phải giải thích lại từ đầu những điều không đổi.
B.Khác gì so với việc nhắc trong khung chat
Cách quen thuộc là mỗi phiên bạn gõ: “Dự án này chạy test bằng lệnh abc, nhớ commit theo kiểu xyz nhé”. Cách này có ba nhược điểm.
- Dễ quên. Bạn đang vội, bỏ một dòng, và phiên đó Claude làm theo thói quen chung thay vì thói quen của dự án.
- Không nhất quán. Hôm nay bạn viết một kiểu, mai viết kiểu khác. Người khác trong nhóm lại dặn kiểu thứ ba.
- Không có chỗ để sửa tập trung. Khi lệnh đổi, bạn phải nhớ dặn lại ở mọi nơi.
File hướng dẫn giải quyết cả ba: viết một lần, nằm cạnh mã nguồn, ai mở dự án cũng thấy cùng một bản. Nó còn có lợi ích phụ là buộc bạn nói rõ những điều mà lâu nay chỉ nằm trong đầu mình.
C.Bản chất là “bối cảnh”, không phải “ép buộc”
Cần hiểu đúng một điều: file này là thông tin đưa cho Claude, không phải cơ chế cưỡng chế. Nó giúp Claude làm đúng, nhưng không đảm bảo tuyệt đối. Nếu có quy tắc mà vi phạm là nguy hiểm (ví dụ không được đụng vào dữ liệu thật), bạn vẫn cần dựa vào quyền truy cập và việc bạn đọc lại kết quả, không chỉ dựa vào một dòng chữ trong file.
II.Làm thế nào viết một file hướng dẫn dùng được
- Tạo bản đầuMở Claude Code trong thư mục gốc dự án, gõ /init nếu chưa có CLAUDE.md
- Ghi lệnh buildViết đúng lệnh bạn vẫn gõ để dựng dự án
- Ghi lệnh testViết đúng lệnh chạy test, kèm một dòng nói khi nào cần chạy
- Ghi quy ước commitMô tả cách đặt tên thông điệp commit của nhóm bạn
- Kiểm tra bản tự sinhThay mọi lệnh sai hoặc đoán bằng lệnh thật của dự án
- Thử bằng phiên mớiMở phiên mới, nhờ Claude chạy test và xem nó dùng lệnh nào
A.Bắt đầu bằng /init, rồi sửa lại
Nếu dự án chưa có file, bạn mở Claude Code trong thư mục gốc rồi gõ /init. Claude sẽ nhìn vào dự án và tạo ra bản đầu của CLAUDE.md. Đây là cách nhanh nhất để có khung.
Nhưng hãy coi đó là bản nháp. Bản tự sinh được suy ra từ những gì Claude nhìn thấy trong dự án, nên có thể chứa lệnh nghe hợp lý mà không phải lệnh bạn thật sự dùng. Video nhấn mạnh đúng điểm này: bản tự sinh cần kiểm tra, thay lệnh sai bằng lệnh thật của dự án.
Cách kiểm tra đơn giản: đọc từng dòng, tự hỏi “mình có gõ đúng lệnh này không?”. Dòng nào bạn không chắc, tự chạy thử trong cửa sổ dòng lệnh. Dòng nào chạy lỗi thì sửa hoặc xoá.
B.Ghi lệnh cụ thể, đừng ghi ý chung chung
Đây là phần quan trọng nhất. Ví dụ giả định trong video: nếu dự án dùng npm test, bạn ghi “Test: npm test”. Còn chỉ ghi “chạy test” thì chưa đủ, vì Claude vẫn phải đoán chạy bằng gì.
Một đoạn mẫu giả định cho dự án dùng npm:
## Lệnh thường dùng
- Build: npm run build
- Test: npm test
- Chạy thử ở máy: npm run dev
## Quy ước commit
- Thông điệp ngắn, viết tiếng Việt, bắt đầu bằng động từ
- Mỗi commit chỉ làm một việc
- Không commit khi test chưa quaĐây chỉ là ví dụ giả định. Dự án của bạn có thể dùng công cụ khác, lệnh khác. Điều cần học là hình dạng: mỗi dòng là một việc cụ thể kèm đúng lệnh để làm việc đó.
C.Ghi quy ước commit ở mức đủ dùng
Quy ước commit không cần dài. Ba đến năm dòng là đủ: ngôn ngữ thông điệp, độ dài, kiểu mở đầu, và việc có gộp nhiều thay đổi vào một commit hay không. Nếu nhóm bạn có mẫu thông điệp riêng, dán một hai ví dụ thật vào. Ví dụ thật có sức nặng hơn mô tả dài.
D.Thêm những thứ mà người mới hay vấp
Ngoài ba mục cốt lõi, bạn có thể thêm vài dòng đáng giá:
- Thư mục nào không được sửa (mã sinh tự động, thư mục dữ liệu).
- Cần dựng môi trường thế nào trước khi chạy test (ví dụ phải cài gói trước).
- Một câu mô tả dự án làm gì, để Claude hiểu mục đích.
Nhưng đừng ôm hết. Càng dài, càng khó bảo trì, và càng dễ có dòng lỗi thời.
E.Thử bằng một phiên mới
Sửa xong, đóng phiên cũ, mở phiên mới bằng claude và nhờ: “Chạy test giúp mình”. Nếu Claude dùng đúng lệnh bạn đã ghi mà không hỏi lại, file đang làm việc. Nếu nó dùng lệnh khác, quay lại xem dòng đó có rõ chưa.
Không ghi mật khẩu, khoá truy cập hay chuỗi kết nối dữ liệu thật vào file hướng dẫn. File này nằm trong thư mục dự án, thường được commit và chia sẻ cho cả nhóm. Chỉ ghi tên biến môi trường cần thiết, không ghi giá trị thật.
III.Dùng vào việc thật
A.Chủ shop có website bán hàng nhỏ
Chị Lan thuê người làm website bán hàng, giờ tự chỉnh vài thứ nhỏ cùng Claude Code. Mỗi lần mở phiên, chị lại quên nhắc cách chạy kiểm tra, nên Claude sửa xong mà không biết cách thử. Chị tạo CLAUDE.md và ghi lại những điều người làm web đã chỉ chị.
Đọc CLAUDE.md ở thư mục gốc. Sau đó đổi dòng chữ “Miễn phí vận chuyển từ 500k” trên trang giỏ hàng thành “Miễn phí vận chuyển từ 700k”. Sửa xong hãy chạy test theo lệnh trong CLAUDE.md và báo mình kết quả, kèm danh sách file đã đổi.Kết quả nhận được: Claude sửa đúng chỗ, chạy lệnh test đã ghi, báo qua hay lỗi. Chị Lan không cần nhớ lệnh nào.
Chỗ cần kiểm tra lại: mở trang giỏ hàng ở bản chạy thử xem chữ đã đổi chưa, và xem có chỗ nào khác còn ghi con số cũ không (email xác nhận, trang giới thiệu). Test qua không có nghĩa là mọi chỗ đã đúng, nhất là khi dự án ít test.
B.Dev mới nhận lại dự án của người khác
Anh Hải nhận một dự án từ đồng nghiệp đã nghỉ. Không ai nhớ rõ cách dựng môi trường. Anh dùng /init để có bản đầu, rồi vừa đọc mã vừa chạy thử để sửa file cho đúng.
Mình vừa tạo CLAUDE.md bằng /init. Hãy đọc file này, rồi liệt kê từng lệnh build và test mà file nêu. Với mỗi lệnh, cho mình biết bạn dựa vào đâu trong dự án để ghi như vậy, và lệnh nào bạn không chắc. Chưa chạy lệnh nào, chỉ liệt kê.Kết quả: một danh sách lệnh kèm căn cứ và các điểm Claude không chắc. Anh Hải tự chạy thử từng lệnh, sửa file theo kết quả thật, rồi để lại cho người sau một bản đã kiểm chứng.
Chỗ cần kiểm tra lại: căn cứ Claude nêu có thể nghe thuyết phục mà vẫn sai. Lệnh nào chưa tự chạy thử thì chưa coi là đúng. Làm xong mục này, anh nên commit file như một thay đổi riêng để lịch sử rõ ràng.
C.Nhân viên văn phòng giữ bộ script xử lý bảng tính
Chị Mai ở phòng kế toán có một thư mục script nhỏ do mình viết cùng Claude, dùng để gộp và làm sạch file bảng tính hàng tháng. Mỗi tháng chị mở lại, quên mất cách chạy và thứ tự các bước.
Đọc CLAUDE.md. Sau đó chạy bước làm sạch dữ liệu theo đúng lệnh ghi trong file, trên thư mục mẫu “thang-mau”, không động vào thư mục “thang-that”. Báo mình số dòng đầu vào, số dòng đầu ra và dòng nào bị loại.Kết quả: Claude chạy đúng lệnh, tách rõ dữ liệu mẫu và dữ liệu thật, trả số liệu để chị đối chiếu. Trong CLAUDE.md chị đã ghi sẵn dòng “Luôn thử trên thư mục mẫu trước”.
Chỗ cần kiểm tra lại: so số dòng vào và ra với bảng gốc, mở vài dòng bị loại xem có đúng là dòng cần loại không. Với dữ liệu thật của công ty, hãy đọc kỹ phần cảnh báo ở dưới về dữ liệu nhạy cảm trước khi để AI chạm vào.
IV.Góc nhìn khách quan
A.Điểm mạnh thật sự
Giá trị lớn nhất là bỏ được việc lặp. Bạn viết một lần, mọi phiên sau hưởng lợi. Với người hay mở nhiều phiên ngắn, khác biệt thấy rõ ngay.
Giá trị thứ hai là ép bạn nói rõ điều ngầm hiểu. Khi phải viết “Test: npm test”, bạn nhận ra mình chưa từng viết ra lệnh đó ở đâu cả. Nhiều nhóm phát hiện tài liệu của dự án thiếu chính những dòng này.
Giá trị thứ ba là người mới cũng đọc được. File nằm cạnh mã nguồn, nên đồng nghiệp mới vào nhóm cũng đọc được và hiểu cách chạy dự án, không chỉ Claude.
Một file hướng dẫn tốt không làm Claude thông minh hơn, nó chỉ làm Claude bớt phải đoán.
Ông T
B.Giới hạn và rủi ro
Trước hết, file có thể lỗi thời. Lệnh đổi mà file không đổi thì Claude vẫn làm theo lệnh cũ, và bạn có thể không để ý vì mọi thứ trông vẫn “có vẻ đúng”. Hãy coi CLAUDE.md như mã nguồn: sửa dự án thì sửa luôn file.
Thứ hai, bản tự sinh có thể sai. Đây là điểm video đã cảnh báo. Lệnh đoán mà không kiểm chứng sẽ tạo cảm giác an toàn giả.
Thứ ba, file dài tốn chỗ trong bối cảnh. Nội dung file được nạp vào mỗi phiên, nên viết dài dòng làm bối cảnh nặng hơn và làm những dòng quan trọng bị chìm. Gói trả phí và hạn mức dùng của bạn cũng tính theo lượng dùng, nên không có lý do gì để nhét vào những thứ không cần.
Thứ tư, bảo mật và dữ liệu. File thường được commit, nên bất cứ gì bạn ghi vào đều đi theo kho mã. Không ghi khoá truy cập, mật khẩu hay thông tin khách hàng. Và nhớ rằng file không thay thế việc kiểm soát quyền truy cập thật: nếu có thư mục không được đụng, đừng chỉ dựa vào một dòng nhắc.
Cuối cùng, không đảm bảo tuyệt đối. Đây là bối cảnh, không phải luật máy móc. Claude thường làm theo, nhưng bạn vẫn là người đọc lại kết quả.
C.Khi nào nên chọn cách khác
Nếu bạn chỉ hỏi một câu rồi thôi, hoặc làm việc một lần với một file lẻ, không cần tạo file hướng dẫn. Cứ nói thẳng trong khung chat là nhanh hơn.
Nếu quy ước của bạn thay đổi theo từng việc (hôm nay làm báo cáo, mai sửa mã), hãy để phần đó trong câu giao việc, còn CLAUDE.md chỉ giữ những điều ổn định.
Nếu nhóm bạn đã dùng công cụ khác như ChatGPT, Codex CLI, Gemini CLI, Cursor hay GitHub Copilot, nguyên tắc vẫn đáng mượn: viết ra cách build, test và quy ước ở một chỗ cố định cho người và máy cùng đọc. Cách mỗi công cụ nạp file đó khác nhau, bạn nên xem tài liệu của chính công cụ đó thay vì mặc định nó chạy giống Claude Code.
V.Lỗi hay gặp và cách tránh
Tin bản tự sinh mà không đọc. Gõ /init xong là để nguyên. Cách tránh: coi đó là nháp, đọc từng dòng, tự chạy thử các lệnh, thay lệnh sai bằng lệnh thật.
Ghi “chạy test” mà không ghi lệnh. Nghe rõ với người, nhưng Claude vẫn phải đoán. Cách tránh: mỗi dòng gồm tên việc và đúng lệnh, ví dụ “Test: npm test” nếu dự án của bạn dùng npm.
Viết quá dài. Dán cả tài liệu nội bộ vào file. Cách tránh: chỉ giữ những gì Claude cần cho mọi phiên. Phần còn lại để ở tài liệu riêng và chỉ nhắc khi cần.
Quên cập nhật. Đổi công cụ build mà file vẫn ghi lệnh cũ. Cách tránh: tạo thói quen, mỗi lần đổi cách build hoặc test thì sửa file trong cùng một commit.
Ghi thông tin bí mật. Dán khoá truy cập vào cho tiện. Cách tránh: chỉ ghi tên biến môi trường, không ghi giá trị; nếu lỡ commit, coi khoá đó là đã lộ và thay mới.
VI.Dự phóng: chủ đề này sẽ đi về đâu
Đây là nhận định của Ông T dựa trên hướng đi chung của các công cụ lập trình bằng AI, không phải tin chính thức và không nhắc tới sản phẩm hay mốc thời gian cụ thể nào.
File hướng dẫn dự án thành thói quen chung của công cụ AI. Mức chắc chắn: khả năng cao. Lý do: bất kỳ agent nào làm việc qua nhiều phiên đều gặp cùng một vấn đề là không nhớ giữa các phiên, và một file nằm cạnh mã nguồn là cách rẻ nhất để giải quyết. Bạn nên chuẩn bị bằng cách viết sẵn thông tin dự án ở dạng văn bản rõ ràng, để dùng được với nhiều công cụ.
Bản tự sinh ngày càng tốt, nhưng vẫn cần người duyệt. Mức chắc chắn: có thể. Lý do: khả năng đọc dự án của AI tăng dần, nên bản nháp sẽ ít sai hơn. Nhưng lệnh nào “thật sự được dùng” thường là thói quen của người trong nhóm, không phải lúc nào cũng nằm trong mã. Bạn nên giữ thói quen tự chạy thử từng lệnh.
File hướng dẫn sẽ nhiều tầng hơn: cá nhân, nhóm, từng thư mục con. Mức chắc chắn: có thể. Lý do: dự án lớn có nhiều phần với quy ước khác nhau, một file duy nhất sẽ phình to. Cách tổ chức cụ thể thì mình chưa khẳng định. Bạn nên bắt đầu bằng tách “điều ai cũng cần biết” khỏi “điều chỉ liên quan một phần”.
Tự động kiểm tra file có lỗi thời không. Mức chắc chắn: còn bỏ ngỏ. Lý do: bài toán đã rõ (lệnh trong file không còn chạy được), nhưng chưa rõ ai sẽ làm và làm thế nào. Trong lúc chờ, bạn có thể tự làm một việc đơn giản: định kỳ nhờ Claude chạy thử từng lệnh trong file và báo lệnh nào lỗi.
VII.Bắt đầu từ đâu
Bạn không cần viết file hoàn hảo. Một file ngắn nhưng đúng lệnh có ích hơn một file dài mà sai. Mục tiêu của tập này rất nhỏ: phiên nào mở ra cũng có sẵn lệnh test, khỏi gõ lại.
Ba việc bạn làm được ngay hôm nay:
- Mở Claude Code trong thư mục gốc dự án (gõ
claude). Nếu chưa có CLAUDE.md, gõ/initđể lấy bản đầu. Nếu đã có, mở ra đọc. - Ghi đúng ba dòng: lệnh build, lệnh test và một hai dòng quy ước commit. Tự chạy từng lệnh để chắc chắn chúng chạy được, rồi thay mọi lệnh sai bằng lệnh thật.
- Đóng phiên, mở phiên mới, nhờ Claude chạy test. Nếu nó dùng đúng lệnh bạn đã ghi, bạn xong. Nếu chưa, sửa dòng đó rồi thử lại.
Bạn vướng mục nào trong ba việc này, cứ để lại bình luận dưới video nhé.
Câu hỏi thường gặp
File hướng dẫn dự án của Claude Code tên là gì và đặt ở đâu?
File tên là CLAUDE.md và đặt ở thư mục gốc của dự án. Khi bạn mở phiên mới trong thư mục đó, Claude Code đọc nội dung file này làm bối cảnh trước khi bắt đầu làm việc.
Chưa có file thì tạo thế nào?
Mở Claude Code trong thư mục gốc dự án và gõ /init để tạo bản đầu. Sau đó bạn cần đọc lại và sửa. Bản tự sinh chỉ là bản nháp, có thể chứa lệnh chưa đúng với dự án của bạn.
Nên ghi những gì trong file?
Tối thiểu là cách build, cách chạy test và quy ước commit. Mỗi mục ghi bằng lệnh hoặc quy tắc cụ thể, ví dụ “Test: npm test” nếu dự án dùng npm. Chỉ ghi “chạy test” thì chưa đủ.
Tại sao phải kiểm tra bản /init tự sinh?
Vì bản đó được suy ra từ những gì Claude nhìn thấy, nên có thể ghi lệnh nghe hợp lý nhưng không phải lệnh bạn thật sự dùng. Hãy tự chạy thử từng lệnh và thay lệnh sai bằng lệnh thật của dự án.
File này có đảm bảo Claude luôn làm đúng không?
Không. Nó là bối cảnh giúp Claude làm đúng hơn, không phải cơ chế cưỡng chế tuyệt đối. Bạn vẫn cần đọc lại kết quả, và với việc nhạy cảm thì phải dựa vào quyền truy cập thật chứ không chỉ một dòng nhắc.
Có nên ghi mật khẩu hay khoá truy cập vào file không?
Không nên. File nằm trong thư mục dự án và thường được commit, chia sẻ cho cả nhóm. Chỉ ghi tên biến môi trường cần có, không ghi giá trị thật.
File dài có tốt hơn không?
Thường là không. Nội dung được nạp vào mỗi phiên nên càng dài càng nặng, và dòng quan trọng dễ bị chìm. Mình khuyên giữ những điều ổn định, ai cũng cần biết, còn lại đưa vào câu giao việc khi cần.


