# 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 [--mode new|extend|replace] [--focus ctx|opt|tco|risk] [--out ] [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 ` | 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//01-context/`: ``` CTX__v1.0.md ← driver, ràng buộc, hiện trạng OPT__v1.0.md ← phương án + chấm điểm + khuyến nghị. PO+Tech Lead ký cái này TCO__v1.0.md ← chi phí 3 năm, 2 kịch bản tải ARISK__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 `. ## 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`