genneral/sys-analysis-design
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
51506aabc7f2e0946078c5ec1cbe594597ade36c
sys-analysis-design/.claude/skills/sa-lifecycle/references/workflow.md
Canhchimlac 51506aabc7 update skill and docs
2026-09-22 13:46:36 +07:00

12 KiB
Raw Blame History

Workflow SA — 4 giai đoạn, 4 gate

1. Sơ đồ

      bài toán nghiệp vụ đã phát biểu được (BRIEF/BACKLOG của BA)
              │
   ┌──────────▼──────────┐
   │ GĐ1 · CONTEXT       │  driver là gì, ràng buộc gì, chọn phương án nào
   │ sa-1-context        │
   └──────────┬──────────┘
              │ AG1 — PO + Tech Lead ký: phương án & ngân sách đã chốt
   ┌──────────▼──────────┐
   │ GĐ2 · ARCHITECTURE  │  lượng hoá NFR, phân rã, contract, dữ liệu, bảo mật, hạ tầng
   │ sa-2-architecture   │
   └──────────┬──────────┘
              │ AG2 — Tech Lead + Security + Ops ký: Ready for Build
   ┌──────────▼──────────┐
   │ GĐ3 · ENABLEMENT    │  guideline, fitness function, design review, tech debt
   │ sa-3-enablement     │
   └──────────┬──────────┘
              │ AG3 — Tech Lead + QA + SRE ký: kiến trúc thi công đúng, sẵn sàng go-live
   ┌──────────▼──────────┐
   │ GĐ4 · EVOLUTION     │  đối chiếu telemetry, đánh giá drift, roadmap kỹ thuật
   │ sa-4-evolution      │
   └──────────┬──────────┘
              │ AG4 — PO + SRE + EA ký: đóng vòng hoặc mở vòng kiến trúc mới
              ▼

sa-conformance chạy song song, cập nhật DTM + ADL sau mỗi giai đoạn và có quyền chặn AG2, AG3, AG4.

2. Tiêu chí pass từng gate

Gate chỉ ✅ khi đủ artifact và đủ nội dung và có chữ ký duyệt ghi trong header artifact (dòng Approved by: <tên> · <ngày>).

Gate kiến trúc khác gate BA ở một điểm: không ký được bằng "trông hợp lý". Mỗi mục dưới đây phải chỉ ra được bằng chứng — một con số, một ADR, một kết quả POC, một bài đo.

AG1 — Option sign-off · duyệt bởi PO + Tech Lead

  • CTX có DRV-nn (driver) — mỗi driver ghi rõ áp lực kinh doanh đứng sau, không phải tính năng
  • CTX có CON-nn (ràng buộc): ngân sách, deadline, cloud/stack bắt buộc, kỹ năng team, pháp lý
  • CTX mô tả hiện trạng as-is: hệ thống, dữ liệu, tích hợp, hợp đồng vendor đang có
  • OPT có ≥ 2 phương án được chấm điểm theo cùng bộ tiêu chí, và nêu rõ phương án bị loại + lý do
  • TCO có chi phí 3 năm: hạ tầng + license + vận hành + con người, theo ≥ 2 kịch bản tải
  • ARISK có rủi ro kỹ thuật mức cao, mỗi cái có người chịu trách nhiệm và cách hạ rủi ro
  • Rủi ro mức cao chưa chứng minh được ⇒ có kế hoạch POC kèm tiêu chí pass/fail

Chặn: chỉ có một phương án ("chúng ta sẽ dùng X") — đó không phải lựa chọn, đó là thói quen. Chặn: ước lượng chỉ có effort dev, không có chi phí hạ tầng và vận hành.

