Bài 3 trong loạt Vibe Code A to Z — hướng dẫn vibe code bằng Claude Code cho người Việt. Bài 2: phiên làm việc đầu tiên.
Mỗi phiên làm việc mới, Claude Code mở ra với đầu óc trắng tinh. Nó không nhớ hôm qua bạn dặn gì, không nhớ dự án này có quy ước gì, không nhớ cái lỗi tuần trước hai bên đã mất buổi chiều để lần ra.
Cách chữa nghe hiển nhiên: viết hết ra một file cho nó đọc mỗi lần bắt đầu. File đó tên là CLAUDE.md, và nó có thật.
Chỗ phản trực giác nằm ở bước sau. Viết càng nhiều vào file đó, nó càng ít làm theo. Tài liệu chính thức của Anthropic nói thẳng: file dài hơn tiêu tốn nhiều context hơn và giảm mức độ tuân thủ. Khuyến nghị là dưới 200 dòng.
File CLAUDE.md của website tôi đang chạy: 496 dòng. Gấp hai lần rưỡi mức khuyến nghị.
CLAUDE.md là gì, và nó không phải cái gì
Đây là file văn bản thường, viết bằng lời thường, đặt ở gốc dự án. Đầu mỗi phiên Claude Code đọc nó và coi như bối cảnh nền: dự án này chạy bằng gì, lệnh nào để khởi động, file nào đặt ở đâu, quy ước nào không được phá.
Thứ nó không phải: luật. Tài liệu gọi đây là context, không phải cấu hình cưỡng chế. Claude đọc và cố làm theo, nhưng không có gì bảo đảm nó tuân thủ tuyệt đối, nhất là với những câu dặn mơ hồ hoặc tự đá nhau. Việc nào bắt buộc phải xảy ra — chạy kiểm tra trước mỗi lần commit chẳng hạn — thì phải dùng cơ chế khác cứng hơn, không trông vào một dòng dặn dò.
Hiểu đúng chỗ này quan trọng. CLAUDE.md không phải hợp đồng bạn ký với nhân viên. Nó là bản mô tả công việc dán trên tường: người ta đọc, người ta nhớ phần lớn, nhưng bạn vẫn phải có chốt kiểm.
Bốn tầng, và tầng nào dành cho ai
File này đặt được ở nhiều nơi, mỗi nơi một phạm vi. Từ rộng tới hẹp:
Tầng cá nhân — `~/.claude/CLAUDE.md`. Nằm trong thư mục người dùng của bạn, áp cho mọi dự án trên máy. Đây là chỗ ghi cách bạn muốn làm việc: dặn nó lập kế hoạch trước khi sửa, dặn nó đừng thêm thư viện ngoài khi chưa hỏi, dặn nó trả lời gọn. Viết một lần, mọi dự án về sau đều thừa hưởng.
Tầng dự án — `./CLAUDE.md` ở gốc dự án. Chỗ ghi thứ thuộc về dự án chứ không thuộc về bạn: lệnh chạy, cấu trúc thư mục, quy ước đặt tên, những cạm bẫy đã gặp. File này đi cùng dự án vào git, nên người khác mở dự án cũng được thừa hưởng.
Tầng riêng tư — `./CLAUDE.local.md`. Cùng gốc dự án nhưng thêm vào `.gitignore`, dành cho thứ chỉ đúng với máy bạn: đường dẫn cục bộ, dữ liệu thử, ghi chú tạm.
Tầng tổ chức thì dành cho công ty triển khai hàng loạt qua hệ thống quản trị máy — người dùng cá nhân không cần quan tâm.
Các file này không ghi đè nhau, chúng cộng dồn theo thứ tự từ rộng đến hẹp. Nên nếu tầng cá nhân dặn một kiểu mà tầng dự án dặn kiểu khác, bạn vừa tạo ra một mâu thuẫn — và tài liệu nói rõ khi hai câu dặn đá nhau, Claude có thể chọn bừa một bên.
Cái bẫy tôi phát hiện trong chính dự án của mình
Dự án website của tôi có hai file dặn dò: `CLAUDE.md` và `AGENTS.md`. `AGENTS.md` là chuẩn dùng chung cho nhiều công cụ AI khác, và trong đó tôi đặt đúng cái quy tắc quan trọng nhất với mình — bắt buộc đọc file quy tắc viết nội dung trước khi viết một chữ nào phát hành dưới tên tôi.
Vấn đề: Claude Code không đọc `AGENTS.md`. Tài liệu ghi rõ một câu — nó đọc `CLAUDE.md`, không đọc `AGENTS.md`. Suốt thời gian đó tôi tưởng đã dặn, thực tế chưa dặn được gì.
Cách chữa mất một dòng: trong `CLAUDE.md`, thêm dòng import trỏ sang file kia, viết đúng là `@AGENTS.md`.
Cú pháp `@` này nạp nội dung file được trỏ vào cùng lúc với CLAUDE.md, và dùng được cho bất cứ file nào — tài liệu kỹ thuật, quy ước viết, hướng dẫn quy trình. Đi được tối đa bốn tầng import lồng nhau, quá thì nó dừng.
Bài học không nằm ở cú pháp. Nó nằm ở chỗ: dặn rồi và nó nhận được lời dặn là hai chuyện khác nhau. Trong phiên bất kỳ, gõ `/context` là thấy danh sách file dặn dò đã nạp thật vào phiên đó. Tên file không có trong danh sách nghĩa là bạn đang nói với tường.
Hai bộ nhớ, một do bạn viết một do nó viết
Chỗ này ít người biết. Song song với CLAUDE.md, Claude Code còn một cơ chế thứ hai gọi là auto memory: nó tự ghi lại những gì học được về dự án của bạn — lệnh build, chỗ hay hỏng, cách bạn thích làm việc — rồi nạp lại ở phiên sau. Mặc định bật.
Phân vai rất rõ và nên tôn trọng: CLAUDE.md là chỗ bạn viết luật chơi; auto memory là chỗ nó ghi những gì rút ra từ lần bạn sửa lưng nó. Bạn không cần chép tay việc nó tự nhớ, và nó không tự viết vào CLAUDE.md của bạn.
Gõ `/memory` trong phiên là xem được toàn bộ: file dặn dò của bạn ở đâu, cái nó tự nhớ có những gì, sửa hay xóa được ngay. Tôi khuyên nên mở ra xem một lần cho biết — đọc thứ một cỗ máy tự ghi chú về cách làm việc của mình là một trải nghiệm hơi lạ, và đôi khi hơi chính xác quá.
Cách viết để nó thật sự nghe
Ba tiêu chí, theo đúng tài liệu chính thức, và cả ba đều là chuyện cắt bớt chứ không phải thêm vào.
Cụ thể tới mức kiểm chứng được. "Dùng thụt lề 2 dấu cách" thắng "định dạng code cho gọn gàng". "Chạy `npm test` trước khi commit" thắng "nhớ kiểm tra kỹ". Câu nào đọc xong vẫn phải đoán ý thì viết lại.
Ngắn. Dưới 200 dòng. Dài hơn thì cắt, hoặc chia ra thành nhiều file nhỏ đặt trong `.claude/rules/`, mỗi file một chủ đề và chỉ nạp khi Claude làm việc với đúng loại file đó. Đây là cách chữa cho file 496 dòng của tôi, và là việc tôi còn nợ chính mình.
Chỉ giữ thứ nó không tự tìm ra được. Cấu trúc thư mục, danh sách thư viện, sơ đồ kiến trúc — nó tự đọc code là biết, viết vào chỉ tốn chỗ. Thứ đáng giữ là cạm bẫy đã gặp, lý do đằng sau một quyết định, và quy ước khác với mặc định của công cụ. Nói cách khác: giữ phần một người mới vào dự án sẽ hỏi, bỏ phần họ tự đọc là thấy.
Có một mẹo nhỏ và dễ chịu: ghi chú dạng chú thích HTML kiểu `<!-- như thế này -->` bị lược bỏ trước khi nội dung vào context. Bạn để lại lời nhắc cho chính mình trong file mà không tốn một chữ nào của Claude.
Chưa có file nào thì đừng ngồi viết từ đầu. Gõ `/init`, Claude đọc dự án rồi tự dựng một bản nháp có lệnh chạy và quy ước nó tìm thấy. Việc của bạn là sửa lại và bổ sung những thứ nó không thể tự biết.
Tài liệu tải về
Tôi gói sẵn một bộ CLAUDE.md dùng được ngay: file mẫu chia đúng các mục nên có kèm chú thích điền vào đâu, một bản CLAUDE.local.md cho phần riêng tư, một ví dụ chia rule theo loại file cho dự án đã phình to, và hướng dẫn kiểm tra file đã nạp thật hay chưa. Tải về, điền tên dự án và lệnh chạy, là xong phần khung.
📥 Tải miễn phí
Bộ CLAUDE.md Dùng Ngay
Tài liệu do tôi biên soạn từ trải nghiệm thật, tham khảo tài liệu chính thức của Anthropic tại code.claude.com/docs. Công cụ này thay đổi rất nhanh — khi có nghi ngờ, bản gốc tiếng Anh luôn là nguồn đúng nhất. Còn cách quyết định giữ gì và bỏ gì khi giao việc cho AI thì nằm ở phần nền trong khóa AI Fluency.
Điều tôi nhận ra
Tôi từng nghĩ viết CLAUDE.md là việc dặn dò, nên càng dặn kỹ càng tốt. Hóa ra nó là việc chọn: mỗi dòng thêm vào là một dòng làm loãng những dòng còn lại, và cái file 496 dòng của tôi là bằng chứng cho việc tôi đã chọn không kỹ.
Người quản lý giỏi không phải người dặn nhiều nhất. Là người biết ba điều gì phải nói, và chấp nhận không nói phần còn lại.
Nhưng đó là dặn dò cho cả dự án, viết một lần dùng mãi. Còn cách nói với nó trong từng việc cụ thể — thứ khiến cùng một câu yêu cầu ra hai kết quả khác nhau trời vực — lại là một kỹ năng riêng, và là chuyện của bài sau.
Tư duy làm việc với AI ở tầm chuyên gia — AI Fluency