90 lines
7.2 KiB
Markdown
90 lines
7.2 KiB
Markdown
# Hướng dẫn viết & maintain các file AGENTS.md
|
||
|
||
`AGENTS.md` là **bộ quy ước, thông tin, business logic ngắn gọn** mà AI/Tools (như Claude Code, Codex, Cursor, Antigravity, ...) nạp vào context khi làm việc. Nó quyết định AI/tools hiểu dự án đến đâu và là nguồn rule chính cho `/code-review` (hoặc các hàm tương tự). 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
|
||
1. [Ba loại CLAUDE.md — đặt ở đâu, dùng cho gì](#1-ba-loai-claudemd)
|
||
2. [Phân cấp & scope](#2-phan-cap--scope)
|
||
3. [Cấu trúc chuẩn (8 phần)](#3-cau-truc-chuan-8-phan)
|
||
4. [Tự động cập nhật (ít sửa tay)](#4-tu-dong-cap-nhat)
|
||
5. [Cập nhật thủ công](#5-cap-nhat-thu-cong)
|
||
|
||
---
|
||
|
||
## 1. Ba loại CLAUDE.md
|
||
|
||
| Loại | Vị trí | Phạm vi | Theo git? |
|
||
|------|--------|---------|-----------|
|
||
| **Cá nhân (global)** | Nằm trong thư mục của tools như `~/.claude/CLAUDE.md` hoặc `.cursor/rules/*.mdc` | Mọi dự án trên máy bạn | Không |
|
||
| **Dự án (root)** | `./CLAUDE.md` hoặc `AGENTS.md`, ... (nằm ở folder root repo) | Cả dự án đó | Có (cả team thấy và sử dụng chung được) |
|
||
| **Thư mục con** | `<module>/*.md` | Chỉ code trong thư mục đó | Có |
|
||
|
||
### a) Cá nhân — `~/.claude/CLAUDE.md` (tương tự ở folder khác cho các tools khác)
|
||
* **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 (tương tự ở folder khác cho các tools khác)
|
||
* **Dùng cho:** mọi thứ thuộc về dự án — tổng quan, lệnh build/test/lint, quy ước, **business rules**, nên làm gì và không được làm gì.
|
||
* **Đặ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` (tương tự ở folder khác cho các tools khác)
|
||
* **Dùng cho:** rule chỉ dùng cho một module cụ thể (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.
|
||
|
||
> Các file được **cộng dồn**: khi làm trong một thư mục con, ví dụ như: Claude sẽ 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 (`./AGENTS.md`).
|
||
* **Rule riêng module** → `<module>/AGENTS.md`. Đừng nhồi hết vào root.
|
||
* **Rule cá nhân, mọi dự án** → `~/.claude/CLAUDE.md` hoặc `.cursor/rules/*.mdc` hoặc tương tự với các tools khác.
|
||
* `/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 thông tin liên quan về 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 — để AI 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**
|
||
* **[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 `@[...].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 AI làm sai. Không cần hoàn hảo ngay.
|
||
|
||
---
|
||
**[Claude Code]**
|
||
## 4. Tự động cập nhật
|
||
|
||
Tools AI **không** tự viết lại các file AGENTS.md hoàn toàn — và đó là điều tốt, vì file tự phình liên tục thì sẽ nhiều rác --> sẽ làm hỏng `/code-review`. Nếu chúng ta muốn muốn cập nhật các file .md mà *gần như không phải sửa tay* thì sẽ có một số cách:
|
||
|
||
* **Dùng `#` (ít ảnh hưởng 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 là tốt nhất, nếu vẫn muốn giữ context hiện tại cho task tiếp theo thì hãy `/compact` nhé) và giữ file và context ngắn giúp rule được ưu tiên hơn.
|