CLAUDE.md: Tệp tin duy nhất giúp phiên làm việc Claude Code nhất quán gấp 10 lần

Nếu bạn đã sử dụng Claude Code được hơn một tuần, có lẽ bạn đã nhận ra vấn đề về sự thiếu nhất quán.

Thứ Hai: Claude nhớ rõ cấu trúc dự án của bạn, tuân theo các quy ước lập trình và biết rằng bạn ưu tiên chế độ nghiêm ngặt (strict mode) của TypeScript.

Thứ Sáu: Cùng một dự án nhưng là một phiên làm việc mới. Claude đề xuất dùng JavaScript. Đưa ra một mô hình mà bạn đã cấm rõ ràng. Quên mất khung kiểm thử (framework) bạn đang dùng.

Vấn đề không nằm ở trí nhớ của Claude, mà là do bạn chưa cung cấp cho nó thông tin cần thiết.

CLAUDE.md thực chất là gì?

CLAUDE.md là một tệp markdown mà bạn đặt tại thư mục gốc (root) của dự án. Claude Code sẽ tự động đọc nó vào đầu mỗi phiên làm việc.

Không có gì phép thuật ở đây. Đó đơn giản là một tệp được thêm vào trước cửa sổ ngữ cảnh (context window) của bạn. Nhưng cơ chế đơn giản này biến nó thành hành động mang lại hiệu quả cao nhất để duy trì sự nhất quán trong các phiên Claude Code.

# Tạo tệp
touch CLAUDE.md

Bây giờ, mỗi khi bạn mở Claude Code trong thư mục đó, Claude sẽ đọc tệp này.

5 phần bắt buộc phải có trong mọi CLAUDE.md

1. Tổng quan dự án (Tối đa 3-5 dòng)

# Project: PaymentService

Microservice Node.js xử lý webhook Stripe và trạng thái đăng ký.
Một phần của monorepo lớn hơn. Dịch vụ này sở hữu lược đồ cơ sở dữ liệu `payments`.
KHÔNG sửa đổi bất cứ thứ gì nằm ngoài /src/payments/.

Phần đơn lẻ này loại bỏ nguồn gốc lớn nhất của sự "lệch pha" (drift) của Claude: không biết ranh giới nằm ở đâu.

2. Ngăn xếp công nghệ (Tech stack - phiên bản cụ thể)

## Stack
- Node.js 20.x (KHÔNG phải 18.x)
- TypeScript 5.4 với strict mode
- Prisma 5.x cho cơ sở dữ liệu (KHÔNG dùng SQL thuần)
- Jest để kiểm thử (KHÔNG dùng Vitest)
- pnpm (KHÔNG dùng npm hay yarn)

Hãy cụ thể. Claude được đào tạo trên hàng triệu mã nguồn và sẽ mặc định sử dụng những gì nó thấy phổ biến nhất. Các ràng buộc của bạn sẽ ghi đè lên điều đó.

3. Quy ước lập trình

## Conventions
- Luôn sử dụng async/await, không bao giờ dùng chuỗi .then()
- Xử lý lỗi: luôn sử dụng mẫu Result<T, E>, không bao giờ throw
- Tất cả cuộc gọi cơ sở dữ liệu phải đi qua /src/db/client.ts - không bao giờ import Prisma trực tiếp
- Hàm tối đa 30 dòng. Nếu dài hơn, hãy tách thành các hàm trợ giúp.
- Không có bình luận giải thích MÃ thực hiện CÁC GÌ. Bình luận chỉ giải thích TẠI SAO.

Đây là nơi bạn mã hóa các quyết định của đội ngũ. Đây là những quy tắc mà lập trình viên mới mất vài tuần để học. Claude có thể học chúng chỉ sau một lần đọc tệp.

4. Những điều KHÔNG nên làm

## Do NOT
- KHÔNG thêm console.log để gỡ lỗi (hãy sử dụng tiện ích logger)
- KHÔNG sửa đổi /src/legacy/ - đây là mã đã đóng băng
- KHÔNG cài đặt gói mới mà không hỏi trước
- KHÔNG sử dụng kiểu `any` trong TypeScript
- KHÔNG thêm bình luận TODO - nếu cần làm, hãy làm ngay hoặc tạo vấn đề trên GitHub

Các ràng buộc tiêu cực thường quan trọng hơn các ràng buộc tích cực. Claude vốn lạc quan theo mặc định — nó sẽ thêm ghi nhật ký, cài đặt gói và sử dụng any khi thấy tiện lợi. Các lệnh cấm rõ ràng sẽ ngăn chặn điều này.

5. Ngữ cảnh hiện tại (Cập nhật thường xuyên)

