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?"	`QAS`, `ASR`, `SAD`, `ADR`, `ICD`, `DAT`, `SEC`, `INF`, `FAIL`	AG2
3	`sa-3-enablement`	Thi công	"Làm sao kiến trúc tồn tại trong code và ở lại đó?"	`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/ (8)
├── sa-3-enablement/    SKILL.md · GUIDE.md · templates/ (4)
├── 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
│   └── adr/             ADR-001_… · ADR-002_… · archive/
├── 03-enablement/       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
`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-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`
Trước khi BA trình G3	`/sa-conformance --gate AG2` → trình AG2
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

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-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.
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, ASR hoặc QAS. Không nguồn ⇒ là giả định, phải ghi ASM-nn.
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:

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.

11 KiB Raw Blame History Unescape Escape