sys-analysis-design/.claude/skills/sa-3-enablement/SKILL.md

name, description

name

description

sa-3-enablement

Giai đoạn 3 của quy trình Solution Architect — đồng hành cùng team trong lúc thi công. Dùng để lập gói bàn giao dev (HANDOFF - mục lục mọi đặc tả/contract/schema/ADR theo đường dẫn thật, checklist đủ-thiếu, dev ký đã nhận), biến kiến trúc thành thứ dev dùng được (architecture guideline, reference implementation, skeleton), dựng fitness function kiểm thử ràng buộc kiến trúc tự động trên CI, điều hành design review cho thay đổi chạm kiến trúc, trả lời câu hỏi thiết kế của dev, và quản lý sổ nợ kỹ thuật có chủ có hạn. Kích hoạt khi người dùng nói "bàn giao cho dev", "gói bàn giao", "handoff", "dev cần đọc gì", "chuẩn code", "architecture guideline", "reference implementation", "dev hỏi về thiết kế", "review thiết kế", "kiểm thử kiến trúc", "ArchUnit", "fitness function", "nợ kỹ thuật", "tech debt", "code không đúng kiến trúc", "lệch so với thiết kế". Input là SAD/ADR đã qua AG2; output vào sa-output/<PROJECT>/03-enablement/ và phải qua Gate AG3 (Build conformance) trước khi go-live.

GĐ3 · ENABLEMENT — Đồng hành thi công

Mục tiêu duy nhất: kiến trúc trên giấy trở thành kiến trúc trong code — và ở lại đó khi người viết tài liệu không còn ngồi cạnh.

Output: HANDOFF · AGD · FIT · DREV · TDEBT trong sa-output/<PROJECT>/03-enablement/

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

1. Không bịa ràng buộc — thiếu ⇒ OQ-nnn, không tự thêm quy tắc không có trong ADR.
2. Không quyết định thay Tech Lead về quy ước code và công cụ. SA chỉ can thiệp khi quyết định đó chạm QAS hoặc một ADR.
3. Mọi ràng buộc phải truy vết được về một ADR hoặc QAS. Ràng buộc không nguồn là sở thích cá nhân, và team sẽ nhận ra điều đó.
4. Không sửa ADR đã Accepted — thi công phát hiện thiết kế sai ⇒ ADR mới có Supersedes:.

Nạp thêm: ../sa-lifecycle/references/design-rules.md (đặc biệt D8) · ../sa-lifecycle/references/decision-radar.md (để phân loại câu hỏi của dev).

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/ (SAD, ADR, ICD, QAS, FAIL), source code hiện có, cấu hình CI, ba-output/…/03-specification/ (SRS).
2. Kiểm AG2 — SAD đã ✅ Baselined chưa, Security và SRE đã ký chưa? Chưa ⇒ báo rõ: ban hành guideline dựa trên kiến trúc chưa chốt sẽ phải ban hành lại.
3. Chọn phạm vi — --focus handoff|agd|fit|review|debt. Ban hành guideline và dựng fitness function là hai việc khác nhau về khối lượng. handoff chạy đầu tiên, ngay khi AG2 ký, và chạy lại mỗi khi phạm vi bàn giao (US/module) mở rộng.
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 — 5 hoạt động

0 — Gói bàn giao dev HANDOFF (--focus handoff)

Điền templates/dev-handoff.md. Không có nội dung mới — chỉ đường dẫn thật + version + status chép từ header, để dev trả lời được một câu: "tôi cần đọc gì, ở đâu, bản nào, ai ký, còn thiếu gì?"

Ba việc:

1. Điền checklist §2 cho phạm vi bàn giao (US/module/release): 9 dòng bộ BA (BACKLOG, BR, RBAC, SRS/AC mỗi US, NFR, API, artifact design nếu screen, RTM) + 14 dòng bộ SA (QAS, SAD, ADR, ICD, CTR file thật, DOM, DAT, PDM + DDL/migration, SEC, INF, FAIL, AGD + reference implementation, FIT, sơ đồ đã deliver). Mở từng file, chép Version/ Status thật; không có file ⇒ để ☐ và ghi thiếu, không ghi "dự kiến".
2. §2.3 việc dev tự quyết — liệt kê đích danh để không ai tưởng đã có (đặt tên, thư viện tiện ích…).
3. §3 OQ chặn hành vi — US còn OQ về hành vi ⇒ loại khỏi gói, ghi rõ; §4 kênh hỏi và SLA trả lời (BA 1 ngày · SA 2 ngày).

