sys-analysis-design/.claude/skills/sa-1-context/SKILL.md

name, description

name

description

sa-1-context

Giai đoạn 1 của quy trình Solution Architect — xác lập bối cảnh và chọn phương án giải pháp. Dùng khi cần làm rõ driver kinh doanh đứng sau một hệ thống, liệt kê ràng buộc (ngân sách, deadline, cloud/stack bắt buộc, kỹ năng team, pháp lý), khảo sát hiện trạng as-is, dựng và chấm điểm 2-3 phương án build/buy/integrate, ước lượng TCO 3 năm, và lập sổ rủi ro kiến trúc kèm kế hoạch POC. Kích hoạt khi người dùng nói "nên dùng công nghệ gì", "so sánh phương án", "build hay mua", "ước lượng chi phí hạ tầng", "TCO", "rủi ro kỹ thuật", "khảo sát hiện trạng hệ thống", "đánh giá khả thi kỹ thuật", "cần POC gì". Output ghi vào sa-output/<PROJECT>/01-context/ và phải qua Gate AG1 trước khi sang sa-2-architecture.

GĐ1 · CONTEXT — Bối cảnh, ràng buộc & lựa chọn phương án

Mục tiêu duy nhất: chốt được chọn phương án nào, vì sao, tốn bao nhiêu, rủi ro ở đâu — trước khi bất kỳ ai vẽ một hộp nào.

Output: CTX · OPT · TCO · ARISK trong sa-output/<PROJECT>/01-context/

Bốn nguyên tắc bất di bất dịch

1. Không bịa ràng buộc — thiếu thông tin ⇒ OQ-nnn, không điền con số "hợp lý".
2. Không quyết định thay PO — trade-off nghiệp vụ và ngân sách là của PO; SA trình bảng đánh đổi kèm hệ quả bằng số.
3. Mọi phương án phải truy vết được về DRV-nn và CON-nn. Không nguồn ⇒ ASM-nn.
4. Không ghi đè tài liệu đã qua gate — sửa qua ADR mới hoặc DEC-nn kèm Change Log.

Nạp thêm: ../sa-lifecycle/references/design-rules.md (D1–D12) và ../sa-lifecycle/references/artifact-map.md §3 (header bắt buộc, kể cả Confidence).

Bước 0 — Chốt input rồi dừng lại

Chưa được ghi file. Làm năm việc rồi dừng chờ người dùng trả lời:

1. Input dùng được — bảng File/Nguồn | Vai trò | Độ tin cậy. Ưu tiên: file người dùng đưa trong hội thoại > ba-output/<PROJECT>/01-discovery/ (BRIEF, GOAL) > ba-output/…/02-analysis/ (BACKLOG, IMPACT) > source code hiện có > docs/.
2. Phân loại bài toán — hệ thống mới hoàn toàn / mở rộng hệ thống đang chạy / thay thế hệ thống cũ (migration). Ba loại này khác nhau hoàn toàn về khối lượng GĐ1: loại 2 rút gọn CTX (chỉ phần delta), loại 3 bắt buộc có phần dữ liệu legacy trong OPT.
3. Ai trả lời được ràng buộc — ngân sách (PO), stack/cloud bắt buộc (Tech Lead/EA), pháp lý (Legal/Security), năng lực vận hành (SRE). Chưa biết ⇒ nói rõ.
4. Cách hiểu bài toán — 2–3 câu, kèm tên file định ghi ra.
5. Hỏi người dùng xác nhận bốn điểm trên.

Bỏ bước dừng khi lệnh có go — khi đó ghi phần tự đánh giá input vào mục Open Questions của CTX và đặt Confidence 🔴.

Thực hiện — 5 bước

Bước 1 — Driver trước, giải pháp sau

Điền templates/solution-context.md §Driver.

DRV-nn là áp lực kinh doanh, không phải tính năng. Phép thử: câu đó có nói được bằng tiền, thời gian, rủi ro, hoặc số người không?

DRV-02 | Đối soát thủ công tốn 2 người × 4 giờ/ngày và phát hiện chênh lệch trung bình
         sau 22 ngày. Mỗi ngày chậm ≈ 30 triệu tiền treo không thu hồi được.
         Nguồn: BRIEF §2 GOAL-02 · Ai xác nhận: chị Lan (2026-08-22)
         Thuộc tính chất lượng bị ép: độ trễ xử lý, độ chính xác dữ liệu

🔴 Bẫy công nghệ giả dạng driver. "Cần chuyển sang microservices" không phải driver — hỏi ngược: "Chuyển xong thì cái gì tốt lên, đo bằng gì?". Câu trả lời ("ba team đang phải chờ nhau release, mỗi lần chờ 2 tuần") mới là DRV. Ghi mong muốn công nghệ của khách vào cột riêng "Định hướng khách gợi ý" — có giá trị tham khảo, không phải driver.

