192 lines
10 KiB
Markdown
192 lines
10 KiB
Markdown
# 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`
|