sys-analysis-design/.claude/skills/sa-lifecycle/SKILL.md

name, description

name

description

sa-lifecycle

Điều phối công việc Solution Architect — xác định dự án đang ở giai đoạn kiến trúc nào, artifact nào đã có, gate nào đang chặn, và skill sa-* nào nên chạy tiếp. Dùng khi người dùng nói "bắt đầu làm kiến trúc", "tôi đang ở đâu", "quy trình SA thế nào", "cần làm gì tiếp", "review toàn bộ tài liệu kiến trúc", "khởi tạo dự án kiến trúc mới", hoặc khi họ mô tả một việc kiến trúc mà chưa rõ thuộc giai đoạn nào. Cũng dùng để khởi tạo cấu trúc thư mục sa-output cho một dự án mới và cập nhật INDEX.

SA · LIFECYCLE — Điều phối pipeline kiến trúc

Skill này không viết tài liệu kiến trúc. Nó trả lời ba câu và chuyển tiếp:

1. Dự án đang ở giai đoạn nào, gate nào đang chặn?
2. Artifact nào đã có, ở version nào, Confidence bao nhiêu, thiếu gì?
3. Việc tiếp theo là gì, chạy skill nào?

Nạp bắt buộc: references/workflow.md · references/artifact-map.md · references/design-rules.md · references/decision-radar.md

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 người có thẩm quyền — trade-off nghiệp vụ là của PO, rủi ro bảo mật là của Security. SA trình phương án kèm hệ quả bằng số.
3. Mọi quyết định phải truy vết được về một DRV, CON, ASR hoặc QAS. Không nguồn ⇒ là giả định, phải ghi ASM-nn và hạ Confidence.
4. Không ghi đè tài liệu đã qua gate — sửa qua ADR mới hoặc DEC-nn kèm Change Log.

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. Quét hiện trạng — tìm theo thứ tự: sa-output/<PROJECT>/, ba-output/<PROJECT>/, .docs/, docs/, và file người dùng đưa trong hội thoại (ưu tiên cao nhất).
2. Phân loại việc — người dùng đang cần: khởi tạo dự án mới · biết đang ở đâu · rà soát toàn bộ · hay chuyển tiếp một việc cụ thể?
3. Xác định đường dẫn ghi — mặc định sa-output/<PROJECT>/. Với project mới luôn hỏi xác nhận trước khi tạo thư mục đầu tiên.
4. Hỏi xác nhận ba điểm trên.

Bỏ bước dừng khi lệnh có go / chạy luôn.

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

Bước 1 — Dựng bảng trạng thái artifact

Quét sa-output/<PROJECT>/ và in bảng. Đọc header từng file, không đoán theo tên:

Loại	File	Version	Status	Confidence	Cập nhật	Ghi chú
CTX	01-context/CTX_…_v1.0.md	1.0	✅ Baselined	🟢	2026-08-25
QAS	—	—	❌ Chưa có	—	—	Chặn AG2

File không có header đúng quy ước ⇒ ghi ⚠️ header không hợp lệ, coi như chưa qua gate.

Bước 2 — Chấm gate

Với mỗi gate AG1..AG4 (tiêu chí ở references/workflow.md §2), in bảng ☐/✅ từng mục. Không đánh ✅ cho có — mục nào chưa đạt phải nói rõ thiếu cái gì và ai phải cung cấp.

Kết luận đúng một dòng:

Giai đoạn hiện tại: GĐ2 · Architecture
Gate gần nhất đã qua: AG1 (2026-08-25, ký bởi chị Lan + anh Tuấn)
Gate đang chặn: AG2 — thiếu QAS (7/9 NFR còn định tính), thiếu SEC (chưa có threat model)

Bước 3 — Kiểm tra đồng bộ với pipeline BA

Đọc ba-output/<PROJECT>/ nếu có. Đối chiếu theo references/artifact-map.md §7 và references/workflow.md §4. Bốn chỗ phải kiểm, đây là nơi hai bộ hay lệch nhau:

Kiểm	Cách kiểm	Lệch thì sao
BA NFR ↔ SA QAS	Mỗi NFR-* của BA có QAS-* tương ứng đã lượng hoá chưa	Ghi OQ, QAS thắng
BA API ↔ SA ICD/CTR	Endpoint trong API có IF-nnn và operationId trong file OpenAPI của CTR không	Ghi OQ, file contract thắng
BA SRS bảng field ↔ SA PDM	Mỗi FLD-* có cột cùng kiểu/độ dài/null	Ghi OQ, hai bên sửa cho khớp, chặn AG2
BA BR ↔ SA DOM	Mỗi BR ràng buộc dữ liệu/tính toán có class kiểm invariant	Thiếu ⇒ DOM bổ sung hoặc OQ cho BA
BA RBAC ↔ SA SEC	Mỗi ROLE-nn map được xuống cơ chế authz chưa	Ghi OQ, chặn AG2
BA BR ràng buộc kiến trúc	BR nào ép consistency/audit/retention đã có ADR chưa	Thiếu ⇒ đề xuất ADR