Cột "Thuộc tính chất lượng bị ép" ở mỗi DRV là cầu nối sang GĐ2: nó chính là danh sách QAS cần lượng hoá.

Bước 2 — Ràng buộc, rà đủ sáu nhóm

Điền templates/solution-context.md §Ràng buộc. CON-nn là thứ không thương lượng được, khác với sở thích.

Nhóm	Câu hỏi phải hỏi	Hỏi ai	Bỏ sót thì sao
Tiền	Ngân sách hạ tầng/tháng đã duyệt? Chi phí một lần cho phép?	PO / tài chính	Thiết kế xong mới biết không đủ tiền chạy
Thời gian	Mốc bắt buộc nào có ràng buộc bên ngoài (hợp đồng, luật, mùa vụ)?	PO / PM	Chọn phương án đúng nhưng không kịp
Công nghệ	Cloud/stack/chuẩn doanh nghiệp bắt buộc? License đã mua?	Tech Lead / EA	Kiến trúc bị EA bác ở phút chót
Con người	Team bao nhiêu, kỹ năng gì, ai vận hành sau go-live?	PM / SRE	Chia 8 service cho 5 người (trái Conway)
Pháp lý	Dữ liệu phải nằm trong lãnh thổ nào? Luật nào áp dụng? Kiểm toán gì?	Legal / Security	Phải làm lại toàn bộ tầng dữ liệu
Hiện trạng	Hệ thống nào bắt buộc phải tích hợp? Vendor nào đang khoá?	Tech Lead	Phát hiện ở GĐ2 khi đã cam kết thiết kế

🔴 Ba nhóm hay bị bỏ nhất: con người (ai vận hành hệ thống sau khi team dự án giải tán), pháp lý (người có quyền phủ quyết muộn nhất và đau nhất), tiền vận hành (ai cũng ước lượng effort dev, ít ai ước lượng hoá đơn cloud tháng thứ 13).

Bước 3 — Khảo sát hiện trạng

Điền templates/solution-context.md §Hiện trạng. Không có bước này thì OPT chỉ là so sánh công nghệ trên giấy.

Bốn thứ phải nhìn tận mắt, không nhận qua mô tả:

Khảo sát	Cách làm	Ghi lại gì
Hệ thống as-is	Đọc code / sơ đồ / hỏi người đang vận hành	Sơ đồ C4 mức Context của hiện tại
Dữ liệu	Mở DB thật, đếm bản ghi, xem chất lượng dữ liệu	Số bảng, số bản ghi lớn nhất, tỉ lệ dữ liệu bẩn
Tích hợp	Đọc tài liệu API bên kia, gọi thử nếu được	Danh sách interface, ai sở hữu, SLA của họ
Vận hành	Xem dashboard, log, hoá đơn cloud, lịch sử sự cố	Traffic thật, p95 hiện tại, chi phí/tháng, sự cố 6 tháng

🔴 Dữ liệu không biết nói dối. Khách nói "khoảng 2.000 đơn/ngày", DB nói 340 đơn/ngày với đỉnh 11.000 vào ngày khuyến mãi. Cả hai con số đều quan trọng và chỉ số thứ hai định hình kiến trúc. Không truy cập được dữ liệu thật ⇒ ghi ASM-nn + OQ, hạ Confidence 🔴.

Bước 4 — Dựng và chấm phương án

Điền templates/option-tradeoff.md. Tối thiểu 2 phương án thực sự khác nhau, cộng phương án "không làm gì / giữ nguyên" làm mốc so sánh.

Quy trình bắt buộc, theo đúng thứ tự:

1. Chốt bộ tiêu chí trước khi mô tả phương án. Tiêu chí sinh từ DRV và CON, có trọng số, PO duyệt trọng số. Chốt tiêu chí sau khi đã có phương án yêu thích là tự lừa mình.
2. Mô tả mỗi phương án đủ để ước lượng: thành phần chính, cái gì mua/cái gì tự làm, dữ liệu ở đâu, ai vận hành.
3. Chấm điểm từng tiêu chí, kèm một câu lý do cho mỗi ô. Ô không có lý do là ô bịa.
4. Nêu rõ phương án bị loại và lý do loại — bắt buộc theo D3.
5. Khuyến nghị của SA, kèm điều kiện: "Khuyến nghị P2, với điều kiện POC-01 chứng minh được throughput ≥ 500 msg/s. POC fail ⇒ chuyển sang P1."

