sys-analysis-design/.claude/skills/sa-2-architecture/GUIDE.md

Hướng dẫn sử dụng — sa-2-architecture (Giai đoạn 2)

Giai đoạn này giải quyết gì

Đầu vào là một phương án đã chọn (OPT qua AG1). Đầu ra là bộ thiết kế đủ để dev bắt tay code, QA biết đo cái gì, SRE biết vận hành thế nào — không ai phải quay lại hỏi "cái này để đâu, gọi ai, hỏng thì sao".

Không làm ở giai đoạn này: viết code sản phẩm, chọn thư viện tiện ích, quy ước đặt tên, cấu trúc thư mục. Những thứ đó thuộc sa-3-enablement và Tech Lead.

Đây là giai đoạn dài nhất — đừng chạy một lần

9 artifact là công việc nhiều tuần, không phải một buổi. Cách chạy đúng:

Tuần 1   /sa-2-architecture <P> --focus qas     → lượng hoá NFR (làm TRƯỚC mọi thứ)
         /sa-2-architecture <P> --focus asr     → chưng cất ASR
Tuần 2   /sa-2-architecture <P> --focus sad     → phân rã + C4 + ADR kiểu kiến trúc
Tuần 3   --focus icd · --focus dat              → chạy song song được
Tuần 4   --focus sec · --focus inf · --focus fail
Liên tục --focus adr                            → viết ADR mỗi khi có quyết định

🔴 Thứ tự 1→2→3 là bắt buộc. Vẽ sơ đồ trước khi có con số thì sơ đồ đó sẽ được bảo vệ bằng mọi giá về sau, kể cả khi con số nói nó sai.

Khi nào gọi

Tình huống	Có nên gọi
Đã qua AG1, bắt đầu thiết kế	✅ Chạy theo lịch trên
Thêm tính năng có endpoint mới, không đổi dữ liệu	✅ Rút gọn: --focus icd + --focus qas
Đổi mô hình dữ liệu / thêm tích hợp ngoài	✅ Bắt buộc --focus dat + --focus icd + ADR
Cần một quyết định được ghi lại	✅ --focus adr
Dev hỏi "chỗ này thiết kế thế nào"	❌ Nếu đã có SAD — sang sa-3-enablement
Chưa qua AG1	⚠️ Chạy được nhưng mọi Confidence là 🔴
Thêm một màn hình dùng API đã có	❌ Không cần SA

Cú pháp

/sa-2-architecture <PROJECT> [--focus qas|asr|sad|adr|icd|dat|sec|inf|fail|all] [--out <path>] [go]

--focus	Sinh ra	Cần có trước
qas	QAS — NFR lượng hoá	CTX, OPT
asr	ASR — yêu cầu định hình kiến trúc	QAS
sad	SAD + ADR kiểu kiến trúc	ASR
icd	ICD — interface catalog	SAD
dat	DAT — kiến trúc dữ liệu	SAD
sec	SEC — threat model + authz	SAD, DAT, RBAC của BA
inf	INF — hạ tầng, HA/DR	SAD, QAS, TCO
fail	FAIL — đường lỗi	SAD, ICD
adr	Một ADR mới	—
all	Cả 9 (cảnh báo: rất dài)

Viết một ADR cụ thể:

/sa-2-architecture Settlement --focus adr
  "quyết định dùng outbox pattern thay vì 2PC cho ghi đơn + phát event"

Chuẩn bị gì trước khi gọi

Cho bước	Chuẩn bị	Không có thì
qas	Số tải thật (CTX §4.4), ngưỡng chấp nhận của PO, ngân sách lỗi	QAS thành ước lượng 🔴
asr	BR của bộ BA (rule nào ép consistency/audit/retention)	Bỏ sót ràng buộc nghiệp vụ
sad	Cơ cấu team (CON-04), ai release độc lập với ai	Chia service trái Conway
icd	API contract đề xuất của BA, tài liệu API hệ thống ngoài	Contract lệch nhau ngay từ đầu
dat	Schema hiện tại, khối lượng dữ liệu legacy, yêu cầu pháp lý	Migration không rollback được
sec	RBAC của BA, chính sách bảo mật doanh nghiệp, người của Security	Bị phủ quyết ở AG2
inf	Báo giá cloud, TCO, năng lực đội SRE	INF lệch TCO
fail	SLA của mọi hệ thống ngoài	Không biết degrade thế nào

🔴 Bước sec cần một người thật từ Security ngồi cùng. Skill dựng được threat model, nhưng người có quyền phủ quyết phải tham gia từ đầu, không phải lúc trình gate.

Bạn sẽ nhận được gì

sa-output/<PROJECT>/02-architecture/
├── ASR_<PROJECT>_v1.0.md
├── QAS_<PROJECT>_v1.0.md          ← QA và SRE dùng cái này để đo
├── SAD_<PROJECT>_v1.0.md          ← tài liệu chính, Tech Lead ký
├── ICD_<PROJECT>_v1.0.md          ← dev BE/FE và đối tác dùng cái này
├── DAT_<PROJECT>_v1.0.md
├── SEC_<PROJECT>_v1.0.md          ← Security ký
├── INF_<PROJECT>_v1.0.md          ← SRE ký
├── FAIL_<PROJECT>_v1.0.md
└── adr/
    ├── ADR-001_kieu-kien-truc.md
    ├── ADR-002_chon-csdl-chinh.md
    └── …

Cộng bốn bảng in ra màn hình: Gate AG2 · quy tắc D1–D12 · đối chiếu với bộ BA · OQ mở.

Đọc một QAS thế nào