AG2 — Ready for Build · duyệt bởi Tech Lead + Security + Ops/SRE

  • ASR liệt kê yêu cầu thực sự định hình kiến trúc, mỗi cái truy về DRV hoặc QAS
  • QAS — mọi NFR đã lượng hoá: kịch bản · con số · cách đo · ai đo. Không còn NFR định tính
  • SAD có sơ đồ C4 mức Context và Container, có deployment view, mỗi CMP-nn ghi rõ trách nhiệm
  • ADR-nnn tồn tại cho mọi quyết định đạt ngưỡng ở decision-radar.md, mỗi cái nêu phương án đã loại
  • ICD — mọi interface ra khỏi hệ thống có contract, owner, versioning policy, chế độ sync/async
  • DAT — mỗi thực thể dữ liệu có đúng một chủ sở hữu; có phân loại PII và retention
  • SEC — có threat model STRIDE cho luồng nhạy cảm; mô hình authn/authz đã chốt; Security ký
  • INF — topology môi trường, HA/DR có RTO/RPO bằng số, chiến lược scale, observability
  • FAIL — mỗi phụ thuộc ra ngoài process có failure mode, timeout, retry, fallback
  • DOM — class diagram cho mỗi bounded context có ghi/đọc dữ liệu: aggregate, entity, value object, invariant truy về BR-nnn; mọi entity có trong DAT §1
  • PDM — schema vật lý đủ cột cho mọi thực thể DAT: kiểu, null, default, constraint, PK/FK/index, cờ PII; DDL + migration trong 02-architecture/schema/ chạy được từ rỗng và có rollback; công cụ migration chốt bằng ADR
  • CTR — mọi IF-nnn sync có file OpenAPI 3.1 và mọi IF-nnn async có file AsyncAPI trong 02-architecture/contracts/, lint pass; cột "Contract ở đâu" của ICD trỏ tới file thật, không "dự kiến"; mỗi mã lỗi E-… của BA có trong response schema
  • Mọi sơ đồ (SAD, INF, SEC, DAT) có spec Archify validate pass; diagram-check.mjs không 🔴
  • sa-conformance báo coverage ASR → ADR/CMP ≥ 100%, IF → CTR = 100%, DAT thực thể → PDM bảng = 100%

Chặn: còn QAS nào ghi "nhanh", "ổn định", "bảo mật" mà không có con số. Chặn: còn interface nào không biết ai sở hữu, hoặc còn "contract dự kiến" chưa có file. Chặn: còn thực thể trong DAT không có bảng trong PDM, hoặc migration không có rollback. Đây là gate nghiêm nhất — một quyết định sai lọt qua AG2 sẽ thành một cuộc viết lại.

AG3 — Build conformance · duyệt bởi Tech Lead + QA + SRE

  • HANDOFF ban hành trong tuần đầu thi công: mọi dòng checklist §2 ✅ bằng đường dẫn thật (SRS/AC theo US, PDM, CTR, ADR, AGD, FAIL), không còn "dự kiến"; Tech Lead + đại diện dev BE/FE/QA ký đã nhận
  • AGD đã ban hành và có reference implementation chạy được, không chỉ văn bản; reference implementation chạy migration của PDM và tuân contract trong CTR
  • FIT — mỗi ràng buộc kiến trúc quan trọng có một kiểm thử tự động, đang xanh trên CI
  • DREV ghi mọi lần review kiến trúc, mỗi phát hiện có trạng thái đóng/mở
  • Mọi QAS mức Must đã có bài đo thực tế chứng minh đạt (không phải ước lượng)
  • FAIL đã được kiểm chứng: ít nhất các failure mode mức cao đã diễn tập (chaos/fault injection hoặc thủ công)
  • TDEBT — mọi lệch so với kiến trúc đã ghi nhận, có chủ và có hạn, không có mục "sẽ sửa sau" trống
  • sa-conformance báo coverage QAS → bài đo và ràng buộc → FIT ≥ 100% cho mức Must

Chặn: ràng buộc kiến trúc chỉ tồn tại trong văn bản, không có fitness function — theo D8 đó là khuyến nghị, không phải ràng buộc.

AG4 — Operational review · duyệt bởi PO + SRE + Enterprise Architect

  • CONF đối chiếu telemetry production với từng QAS: đạt / không đạt / chưa đo được
  • Chi phí hạ tầng thực tế so với TCO, giải thích chênh lệch > 20%
  • Mọi sự cố production trong kỳ truy được về một ADR, một ASM, hoặc ghi nhận là điểm mù mới
  • PMR — đánh giá kiến trúc, liệt kê drift so với SAD
  • TRM — roadmap kỹ thuật vòng sau, TDEBT đã xếp ưu tiên và đưa vào backlog
  • ADL — mọi ADR có trạng thái đúng (Accepted / Superseded / Deprecated)

Chặn: không đo được QAS vì AG2 không định nghĩa cách đo — ghi nhận là bài học, không lấp liếm.

3. Ai làm gì

