Cơn ác mộng ngữ cảnh lúc 2 giờ sáng
Lúc đó là 2:14 sáng. Bạn đang nhìn chằm chằm vào cửa sổ terminal tràn ngập những dòng thông báo lỗi màu đỏ. Một bug production vừa xuất hiện và bạn đang trông cậy vào một trợ lý AI để giúp vá lỗi trước khi ca sáng bắt đầu. Vấn đề là gì? AI liên tục gợi ý lệnh npm run dev, nhưng dự án cũ của bạn lại sử dụng lệnh make shell tùy chỉnh. Nó liên tục đưa ra các class Tailwind CSS trong khi team của bạn chỉ sử dụng CSS Modules. Mỗi câu lệnh (prompt) bạn viết đều bắt đầu bằng 400 từ kiểu “đừng làm thế này” và “hãy dùng cái kia thay thế”.
Lãng phí token và việc phải sửa lỗi liên tục cho AI sẽ giết chết năng suất. Bạn cuối cùng phải dành nhiều năng lượng để quản lý các giả định của AI hơn là thực sự sửa code. Một file CLAUDE.md sẽ giải quyết vấn đề này. Nó đóng vai trò là nguồn sự thật duy nhất (source of truth) xác định chính xác cách dự án của bạn build, test và mở rộng.
Bắt đầu nhanh: File CLAUDE.md đầu tiên trong 5 phút
Bạn không cần một cấu hình phức tạp để thấy ngay kết quả. CLAUDE.md đơn giản là một file Markdown nằm trong thư mục gốc của dự án. Các công cụ hiện đại như CLI Claude Code của Anthropic và extension Cline sẽ tự động tìm kiếm file này để điều chỉnh hành vi của chúng.
Hãy tạo file và đưa vào cấu trúc thiết yếu sau:
# Ngữ cảnh dự án: API Cổng thanh toán
## Build & Phát triển
- Build: `make build`
- Test: `pytest tests/unit`
- Lint: `flake8 .`
- Local Dev: `docker-compose up`
## Tiêu chuẩn lập trình
- Sử dụng Python Type Hints cho tất cả các function signature.
- Ưu tiên `async/await` thay vì threading cho các tác vụ I/O-bound.
- Lỗi: Sử dụng custom exception từ `src/core/exceptions.py`.
- Docs: Chỉ sử dụng Google-style docstrings.
## Kiến trúc
- Pattern: Hexagonal / Ports and Adapters.
- Logic nghiệp vụ (Domain logic) nằm trong `src/domain`.
- Logic cơ sở dữ liệu nằm trong `src/infrastructure/db`.Khi file này tồn tại, AI sẽ ngừng đoán mò. Nó biết trình chạy test, quy tắc linting và các ranh giới kiến trúc của bạn ngay từ tin nhắn đầu tiên.
Tại sao chiến lược này hiệu quả
Ngay cả với cửa sổ ngữ cảnh (context window) lên đến 200k token, các LLM vẫn có thể bị lạc lối trong mớ hỗn độn của một codebase đồ sộ. Việc cung cấp CLAUDE.md tạo ra một bản đồ mật độ cao cho mô hình. Thay vì AI phải quét 500 file để suy luận ra các pattern của bạn, nó sẽ đọc bản đồ trước.
Phần Build & Test
Đây là trung tâm điều khiển cho các agent tự hành. Nếu AI không thể chạy test, nó không thể xác minh công việc của chính mình. Tôi nhận thấy rằng việc bao gồm bốn loại lệnh cụ thể này giúp giảm gần 90% các lệnh “ảo giác”:
- Cài đặt dependency: (ví dụ:
poetry installso vớipip install). - Kiểm thử chi tiết: Cách chạy một file test đơn lẻ so với toàn bộ suite.
- Thiết lập dữ liệu: Các lệnh để seed cơ sở dữ liệu hoặc chạy migration.
- Dọn dẹp: Cách xóa cache Redis hoặc các artifact khi build.
Thực thi những quy tắc “ngầm”
Mọi codebase đều có “kiến thức ngầm”—những quy tắc không có trong tài liệu chính thức nhưng mọi người đều tuân theo. Có thể bạn thích f-strings hơn .format(), hoặc có lẽ bạn tránh các khối else để giảm độ lồng nhau (nesting). Nếu những điều này không có trong CLAUDE.md, AI sẽ mặc định sử dụng các pattern chung chung mà nó học được trong quá trình huấn luyện. Việc nêu rõ các ưu tiên này buộc AI phải thích nghi với phong cách của bạn, thay vì bắt bạn phải sửa kết quả đầu ra của nó sau đó.
Định hướng trong mê cung thư mục
Đừng giả định rằng AI hiểu cấu trúc thư mục của bạn. Nếu /dist được tạo tự động, hãy bảo AI bỏ qua nó. Nếu /scripts chứa các công cụ triển khai quan trọng, hãy chỉ rõ. Bước đơn giản này ngăn AI cố gắng “refactor” một file thực chất là artifact đã được minified khi build.
Các chiến thuật nâng cao cho dự án phức tạp
Khi repo của bạn lớn dần, một danh sách lệnh đơn giản có thể là chưa đủ. Bạn có thể sử dụng CLAUDE.md để xử lý các nợ kỹ thuật (technical debt) tinh tế hoặc các ràng buộc môi trường cụ thể.
Đặc thù môi trường
Nếu dự án của bạn hoạt động trên macOS khác với trên Linux, hãy ghi chú lại. Điều này ngăn AI gợi ý các lệnh apt-get khi bạn đang làm việc bên trong một Docker image Alpine tối giản. Hãy đề cập đến trình quản lý gói của bạn (Poetry, Bun, hoặc Pnpm) để đảm bảo AI sử dụng đúng các file lock.
### Môi trường Dev
- Runtime: Node.js v20.11 (LTS)
- Package Manager: pnpm
- Lưu ý: Luôn sử dụng `pnpm dlx` cho các lần thực thi binary một lần.Ràng buộc thư viện
Việc cài đặt hai thư viện có mục đích tương tự nhau như requests và httpx là rất phổ biến. Hãy sử dụng file cấu hình của bạn để chỉ định thư viện ưu tiên. Ví dụ, hãy nói với AI: “Sử dụng `pydantic` v2 để xác thực dữ liệu; không sử dụng cú pháp v1.” Điều này giữ cho codebase nhất quán và ngăn các pattern cũ quay trở lại.
Chiến lược ‘Trạng thái’ (State)
Đối với các đợt refactor kéo dài, tôi duy trì một phần ‘Trạng thái hiện tại’ (Current Status). Khu vực động này ghi lại tiến độ. Nếu bạn ngừng làm việc lúc 6 giờ tối và quay lại vào sáng hôm sau, AI sẽ đọc phần này và biết ngay module nào đã hoàn thành và module nào vẫn còn lỗi.
Mẹo bảo trì thực tế
File CLAUDE.md chỉ hữu ích nếu nó luôn chính xác. Nếu bạn chuyển trình chạy test từ Mocha sang Vitest nhưng quên cập nhật file, bạn sẽ lãng phí 20 phút tranh cãi với AI về lý do tại sao các bài test thất bại.
- Commit vào Git: Hãy coi file này là một phần trong hạ tầng cốt lõi của bạn. Kiểm tra các thay đổi của nó trong quá trình PR.
- Ngắn gọn, súc tích: Tránh các đoạn văn dài. Các mô hình AI xử lý danh sách gạch đầu dòng và tiêu đề hiệu quả hơn nhiều so với văn xuôi.
- Xác định các Anti-Pattern: Nếu bạn thấy các lập trình viên lặp lại cùng một sai lầm, hãy thêm phần ‘Không nên’. Nói với AI: “Không sử dụng kiểu `any` trong TypeScript.”
- Hỗ trợ onboarding cho con người: File này cũng đóng vai trò như một hướng dẫn ‘Bắt đầu’ cho những nhân sự mới. Đây là giải pháp đôi bên cùng có lợi cho cả team.
Khi bạn đang debug lúc 2 giờ sáng, bạn sẽ không muốn giải thích cấu trúc thư mục của mình lần thứ mười. Hãy dành 10 phút cho CLAUDE.md ngay hôm nay. Bạn đang tặng cho chính mình trong tương lai một trợ lý tập trung hơn, chuyên nghiệp hơn, hiểu rõ môi trường của bạn từ trong ra ngoài.
