238 lines
13 KiB
Markdown
238 lines
13 KiB
Markdown
# 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`](../../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`](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:
|
||
|
||
1. **Không bịa con số.** Thiếu thông tin ⇒ ghi `OQ-nnn` và 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.
|
||
2. **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ố**.
|
||
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`.
|
||
4. **Không ghi đè tài liệu đã qua gate.** Sửa qua `ADR` mới có `Supersedes:` hoặc `DEC-nn`,
|
||
kèm Change Log. `ADR` đã `Accepted` không bao giờ được sửa nội dung.
|
||
|
||
Cộng hai quy tắc riêng của nghề kiến trúc:
|
||
|
||
5. **Không có phương án bị loại thì không phải quyết định** (`D3`).
|
||
6. **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`.
|