Vai trò Trách nhiệm trong pipeline SA
Solution Architect Sở hữu toàn bộ artifact ở đây. Thiết kế, quyết định, ghi ADR, gác conformance
PO / Khách hàng Quyết trade-off nghiệp vụ và ngân sách. Ký AG1, AG4
Tech Lead Ký AG1–AG3 về khả thi thi công. Phản biện thiết kế. Sở hữu chất lượng code
Security Ký AG2. Có quyền phủ quyết threat model và mô hình authz
Ops / SRE Ký AG2, AG3, AG4. Chốt HA/DR, observability, chi phí vận hành
QA Ký AG3. Xác nhận QAS đo được và đã đo
Enterprise Architect Ký AG4. Xác nhận không lệch chuẩn doanh nghiệp
BA Cung cấp input nghiệp vụ. Không ký gate kiến trúc

SA không thay PO quyết trade-off nghiệp vụ, không thay Security chấp nhận rủi ro, không thay PM quản tiến độ — nhưng phải cung cấp đủ thông tin để cả ba ra quyết định.

4. Khớp với pipeline BA

Hai bộ chạy đan xen, không nối tiếp. Bảng này chốt thứ tự thật:

Mốc Điều kiện Vì sao
SA GĐ1 bắt đầu BA đã qua G1 (có BRIEF, GOAL, RQ) Không có driver thì không chấm được phương án
BA gate G2 SA đã qua AG1 Tech Lead ký G2 "khả thi kỹ thuật" dựa trên OPT + ARISK của SA
BA gate G3 SA đã qua AG2 API contract trong SRS phải khớp ICD; NFR của BA phải khớp QAS
BA gate G4 SA đã qua AG3 UAT không nên chạy trên kiến trúc chưa đo được NFR
BA gate G5 SA đã qua AG4 Benefit review nghiệp vụ đi cùng conformance kỹ thuật

🔴 Điểm giao thường bị bỏ: BA viết API contract đề xuất ở GĐ3 và đánh dấu "BA đề xuất — chờ BE xác nhận". Người xác nhận đó chính là SA qua ICD. Không nối hai chỗ này thì SRS và kiến trúc lệch nhau ngay từ ngày đầu.

5. Khi nào được bỏ giai đoạn

Tình huống Được bỏ Bắt buộc giữ
Thêm màn hình trong module đã có, không đổi contract GĐ1, GĐ2 Rà FIT còn xanh, cập nhật SAD nếu thêm CMP
Thêm tính năng có endpoint mới, không đổi mô hình dữ liệu GĐ1 GĐ2 rút gọn: chỉ ICD + QAS liên quan
Đổi mô hình dữ liệu / thêm tích hợp ngoài / đổi hạ tầng — Đủ 4 giai đoạn
Hệ thống mới hoàn toàn — Đủ 4 giai đoạn
POC / thử nghiệm GĐ3, GĐ4 GĐ1 (để biết đang chứng minh gì), GĐ2 rút gọn

Bỏ giai đoạn phải ghi lý do vào DEC-nn trong 00-index/. Bỏ im lặng là nợ kiến trúc: sáu tháng sau không ai biết hệ thống đang chạy trên giả định nào.

6. Vòng lặp ngược

Gate không phải một chiều. Bốn đường quay lui hợp lệ:

  • GĐ3 → GĐ2: thi công phát hiện thiết kế không khả thi ⇒ ADR mới có Supersedes: ADR-nnn, cập nhật SAD, không cần ký lại AG2 nếu không đụng ICD/DAT/SEC. Đụng ⇒ ký lại.
  • GĐ4 → GĐ2: telemetry cho thấy QAS không đạt do thiết kế ⇒ mở ADR mới, đây là tín hiệu AG2 đã ký trên ước lượng thay vì bài đo.
  • GĐ2 → GĐ1: thiết kế chi tiết cho thấy phương án đã chọn quá đắt ⇒ quay lại OPT, ghi DEC-nn giải thích vì sao đổi. Rẻ hơn nhiều so với phát hiện ở GĐ3.
  • Bất kỳ → GĐ1: driver kinh doanh thay đổi ⇒ CTX phiên bản mới, rà lại toàn bộ ADR có trạng thái Accepted xem còn đúng không.

7. Nhịp chạy đề xuất

Kiến trúc không phải một đợt làm rồi thôi. Nhịp tối thiểu cho một dự án 6 tháng:

Việc Tần suất
Cập nhật ADL + DTM (sa-conformance) Cuối mỗi sprint
Design review các thay đổi chạm kiến trúc (DREV) Theo yêu cầu, tối đa 2 ngày chờ
Rà TDEBT, xếp lại ưu tiên Hai tuần một lần
Đo QAS mức Must trên môi trường gần production Trước mỗi release
CONF đối chiếu telemetry Hàng tháng sau go-live
PMR đánh giá kiến trúc Mỗi quý hoặc sau mỗi sự cố nghiêm trọng