13 KiB
Bộ skill SA — Solution Architect Toolkit
Sáu skill bao trọn bốn giai đoạn công việc của một Solution Architect trong dự án, từ lúc nhận một bài toán nghiệp vụ đến lúc đối chiếu hệ thống đang chạy với những gì đã cam kết.
Mỗi skill làm đúng một giai đoạn, có đầu vào rõ, đầu ra rõ, và một gate phải qua trước khi sang giai đoạn sau. Không skill nào được lấn sân skill khác.
Nền tảng lý thuyết của bộ này: ../../solution-architect-role.md
1. Bản đồ skill
| # | Skill | Giai đoạn | Câu hỏi nó trả lời | Output chính | Gate |
|---|---|---|---|---|---|
| 0 | sa-lifecycle |
Điều phối | "Tôi đang ở đâu, làm gì tiếp?" | Bảng trạng thái pipeline, INDEX |
— |
| 1 | sa-1-context |
Bối cảnh | "Áp lực gì, ràng buộc gì, chọn phương án nào, tốn bao nhiêu?" | CTX, OPT, TCO, ARISK |
AG1 |
| 2 | sa-2-architecture |
Kiến trúc | "Hệ thống gồm gì, giao tiếp thế nào, hỏng thì sao — và dev code theo file nào?" | QAS, ASR, SAD, ADR, ICD, DAT, SEC, INF, FAIL + DOM, CTR, PDM (class diagram · OpenAPI/AsyncAPI · schema + DDL/migration) |
AG2 |
| 3 | sa-3-enablement |
Thi công | "Dev cần đọc gì, và làm sao kiến trúc tồn tại trong code?" | HANDOFF, AGD, FIT, DREV, TDEBT |
AG3 |
| 4 | sa-4-evolution |
Vận hành | "Chạy thật có đúng như cam kết không?" | CONF, TRM, PMR |
AG4 |
| ⊕ | sa-conformance |
Xuyên suốt | "Có chỗ nào đứt không?" | DTM, ADL, báo cáo coverage |
Chặn AG2–AG4 |
┌──────────── sa-lifecycle (router, gọi bất cứ lúc nào) ─────────────┐
│ │
┌────▼─────┐ AG1 ┌──────────┐ AG2 ┌──────────┐ AG3 ┌──────────┐ AG4
│1 Context │ ────► │2 Archit. │ ────► │3 Enable. │ ────► │4 Evolut. │ ────►
└──────────┘ └──────────┘ └──────────┘ └──────────┘
│ │ │ │
└───────────────────┴─ sa-conformance (DTM + ADL liên tục) ┘
2. Cấu trúc thư mục
D:\Kakao\Docs\.claude\skills\
├── README.md ← bộ BA
├── README-SA.md ← file này
├── sa-lifecycle/
│ ├── SKILL.md ← quy trình cho Claude
│ ├── GUIDE.md ← hướng dẫn sử dụng cho người
│ └── references/
│ ├── workflow.md ← 4 gate, ai duyệt, tiêu chí pass, khớp với pipeline BA
│ ├── artifact-map.md ← artifact nào ở đâu, header bắt buộc, vòng đời ADR
│ ├── design-rules.md ← 12 quy tắc viết tài liệu kiến trúc (D1–D12)
│ └── decision-radar.md ← quyết định nào cần ADR, quyết định nào không
├── sa-1-context/ SKILL.md · GUIDE.md · templates/ (4)
├── sa-2-architecture/ SKILL.md · GUIDE.md · templates/ (11 + contracts/ + diagrams/) · scripts/contract-check.mjs
├── sa-3-enablement/ SKILL.md · GUIDE.md · templates/ (5) · scripts/handoff-check.mjs
├── sa-4-evolution/ SKILL.md · GUIDE.md · templates/ (3)
└── sa-conformance/ SKILL.md · GUIDE.md · templates/ (2)
SKILL.md = quy trình Claude thực thi. GUIDE.md = tài liệu bạn đọc: khi nào dùng, cần chuẩn bị gì, ví dụ hội thoại, lỗi thường gặp. templates/ = khung tài liệu để điền.
3. Nơi ghi output
sa-output/<PROJECT>/
├── 00-index/ INDEX · DTM · ADL · GLOSSARY · DEC · OQ
├── 01-context/ CTX · OPT · TCO · ARISK
├── 02-architecture/ ASR · QAS · SAD · ICD · DAT · SEC · INF · FAIL · DOM · CTR · PDM
│ ├── adr/ ADR-001_… · ADR-002_… · archive/
│ ├── contracts/ openapi/*.yaml · asyncapi/*.yaml · partners/*.yaml ← file máy đọc, thắng mọi bảng
│ ├── schema/<kho>/ V001__*.sql · V001__*.down.sql · seed/ ← DDL + migration có rollback
│ └── diagrams/ *.<type>.json (spec Archify) · *.html (đã deliver)
├── 03-enablement/ HANDOFF · AGD · FIT · DREV · TDEBT
└── 04-evolution/ CONF · TRM · PMR
Muốn nơi khác thì nói rõ khi gọi, ví dụ /sa-1-context Settlement --out .docs/architecture.
Skill luôn hỏi xác nhận đường dẫn trước khi ghi file đầu tiên của một project mới.
Quy ước đặt tên
<LOẠI>_<PHẠM_VI>_v<major>.<minor>.md → SAD_Settlement_v1.0.md
adr/ADR-<nnn>_<slug>.md → adr/ADR-007_chon-postgres.md
CONF_<PROJECT>_<YYYY-MM>.md → CONF_Settlement_2026-09.md
Sửa nhỏ +0.1; đổi quyết định kiến trúc +1.0 và phải có ADR đi kèm. Mọi file có Change
Log. Không ghi đè mất version cũ — bản cũ vào archive/.
ADR không dùng version. ADR bất biến sau khi Accepted; đổi quyết định thì viết ADR mới
có Supersedes:. ADR bị Rejected vẫn giữ lại.
4. Quy ước ID
| Tiền tố | Nghĩa | Sinh ở giai đoạn |
|---|---|---|
DRV-nn |
Driver — áp lực kinh doanh | 1 |
CON-nn |
Ràng buộc không thương lượng được | 1 |
ASM-nn |
Giả định | 1 |
ARISK-nn |
Rủi ro kiến trúc | 1 |
ASR-nnn |
Yêu cầu định hình kiến trúc | 2 |
QAS-nnn |
Quality attribute scenario (NFR lượng hoá) | 2 |
ADR-nnn |
Architecture decision record | mọi giai đoạn |
CMP-nn |
Container/component trong SAD |
2 |
IF-nnn |
Interface | 2 |
THR-nn |
Mối đe doạ (STRIDE) | 2 |
FM-nn |
Failure mode | 2 |
TBL-nnn |
Bảng vật lý trong PDM |
2 |
MIG-nnn |
Migration (cặp up/down) trong PDM §4 |
2 |
CTR-nn |
File contract trong CTR |
2 |
FIT-nn |
Fitness function | 3 |
DREV-nnn |
Mục design review | 3 |
TD-nn |
Nợ kỹ thuật | 3 |
TRM-nn |
Mục roadmap kỹ thuật | 4 |
OQ-nnn · DEC-nn |
Open question · quyết định nhỏ | mọi giai đoạn (dùng chung với bộ BA) |
ID không bao giờ tái sử dụng. Bỏ một mục ⇒ đánh dấu [DROPPED], giữ nguyên số.
5. Cách gọi
/sa-lifecycle Settlement # đang ở đâu, làm gì tiếp
/sa-lifecycle Settlement --mode init # khởi tạo dự án mới
/sa-1-context Settlement --mode new # bối cảnh + phương án
/sa-2-architecture Settlement --focus qas # lượng hoá NFR (làm TRƯỚC mọi thứ)
/sa-2-architecture Settlement --focus sad # phân rã + C4
/sa-2-architecture Settlement --focus adr "..." # viết một ADR
/sa-2-architecture Settlement --focus ctr # sinh OpenAPI/AsyncAPI thật từ ICD
/sa-2-architecture Settlement --focus pdm # schema vật lý + DDL/migration
/sa-3-enablement Settlement --focus handoff # gói bàn giao dev (chạy ngay khi AG2 ký)
/sa-3-enablement Settlement --focus fit # dựng fitness function
/sa-3-enablement Settlement --focus review "..." # review một thay đổi
/sa-4-evolution Settlement --focus conf --period 2026-09
/sa-conformance Settlement --mode full --gate AG2 # kiểm coverage trước khi trình gate
Không nhớ tên skill thì cứ mô tả việc cần làm — skill tự kích hoạt theo mô tả.
Mọi skill đều có Bước 0 "chốt input rồi dừng": liệt kê input tìm được, nêu input còn
thiếu, tóm tắt cách hiểu, rồi chờ bạn xác nhận mới làm. Thêm go vào lệnh để bỏ bước dừng.
6. Lịch chạy điển hình cho một dự án 6 tháng
| Thời điểm | Chạy gì |
|---|---|
| BA vừa qua G1 | /sa-lifecycle --mode init → /sa-1-context |
| Trước khi BA trình G2 | /sa-conformance --gate AG1 → trình AG1 |
| Tuần 1 sau AG1 | /sa-2-architecture --focus qas rồi --focus asr |
| Tuần 2 | --focus sad |
| Tuần 3 | --focus icd · --focus dat |
| Tuần 4 | --focus sec · --focus inf · --focus fail |
| Tuần 5 | --focus dom · --focus ctr · --focus pdm — lớp bàn giao dev |
| Trước khi BA trình G3 | /sa-conformance --gate AG2 → trình AG2 |
| Ngày AG2 ký | /sa-3-enablement --focus handoff → dev ký đã nhận |
| Tuần 1 thi công | /sa-3-enablement --focus agd |
| Tuần 2–4 thi công | --focus fit theo lộ trình 4 tuần |
| Suốt thi công | --focus review mỗi thay đổi chạm kiến trúc · --focus debt mỗi lệch |
| Cuối mỗi sprint | /sa-conformance --mode dtm |
| Trước go-live | /sa-conformance --gate AG3 → trình AG3 |
| Hàng tháng sau go-live | /sa-4-evolution --focus conf |
| Mỗi quý | /sa-4-evolution --focus review → --focus roadmap → trình AG4 |
6b. Sơ đồ — chuẩn Archify
Mọi sơ đồ của bộ SA tuân chuẩn và phong cách Archify (ba-lifecycle/references/diagram-rules.md,
gói đã nhúng ở archify/): mỗi sơ đồ = spec JSON (diagrams/<ARTIFACT>_<slug>.<type>.json,
quality_profile: showcase, archify validate 0 lỗi) + mermaid có marker trong .md + bảng đi kèm.
| Sơ đồ SA | Loại Archify |
|---|---|
| C4 Context/Container/Component, deployment, ranh giới tin cậy, phương án mức khối | architecture |
| Luồng chính có nhánh lỗi | sequence |
| Ownership / luồng dữ liệu | dataflow |
| Phụ thuộc roadmap | workflow |
| ERD khái niệm, class diagram | mermaid-only |
Một đường chính, ≤ 12 node, nhãn cạnh ghi giao thức + sync/async, không màu. Kiểm:
node .claude/skills/ba-lifecycle/scripts/diagram-check.mjs --md <artifact>. Spec mẫu đã pass:
sa-2-architecture/templates/diagrams/.
7. Quan hệ với bộ skill BA
Hai bộ chạy đan xen, không nối tiếp. Bảng chốt thứ tự:
| Mốc | Điều kiện | Vì sao |
|---|---|---|
| SA GĐ1 bắt đầu | BA đã qua G1 | Không có GOAL/RQ thì không có DRV |
| BA gate G2 | SA đã qua AG1 | Tech Lead ký "khả thi kỹ thuật" dựa trên OPT + ARISK |
| BA gate G3 | SA đã qua AG2 | API trong SRS phải khớp ICD; NFR 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 |
Bốn chỗ hai bộ giao nhau — kiểm mỗi lần chạy /sa-lifecycle:
| BA | SA | Ai thắng khi lệch |
|---|---|---|
NFR |
QAS |
QAS — BA ghi nhu cầu, SA chốt con số và cách đo |
API (đề xuất) |
ICD |
ICD — BA đánh dấu "chờ xác nhận", SA là người xác nhận |
RBAC |
SEC §3.1 |
Bổ sung nhau — SEC map vai trò nghiệp vụ xuống cơ chế kỹ thuật |
BR ép ràng buộc kiến trúc |
ADR |
BR là nguồn, ADR là quyết định |
🔴 Không copy nội dung giữa hai bộ. Tham chiếu bằng đường dẫn + ID. Copy là cách chắc chắn nhất để hai tài liệu lệch nhau sau ba lần sửa.
Ánh xạ chi tiết: sa-lifecycle/references/artifact-map.md §7 · workflow.md §4.
8. Nguyên tắc bất di bất dịch
Bốn quy tắc này ghi trong mọi SKILL.md và không skill nào được vi phạm:
- Không bịa con số. Thiếu thông tin ⇒ ghi
OQ-nnnvà hạConfidence, không điền giá trị "hợp lý". Kiến trúc dựng trên giả định ngầm là kiến trúc sẽ phải làm lại. - Không quyết định thay người có thẩm quyền. Trade-off nghiệp vụ là của PO; chấp nhận rủi ro bảo mật là của Security; ngân sách và tiến độ là của PO/PM. SA trình phương án kèm hệ quả của phương án ngược bằng số.
- Mọi quyết định phải truy vết được về một
DRV,CON,ASRhoặcQAS. Không nguồn ⇒ là giả định, phải ghiASM-nn. - Không ghi đè tài liệu đã qua gate. Sửa qua
ADRmới cóSupersedes:hoặcDEC-nn, kèm Change Log.ADRđãAcceptedkhông bao giờ được sửa nội dung.
Cộng hai quy tắc riêng của nghề kiến trúc:
- Không có phương án bị loại thì không phải quyết định (
D3). - Ràng buộc không verify tự động được là khuyến nghị, không phải ràng buộc (
D8).
12 quy tắc viết đầy đủ: sa-lifecycle/references/design-rules.md.