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-1-context/GUIDE.md
+++ b/.claude/skills/sa-1-context/GUIDE.md
@@ -0,0 +1,191 @@
+# Hướng dẫn sử dụng — `sa-1-context` (Giai đoạn 1)
+
+## Giai đoạn này giải quyết gì
+
+Đầu vào là một câu kiểu *"cần xây hệ thống đối soát cho POS"* hoặc *"nên chuyển sang
+microservices không"*. Đầu ra là **một phương án đã chọn, có lý do viết ra được, có giá tiền
+3 năm, có danh sách rủi ro kèm người chịu trách nhiệm**.
+
+**Không làm ở giai đoạn này:** vẽ component, thiết kế API, chọn thư viện, viết schema. Thấy
+mình đang làm mấy thứ đó ⇒ đã trượt sang GĐ2.
+
+## Khi nào gọi
+
+| Tình huống | Có nên gọi |
+|---|---|
+| Hệ thống mới hoàn toàn | ✅ Chạy đầy đủ 5 bước |
+| Mở rộng hệ thống đang chạy, không đổi mô hình dữ liệu | ✅ Chạy rút gọn — chỉ `CON` delta + `ARISK` |
+| Thay thế hệ thống cũ (migration) | ✅ Chạy đầy đủ, **bắt buộc** có phần dữ liệu legacy |
+| Khách hỏi "nên dùng công nghệ gì" | ✅ Đúng mục đích — nhưng phải làm Bước 1 trước, đừng trả lời ngay |
+| Cần con số cho báo giá/đấu thầu | ✅ Gọi và nói rõ "chỉ cần `OPT` + `TCO`" |
+| Đã chốt phương án, cần thiết kế chi tiết | ❌ Sang thẳng `/sa-2-architecture` |
+| Thêm một màn hình vào module đã có | ❌ Không cần SA giai đoạn này |
+
+## Cú pháp
+
+```
+/sa-1-context <PROJECT> [--mode new|extend|replace] [--focus ctx|opt|tco|risk] [--out <path>] [go]
+```
+
+| Tham số | Ý nghĩa |
+|---|---|
+| `--mode new` | Hệ thống mới — chạy đủ 5 bước *(mặc định)* |
+| `--mode extend` | Mở rộng — Bước 2 (chỉ ràng buộc mới), Bước 5 (rủi ro) |
+| `--mode replace` | Thay thế hệ thống cũ — đủ 5 bước + phần dữ liệu legacy bắt buộc |
+| `--focus <artifact>` | Chỉ sinh một artifact, ví dụ `--focus tco` khi cần gấp con số |
+| `go` | Bỏ bước dừng xác nhận input |
+
+Kèm file input bằng cách đính kèm trong hội thoại hoặc ghi đường dẫn:
+
+```
+/sa-1-context Settlement --mode new
+  input: ba-output/Settlement/01-discovery/BRIEF_Settlement_v1.0.md,
+         báo giá cloud từ anh Tuấn, ảnh chụp dashboard hệ thống POS
+```
+
+## Chuẩn bị gì trước khi gọi
+
+**Tối thiểu** (không có thì skill vẫn chạy nhưng `Confidence` sẽ là 🔴):
+- Mô tả bài toán, dù mơ hồ
+- Biết ai trả lời được về ngân sách
+
+**Nên có** — mỗi thứ dưới đây nâng chất lượng output rõ rệt:
+
+| Chuẩn bị | Nó quyết định cái gì |
+|---|---|
+| `BRIEF` + `GOAL` của bộ BA | `DRV-nn` — không có thì driver là suy đoán |
+| Ngân sách hạ tầng đã duyệt | Loại bỏ phương án ngay từ đầu, tiết kiệm cả tuần |
+| Chuẩn công nghệ của doanh nghiệp / EA | Tránh bị bác ở phút chót |
+| Quyền đọc DB và dashboard hệ thống hiện tại | Thay ước lượng bằng số thật |
+| Tài liệu API của hệ thống phải tích hợp | Phát hiện sớm ràng buộc không đổi được |
+| Danh sách team + kỹ năng + ai vận hành sau go-live | Ranh giới service khả thi (Conway) |
+| Hoá đơn cloud 3 tháng gần nhất | Mốc để `TCO` không phải bịa |
+
+## Quy trình 5 bước — bạn tham gia ở đâu
+
+| Bước | Skill làm | Bạn làm |
+|---|---|---|
+| 1. Driver | Chưng cất `BRIEF`/mô tả thành `DRV-nn`, chặn "công nghệ giả dạng driver" | Xác nhận con số áp lực với PO |
+| 2. Ràng buộc | Sinh bộ câu hỏi 6 nhóm, đánh dấu nhóm còn trống | **Đi hỏi** — skill không hỏi thay bạn |
+| 3. Hiện trạng | Sinh khung khảo sát, gợi ý chỗ phải nhìn tận mắt | **Mở DB, xem dashboard, gọi thử API** |
+| 4. Phương án | Dựng ≥2 phương án, chấm điểm, nêu cái bị loại | Duyệt trọng số tiêu chí với PO |
+| 5. Chi phí & rủi ro | Dựng `TCO` 3 năm × 2 kịch bản, rà 6 nguồn rủi ro | Cung cấp báo giá, chỉ định chủ rủi ro |
+
+🔴 **Bước 3 là bước skill không làm thay được.** Nó liệt kê cái cần nhìn; việc mở database
+thật và đọc hoá đơn cloud thật là của bạn. Đưa số liệu thô vào, skill sẽ chưng cất.
+
+## Bạn sẽ nhận được gì
+
+Bốn file trong `sa-output/<PROJECT>/01-context/`:
+
+```
+CTX_<PROJECT>_v1.0.md      ← driver, ràng buộc, hiện trạng
+OPT_<PROJECT>_v1.0.md      ← phương án + chấm điểm + khuyến nghị. PO+Tech Lead ký cái này
+TCO_<PROJECT>_v1.0.md      ← chi phí 3 năm, 2 kịch bản tải
+ARISK_<PROJECT>_v1.0.md    ← rủi ro + kế hoạch POC
+```
+
+Cộng ba bảng in ra màn hình: Gate AG1 · quy tắc D1–D12 · danh sách `OQ` mở.
+
+## Đọc bảng chấm điểm phương án thế nào
+
+```
+Tiêu chí                        Trọng số   P1 Mua SaaS   P2 Tự xây   P3 Giữ nguyên
+Đáp ứng DRV Must                  25%         4 (×)         5           1
+Chi phí 3 năm                     20%         3             4           5
+Thời gian tới bản chạy được       15%         5             2           5
+Rủi ro kỹ thuật                   15%         4             2           5
+Phù hợp năng lực team             15%         5             3           5
+Khả năng tiến hoá                 10%         2 (×)         5           1
+────────────────────────────────────────────────────────────────────────────
+Tổng có trọng số                             3.85          3.65        3.60
+
+(×) = chỗ phương án này THUA. Đọc hai ô này trước khi đọc điểm tổng.
+```
+
+🔴 **Điểm tổng gần nhau (3.85 vs 3.65) nghĩa là bộ tiêu chí chưa phân biệt được.** Đừng chọn
+theo chênh lệch 0.2 — quay lại hỏi PO tiêu chí nào thực sự quan trọng nhất, tăng trọng số của
+nó, rồi chấm lại. Hoặc chấp nhận rằng cả hai đều được và chọn theo tiêu chí phụ (ví dụ: cái
+nào đảo ngược rẻ hơn).
+
+## Ví dụ hội thoại
+
+```
+Bạn:    /sa-1-context Settlement
+        Cần xây hệ thống đối soát doanh thu POS. Khách bảo muốn dùng microservices.
+        Đính kèm: BRIEF_Settlement_v1.0.md
+
+Claude: [Bước 0]
+        Input dùng được:
+        | BRIEF_Settlement_v1.0.md | GOAL-01..03, RQ-001..018 | Cao |
+        | "khách muốn microservices" | Định hướng khách gợi ý | Thấp — chưa phải driver |
+
+        Phân loại: hệ thống MỚI (BRIEF §5 nói chưa có hệ thống đối soát).
+
+        ⚠️ "Muốn dùng microservices" là giải pháp, không phải driver. Tôi sẽ ghi vào
+        cột "Định hướng khách gợi ý" và hỏi ngược: chuyển xong thì cái gì tốt lên?
+
+        Ràng buộc tôi CHƯA có — cần bạn đi hỏi:
+        - Ngân sách hạ tầng/tháng (PO)
+        - Kakao có bắt buộc cloud/stack nào không (Tech Lead/EA)
+        - Dữ liệu POS có ràng buộc lãnh thổ không (Legal)
+        - Ai vận hành sau go-live (PM)
+
+        Cách hiểu: driver thật là phát hiện chênh lệch muộn 22 ngày (GOAL-02),
+        thuộc tính chất lượng bị ép là độ trễ xử lý + độ chính xác dữ liệu.
+
+        Ghi vào sa-output/Settlement/01-context/. Xác nhận giúp tôi.
+
+Bạn:    Ngân sách 15tr/tháng. Bắt buộc AWS ap-northeast-2. Dữ liệu phải ở Hàn.
+        Vận hành: đội SRE chung, 3 người, không có ai chuyên Kafka.
+
+Claude: [sinh CTX với DRV-01..03, CON-01..07, khung khảo sát hiện trạng
+         + cảnh báo: CON-05 "SRE không có kinh nghiệm Kafka" sẽ loại phương án
+         event-driven nặng, hoặc buộc phải tính chi phí đào tạo vào TCO]
+```
+
+## Lỗi thường gặp
+
+**"Skill toàn hỏi, chưa cho tôi câu trả lời nào."**
+Đúng như thiết kế ở Bước 2–3. Chọn kiến trúc mà không biết ngân sách và ràng buộc pháp lý là
+chọn bừa. Danh sách câu hỏi chính là danh sách việc bạn cần đi hỏi — mỗi câu trả lời loại bớt
+phương án, tiết kiệm nhiều hơn thời gian đi hỏi.
+
+**"Khách đã chốt công nghệ rồi, sao còn dựng phương án?"**
+Vì "khách đã chốt" thường là *một người* đã chốt dựa trên *một bài blog*. Dựng phương án thứ
+hai mất nửa ngày; phát hiện phương án đã chốt không chạy được mất ba tháng. Nếu khách vẫn giữ
+lựa chọn của họ sau khi xem bảng so sánh — ghi thành `CON-nn` ("ràng buộc do khách chỉ định")
+và đi tiếp, vậy là hợp lệ.
+
+**"Không lấy được số liệu tải hiện tại."**
+Đừng bỏ trống. Ghi `ASM-nn` + đề xuất cách ước: đếm số bản ghi trong DB chia cho số ngày, đọc
+log 1 tuần, hoặc hỏi người vận hành "ngày đông nhất bao nhiêu đơn". Ước lượng có ghi rõ cách
+ước vẫn tốt hơn không có gì — nhưng phải đánh dấu 🔴.
+
+**"TCO ra con số quá lớn, khách sẽ sốc."**
+Đó là giá trị của `TCO`, không phải vấn đề của nó. Con số lớn xuất hiện ở GĐ1 thì còn đổi
+được phương án; xuất hiện ở tháng thứ 13 thì đã muộn. Trình kèm bảng "cắt cái gì thì giảm bao
+nhiêu" để PO có lựa chọn.
+
+**"Phương án tôi thích thắng mọi tiêu chí."**
+Bộ tiêu chí đang được viết ngược từ kết luận. Thêm tiêu chí "chi phí đảo ngược" và "phù hợp
+năng lực vận hành" — hai tiêu chí này thường lật ngược kết quả.
+
+## Ra khỏi giai đoạn này khi nào
+
+Đủ cả bốn:
+
+1. Bảng tự chấm AG1 toàn ✅
+2. PO **và** Tech Lead đã điền `Approved by` vào header `OPT`
+3. Mọi `ARISK` mức cao có chủ, có biện pháp cụ thể (không phải "theo dõi")
+4. Rủi ro cao chưa chứng minh được đã có POC **đã chạy xong**, kết quả ghi vào `ARISK`
+
+Rồi chạy `/sa-2-architecture <PROJECT>`.
+
+## Liên quan
+
+- Tiêu chí gate AG1: `../sa-lifecycle/references/workflow.md` §2
+- Quy tắc viết: `../sa-lifecycle/references/design-rules.md`
+- Khi nào cần POC: `../sa-lifecycle/references/decision-radar.md` §6
+- Template: `templates/solution-context.md` · `templates/option-tradeoff.md` ·
+  `templates/cost-model.md` · `templates/architecture-risk.md`