BA chưa qua G1 mà đã gọi SA ⇒ báo rõ: kiến trúc dựng trên bài toán chưa chốt sẽ phải làm lại. Vẫn chạy được nếu người dùng muốn, nhưng Confidence toàn bộ artifact GĐ1 phải là 🔴.

Bước 4 — Rà sổ quyết định và rủi ro

In ba bảng ngắn:

① ADR cần chú ý — mọi ADR ở trạng thái Proposed quá 10 ngày, mọi ADR Accepted mà QAS nguồn của nó đã đổi, mọi ADR điểm radar ≥ 8 chưa có POC.

② ARISK mức cao đang mở — kèm chủ và hạn. Rủi ro quá hạn ⇒ đánh dấu 🔴.

③ OQ đang chặn gate — kèm người phải trả lời và cái nó chặn.

Bước 5 — Đề xuất việc tiếp theo

Đúng một khuyến nghị chính, kèm lệnh chạy. Không liệt kê mọi khả năng.

▶ Việc tiếp theo: lượng hoá 7 NFR còn định tính
  Chạy: /sa-2-architecture <PROJECT> --focus qas
  Cần chuẩn bị: số liệu tải hiện tại (rps giờ cao điểm), số bản ghi lớn nhất mỗi bảng
  Ai phải trả lời: anh Tuấn (SRE) cho ngân sách lỗi, PO cho ngưỡng chấp nhận

Kèm tối đa 2 việc chạy song song được, nếu có.

Cuối cùng: cập nhật 00-index/INDEX_<PROJECT>.md theo mẫu ở references/artifact-map.md §8. Chỉ skill này được sửa INDEX.

Chế độ khởi tạo dự án mới

Khi sa-output/<PROJECT>/ chưa tồn tại và người dùng xác nhận đường dẫn:

1. Tạo cây thư mục theo references/artifact-map.md §2 (kể cả 02-architecture/adr/).
2. Tạo 00-index/INDEX_<PROJECT>.md, ADL_<PROJECT>.md, DTM_<PROJECT>.md, OQ_<PROJECT>.md, DEC_<PROJECT>.md, GLOSSARY_<PROJECT>.md — chỉ khung rỗng có header, không nội dung bịa.
3. In bảng "cần chuẩn bị trước khi chạy /sa-1-context".
4. Không tự chạy skill giai đoạn — để người dùng quyết.

Chế độ rà soát toàn bộ

Khi người dùng nói "review toàn bộ tài liệu kiến trúc":

1. Bước 1–4 như trên.
2. Thêm: chấm D1–D12 (references/design-rules.md) cho từng artifact, in ma trận artifact × D1..D12 dạng ✅/❌/—.
3. Thêm: gọi kiểm tra của sa-conformance — coverage ASR→ADR, QAS→FIT, QAS→bài đo.
4. Xếp phát hiện theo mức độ: 🔴 chặn gate · 🟠 nợ phải trả trước release · 🟡 cải thiện.

Định tuyến — mô tả việc → skill

Người dùng nói gì	Skill
"chọn công nghệ gì", "so sánh phương án", "ước lượng chi phí hạ tầng", "rủi ro kỹ thuật"	sa-1-context
"vẽ kiến trúc", "thiết kế hệ thống", "chốt NFR", "thiết kế API/dữ liệu/bảo mật/hạ tầng", "viết ADR", "class diagram", "OpenAPI/AsyncAPI", "schema vật lý", "DDL", "migration"	sa-2-architecture (dom/ctr/pdm)
"bàn giao cho dev", "dev cần đọc gì", "chuẩn code", "dev hỏi thiết kế", "review thiết kế", "kiểm thử kiến trúc", "nợ kỹ thuật"	sa-3-enablement (handoff trước)
"hệ thống chạy có đạt không", "tối ưu chi phí", "roadmap kỹ thuật", "post-mortem"	sa-4-evolution
"có quyết định nào chưa ghi không", "kiểm tra coverage", "ADR nào lỗi thời"	sa-conformance
"yêu cầu nghiệp vụ", "user story", "acceptance criteria", "UAT"	⟶ bộ ba-*, không phải SA

Mô tả rơi vào vùng xám ⇒ hỏi lại một câu duy nhất để phân định, đừng đoán.

Trước khi kết thúc

In ba thứ: ① bảng trạng thái artifact · ② bảng chấm gate hiện tại · ③ đúng một khuyến nghị việc tiếp theo kèm lệnh.

Bẫy thường gặp

Chạy SA khi BA chưa qua G1. Không có GOAL/RQ thì không có DRV, không có DRV thì không chấm được phương án — OPT sẽ thành bảng so sánh công nghệ chung chung, vô dụng.

Coi sa-output/ có file là đã qua gate. Gate đọc Status và Approved by trong header, không đọc sự tồn tại của file. File 🟡 Draft không tính.

Bỏ qua Confidence. Một TCO 🔴 (toàn ước lượng) và một TCO 🟢 (có báo giá) trông giống nhau trên bảng trạng thái nhưng khác nhau hoàn toàn về giá trị. Luôn in cột này.

Đề xuất năm việc cùng lúc. Người dùng gọi skill này vì đang không biết làm gì tiếp. Trả về một danh sách dài là trả lại đúng vấn đề họ mang đến.