QAS-004 · Thông lượng đối soát · Must
  Kích thích  : job nửa đêm, 1,2 triệu bản ghi POS của một ngày
  Môi trường  : giờ thấp điểm, 1 node worker, DB không tải khác
  Phản hồi    : đối soát xong + sinh báo cáo chênh lệch
  Đo lường    : ≤ 45 phút (p95 trong 30 lần chạy)
  Đo thế nào  : perf/settlement-batch.js trên stg, dữ liệu sinh 1,2M bản ghi
  Ai đo       : QA + SRE, trước mỗi release

Thiếu dòng "Đo thế nào" thì QAS này không dùng được: AG3 yêu cầu bài đo thật cho mọi QAS mức Must, và không ai biết phải đo gì.

Ví dụ hội thoại

Bạn:    /sa-2-architecture Settlement --focus qas

Claude: [Bước 0]
        Input: CTX v1.0 ✅, OPT v1.0 ✅ (P2 tự xây, AG1 đã ký 2026-08-28),
               BRIEF §NFR của BA (5 mục, cả 5 đều định tính)

        AG1: ✅ đã qua.

        Tôi đọc được 5 NFR của BA, cả 5 chưa lượng hoá được:
        | NFR-01 "màn hình phải nhanh"      | cần: thao tác nào, tải nào, p95 bao nhiêu |
        | NFR-02 "hệ thống ổn định"         | cần: % uptime ⇒ ngân sách lỗi phút/tháng  |
        | NFR-03 "bảo mật dữ liệu POS"      | cần: mối đe doạ nào, kiểm chứng thế nào   |
        | NFR-04 "chịu được tăng trưởng"    | cần: tăng bao nhiêu trong bao lâu         |
        | NFR-05 "dễ bảo trì"               | không đo được ⇒ đề xuất bỏ hoặc đổi thành
                                              "onboard dev mới ≤ 3 ngày"               |

        Câu tôi cần bạn hỏi PO — mỗi câu quyết định một phần kiến trúc và chi phí:
        1. Hệ thống dừng 43 phút/tháng (99.9%) hay 4 phút/tháng (99.99%)?
           → chênh lệch chi phí hạ tầng khoảng 2,5×
        2. Job đối soát chạy xong trước mấy giờ sáng thì chấp nhận được?
        3. Chênh lệch số liệu được phép trễ bao lâu mới hiển thị? (0 giây hay 5 phút)
           → quyết định có dùng eventual consistency được không

        Xác nhận giúp tôi ghi vào sa-output/Settlement/02-architecture/QAS_…_v1.0.md
        với các mục chưa có câu trả lời để Confidence 🔴.

Lỗi thường gặp

"PO không trả lời được câu hỏi về uptime." Đừng hỏi bằng phần trăm. Hỏi bằng hệ quả: "Nếu hệ thống dừng 40 phút vào ngày chốt sổ thì chuyện gì xảy ra?" — PO trả lời được câu đó. Từ câu trả lời suy ra mức SLA, rồi trình kèm chênh lệch chi phí để PO chốt.

"Không đo được vì chưa có hệ thống." Đúng, và không sao. QAS ở GĐ2 là mục tiêu kèm cách đo đã thiết kế. Bài đo thật chạy ở GĐ3 (AG3). Cái phải có ngay bây giờ là con số mục tiêu và tên bài đo, không phải kết quả.

"Chia service thế nào là đúng?" Không có đáp án phổ quát. Ba câu hỏi loại bớt 90% phương án sai: (1) hai phần này có bao giờ release riêng không? (2) chúng có dùng chung dữ liệu ghi không? (3) đội vận hành có chịu nổi thêm một service nữa không? Ba lần "không" ⇒ đừng tách.

"Sơ đồ của tôi trông giống mọi sơ đồ khác." Kiểm tra: che phần chữ đi, sơ đồ còn nói được gì không? Mũi tên không nhãn giao thức, không phân biệt sync/async là mũi tên trang trí. Thêm nhãn, hoặc bỏ mũi tên.

"ADR nhiều quá, không ai đọc." Đang viết ADR cho quyết định không đạt ngưỡng. Chấm lại theo ../sa-lifecycle/references/decision-radar.md §2 — điểm 3–4 chỉ cần một dòng DEC-nn, không cần ADR. Sổ ADR chỉ có giá trị khi mọi mục trong đó đều đáng đọc.

"Security bảo phải làm lại toàn bộ tầng dữ liệu." Kinh điển, và tránh được: mời Security vào từ bước sec, không phải lúc trình AG2. Chi phí sửa ở GĐ2 là vài ngày; ở GĐ3 là vài tuần.

Ra khỏi giai đoạn này khi nào

Đủ cả năm:

1. Bảng tự chấm AG2 toàn ✅
2. Tech Lead + Security + Ops/SRE đã ký (Approved by trong header từng tài liệu)
3. Không còn QAS nào định tính; mọi QAS Must có tên bài đo
4. Mọi ADR điểm radar ≥ 8 đã có POC chạy xong
5. Bảng đối chiếu với bộ BA không còn dòng lệch chưa xử lý

Rồi chạy /sa-3-enablement <PROJECT>.

Liên quan

• Tiêu chí gate AG2: ../sa-lifecycle/references/workflow.md §2
• Quyết định nào cần ADR: ../sa-lifecycle/references/decision-radar.md
• Quy tắc viết: ../sa-lifecycle/references/design-rules.md
• Đối chiếu với bộ BA: ../sa-lifecycle/references/artifact-map.md §7
• Template: templates/quality-scenarios.md · templates/sad.md · templates/adr.md · templates/interface-catalog.md · templates/data-architecture.md · templates/security-architecture.md · templates/infrastructure-design.md · templates/failure-mode.md