Hướng Dẫn Viết & Duy Trì CLAUDE.md

CLAUDE.md là bộ luật ngắn gọn Claude Code nạp vào context khi làm việc. Nó quyết định Claude hiểu dự án đến đâu và là nguồn rule chính cho /code-review. Nguyên tắc số một: đây là bộ luật, không phải tài liệu — mỗi dòng thừa làm loãng tín hiệu và khiến AI dễ lạc đề.

Mục lục

Ba loại CLAUDE.md — đặt ở đâu, dùng cho gì
Phân cấp & scope
Cấu trúc chuẩn (8 phần)
Tự động cập nhật (ít sửa tay)
Cập nhật thủ công

1. Ba loại CLAUDE.md

Loại	Vị trí	Phạm vi	Theo git?
Cá nhân (global)	`~/.claude/CLAUDE.md`	Mọi dự án trên máy bạn	Không
Dự án (root)	`./CLAUDE.md` (gốc repo)	Cả dự án đó	Có (cả team thấy)
Thư mục con	`<module>/CLAUDE.md`	Chỉ code trong thư mục đó	Có

a) Cá nhân — `~/.claude/CLAUDE.md`

Dùng cho: phong cách & nguyên tắc làm việc của riêng bạn, áp cho mọi dự án (ví dụ: nguyên tắc Karpathy, "ưu tiên dùng skill", "lập kế hoạch & hỏi trước khi code").
KHÔNG để: lệnh build/test hay business rule riêng của một dự án — vì nó áp cho tất cả.
Lưu ý: chỉ tồn tại trên máy bạn, không đi theo repo nên đồng đội không thấy.

b) Dự án — `./CLAUDE.md` ở gốc repo

Dùng cho: mọi thứ thuộc về dự án — tổng quan, lệnh build/test/lint, convention, business rules, do/don't.
Đặt ở gốc repo (không phải trong .claude/), được commit nên cả team clone về là có.
Đây là vị trí chắc chắn được nạp và quan trọng nhất cho chất lượng /code-review.

c) Thư mục con — `<module>/CLAUDE.md`

Dùng cho: rule chỉ đúng cho một phần (ví dụ src/payment/CLAUDE.md: rule về idempotency, xử lý refund).
Vì sao quan trọng: /code-review chỉ áp rule có cùng path hoặc thư mục cha của file đang xét. Đặt rule đúng chỗ → review đúng trọng tâm, không lôi rule chỗ khác vào.

Lưu ý về .claude/ trong dự án: thư mục này chứa settings.json, commands/, agents/ — không phải nơi để file memory. File memory của dự án để ở gốc repo (./CLAUDE.md). Vị trí global đáng tin là ~/.claude/CLAUDE.md (trong home).

Các file được cộng dồn: khi làm trong một thư mục con, Claude nạp đồng thời CLAUDE.md cá nhân + gốc dự án + thư mục con.

2. Phân cấp & scope

Rule chung → gốc repo (./CLAUDE.md).
Rule riêng module → <module>/CLAUDE.md. Đừng nhồi hết vào root.
Rule cá nhân, mọi dự án → ~/.claude/CLAUDE.md.
/code-review xét rule theo scope phân cấp — đặt sai chỗ thì hoặc bị bỏ qua, hoặc áp nhầm sang code không liên quan.

3. Cấu trúc chuẩn (8 phần)

Phần 1, 2, 4, 5, 6 là cốt lõi; 3, 7 tùy dự án; 8 tự lớn theo thời gian. (File cá nhân chủ yếu dùng phần 4 + 6; file dự án dùng đủ; file thư mục con chỉ phần liên quan module.)

[1] Tổng quan dự án (bắt buộc): tên, mô tả ngắn, tech stack, env. 3–5 dòng.
[2] Lệnh hay dùng (bắt buộc): build / test / lint / dev / deploy — để Claude chạy đúng thay vì đoán.
[3] Cấu trúc thư mục (tùy chọn): chỉ ghi thư mục dễ nhầm (ví dụ: logic ở services/, không ở api/).
[4] Quy ước code (bắt buộc): naming, pattern, error handling — những rule linter không bắt được.
[5] Business rules (bắt buộc): logic nghiệp vụ AI không thể tự đoán (ví dụ: không cancel order đã "shipped"). Quan trọng nhất để /code-review không báo sai.
[6] Do / Don't (bắt buộc): dạng cấm rõ ràng, ngắn, dứt khoát (ví dụ: KHÔNG commit .env).
[7] References (tùy chọn): import file ngoài bằng @docs/....md để giữ file chính gọn.
[8] Learned patterns (tự cập nhật): phần Claude tự ghi sau mỗi phiên, kèm ngày.

Mẹo giữ gọn: phần dài thì tách ra file riêng rồi @import (ví dụ @KarpathyCodeGuidelines.md). Dùng import cho cả file cá nhân lẫn dự án.

Thứ tự viết lần đầu: làm 1, 2, 6 trước (~30 phút), rồi bổ sung 4, 5 dần theo lúc thấy Claude làm sai. Không cần hoàn hảo ngay.

4. Tự động cập nhật

Claude Code không tự viết lại CLAUDE.md hoàn toàn — và đó là điều tốt, vì file tự phình rác sẽ làm hỏng /code-review. Mục tiêu là gần như không phải sửa tay:

Phím # (ít ma sát nhất): gõ tin nhắn bắt đầu bằng #, ví dụ # luôn dùng dayjs thay vì moment → Claude tự ghi vào memory và hỏi bỏ vào file nào (cá nhân / dự án / thư mục con).
Lệnh /update-memory (tự tạo): tạo .claude/commands/update-memory.md yêu cầu Claude rà git log + phiên gần đây, đề xuất rule high-signal cho bạn duyệt. Chạy cuối ngày hoặc sau mỗi feature.
Hook (tùy chọn): gắn hook sự kiện Stop để nhắc cập nhật. ⚠️ Đừng để hook tự ghi không qua duyệt — dễ tạo vòng lặp và làm file rác.

5. Cập nhật thủ công

/init: quét codebase sinh CLAUDE.md nháp. Nếu đã có file, nó bổ sung chứ không ghi đè, nhưng có thể sắp xếp lại — nên git commit trước khi chạy để dễ rollback. Hợp cho lúc khởi tạo / làm mới toàn diện.
/memory: liệt kê các file memory và mở ra sửa trực tiếp; dùng khi muốn dọn/sắp xếp lại.
Sửa file như thường: CLAUDE.md chỉ là markdown — mở editor sửa, lưu, lần sau Claude tự đọc lại (không cần restart).
Giữ gọn: thêm rule mới thì xóa rule lỗi thời; mỗi rule một dòng; phần dài thì tách file rồi @import.

Quy trình khuyên dùng: /init (1 lần) → dùng # bắt rule trong lúc làm → chạy /update-memory định kỳ & duyệt.

Lưu ý về session dài: context đầy dần sẽ làm rule bị "loãng" và Claude dễ quên — chia nhỏ session (/clear sau mỗi task) và giữ file ngắn giúp rule "nặng ký" hơn.

Chi tiết sản phẩm có thể thay đổi theo phiên bản — đối chiếu tại https://docs.claude.com/en/docs/claude-code/overview

6.8 KiB Raw Blame History Unescape Escape