🔴 Gói bàn giao có dòng ☐ ở §2.1 hàng 4–5 (SRS/AC) hoặc §2.2 hàng 14, 17 (CTR, PDM) là gói chưa bàn giao được — dev sẽ phải tự đoán contract và schema, đúng hai chỗ tốn nhất để sửa sau.

Người điều phối chạy node .claude/skills/sa-3-enablement/scripts/handoff-check.mjs --handoff <file> (H1–H5) và chép kết quả vào §5. Tech Lead + đại diện Dev BE/FE/QA ký §6 "đã nhận".

1 — Architecture Guidelines AGD (--focus agd)

Điền templates/architecture-guidelines.md.

Nguyên tắc: guideline chỉ chứa thứ truy được về ADR hoặc QAS. Quy ước đặt tên biến và thứ tự import thuộc Tech Lead, không thuộc tài liệu này. Trộn hai loại vào nhau làm dev ngừng phân biệt cái nào quan trọng.

Mỗi quy tắc trong AGD phải có bốn cột: quy tắc · nguồn (ADR/QAS) · ví dụ đúng/sai · cách kiểm (FIT-nn hoặc ⚠️ Khuyến nghị).

Reference implementation là bắt buộc, không phải phần thêm. Một module chạy được, thể hiện đúng các quyết định kiến trúc, có kiểm thử. Dev đọc code nhanh gấp nhiều lần đọc văn bản.

Reference implementation phải thể hiện	Vì sao
Cấu trúc module chuẩn	Dev copy cấu trúc, không copy nhầm
Chạy migration của PDM và stub/client sinh từ CTR	Schema và contract có một nguồn sự thật, không chép tay
Xử lý lỗi và mã lỗi theo ICD	Thống nhất từ file đầu tiên
Log có correlation id	Thêm sau rất tốn
Gọi phụ thuộc ngoài có timeout/retry theo FAIL	Đây là chỗ dev hay tự bịa nhất
Kiểm thử ở đủ các mức	Đặt chuẩn cho cả dự án

2 — Fitness function FIT (--focus fit)

Điền templates/fitness-functions.md. Quy tắc D8: ràng buộc không kiểm tự động được thì chỉ là khuyến nghị.

Với mỗi ràng buộc trong AGD và mỗi QAS mức Must, chọn một trong hai:

• Viết một bài kiểm chạy trên CI ⇒ FIT-nn
• Ghi thẳng nhãn ⚠️ Khuyến nghị — không tự kiểm được + cách kiểm thủ công + tần suất

Bảng công cụ theo loại ràng buộc:

Loại ràng buộc	Công cụ	Ví dụ
Phụ thuộc giữa module/tầng	ArchUnit (JVM), dependency-cruiser (JS/TS), import-linter (Python)	"Tầng domain không được import tầng infra"
Ranh giới package/thư mục	lint rule tuỳ biến, eslint boundaries	"Module A không gọi trực tiếp repository của module B"
Hiệu năng	k6 / JMeter / Gatling chạy trên stg	QAS-004 p95 ≤ …
Kích thước & thời gian build	script CI	"Bundle JS ≤ … KB"
Bảo mật	quét thư viện, quét secret, quét ảnh container	THR-nn
Hạ tầng	kiểm tra IaC (tfsec, checkov), policy-as-code	"Mọi bucket phải bật mã hoá"
Contract	kiểm thử contract (Pact), lint OpenAPI	IF-nnn không đổi breaking

Mỗi FIT-nn ghi: ràng buộc kiểm · ADR/QAS nguồn · công cụ · chạy ở đâu trong CI · vi phạm thì chặn merge hay chỉ cảnh báo · ai sửa khi đỏ.

🔴 Bắt đầu bằng cảnh báo, chuyển sang chặn sau. Bật chế độ chặn ngay trên codebase đã có nợ sẽ làm CI đỏ toàn bộ và team sẽ tắt nó. Ghi rõ ngày chuyển từ cảnh báo sang chặn.

3 — Design review DREV (--focus review)

Điền templates/design-review-log.md.

Chỉ review thay đổi chạm kiến trúc. Chấm nhanh theo ../sa-lifecycle/references/decision-radar.md §2: điểm ≥ 5 ⇒ cần review và có thể cần ADR; điểm < 3 ⇒ trả lại cho Tech Lead.

Quy trình mỗi lần review:

