Tại sao cần file chỉ dẫn dự án
Agent không nhớ gì giữa các phiên. File chỉ dẫn dự án (CLAUDE.md cho Claude Code, .cursorrules cho Cursor, .github/copilot-instructions.md cho Copilot) là nơi bạn ghi quy ước bền vững — được tự động nạp vào context mỗi phiên. Đây là "bộ nhớ dài hạn" của agent trong dự án.
Viết file này tốt = mỗi phiên agent đã "lên tay" mà không cần nhắc lại.
Một CLAUDE.md tốt gồm gì
# Dự án: Payment Service
## Stack & lệnh
- Python 3.11, FastAPI, SQLAlchemy, Postgres
- Chạy test: `pytest -q`
- Lint: `ruff check .` (BẮT BUỘC pass trước khi báo xong)
## Quy ước code
- Tên hàm/biến: snake_case. Class: PascalCase.
- Mọi query DB qua repository (repositories/), KHÔNG raw SQL trong route.
- Route bảo mật dùng decorator @require_auth.
- Tiền tệ dùng Decimal, KHÔNG float.
## Kiến trúc
- routes/ -> services/ -> repositories/ -> models/
- Không gọi tắt route -> models.
## Định nghĩa "xong"
- Có test cho happy path + 1 edge case.
- ruff + pytest pass.
Nguyên tắc viết
- Cụ thể, kiểm chứng được — "dùng Decimal cho tiền" tốt hơn "viết code sạch".
- Ngắn và ưu tiên — file quá dài cũng ngốn ngân sách và loãng. Giữ những gì agent hay làm sai.
- Nói cả điều CẤM — "KHÔNG raw SQL trong route" chặn được cả lớp lỗi.
- Ghi lệnh chạy được — agent tự verify được là vàng.
- Định nghĩa "xong" — để agent tự biết khi nào dừng.
Các bước xây dựng CLAUDE.md từ số 0
- Ghi stack + các lệnh test/lint/build.
- Thêm 5-8 quy ước bạn hay phải sửa lại cho agent nhất.
- Vẽ luồng kiến trúc bằng 1-2 dòng (layer nào gọi layer nào).
- Liệt kê các điều CẤM đã từng gây bug.
- Định nghĩa "xong".
- Chạy thử vài tác vụ, thấy agent làm sai gì lặp lại thì bổ sung quy tắc.
Khung phân tầng chỉ dẫn
Global (~/.claude/CLAUDE.md) -> sở thích cá nhân, mọi dự án
Project (./CLAUDE.md) -> quy ước riêng dự án này
Thư mục con (./api/CLAUDE.md) -> quy tắc riêng module
Đặt quy tắc ở đúng tầng: đừng nhét quy ước chỉ đúng cho module api/ vào file gốc.
Checklist một file chỉ dẫn chất lượng
- [ ] Có lệnh test/lint/build chạy được
- [ ] Quy ước cụ thể, kiểm chứng được, không chung chung
- [ ] Có mục CẤM rõ ràng
- [ ] Có "định nghĩa xong"
- [ ] Đủ ngắn (thường < 150 dòng)
- [ ] Không chứa bí mật (API key, mật khẩu)
Bảo trì file theo thời gian
CLAUDE.md không phải viết một lần rồi quên. Coi nó như tài liệu sống: mỗi khi bạn thấy agent lặp lại một lỗi (dùng float cho tiền, đặt file sai thư mục, quên chạy lint), đó là tín hiệu thiếu một dòng quy tắc. Thêm dòng đó vào file, và lỗi biến mất ở mọi phiên sau. Một mẹo hay: cuối mỗi tuần, đọc lại các lần bạn phải sửa tay cho agent, rồi hỏi "quy tắc nào sẽ chặn việc này?". Ngược lại, nếu file phình quá 150 dòng, hãy cắt bớt những quy tắc hiển nhiên ("viết code có test") để giữ tín hiệu đậm đặc.
# Ví dụ mục CẤM tích lũy từ bug thật
- KHÔNG dùng float cho tiền (đã gây bug làm tròn #142).
- KHÔNG gọi API bên thứ 3 trực tiếp trong route (đặt trong services/).
- KHÔNG commit file .env hay khóa bí mật.
Sai lầm thường gặp
- Viết chung chung như "code phải tốt, dễ đọc" — agent không hành động được. Phải cụ thể.
- Nhồi cả wiki công ty vào file — ngốn ngân sách, loãng. Chỉ giữ điều thiết yếu, hay sai.
- Không cập nhật — khi đổi quy ước mà quên sửa file, agent làm theo luật cũ.
- Bỏ lệnh verify — không cho agent cách tự chạy test/lint thì nó không tự sửa được.
- Để lộ secret trong file chỉ dẫn (nó đi vào context và có thể lộ). Dùng biến môi trường.
- Nhồi quy tắc module vào file gốc — đặt đúng tầng để tránh loãng và mâu thuẫn.