Đổi tên các file hướng dẫn sang Tiếng Việt

Huong-Dan-Viet-Va-Duy-Tri-CLAUDE-md.md

@@ -0,0 +1,93 @@
+# 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
+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)** | `~/.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