init git

2026-09-08 10:26:21 +07:00
commit c81f249920
169 changed files with 38726 additions and 0 deletions
--- a/.claude/skills/sa-4-evolution/GUIDE.md
+++ b/.claude/skills/sa-4-evolution/GUIDE.md
@@ -0,0 +1,174 @@
+# Hướng dẫn sử dụng — `sa-4-evolution` (Giai đoạn 4)
+
+## Giai đoạn này giải quyết gì
+
+Hệ thống đã chạy thật. Câu hỏi bây giờ không còn là "thiết kế thế nào" mà là **"kiến trúc ta
+thiết kế và kiến trúc đang chạy có phải một không"**.
+
+Đầu vào là số liệu vận hành thật. Đầu ra là **bảng đối chiếu cam kết × thực tế**, và một
+roadmap kỹ thuật PO duyệt được.
+
+**Không làm ở giai đoạn này:** thiết kế lại hệ thống (đó là vòng mới, quay về `sa-1-context`),
+post-mortem vận hành (thuộc SRE — ở đây chỉ làm phần kiến trúc).
+
+## Khi nào gọi
+
+| Tình huống | Có nên gọi |
+|---|---|
+| Một tháng sau go-live | ✅ `--focus conf` — lần đối chiếu đầu tiên |
+| Định kỳ hàng tháng | ✅ `--focus conf` |
+| Hoá đơn cloud tăng bất thường | ✅ `--focus conf`, đọc §b trước |
+| Vừa có sự cố nghiêm trọng | ✅ `--focus review` sau khi SRE xong post-mortem vận hành |
+| Lập kế hoạch quý | ✅ `--focus roadmap` |
+| Đánh giá kiến trúc định kỳ | ✅ `--focus review` mỗi quý |
+| Cần thiết kế một hệ thống mới | ❌ `/sa-1-context` |
+| Chưa có telemetry gì | ⚠️ Chạy được, nhưng `CONF` sẽ toàn "chưa đo được" — đó cũng là một phát hiện |
+
+## Cú pháp
+
+```
+/sa-4-evolution <PROJECT> [--focus conf|roadmap|review] [--period 2026-09] [--out <path>] [go]
+```
+
+| Tham số | Ý nghĩa |
+|---|---|
+| `--focus conf` | Đối chiếu `QAS`/`TCO`/sự cố/drift với thực tế |
+| `--focus roadmap` | Lập `TRM` từ phát hiện của `CONF` |
+| `--focus review` | Đánh giá kiến trúc định kỳ hoặc post-mortem sau sự cố |
+| `--period <YYYY-MM>` | Kỳ đối chiếu, mặc định tháng gần nhất |
+| `go` | Bỏ bước dừng xác nhận input |
+
+```
+/sa-4-evolution Settlement --focus conf --period 2026-09
+/sa-4-evolution Settlement --focus review   "sự cố INC-2026-0912: batch đối soát chạy 3 giờ, chặn báo cáo sáng"
+```
+
+## Chuẩn bị gì trước khi gọi
+
+🔴 **Đây là giai đoạn phụ thuộc dữ liệu nhiều nhất.** Không có số thì skill chỉ in ra bảng
+trống — và đó là kết luận, không phải lỗi.
+
+| Cần | Lấy ở đâu | Dùng cho |
+|---|---|---|
+| Số đo p50/p95/p99 các thao tác chính | APM / dashboard | `QAS` × thực tế |
+| Uptime thật + tổng downtime trong kỳ | uptime monitor | `QAS` sẵn sàng |
+| Thông lượng thật, đỉnh trong kỳ | metric | `QAS` thông lượng |
+| **Hoá đơn cloud chi tiết theo dịch vụ** | cổng thanh toán cloud | `TCO` × thực tế |
+| Danh sách sự cố trong kỳ + nguyên nhân | log sự cố / ticket | Sự cố × `ADR` |
+| Lịch sử `FIT` trên CI | CI | Drift |
+| Trace/log để biết interface thật đang gọi nhau thế nào | tracing | Drift |
+
+## Bạn sẽ nhận được gì
+
+```
+sa-output/<PROJECT>/04-evolution/
+├── CONF_<PROJECT>_<YYYY-MM>.md   ← mỗi kỳ một file, không ghi đè
+├── TRM_<PROJECT>_v1.0.md         ← roadmap, lên version
+└── PMR_<PROJECT>_<YYYY-Qn>.md    ← đánh giá định kỳ
+    PMR_<PROJECT>_<INC-id>.md     ← post-mortem sau sự cố
+```
+
+## Đọc bảng đối chiếu thế nào
+
+```
+QAS × thực tế · kỳ 2026-09
+┌──────────┬──────────────────┬──────────────┬──────────┬─────────────────────────┐
+│ QAS-001  │ p95 ≤ 300ms      │ p95 = 240ms  │ ✅ đạt   │                         │
+│ QAS-004  │ batch ≤ 45 phút  │ 52 phút      │ ❌       │ TD-05 · TRM mục 1       │
+│ QAS-007  │ SLA 99.9%        │ 99.94%       │ ✅ đạt   │ downtime 26/43 phút     │
+│ QAS-011  │ cảnh báo ≤ 3 phút│ chưa đo được │ ⚠️       │ thiếu bài đo — bài học  │
+└──────────┴──────────────────┴──────────────┴──────────┴─────────────────────────┘
+```
+
+- ✅ đạt · ❌ không đạt ⇒ vào `TRM` · ⚠️ **chưa đo được** ⇒ AG2 định nghĩa cách đo không khả
+  thi, hoặc observability thiếu
+
+⚠️ **không xấu hơn ❌.** Nó xấu hơn: ❌ ta biết mình đang ở đâu, ⚠️ ta không biết gì cả.
+
+## Ví dụ hội thoại
+
+```
+Bạn:    /sa-4-evolution Settlement --focus conf --period 2026-09
+        Đính kèm: hoá đơn AWS tháng 9, export dashboard Grafana, log sự cố
+
+Claude: [Bước 0]
+        Input: QAS v1.1 ✅, TCO v1.0 ✅, hoá đơn AWS 09/2026, Grafana export, 3 sự cố.
+        Đủ để đối chiếu QAS (8/11 mục) và TCO (đầy đủ).
+        Thiếu: bài đo cho QAS-009 và QAS-011 (observability) → sẽ ghi "chưa đo được".
+        Xác nhận ghi vào CONF_Settlement_2026-09.md?
+
+Bạn:    ok
+
+Claude: ② QAS × thực tế: 6 đạt · 2 không đạt · 3 chưa đo được
+
+        ③ TCO × hoá đơn:
+        | Compute        | ước 4,2tr | thật 4,0tr | −5%   ✅ |
+        | CSDL           | ước 3,5tr | thật 3,3tr | −6%   ✅ |
+        | Observability  | ước 1,0tr | thật 3,8tr | +280% 🔴 |
+        | Egress         | ước 0,5tr | thật 2,1tr | +320% 🔴 |
+        | Tổng           | ước 11tr  | thật 15,4tr| +40%     |
+
+        Truy nguyên hai khoản vượt:
+        - Observability: đang giữ log 90 ngày, INF §8 thiết kế 30 ngày.
+          → drift cấu hình. Giảm về 30 ngày tiết kiệm ~2,5tr/tháng.
+        - Egress: báo cáo tải file PDF trực tiếp từ service, không qua CDN.
+          → không có trong thiết kế. Không thuộc 4 loại lý do hợp lệ ⇒ có thứ
+            chạy mà thiết kế không biết. Cần xác nhận với dev.
+
+        ④ Sự cố:
+        - INC-0912 (batch 3 giờ)     → truy về QAS-004 không đạt, đã biết trước
+        - INC-0918 (5xx 12 phút)     → truy về ASM-04 "API POS luôn trả trong 2s" SAI
+                                       thực tế có lúc 30s ⇒ FM-02 timeout đặt quá cao
+        - INC-0925 (sai số báo cáo)  → 🔴 ĐIỂM MÙ MỚI: cache không invalidate khi
+                                       sửa đơn hàng cũ. DAT §7 không nói tới trường hợp này.
+
+        Điểm mù mới là phát hiện giá trị nhất kỳ này → đề xuất QAS mới + FIT mới.
+
+        ▶ Ba mục đầu cho TRM (PO xếp thứ tự):
+        1. Giảm retention log về 30 ngày   · 0,5 ngày công · −2,5tr/tháng
+        2. Đưa tải file qua CDN            · 3 ngày công   · −1,8tr/tháng
+        3. Sửa chiến lược cache            · 5 ngày công   · ngăn tái diễn INC-0925
+```
+
+## Lỗi thường gặp
+
+**"Không có dashboard, không đo được gì."**
+Vậy kết luận của kỳ này là *"hệ thống đang chạy mà không ai biết nó chạy thế nào"* — một phát
+hiện nghiêm trọng và đáng trình. Mục đầu tiên của `TRM` là dựng observability.
+
+**"Chi phí vẫn trong ngân sách nên không cần xem."**
+Trong ngân sách nhưng gấp 3 lần ước lượng nghĩa là mô hình chi phí sai — và nó sẽ sai tiếp,
+lớn hơn, khi tải tăng. Truy nguyên chênh lệch kể cả khi chưa vượt.
+
+**"Sự cố do dev quên đặt timeout, không phải lỗi kiến trúc."**
+Câu hỏi kiến trúc không phải "ai quên" mà "vì sao hệ thống cho phép một lời gọi không timeout
+tồn tại". Câu trả lời thường là một `FIT` mới — và nó ngăn cả lớp lỗi đó, không chỉ một lần.
+
+**"PO không duyệt mục nào trong roadmap kỹ thuật."**
+Roadmap đang viết bằng ngôn ngữ kỹ thuật. Đổi "tái cấu trúc module Order" thành "giảm 2 ngày
+cho mỗi tính năng chạm Order; quý tới có 6 tính năng như vậy ⇒ tiết kiệm 12 ngày". PO duyệt
+con số, không duyệt danh từ kỹ thuật.
+
+**"ADR-005 hoá ra sai, tôi sửa lại nội dung cho đúng."**
+Đừng. Viết `ADR` mới có `Supersedes: ADR-005`, đổi trạng thái bản cũ thành `Superseded by`.
+Giá trị lớn nhất của ADR là ghi lại điều ta *đã tin* lúc đó — sửa đi là xoá mất bài học.
+
+## Ra khỏi giai đoạn này khi nào
+
+Đủ cả bốn:
+
+1. Bảng tự chấm AG4 toàn ✅
+2. **PO + SRE + EA** đã ký
+3. Mọi sự cố trong kỳ đã truy về `ADR`, `ASM`, hoặc được ghi nhận là điểm mù mới
+4. `TRM` đã được PO xếp thứ tự và các mục đầu đã vào backlog
+
+Sau đó: quay lại `--focus conf` ở kỳ tiếp theo, hoặc mở vòng kiến trúc mới bằng
+`/sa-1-context` nếu driver kinh doanh đã đổi.
+
+## Liên quan
+
+- Tiêu chí gate AG4: `../sa-lifecycle/references/workflow.md` §2
+- Nhịp chạy đề xuất: `../sa-lifecycle/references/workflow.md` §7
+- Vòng đời ADR: `../sa-lifecycle/references/artifact-map.md` §4
+- Template: `templates/conformance-report.md` · `templates/technical-roadmap.md` ·
+  `templates/architecture-review.md`