1. Phân loại yêu cầu — câu hỏi làm rõ (trả lời trong ngày) / đề xuất thay đổi thiết kế (review) / phát hiện thiết kế sai (có thể cần ADR mới)
2. Đối chiếu với SAD, ADR liên quan, QAS bị ảnh hưởng
3. Kết luận một trong bốn: đúng thiết kế · lệch nhưng chấp nhận được (⇒ TDEBT) · lệch phải sửa · thiết kế sai, cần ADR mới
4. Ghi vào DREV kèm người quyết và ngày. Không ghi thì tháng sau tranh luận lại.

Thời gian chờ tối đa 2 ngày làm việc. Review chậm hơn thì dev sẽ đi tiếp mà không chờ — và lúc đó review thành phê bình sau khi đã code xong, vô ích và gây mâu thuẫn.

🔴 Kết luận thứ tư là kết luận quan trọng nhất và khó nhất. Thi công là lúc giả định gặp thực tế; kiến trúc sai mà không chịu thừa nhận sẽ được team lách qua chứ không được sửa.

4 — Technical debt TDEBT (--focus debt)

Điền templates/tech-debt-register.md.

Mỗi lệch so với kiến trúc được chấp nhận có ý thức phải trở thành một TD-nn: mô tả · vì sao chấp nhận · lãi suất (chi phí phải trả mỗi tháng nếu không sửa) · chi phí sửa · chủ · hạn xét lại.

Phân loại nợ để xử lý khác nhau:

Loại	Ví dụ	Xử lý
Nợ có ý thức, có kế hoạch	"Dùng bảng tạm cho đến khi có event bus ở quý sau"	Ghi hạn, theo dõi
Nợ có ý thức, chưa có kế hoạch	"Biết là sai nhưng chưa biết sửa thế nào"	Ghi, đưa vào TRM
Nợ vô ý	Phát hiện qua review hoặc FIT đỏ	Đánh giá rồi xếp vào một trong hai loại trên
Nợ do kiến trúc sai	Thiết kế không khả thi	Không phải nợ — là ADR mới

🔴 Nợ không có "lãi suất" thì không ai ưu tiên trả. Viết bằng con số: "mỗi tính năng mới chạm module này tốn thêm 2 ngày", "gây trung bình 1 sự cố/tháng". Đó là ngôn ngữ PM và PO hiểu.

Mục "sẽ sửa sau" không có chủ và hạn ⇒ không phải mục nợ hợp lệ, chặn AG3.

Trước khi kết thúc

In bốn thứ:

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

② Bảng trạng thái FIT — mỗi fitness function: xanh/đỏ/chưa bật · chế độ (cảnh báo/chặn).

③ Bảng QAS mức Must × bài đo thật — đã đo / chưa đo / kết quả. AG3 yêu cầu đã đo, không chấp nhận ước lượng.

④ Danh sách TD-nn mới phát sinh kèm chủ và hạn.

⑤ Trạng thái HANDOFF — số dòng ✅/☐ ở §2, US bị loại khỏi gói vì OQ, ai đã ký §6.

Rồi nhắc người dùng: AG3 cần Tech Lead + QA + SRE ký.

Bẫy thường gặp

Ban hành guideline dài 40 trang. Không ai đọc. Giữ AGD ngắn, mọi thứ dài chuyển vào reference implementation — code luôn thắng văn bản về khả năng được đọc.

Fitness function bật chế độ chặn ngay ngày đầu. CI đỏ toàn bộ, team tắt nó, và không ai bật lại. Bắt đầu bằng cảnh báo, công bố ngày chuyển sang chặn, dọn nợ trước ngày đó.

Review mọi PR. SA không phải người gác cổng code. Review mọi thứ nghĩa là trở thành nút thắt, và team sẽ tìm cách đi vòng. Chỉ review cái chạm kiến trúc.

Trả lời câu hỏi của dev bằng "xem tài liệu đi". Nếu dev phải hỏi thì tài liệu chưa rõ. Trả lời câu hỏi, rồi sửa tài liệu — câu hỏi là dữ liệu về chất lượng tài liệu của bạn.

Coi mọi lệch so với thiết kế là lỗi của dev. Đôi khi dev đúng và thiết kế sai. Kết luận "thiết kế sai, cần ADR mới" phải là một lựa chọn thật, không phải lối thoát danh dự.

Sổ nợ chỉ tăng không giảm. Nợ không bao giờ được trả nghĩa là nó chưa bao giờ được ưu tiên — thường vì thiếu cột "lãi suất". Thêm con số vào, PM sẽ tự đưa vào sprint.