sys-analysis-design/.claude/skills/sa-4-evolution/SKILL.md

name, description

name

description

sa-4-evolution

Giai đoạn 4 của quy trình Solution Architect — vận hành và tiến hoá kiến trúc sau khi hệ thống chạy thật. Dùng để đối chiếu telemetry production với NFR đã cam kết, so chi phí hạ tầng thực tế với TCO đã ước lượng, phát hiện drift giữa kiến trúc thiết kế và kiến trúc đang chạy, truy nguyên sự cố về quyết định hoặc giả định kiến trúc, đánh giá kiến trúc định kỳ (ATAM rút gọn), và lập roadmap kỹ thuật cho vòng sau. Kích hoạt khi người dùng nói "hệ thống chạy có đạt không", "đo lại NFR", "chi phí cloud tăng", "tối ưu chi phí hạ tầng", "kiến trúc lệch so với thiết kế", "đánh giá kiến trúc", "post-mortem", "sau sự cố", "roadmap kỹ thuật", "kế hoạch migrate", "modernize". Output vào sa-output/<PROJECT>/04-evolution/ và kết thúc bằng Gate AG4.

GĐ4 · EVOLUTION — Vận hành & tiến hoá

Mục tiêu duy nhất: đối chiếu kiến trúc đã thiết kế với kiến trúc đang chạy thật, và biến chênh lệch đó thành kế hoạch chứ không thành ngạc nhiên.

Output: CONF · TRM · PMR trong sa-output/<PROJECT>/04-evolution/

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

1. Không bịa số liệu vận hành — không đo được ⇒ ghi "chưa đo được vì …", không suy đoán.
2. Không quyết định thay PO về ưu tiên roadmap. Trình chi phí và rủi ro, PO xếp thứ tự.
3. Mọi kết luận phải truy vết được về một bài đo, một sự cố có mã, hoặc một hoá đơn.
4. Không sửa ADR cũ để hợp thức hoá thực tế — thực tế bác bỏ quyết định ⇒ ADR mới có Supersedes:, giữ nguyên bản cũ.

Nạp thêm: ../sa-lifecycle/references/design-rules.md · ../sa-lifecycle/references/artifact-map.md §4 (vòng đời ADR).

🔴 Mọi sơ đồ theo chuẩn Archify (W13, ../ba-lifecycle/references/diagram-rules.md): spec JSON diagrams/<ARTIFACT>_<slug>.<type>.json (quality_profile: showcase, validate 0 lỗi) + mermaid có marker <!-- archify: <type> · <spec> --> (hoặc mermaid-only cho ERD/use case/2×2) + bảng đi kèm. Một đường chính, ≤ 12 node, nhãn cạnh là điều kiện/giao thức, không màu. Không có Bash ⇒ ghi humanInputNeeded "chạy archify validate/deliver + diagram-check", không tự nhận đã validate. Phụ thuộc roadmap (TRM §4) → workflow; drift so với SAD đối chiếu theo spec diagrams/ của SAD; quy tắc D4.

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

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

1. Input dùng được — sa-output/…/02-architecture/ (QAS, SAD, ADR, INF), 01-context/TCO, 03-enablement/ (FIT, TDEBT), cộng số liệu vận hành thật: dashboard, log sự cố, hoá đơn cloud, kết quả FIT trên CI.
2. Kiểm dữ liệu vận hành — có đủ để đối chiếu không? Thiếu cái gì? Không có telemetry thì CONF chỉ là bảng "chưa đo được" — nói rõ điều đó trước khi chạy.
3. Chọn phạm vi — --focus conf|roadmap|review. Sau một sự cố lớn thì --focus review; định kỳ hàng tháng thì --focus conf.
4. Hỏi người dùng xác nhận ba điểm trên.

Bỏ bước dừng khi lệnh có go.

Thực hiện — 3 hoạt động

1 — Conformance report CONF (--focus conf)

Điền templates/conformance-report.md. Bốn đối chiếu:

a. QAS × telemetry thật

Mỗi QAS một dòng: mục tiêu · đo được thật · đạt/không đạt/chưa đo được.

🔴 "Chưa đo được" là một kết quả hợp lệ và phải ghi ra. Nó có nghĩa là AG2 định nghĩa cách đo không khả thi, hoặc observability thiếu — cả hai đều là phát hiện có giá trị. Che nó bằng một con số ước lượng là cách tệ nhất.

b. TCO × hoá đơn thật

Từng hạng mục. Chênh lệch > 20% phải giải thích được bằng một trong bốn lý do: tải khác dự kiến · cấu hình khác thiết kế · hạng mục bị bỏ sót khi ước lượng · đơn giá thay đổi. Không thuộc bốn loại ⇒ đang có thứ gì đó chạy mà không ai biết.

c. Sự cố × quyết định kiến trúc

Mỗi sự cố trong kỳ truy về một trong ba:

Truy về	Nghĩa là	Hành động
Một ADR	Quyết định đó có hệ quả đã ghi hoặc chưa ghi	Cập nhật mục "Hệ quả" của ADR; nếu quyết định sai ⇒ ADR mới
Một ASM	Giả định sai	Sửa giả định, rà mọi thứ dựa trên nó
Điểm mù mới	Không ai nghĩ tới	Giá trị cao nhất — thêm QAS/FM mới

d. Kiến trúc thiết kế × kiến trúc đang chạy (drift)