## Current focus
Đang chuyển đổi từ webhook Stripe v2 sang v3. Tham khảo: /docs/stripe-v3-migration.md
Vấn đề đã biết: tính năng khử trùng webhook bị lỗi trong môi trường sản xuất. Bản sửa lỗi nằm ở PR #447.
KHÔNG chạm vào mã khử trùng cho đến khi PR #447 được hợp nhất.

Phần này thay đổi theo từng tuần. Đây là nơi bạn đặt "nhận thức tình huống" mà sẽ mất 10 phút để giải thích trong mỗi phiên.

Ví dụ thực tế: Trước và Sau

Không có CLAUDE.md:

Bạn: Thêm xử lý lỗi cho webhook thanh toán này Claude: Đây là hàm đã cập nhật. Tôi đã thêm try/catch và console.error để gỡ lỗi, đồng thời sử dụng Promise.then() cho chuỗi bất đồng bộ.

Ba vi phạm trong một phản hồi.

Có CLAUDE.md:

Bạn: Thêm xử lý lỗi cho webhook thanh toán này

Claude: Đây là hàm đã cập nhật sử dụng mẫu Result. Tôi đang sử dụng tiện ích logger của bạn cho các lỗi. Lưu ý: Tôi đã tránh sửa đổi logic khử trùng vì bạn đã đề cập PR #447 đang chờ xử lý.

Bây giờ Claude đang làm việc cùng ngữ cảnh của bạn thay vì chống lại nó.

Nâng cao: Các tệp CLAUDE.md lồng nhau

Claude Code tôn trọng các tệp CLAUDE.md ở nhiều cấp độ:

your-project/
├── CLAUDE.md          # Quy tắc toàn cục cho dự án
├── src/
│   ├── payments/
│   │   └── CLAUDE.md  # Quy tắc riêng cho Thanh toán
│   └── auth/
│       └── CLAUDE.md  # Quy tắc riêng cho Xác thực

Tệp lồng nhau sẽ thêm ngữ cảnh khi bạn làm việc trong thư mục con đó. Các quy tắc toàn cục vẫn được áp dụng.

Điều này rất hữu ích cho các monorepo nơi các gói khác nhau có các quy ước khác nhau.

Vấn đề giới hạn tốc độ với các tệp CLAUDE.md dài

Đây là sự đánh đổi: mỗi dòng trong CLAUDE.md đều tốn token. Trong mỗi phiên. Mãi mãi.

Một tệp CLAUDE.md dài 500 dòng sẽ "ăn" sạch cửa sổ ngữ cảnh của bạn nhanh hơn. Các phiên dài sẽ chạm giới hạn sớm hơn.

Giải pháp là giữ cho CLAUDE.md tập trung: cấu trúc dự án, các quy ước không thể thương lượng, các chặn hiện tại. Hãy chuyển tài liệu chi tiết sang các tệp riêng biệt mà bạn tham chiếu trong CLAUDE.md:

## Architecture
Xem /docs/architecture.md để có sơ đồ hệ thống đầy đủ.
Ràng buộc chính: tất cả cuộc gọi API bên ngoài phải đi qua /src/gateway/ — không bao giờ gọi trực tiếp.

Mẫu bạn có thể sử dụng ngay hôm nay

# Project: [TÊN DỰ ÁN]

[Mô tả 2-3 câu về chức năng và phần sở hữu]

## Stack
- [Runtime + phiên bản]
- [Ngôn ngữ + phiên bản]
- [Các khung chính + phiên bản]
- [Khung kiểm thử]
- [Trình quản lý gói]

## Conventions
- [Mẫu bất đồng bộ]
- [Mẫu xử lý lỗi]
- [Quy tắc tổ chức tệp]
- [Quy ước đặt tên]

## Do NOT
- [Lỗi phổ biến nhất #1]
- [Lỗi phổ biến nhất #2]
- [Các tệp/thư mục đã đóng băng]

## Current focus
[Đang xảy ra gì tuần này. Cập nhật mỗi Thứ Hai.]
[Các PR đang hoạt động mà Claude cần biết]
[Các vấn đề đã biết mà Claude nên tránh chạm vào]

Hãy sao chép cái này. Điền vào cho dự án của bạn. Commit nó. Các phiên làm việc của bạn sẽ ngay lập tức nhất quán hơn.

Một điều nữa

CLAUDE.md cũng hữu ích cho việc hội nhập các lập trình viên con người. Có đồng nghiệp mới? Họ có thể đọc CLAUDE.md của bạn và nhận được sự nhận thức tình huống giống như Claude. Nó buộc bạn phải viết ra các quy tắc bất thành văn.

Tài liệu hóa cho AI. Nhận tài liệu có thể đọc được cho con người miễn phí.