init git

.claude/skills/sa-3-enablement/GUIDE.md

@@ -0,0 +1,171 @@
+# Hướng dẫn sử dụng — `sa-3-enablement` (Giai đoạn 3)
+
+## Giai đoạn này giải quyết gì
+
+Đầu vào là bộ thiết kế đã ký (AG2). Đầu ra là **kiến trúc đó tồn tại trong code và ở lại đó**
+— có chuẩn dev dùng được, có bài kiểm tự động, có sổ nợ khi phải lệch, có nhật ký quyết định
+phát sinh trong lúc thi công.
+
+**Không làm ở giai đoạn này:** thiết kế lại kiến trúc, viết code sản phẩm, quản lý sprint.
+
+## Vì sao giai đoạn này quyết định thành bại
+
+Kiến trúc trên giấy không có giá trị. Ba thứ làm nó biến mất trong 6 tháng:
+
+1. Dev không biết ràng buộc tồn tại ⇒ **`AGD` + reference implementation**
+2. Biết nhưng không ai kiểm ⇒ **`FIT`**
+3. Phải lệch vì gấp, rồi quên ⇒ **`TDEBT`**
+
+Bỏ một trong ba thì hai cái còn lại cũng vô dụng.
+
+## Khi nào gọi
+
+| Tình huống | Có nên gọi |
+|---|---|
+| Vừa qua AG2, dev sắp bắt đầu | ✅ `--focus agd` trước, ngay trong tuần đầu |
+| CI chưa kiểm gì về kiến trúc | ✅ `--focus fit` |
+| Dev đề xuất một thay đổi chạm thiết kế | ✅ `--focus review` |
+| Phải lệch thiết kế vì deadline | ✅ `--focus debt` — ghi lại ngay, đừng để nhớ sau |
+| Codebase kế thừa, không rõ kiến trúc thật là gì | ✅ `--focus fit` để đo hiện trạng trước |
+| Dev hỏi "hàm này đặt tên gì" | ❌ Thuộc Tech Lead |
+| Muốn đổi một quyết định kiến trúc | ❌ Sang `/sa-2-architecture --focus adr` |
+
+## Cú pháp
+
+```
+/sa-3-enablement <PROJECT> [--focus agd|fit|review|debt|all] [--out <path>] [go]
+```
+
+| `--focus` | Sinh ra | Khi nào chạy |
+|---|---|---|
+| `agd` | `AGD` + đề cương reference implementation | Ngay sau AG2 |
+| `fit` | `FIT` — danh sách bài kiểm + cấu hình CI đề xuất | Tuần 1–2 của thi công |
+| `review` | Một mục trong `DREV` | Mỗi lần có thay đổi chạm kiến trúc |
+| `debt` | Một mục trong `TDEBT` | Mỗi lần chấp nhận lệch |
+| `all` | Cả bốn | |
+
+Review một thay đổi cụ thể:
+
+```
+/sa-3-enablement Settlement --focus review
+  "Dev đề xuất gọi trực tiếp DB của module Order từ module Report cho nhanh,
+   thay vì qua API. Lý do: query join 3 bảng qua API mất 4 giây."
+```
+
+## Chuẩn bị gì trước khi gọi
+
+| Cho bước | Chuẩn bị |
+|---|---|
+| `agd` | `SAD`, `ADR`, `ICD`, `FAIL` đã ký · quy ước code hiện có của team |
+| `fit` | Cấu hình CI hiện tại · ngôn ngữ/framework · quyền sửa pipeline |
+| `review` | Mô tả thay đổi + lý do dev đưa ra + code/PR nếu có |
+| `debt` | Lệch cụ thể là gì · vì sao phải lệch · ai chấp nhận |
+
+## Bạn sẽ nhận được gì
+
+```
+sa-output/<PROJECT>/03-enablement/
+├── AGD_<PROJECT>_v1.0.md      ← dev đọc cái này
+├── FIT_<PROJECT>_v1.0.md      ← danh sách bài kiểm + trạng thái xanh/đỏ
+├── DREV_<PROJECT>.md          ← nhật ký, ghi thêm liên tục, không lên version
+└── TDEBT_<PROJECT>.md         ← sổ nợ, ghi thêm liên tục
+```
+
+`DREV` và `TDEBT` là **sổ sống** — ghi thêm mỗi lần, không tạo version mới.
+
+## Fitness function: bắt đầu thế nào
+
+Đừng cố phủ hết ngay. Thứ tự đem lại giá trị nhanh nhất:
+
+```
+Tuần 1  ① Phụ thuộc giữa tầng/module          ← rẻ nhất, chặn được nhiều lỗi nhất
+        ② Quét secret trong mã nguồn           ← rủi ro cao, công cụ có sẵn
+Tuần 2  ③ Quét lỗ hổng thư viện
+        ④ Lint contract (OpenAPI)
+Tuần 3  ⑤ Kiểm thử hiệu năng QAS mức Must      ← tốn công dựng nhất, để sau
+Tuần 4  ⑥ Kiểm tra IaC / policy hạ tầng
+```
+
+Mỗi bài kiểm bật ở **chế độ cảnh báo** trước, công bố ngày chuyển sang **chặn merge**, dọn nợ
+trước ngày đó.
+
+```
+FIT-01  Tầng domain không import tầng infra
+        Nguồn : ADR-002
+        Công cụ: ArchUnit · chạy ở CI bước `test`
+        Chế độ : ⚠️ cảnh báo (từ 2026-09-01) → 🚫 chặn (từ 2026-09-20)
+        Hiện tại: 🔴 12 vi phạm → TD-03, chủ: anh Nam, hạn 2026-09-18
+```
+
+## Ví dụ hội thoại — design review
+
+```
+Bạn:    /sa-3-enablement Settlement --focus review
+        Dev muốn gọi thẳng DB module Order từ module Report vì query qua API mất 4 giây.
+
+Claude: Chấm điểm radar:
+        - Chi phí đảo ngược:      1 (sửa được trong ~2 tuần)
+        - Bán kính ảnh hưởng:     2 (phá ranh giới module, ảnh hưởng mọi thay đổi Order sau này)
+        - Chạm QAS:               2 (QAS-003 p95 báo cáo ≤ 3s — đây chính là vấn đề)
+        - Ràng buộc dài hạn:      2 (khi tách service, chỗ này sẽ chặn)
+        - Tranh cãi:              1
+        → 8/10 ⇒ cần ADR, không phải quyết định trong PR.
+
+        Đối chiếu: ADR-004 chốt module chỉ giao tiếp qua interface công khai.
+        QAS-003 yêu cầu p95 ≤ 3s — thiết kế hiện tại KHÔNG đạt. Dev đúng về vấn đề.
+
+        Bốn phương án, không chỉ hai:
+        1. Giữ ranh giới + thêm read model cho báo cáo   → đúng ADR-004, +1 tuần
+        2. Giữ ranh giới + cache kết quả                 → nhanh nhất, dữ liệu trễ ≤ 5 phút
+        3. Gọi thẳng DB                                  → vi phạm ADR-004
+        4. Nới QAS-003 lên 5s                            → cần PO chấp nhận
+
+        Khuyến nghị: PA-2 nếu PO chấp nhận trễ 5 phút (rẻ nhất), PA-1 nếu không.
+        PA-3 chỉ chấp nhận như TDEBT có hạn, kèm FIT-01 whitelist tạm thời.
+
+        Cần ai quyết: PO (trễ 5 phút có chấp nhận được không) → OQ-034
+        Ghi vào DREV-012.
+```
+
+## Lỗi thường gặp
+
+**"Guideline viết xong không ai đọc."**
+Bình thường nếu nó dài. Kiểm tra: quy tắc nào không truy được về `ADR`/`QAS` thì cắt. Phần
+còn lại chuyển thành reference implementation — dev đọc code, không đọc văn bản.
+
+**"Bật fitness function thì CI đỏ 200 chỗ."**
+Đúng như dự kiến với codebase đã có. Bật chế độ cảnh báo, ghi số vi phạm hiện tại làm mốc,
+đặt quy tắc "không tăng thêm", rồi giảm dần. Chuyển sang chặn khi về 0.
+
+**"Dev bảo kiến trúc không thực tế."**
+Nghe kỹ trước khi bảo vệ thiết kế. Ba lần trở lên cùng một phản hồi về cùng một chỗ ⇒ khả năng
+cao thiết kế sai thật. Kết luận "thiết kế sai, cần `ADR` mới" là kết luận hợp lệ và là dấu
+hiệu của một SA làm việc tốt, không phải thất bại.
+
+**"Sổ nợ chỉ tăng, không bao giờ giảm."**
+Thiếu cột "lãi suất". Viết bằng con số PM hiểu: *"module này khiến mỗi tính năng mới tốn thêm
+2 ngày; đã có 6 tính năng chạm nó trong quý"* — 12 ngày đó sẽ tự tìm được chỗ trong sprint.
+
+**"Tôi thành nút thắt, mọi PR đều chờ tôi."**
+Đang review quá rộng. Chấm radar: điểm < 3 trả lại Tech Lead. Và đầu tư vào `FIT` — bài kiểm
+tự động review nhanh hơn bạn và không nghỉ phép.
+
+## Ra khỏi giai đoạn này khi nào
+
+Đủ cả năm:
+
+1. Bảng tự chấm AG3 toàn ✅
+2. **Tech Lead + QA + SRE** đã ký
+3. Mọi `FIT` cho ràng buộc quan trọng đang **xanh trên CI**, không phải "đã viết"
+4. Mọi `QAS` mức Must có **bài đo thật đã chạy**, không phải ước lượng
+5. Mọi `TD-nn` có chủ và hạn — không còn mục "sẽ sửa sau" trống
+
+Rồi go-live, và chạy `/sa-4-evolution <PROJECT>` sau kỳ vận hành đầu tiên.
+
+## Liên quan
+
+- Tiêu chí gate AG3: `../sa-lifecycle/references/workflow.md` §2
+- Quy tắc `D8` (ràng buộc phải verify được): `../sa-lifecycle/references/design-rules.md`
+- Chấm điểm thay đổi có cần ADR không: `../sa-lifecycle/references/decision-radar.md` §2
+- Template: `templates/architecture-guidelines.md` · `templates/fitness-functions.md` ·
+  `templates/design-review-log.md` · `templates/tech-debt-register.md`