Bài 2.115 phút · 5 thẻ · 8 bài tập · 1 nhiệm vụ

CLAUDE.md: viết gì, không viết gì

Ghi lại điều Claude không tự thấy, viết cụ thể để làm theo được, và giữ file ngắn.

Tuần trước bạn đã sửa bug xóa hai lần trong todo-api. Hôm nay mở phiên mới để thêm endpoint khôi phục việc đã xóa, và bạn lại phải dặn Claude những điều y như tuần trước: chạy test bằng lệnh nào, rằng việc xóa ở đây là xóa mềm, rằng find trả về cả dòng đã xóa. Mỗi phiên Claude Code bắt đầu trắng, nên nếu không ghi lại ở đâu đó, lần nào bạn cũng phải nói lại. Chỗ để ghi lại chính là CLAUDE.md.

CLAUDE.md là gì

CLAUDE.md là một file Markdown bình thường, thường đặt ở gốc dự án. Claude Code đọc nó ở đầu mọi phiên, nên những gì nằm trong file luôn có mặt trong bối cảnh của Claude mà bạn không phải nhắc. File được commit cùng code, nên cả team dùng chung.

Có hai điều cần hiểu đúng ngay từ đầu.

Thứ nhất, CLAUDE.md là bối cảnh, không phải cấu hình bắt buộc. Claude đọc và cố làm theo, thường là làm theo, nhưng không có gì bảo đảm tuyệt đối. Nếu một điều không bao giờ được xảy ra, ví dụ ghi vào thư mục code sinh tự động, thì đó là việc của hook, sẽ học ở cấp 6.

Thứ hai, mỗi dòng trong file chiếm một chút sự chú ý của Claude trong mọi việc, kể cả việc không liên quan. File càng nhiều dòng thừa, những dòng quan trọng càng dễ bị lấn át.

Nên viết gì

Một phép thử đơn giản: chỉ ghi điều Claude không thể tự tìm ra khi đọc code, hoặc điều nó phải mất công đào lại ở mỗi phiên. Theo docs, những thứ đáng ghi thường thuộc bốn nhóm:

  • Cách kiểm tra việc trong repo này: lệnh test, typecheck, lint chính xác, và cách chạy riêng một file test. Có lệnh, Claude tự kiểm tra được việc của mình.
  • Chỗ code dễ gây hiểu lầm: một kiểu viết cũ có ở khắp nơi nhưng code mới không được bắt chước, hay một thư mục trông như bỏ đi mà vẫn đang dùng.
  • Quyết định không nằm trong repo: team đã chốt dùng hàm báo lỗi nào, deploy ra sao, thay đổi nào phải qua review migration.
  • Điều bạn đã phải sửa hai lần.

Docs cũng gợi ý những lúc nên thêm một dòng: Claude mắc cùng một lỗi lần thứ hai; review bắt được điều Claude lẽ ra phải biết; bạn thấy mình gõ lại đúng lời nhắc của phiên trước; hoặc một người mới vào team cũng cần biết đúng bối cảnh đó.

Với todo-api, một file đủ dùng có thể chỉ thế này:

# Commands
- Install: `npm install`
- Test: `npm test`
- One file: `node --test test/todos.test.js`

# Gotchas
- Deletes are soft: set `deletedAt`, never remove rows
- `db.todos.find` also returns soft-deleted rows; check `deletedAt`

Dòng cuối chính là thứ đã gây ra bug tuần trước. Ghi nó vào đây, lần sau Claude sẽ không vấp lại.

Không nên viết gì

