196 lines
12 KiB
Markdown
196 lines
12 KiB
Markdown
---
|
||
name: sa-3-enablement
|
||
description: 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.
|