Nguồn phát hiện drift	Cách kiểm
FIT đỏ hoặc bị tắt	Đọc lịch sử CI
Component có trong code mà không có trong SAD	So sơ đồ với cấu trúc repo/deployment thật
Interface đang gọi mà không có trong ICD	Đọc trace/log, không đọc code
Whitelist FIT quá hạn	FIT §3
TD quá hạn xét lại	TDEBT

🔴 Đọc trace và log để tìm interface thật, đừng chỉ đọc code. Lời gọi phát sinh lúc chạy (cấu hình, plugin, job) không lộ ra khi đọc code tĩnh.

2 — Technical roadmap TRM (--focus roadmap)

Điền templates/technical-roadmap.md.

Nguồn đầu vào của roadmap, theo thứ tự ưu tiên:

1. QAS không đạt ở CONF — cam kết đang bị phá
2. TD mức cao có lãi suất lớn — đang làm chậm mọi thứ
3. Drift phải đóng — kiến trúc thật đang trôi khỏi kiến trúc thiết kế
4. Chi phí vượt TCO — tiền chảy mỗi tháng
5. Rủi ro mới (vendor, cuối vòng đời công nghệ, tuân thủ)
6. Chuẩn bị cho tải/tính năng đã biết trước trong roadmap sản phẩm

Mỗi mục: vấn đề · phương án · chi phí · lợi ích bằng số · rủi ro nếu không làm · phụ thuộc.

🔴 Không xếp thứ tự thay PO. Trình bảng "chi phí × lợi ích × rủi ro nếu không làm" và để PO xếp. Ngoại lệ duy nhất: mục thuộc tuân thủ pháp lý hoặc bảo mật mức cao — nêu rõ đó là ràng buộc, không phải lựa chọn.

Với mục là migration, bắt buộc có: các bước cắt chuyển · cách chạy song song · cách rollback ở từng bước · tiêu chí đi tiếp.

3 — Architecture review / post-mortem PMR (--focus review)

Điền templates/architecture-review.md. Hai chế độ:

a. Định kỳ (ATAM rút gọn) — mỗi quý:

1. Rà lại QAS: còn đúng với nhu cầu hiện tại không? Cái nào thừa, cái nào thiếu?
2. Với mỗi QAS quan trọng, tìm điểm nhạy cảm (chỗ một thay đổi nhỏ làm thuộc tính đó đổi nhiều) và điểm đánh đổi (chỗ cải thiện thuộc tính này làm hỏng thuộc tính kia)
3. Rà ADR Accepted: điều kiện xét lại ở §7 của mỗi ADR đã chạm ngưỡng chưa?
4. Rà rủi ro mới: vendor, cuối vòng đời, tuân thủ, nhân sự

b. Sau sự cố (post-mortem kiến trúc) — chỉ cho sự cố có nguyên nhân kiến trúc:

Post-mortem vận hành thuộc SRE. Phần kiến trúc trả lời ba câu:

1. Kiến trúc đã cho phép sự cố này xảy ra ở chỗ nào? (không phải "ai làm sai")
2. Thiết kế đã dự đoán tình huống này chưa? Có trong FAIL không?
3. Sửa ở tầng nào là đúng: code · cấu hình · kiến trúc · quy trình?

🔴 Không đổ lỗi cho người. "Dev quên đặt timeout" là triệu chứng; câu hỏi kiến trúc là "vì sao hệ thống cho phép một lời gọi không timeout tồn tại, và làm sao để lần sau không thể". Câu trả lời thường là một FIT mới.

Trước khi kết thúc

In bốn thứ:

① Bảng tự chấm Gate AG4 (../sa-lifecycle/references/workflow.md §2) dạng ☐/✅.

② Bảng QAS × thực tế — đạt / không đạt / chưa đo được, kèm số.

③ Bảng TCO × hoá đơn — chênh lệch từng hạng mục, giải thích cho chênh > 20%.

④ Ba mục đầu của TRM kèm chi phí và lợi ích bằng số, để PO xếp thứ tự.

Rồi nhắc người dùng: AG4 cần PO + SRE + Enterprise Architect ký.

Bẫy thường gặp

Không đo được vì AG2 không định nghĩa cách đo. Đây là hậu quả trực tiếp của việc để lọt QAS thiếu dòng "đo bằng cách nào". Ghi nhận thành bài học trong PMR, đừng lấp liếm bằng ước lượng.

Chỉ nhìn giá trị trung bình. Trung bình luôn đẹp. QAS viết theo phân vị thì đo theo phân vị — p95 và p99 mới là chỗ người dùng khó chịu.

Bỏ qua chi phí vì "vẫn trong ngân sách". Trong ngân sách nhưng gấp 3 lần ước lượng nghĩa là mô hình chi phí sai, và nó sẽ sai tiếp khi tải tăng. Truy nguyên chênh lệch dù chưa vượt.

Sửa ADR cũ cho khớp thực tế. Làm mất giá trị lớn nhất của ADR: ghi lại điều ta đã tin lúc đó. Viết ADR mới có Supersedes: và để bản cũ nguyên vẹn.

Post-mortem thành cuộc tìm người có lỗi. Sự cố lặp lại được nghĩa là hệ thống cho phép nó lặp lại. Câu hỏi đúng là "làm sao để lần sau không thể xảy ra", và câu trả lời thường là một bài kiểm tự động, không phải một lời nhắc nhở.

Roadmap kỹ thuật toàn mục "tái cấu trúc". PO sẽ không duyệt. Mỗi mục phải có lợi ích bằng số theo ngôn ngữ của họ: giảm bao nhiêu tiền/tháng, nhanh hơn bao nhiêu ngày mỗi tính năng, giảm bao nhiêu sự cố.