Nhiều người viết CLAUDE.md như một bản giới thiệu dự án. Phần lớn nội dung đó là thừa:

  • Cây thư mục, danh sách thư viện, tổng quan kiến trúc. Claude đọc package.json và mở các thư mục là biết. Lệnh /doctor thậm chí còn đề xuất cắt chính những phần này.
  • Câu chung chung không kiểm chứng được, như "hãy viết code sạch".
  • Quy trình nhiều bước, như các bước release. Phần này nên là một skill (cấp 3): Claude chỉ đọc toàn bộ skill khi việc cần tới, nên nó không chiếm chỗ trong mọi phiên.
  • Điều chỉ đúng cho một phần code, như quy tắc riêng cho src/routes/. Phần này nên là một rule theo đường dẫn (bài 2.3), chỉ được nạp khi Claude làm việc với các file khớp.
  • Luật không có ngoại lệ. Viết trong CLAUDE.md thì Claude làm theo gần như mọi lần. Muốn mọi lần, dùng hook.

Viết để Claude làm theo

Claude coi CLAUDE.md là bối cảnh, nên cách viết quyết định nó làm theo ổn định tới đâu. Docs đưa ra mấy cặp so sánh dễ nhớ:

  • "Use 2-space indentation" thay vì "Format code properly".
  • "Run npm test before committing" thay vì "Test your changes".
  • "API handlers live in src/api/handlers/" thay vì "Keep files organized".

Vế đầu kiểm chứng được, vế sau thì không.

Thêm hai thói quen. Một là chia mục bằng tiêu đề và gạch đầu dòng: các mục rõ ràng dễ theo hơn một đoạn văn dày. Hai là giữ nhất quán: nếu hai dòng nói ngược nhau, Claude có thể chọn một trong hai một cách tùy ý.

Một mẹo nhỏ: comment HTML dạng khối như <!-- ghi chú cho người bảo trì --> bị bỏ đi trước khi nội dung tới Claude. Bạn có thể để lại ghi chú cho đồng nghiệp mà không tốn chỗ trong bối cảnh.

Giữ file gọn

Docs khuyên giữ mỗi file CLAUDE.md dưới 200 dòng. File dài hơn vừa tốn bối cảnh vừa làm Claude làm theo kém đi. Khi một file vượt độ dài khuyến nghị, Claude Code hiện cảnh báo lúc khởi động và trong /status.

Có ba công cụ giúp file luôn gọn:

  • /init tạo bản khởi đầu từ codebase. Từ đó việc của bạn chủ yếu là xóa bớt. Bài sau nói kỹ về /init.
  • /doctor đề xuất cắt những gì Claude tự suy ra được từ code.
  • /doctor prompt-audit tìm chỉ dẫn viết cho model đời cũ, trỏ tới file hay lệnh không còn tồn tại, hoặc mâu thuẫn với nhau. Nó chỉ đưa ra báo cáo; file của bạn không đổi cho tới khi bạn bảo áp dụng.

Khi Claude không làm theo

Nếu Claude có vẻ phớt lờ một dòng, kiểm tra theo thứ tự:

  1. File có được nạp không? Gõ /context all và xem danh sách dưới mục Memory files. Không có tên file ở đó thì Claude không thấy nó.
  2. Dòng đó có đủ cụ thể không? Viết lại theo kiểu kiểm chứng được.
  3. Có dòng nào mâu thuẫn không? Tìm trong các file CLAUDE.md khác của dự án.
  4. File có quá dài không? Dòng quan trọng có thể đang bị lấn át.

Đừng vội thêm chữ IMPORTANT viết hoa. Docs nói rõ cách đó hiếm khi giải quyết được: hoặc file đã quá dài, hoặc dòng đó là luật không ngoại lệ và nên chuyển thành hook. Tương tự, dòng "luôn chạy typecheck trước khi xong" giúp Claude biết lệnh để tự kiểm tra; muốn bắt buộc typecheck phải đạt thì cần Stop hook.

Bài sau: CLAUDE.md không chỉ có một file. Có bốn tầng, từ cả công ty tới riêng bạn, cộng thêm phần bộ nhớ Claude tự ghi.

Luyện tập bài 2.1

5 thẻ ghi nhớ, 8 bài tập chấm ngay trên trang, 1 nhiệm vụ làm trên máy.

Bắt đầu luyện tập

Tra cứu liên quan

Gõ để tìm trong tra cứu, mẫu cấu hình và bài học. Không dấu cũng được.