Bộ tiêu chí mặc định (cắt/thêm theo dự án, giữ trọng số cộng lại 100%):

Tiêu chí	Trọng số gợi ý	Đo bằng
Đáp ứng DRV mức Must	25%	Có/không cho từng driver
Chi phí 3 năm (TCO)	20%	Tiền
Thời gian tới bản chạy được	15%	Tuần
Rủi ro kỹ thuật	15%	Số ARISK mức cao
Phù hợp năng lực team & vận hành	15%	Kỹ năng phải tuyển/đào tạo
Khả năng tiến hoá (đổi được về sau)	10%	Chi phí đảo ngược

🔴 Đừng chấm điểm để hợp thức hoá lựa chọn đã có. Dấu hiệu: phương án yêu thích thắng mọi tiêu chí. Kiến trúc thật luôn có đánh đổi — phương án thắng phải thua ở ít nhất một tiêu chí, và chỗ thua đó phải được nói ra.

Bước 5 — Chi phí và rủi ro

TCO — điền templates/cost-model.md. Ba nguyên tắc:

• Tính 3 năm, không tính một lần. Chi phí kiến trúc nằm ở năm thứ hai và ba.
• Bốn nhóm, thiếu nhóm nào cũng sai: hạ tầng · license · vận hành (người + công cụ) · xây dựng.
• Tối thiểu 2 kịch bản tải (dự kiến, và dự kiến × 3). Kiến trúc chỉ chạy đúng ở một mức tải là kiến trúc chưa xong.

ARISK — điền templates/architecture-risk.md. Rà đủ sáu nguồn rủi ro:

Nguồn	Câu hỏi
Công nghệ mới	Có ai trong team từng chạy production cái này chưa?
Phụ thuộc bên ngoài	Bên kia có SLA không? Ta có phương án khi họ hỏng/đổi/ngừng?
Dữ liệu	Migration có rollback được không? Dữ liệu bẩn tới mức nào?
Hiệu năng	Con số throughput/latency lấy từ đâu — bài đo hay suy đoán?
Con người	Người duy nhất biết hệ thống cũ có còn ở công ty không?
Chi phí	Hoá đơn cloud có thành phần nào tăng theo tải một cách phi tuyến không?

Mỗi ARISK-nn: mô tả · xác suất × tác động · chủ · biện pháp hạ rủi ro · hạn. Rủi ro mức cao mà biện pháp là "sẽ theo dõi" ⇒ chưa có biện pháp. Phải là POC, spike, đàm phán hợp đồng, hoặc đổi phương án.

Kế hoạch POC — mọi rủi ro cao chưa chứng minh được phải có POC với tiêu chí pass/fail viết trước khi làm (xem ../sa-lifecycle/references/decision-radar.md §6).

Trước khi kết thúc

In ba thứ:

① Bảng tự chấm Gate AG1 (checklist ở ../sa-lifecycle/references/workflow.md §2) dạng ☐/✅. Mục chưa đạt phải nói rõ thiếu gì — không đánh ✅ cho có.

② Checklist D1–D12 (../sa-lifecycle/references/design-rules.md) dạng ☐/✅.

③ Danh sách OQ mở kèm người phải trả lời, deadline đề xuất, và cái nó chặn.

Rồi nhắc người dùng: AG1 cần PO + Tech Lead ký (điền Approved by vào header OPT) trước khi chạy /sa-2-architecture.

Bẫy thường gặp

Nhảy sang thiết kế quá sớm. Dấu hiệu: trong CTX đã xuất hiện tên service, tên bảng, tên queue. GĐ1 chỉ nói áp lực, ràng buộc, phương án ở mức khối. Thấy mình đang vẽ component ⇒ dừng, quay lại hỏi "driver nào ép ra cái này".

Một phương án duy nhất. "Chúng ta sẽ dùng X" không phải lựa chọn, đó là thói quen được viết hoa. Bắt buộc dựng phương án thứ hai đủ nghiêm túc để nó có thể thắng.

Ước lượng chỉ có effort dev. Hỏi ba câu: hoá đơn cloud tháng thứ 13 bao nhiêu? Ai trực sự cố? Chi phí license khi số người dùng gấp đôi?

Lấy con số hiệu năng từ blog. "Kafka làm được 1 triệu msg/s" — trong ngữ cảnh của họ, phần cứng của họ, kích thước message của họ. Con số dùng để quyết định phải đến từ POC trong ngữ cảnh của bạn, hoặc được đánh dấu 🔴 giả định.

Bỏ qua phương án "không làm gì". Nó là mốc so sánh, và đôi khi nó thắng. Không đưa nó vào thì không ai biết dự án tạo ra bao nhiêu giá trị so với hiện trạng.