genneral/sys-analysis-design
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init git

Browse Source
This commit is contained in:
Leonard-ThindPad-P50
2026-09-08 10:26:21 +07:00
commit c81f249920
169 changed files with 38726 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

157
.claude/skills/sa-conformance/GUIDE.md Normal file
View File

@@ -0,0 +1,157 @@
# Hướng dẫn sử dụng — `sa-conformance` (xuyên suốt)
## Skill này giải quyết gì
Tài liệu kiến trúc luôn trông đầy đủ khi đọc riêng từng file. Chỗ đứt chỉ lộ ra khi nối chúng
lại: một yêu cầu định hình kiến trúc mà **không ai quyết định gì** về nó, một NFR mức Must
**chưa ai đo**, một component tồn tại mà **không phục vụ yêu cầu nào**.
Skill này nối và chỉ ra chỗ đứt. Nó **có quyền chặn AG2, AG3, AG4**.
**Không làm ở skill này:** thiết kế, viết ADR, sửa tài liệu của skill khác.
## Khi nào gọi
| Tình huống | Có nên gọi |
|---|---|
| **Trước mỗi lần trình gate** | ✅ `--mode full` — đỡ bị trả về |
| Sau mỗi sprint | ✅ `--mode dtm` |
| Vừa viết xong một `ADR` | ✅ `--mode adl` |
| Nhận bàn giao kiến trúc từ người khác | ✅ `--mode full` |
| Nghi ngờ có quyết định nào chưa được ghi | ✅ |
| Muốn biết làm gì tiếp | ❌ `/sa-lifecycle` |
| Muốn sửa chỗ đứt | ❌ Skill này chỉ báo — sửa bằng skill giai đoạn |
## Cú pháp
```
/sa-conformance <PROJECT> [--mode dtm|adl|full] [--gate AG2|AG3|AG4] [--out <path>] [go]
```
| Tham số | Ý nghĩa |
|---|---|
| `--mode dtm` | Chỉ ma trận truy vết quyết định |
| `--mode adl` | Chỉ mục lục ADR + 5 kiểm tra về ADR |
| `--mode full` | *(mặc định)* Cả hai + coverage + kết luận gate |
| `--gate AG2` | Chỉ chấm những kiểm tra chặn gate đó |
## Bạn sẽ nhận được gì
```
sa-output/<PROJECT>/00-index/
├── DTM_<PROJECT>.md ← ma trận truy vết quyết định
└── ADL_<PROJECT>.md ← mục lục ADR + cảnh báo
```
Cộng ba bảng in ra màn hình: coverage · danh sách phát hiện xếp theo mức · kết luận gate.
## Đọc báo cáo coverage thế nào
```
DRV → ASR/QAS 8/8 100% ✅
ASR → ADR 11/13 85% 🔴 đứt: ASR-004, ASR-009 → chặn AG2
ADR → nguồn 14/16 88% 🟠 không nguồn: ADR-006, ADR-012
QAS(Must) → bài đo 6/9 67% 🔴 thiếu: QAS-009, QAS-011, QAS-012 → chặn AG3
Ràng buộc AGD → FIT 12/18 67% 🔴 thiếu và không có nhãn: §3.2-2, §3.4-3
CMP → ASR 9/11 82% 🟠 không phục vụ ASR nào: CMP-07, CMP-10
```
**Luôn có danh sách ID, không chỉ tỉ lệ.** "85%" không hành động được; "`ASR-004`, `ASR-009`"
thì hành động được ngay.
## Sáu chỗ đứt và ý nghĩa
| Chỗ đứt | Nghĩa là | Sửa bằng |
|---|---|---|
| `DRV` không có `ASR`/`QAS` | Áp lực kinh doanh không được kiến trúc phục vụ | `/sa-2-architecture --focus asr` |
| `ASR` không có `ADR` | Yêu cầu định hình kiến trúc mà không ai quyết gì | `/sa-2-architecture --focus adr` |
| `ADR` không có nguồn | Quyết định là sở thích cá nhân | Bổ sung §1 của ADR |
| `QAS` Must không có bài đo | Cam kết không kiểm chứng được | `/sa-3-enablement --focus fit` |
| Ràng buộc `AGD` không có `FIT`, không có nhãn | Sẽ bị vi phạm mà không ai biết | `/sa-3-enablement --focus fit` |
| `CMP` không phục vụ `ASR` nào | Thành phần có thể thừa | Rà lại `SAD` §4.1 |
## Năm kiểm tra riêng cho ADR
| Kiểm | Phát hiện gì | Hay gặp không |
|---|---|---|
| Chuỗi supersede | `ADR-A` nói bị `ADR-B` thay, nhưng `ADR-B` không nói thay `ADR-A` | Rất hay |
| `Proposed` quá 10 ngày | Quyết định treo, có người đang chờ mà không ai biết | Rất hay |
| Điểm radar ≥ 8 mà `Accepted` không POC | Cam kết dựa trên suy đoán | Hay |
| Nguồn đã đổi | ADR dựa trên một `QAS` đã bị sửa/bỏ | Hay, khó tự thấy |
| **Hai ADR mâu thuẫn** | Hai quyết định `Accepted` ngược nhau cùng chủ đề | Ít, nhưng đắt nhất |
🔴 Kiểm tra cuối chỉ tìm được khi rà **theo chủ đề** (dữ liệu, tích hợp, bảo mật, hạ tầng),
không phải theo số thứ tự. Đó là lý do skill này tồn tại thay vì đọc lướt sổ ADR.
## Ví dụ hội thoại
```
Bạn: /sa-conformance Settlement --mode full --gate AG2
Claude: [Bước 0]
Quét được: CTX v1.0 ✅ · OPT v1.0 ✅ · QAS v1.1 🟠 · ASR v1.0 🟠 ·
SAD v1.0 🟠 · ICD v1.0 🟡 · 13 ADR · DAT v1.0 🟡 · SEC ❌ chưa có
⚠️ ICD và DAT đang 🟡 Draft — sẽ quét nhưng tách riêng, không tính vào coverage chặn.
Xác nhận?
Bạn: go
Claude: ① Coverage (chỉ tính artifact 🟠 trở lên)
DRV → ASR/QAS 8/8 100% ✅
ASR → ADR 11/13 85% 🔴 đứt: ASR-004, ASR-009
ADR → nguồn 11/13 85% 🟠 không nguồn: ADR-006, ADR-012
CMP → ASR 9/11 82% 🟠 thừa?: CMP-07, CMP-10
② Phát hiện
🔴 CHẶN AG2
1. ASR-004 "chịu được POS mất kết nối ≤ 4 giờ" (ASR_… §B2)
→ không có ADR nào. ASR này ép ra cơ chế hàng đợi bền, nhưng SAD §4.1
không có component nào đảm nhận. Chạy /sa-2-architecture --focus adr.
2. ASR-009 "dữ liệu cá nhân trong lãnh thổ HQ" (ASR_… §B2)
→ không có ADR. Đây là ràng buộc pháp lý (CON-05), không được bỏ qua.
3. SEC chưa tồn tại → AG2 yêu cầu Security ký. Chạy /sa-2-architecture --focus sec.
🟠 NỢ
4. ADR-006 "dùng Redis làm cache" — §1 không tham chiếu QAS/CON nào.
Bổ sung nguồn, hoặc hạ xuống DEC-nn nếu điểm radar < 5.
5. CMP-07 "NotificationRelay" không phục vụ ASR nào và không có trong BACKLOG của BA.
Rà lại: có ai cần nó không?
🟡 CẢI THIỆN
6. ADR-003 đang Proposed từ 2026-08-30 (18 ngày). Ai đang chờ quyết định này?
⚠️ TRONG BẢN NHÁP (chưa tính)
7. ICD 🟡: 4/9 IF-nnn chưa có cột "ai sở hữu contract".
③ Kết luận
AG2: 🔴 CHẶN — 3 mục. Việc gần nhất: /sa-2-architecture --focus adr
```
## Lỗi thường gặp
**"Coverage 100% nhưng vẫn có vấn đề."**
Kiểm tra chất lượng liên kết, không chỉ sự tồn tại. Một `ADR` gắn với `ASR-004` nhưng nội dung
không thực sự giải quyết `ASR-004` vẫn đếm là có liên kết. Skill báo được chỗ đứt, không thay
được việc đọc.
**"Nó chặn gate của tôi trong khi tôi đang gấp."**
Đó là mục đích. Nhưng bạn có thể **chấp nhận có ý thức**: ghi `DEC-nn` nêu rõ chấp nhận đứt
chỗ nào, ai chấp nhận, và hạn xử lý. Chấp nhận có ghi chép khác hoàn toàn với bỏ qua.
**"Ma trận trống nhiều quá, nhìn nản."**
Ma trận trống trung thực tốt hơn ma trận đầy do suy diễn. Ô trống là danh sách việc; ô điền
bừa là cảm giác an toàn giả.
**"CMP-07 không phục vụ ASR nào nhưng nó cần thật."**
Hợp lệ — không phải component nào cũng sinh từ `ASR`. Ghi vào `SAD` §4.1 nguồn của nó (một
`US` trong `BACKLOG` của BA chẳng hạn) và skill sẽ ngừng báo.
## Liên quan
- Quan hệ phụ thuộc giữa artifact: `../sa-lifecycle/references/artifact-map.md` §6
- Tiêu chí gate: `../sa-lifecycle/references/workflow.md` §2
- Chấm điểm ADR: `../sa-lifecycle/references/decision-radar.md` §2
- Bộ BA tương ứng: `../ba-traceability/GUIDE.md`
- Template: `templates/decision-traceability-matrix.md` · `templates/adr-ledger.md`

163
.claude/skills/sa-conformance/SKILL.md Normal file
View File

@@ -0,0 +1,163 @@
---
name: sa-conformance
description: Skill xuyên suốt của quy trình Solution Architect — dựng và kiểm tra ma trận truy vết quyết định (DTM) và sổ mục lục ADR (ADL). Dùng để phát hiện yêu cầu định hình kiến trúc chưa ai quyết định gì, quyết định kiến trúc không truy được về nguồn nào, NFR chưa có bài đo hoặc bài kiểm tự động, component tồn tại mà không phục vụ yêu cầu nào, ADR mâu thuẫn hoặc lỗi thời, và tham chiếu gãy giữa các tài liệu kiến trúc. Kích hoạt khi người dùng nói "kiểm tra coverage kiến trúc", "có quyết định nào chưa ghi không", "ADR nào lỗi thời", "ma trận truy vết quyết định", "DTM", "rà soát chéo tài liệu kiến trúc", "trước khi trình gate kiến trúc", "NFR nào chưa được kiểm". Chạy được ở mọi giai đoạn và có quyền chặn Gate AG2, AG3, AG4.
---
# SA · CONFORMANCE — Truy vết quyết định & mục lục ADR
Skill này **không thiết kế gì**. Nó trả lời một câu: **"có chỗ nào đứt không?"** — và có
quyền chặn gate khi câu trả lời là có.
Output: `DTM` · `ADL` trong `sa-output/<PROJECT>/00-index/`
## Chuỗi truy vết phải liền mạch
```
DRV ──► ASR ──► ADR ──► CMP ──► FIT
│ │ │ │ │
└───────┴──► QAS ───────┴──► bài đo ──► CONF
```
Sáu chỗ đứt phải phát hiện được, và mỗi chỗ có nghĩa khác nhau:
| Chỗ đứt | Nghĩa là | Mức |
|---|---|---|
| `DRV` không có `ASR`/`QAS` nào | Áp lực kinh doanh không được kiến trúc phục vụ | 🔴 chặn AG2 |
| `ASR` không có `ADR` nào | Yêu cầu định hình kiến trúc mà không ai quyết định gì | 🔴 chặn AG2 |
| `ADR` không truy về `DRV`/`CON`/`QAS`/`ASR` | Quyết định không có nguồn — sở thích cá nhân | 🟠 |
| `QAS` không có bài đo | Cam kết không kiểm chứng được | 🔴 chặn AG3 (mức Must) |
| Ràng buộc `AGD` không có `FIT` và không có nhãn khuyến nghị | Sẽ bị vi phạm mà không ai biết | 🔴 chặn AG3 |
| `CMP` không phục vụ `ASR` nào và không có nhu cầu chức năng rõ | Thành phần thừa | 🟠 |
## Bốn nguyên tắc bất di bất dịch
1. **Không bịa liên kết** — không thấy quan hệ thì báo đứt, không suy diễn cho đẹp ma trận.
2. **Không tự sửa artifact của skill khác** — báo chỗ đứt và đề xuất, để skill giai đoạn sửa.
3. **Mọi phát hiện phải chỉ được file và mục cụ thể** — "tài liệu chưa đầy đủ" là báo cáo vô dụng.
4. **Có quyền chặn gate** — và phải dùng quyền đó, không hạ mức cho dễ chịu.
Nạp thêm: `../sa-lifecycle/references/artifact-map.md` §6 (quan hệ phụ thuộc) ·
`../sa-lifecycle/references/design-rules.md` · `../sa-lifecycle/references/decision-radar.md`.
## Bước 0 — Chốt input rồi dừng lại
**Chưa được ghi file.** Làm ba việc rồi **dừng chờ người dùng trả lời**:
1. **Quét được gì** — bảng artifact tìm thấy, kèm version và `Status`. Artifact `🟡 Draft` vẫn
quét nhưng đánh dấu riêng: chỗ đứt trong bản nháp chưa phải lỗi.
2. **Chọn phạm vi** — `--mode dtm|adl|full`. `full` là cả hai cộng báo cáo coverage.
3. **Hỏi người dùng** xác nhận.
Bỏ bước dừng khi lệnh có `go`.
## Thực hiện — 5 bước
### Bước 1 — Thu ID từ mọi artifact
Đọc và trích ID. **Đọc header trước** để biết version và `Status`:
| Nguồn | Trích ID |
|---|---|
| `CTX` | `DRV-nn`, `CON-nn`, `ASM-nn` |
| `ARISK` | `ARISK-nn`, POC |
| `QAS`/`ASR` | `QAS-nnn`, `ASR-nnn` |
| `SAD` | `CMP-nn` |
| `adr/` | `ADR-nnn` + trạng thái + `Supersedes`/`Superseded by` |
| `ICD` | `IF-nnn` |
| `DAT` | thực thể + chủ sở hữu |
| `SEC` | `THR-nn` |
| `FAIL` | `FM-nn` |
| `AGD` | ràng buộc §3 |
| `FIT` | `FIT-nn` + trạng thái |
| `TDEBT` | `TD-nn` |
| `CONF` | kết quả đo |
ID trùng nhau ở hai file ⇒ 🔴 báo ngay, đó là lỗi nghiêm trọng hơn mọi chỗ đứt.
### Bước 2 — Dựng `DTM`
Điền `templates/decision-traceability-matrix.md`. Bốn ma trận hai chiều:
| Ma trận | Đọc xuôi | Đọc ngược |
|---|---|---|
| `DRV` × `ASR`/`QAS` | Driver này được phục vụ bởi cái gì | Yêu cầu này sinh từ đâu |
| `ASR` × `ADR` | Yêu cầu này được quyết định thế nào | Quyết định này phục vụ gì |
| `ADR` × `CMP` | Quyết định này hiện ra ở đâu trong hệ thống | Component này tồn tại vì gì |
| `QAS` × bài đo × `FIT` | Cam kết này kiểm chứng bằng gì | Bài kiểm này bảo vệ cam kết nào |
**Đọc ngược quan trọng hơn đọc xuôi.** Đọc xuôi tìm chỗ thiếu; đọc ngược tìm chỗ thừa — và
chỗ thừa (component không ai cần, ADR không phục vụ gì) thường không bao giờ bị phát hiện.
### Bước 3 — Dựng `ADL`
Điền `templates/adr-ledger.md`. Mục lục mọi ADR kèm trạng thái, và **năm kiểm tra**:
| Kiểm | Phát hiện |
|---|---|
| Chuỗi supersede | `ADR-A` ghi `Superseded by ADR-B` nhưng `ADR-B` không ghi `Supersedes ADR-A` ⇒ tham chiếu gãy |
| `Proposed` quá hạn | `Proposed` > 10 ngày ⇒ quyết định đang treo, ai đó đang chờ |
| Điểm radar ≥ 8 chưa POC | `Accepted` mà không có POC ⇒ vi phạm `decision-radar.md` §6 |
| Nguồn đã đổi | `ADR` dựa trên `QAS-nnn` mà `QAS` đó đã sửa/bỏ ⇒ quyết định có thể không còn đúng |
| Mâu thuẫn | Hai `ADR` `Accepted` quyết ngược nhau về cùng một chủ đề |
🔴 Kiểm tra cuối là kiểm tra khó nhất và có giá trị nhất. Rà theo chủ đề (dữ liệu, tích hợp,
bảo mật, hạ tầng), không rà theo số thứ tự.
### Bước 4 — Báo cáo coverage
In bảng, mỗi dòng có **tỉ lệ + danh sách ID bị đứt** (không chỉ tỉ lệ):
```
DRV → ASR/QAS 8/8 100% ✅
ASR → ADR 11/13 85% 🔴 đứt: ASR-004, ASR-009 → chặn AG2
ADR → nguồn 14/16 88% 🟠 không nguồn: ADR-006, ADR-012
QAS(Must) → bài đo 6/9 67% 🔴 thiếu: QAS-009, QAS-011, QAS-012 → chặn AG3
Ràng buộc AGD → FIT 12/18 67% 🔴 thiếu và không có nhãn: §3.2-2, §3.4-3
CMP → ASR 9/11 82% 🟠 không phục vụ ASR nào: CMP-07, CMP-10
```
### Bước 5 — Xếp phát hiện và kết luận gate
Ba mức: 🔴 chặn gate · 🟠 nợ phải trả trước gate sau · 🟡 cải thiện.
Mỗi phát hiện ghi: **file · mục · cái đứt · hành động đề xuất · skill nào sửa**.
Kết luận đúng một dòng cho mỗi gate đang mở:
```
AG2: 🔴 CHẶN — ASR-004 và ASR-009 chưa có ADR nào. Chạy /sa-2-architecture --focus adr.
AG3: 🔴 CHẶN — 3 QAS mức Must chưa có bài đo. Chạy /sa-3-enablement --focus fit.
```
## Chế độ chạy
| `--mode` | Làm gì | Khi nào |
|---|---|---|
| `dtm` | Chỉ dựng/cập nhật `DTM` | Sau mỗi sprint |
| `adl` | Chỉ dựng/cập nhật `ADL` | Sau mỗi ADR mới |
| `full` | Cả hai + coverage + kết luận gate | Trước mỗi gate |
## Trước khi kết thúc
In ba thứ: **① bảng coverage đầy đủ** (tỉ lệ + ID đứt) · **② danh sách phát hiện xếp theo
mức, mỗi cái chỉ được file và mục** · **③ kết luận gate**.
Cập nhật `DTM` và `ADL`. **Không sửa artifact của skill khác.**
## Bẫy thường gặp
**Điền ma trận cho đủ.** Ma trận 100% mà một nửa liên kết là suy diễn thì tệ hơn ma trận 70%
trung thực — nó tạo cảm giác an toàn giả. Không thấy quan hệ thì để trống và báo đứt.
**Chỉ đọc xuôi.** Đọc ngược mới tìm ra thành phần thừa và quyết định không phục vụ gì. Đó là
chỗ chi phí ẩn nằm.
**Hạ mức để gate qua được.** Skill này tồn tại để chặn. Chặn ở đây tốn một tuần; chặn ở
production tốn nhiều hơn thế.
**Báo cáo "tài liệu chưa đầy đủ".** Vô dụng. Phải là: *"`ASR-004` (file `ASR_… §B2`) không có
`ADR` nào hiện thực hoá; đề xuất viết ADR về cơ chế hàng đợi; chạy
`/sa-2-architecture --focus adr`."*
**Quét cả bản nháp rồi báo đỏ.** Artifact `🟡 Draft` chưa cam kết gì. Tách riêng, đánh dấu
"trong bản nháp", không tính vào coverage chặn gate.

147
.claude/skills/sa-conformance/templates/adr-ledger.md Normal file
View File

@@ -0,0 +1,147 @@
# ADL — ADR Ledger — <PROJECT>
| | |
|---|---|
| **Cập nhật** | YYYY-MM-DD |
| **Author** | <SA> (skill sa-conformance) |
| **Tổng số ADR** | |
| **Nguồn quét** | `02-architecture/adr/` |
> Sổ này là **mục lục**, không phải nơi chứa nội dung quyết định. Nội dung ở từng file ADR.
---
## 1. Tóm tắt
| Trạng thái | Số lượng |
|---|---|
| `Proposed` | |
| `Accepted` | |
| `Rejected` | |
| `Superseded` | |
| `Deprecated` | |
| Cảnh báo | Số lượng |
|---|---|
| `Proposed` quá 10 ngày | |
| Điểm radar ≥ 8 mà `Accepted` không có POC | |
| Nguồn (`QAS`/`ASR`) đã đổi sau khi ADR được ký | |
| Chuỗi supersede gãy | |
| **Hai ADR mâu thuẫn** | |
## 2. Mục lục
| ID | Quyết định | Chủ đề | Status | Ngày | Người quyết | Radar | POC | Nguồn | Supersedes | Superseded by |
|---|---|---|---|---|---|---|---|---|---|---|
| `ADR-001` | | cấu trúc | Accepted | | | 9 | POC-01 | `ASR-001` | — | — |
| `ADR-002` | | dữ liệu | Accepted | | | 7 | — | `QAS-004` | — | `ADR-011` |
**Chủ đề** *(dùng để rà mâu thuẫn — rà theo chủ đề, không theo số thứ tự)*: cấu trúc · dữ liệu ·
tích hợp · bảo mật · hạ tầng · frontend · vận hành
## 3. Theo chủ đề
*Đây là bảng dùng để tìm mâu thuẫn — kiểm tra khó nhất và đắt nhất khi bỏ sót.*
### Cấu trúc hệ thống
| `ADR` | Quyết định | Status | Có mâu thuẫn với |
|---|---|---|---|
### Dữ liệu
| `ADR` | Quyết định | Status | Có mâu thuẫn với |
|---|---|---|---|
### Tích hợp
| `ADR` | Quyết định | Status | Có mâu thuẫn với |
|---|---|---|---|
### Bảo mật
| `ADR` | Quyết định | Status | Có mâu thuẫn với |
|---|---|---|---|
### Hạ tầng & vận hành
| `ADR` | Quyết định | Status | Có mâu thuẫn với |
|---|---|---|---|
## 4. Năm kiểm tra
### 4.1 Chuỗi supersede
| `ADR` cũ | Ghi `Superseded by` | `ADR` mới | Ghi `Supersedes` ngược lại | Khớp |
|---|---|---|---|---|
| `ADR-002` | `ADR-011` | `ADR-011` | `ADR-002` | ✅ |
| `ADR-005` | `ADR-013` | `ADR-013` | *(trống)* | 🔴 gãy |
### 4.2 `Proposed` quá hạn
| `ADR` | Đề xuất ngày | Số ngày treo | Ai phải quyết | Đang chặn gì |
|---|---|---|---|---|
*Quá 10 ngày ⇒ có người đang chờ mà không ai biết. Đây là cảnh báo hay đúng nhất.*
### 4.3 Điểm radar ≥ 8 chưa có POC
| `ADR` | Radar | Status | POC | Vi phạm |
|---|---|---|---|---|
| | | Accepted | — | 🔴 `decision-radar.md` §6 |
*Quyết định điểm cao dựa trên suy đoán là quyết định sẽ phải làm lại.*
### 4.4 Nguồn đã đổi
| `ADR` | Dựa trên | Nguồn đó đã đổi | Quyết định còn đúng không |
|---|---|---|---|
| `ADR-007` | `QAS-004` (v1.0) | `QAS-004` sửa ở v1.1: 45→30 phút | ☐ cần xem lại |
### 4.5 Mâu thuẫn
| `ADR` A | `ADR` B | Cùng chủ đề | Mâu thuẫn ở đâu | Xử lý |
|---|---|---|---|---|
🔴 Hai `ADR` cùng `Accepted` quyết ngược nhau ⇒ team đang thi công theo hai hướng. Đây là phát
hiện đắt nhất của skill này. **Chặn gate.**
## 5. Điều kiện xét lại đã chạm ngưỡng
| `ADR` | Điều kiện (§7 của ADR) | Ngưỡng | Thực tế | Chạm | Hành động |
|---|---|---|---|---|---|
| `ADR-004` | thông lượng vượt … | | *(từ `CONF`)* | ☐ | |
## 6. ADR không có `FIT` bảo vệ
*Quyết định không kiểm chứng được sẽ bị vi phạm trong 6 tháng mà không ai biết (quy tắc `D8`).*
| `ADR` | Ràng buộc nó đặt ra | `FIT` | Nhãn `⚠️ Khuyến nghị` | Đứt |
|---|---|---|---|---|
## 7. Quyết định KHÔNG đủ tầm ADR — `DEC`
*Điểm radar 3–4. Ghi ở đây một dòng, không cần file riêng.*
| `DEC` | Quyết định | Ngày | Ai | Radar |
|---|---|---|---|---|
| `DEC-01` | | | | 4 |
## 8. Việc phải làm
| # | Việc | ADR liên quan | Chủ | Hạn | Mức |
|---|---|---|---|---|---|
| 1 | Nối lại chuỗi supersede `ADR-005` ↔ `ADR-013` | | | | 🟠 |
| 2 | | | | | |
## 9. Thống kê theo thời gian
*Nhịp ra quyết định nói lên tình trạng dự án.*
| Kỳ | ADR mới | Superseded | Ghi chú |
|---|---|---|---|
| 2026-Q3 | | | |
- **Nhiều ADR mới ở giai đoạn muộn** ⇒ GĐ2 làm chưa đủ, quyết định đang bị đẩy sang lúc thi công
- **Nhiều supersede trong thời gian ngắn** ⇒ quyết định đang được ký khi chưa đủ bằng chứng
- **Không có ADR nào trong 3 tháng** ⇒ hoặc dự án ổn định, hoặc quyết định đang xảy ra mà không ai ghi

174
.claude/skills/sa-conformance/templates/decision-traceability-matrix.md Normal file
View File

@@ -0,0 +1,174 @@
# DTM — Decision Traceability Matrix — <PROJECT>
| | |
|---|---|
| **Cập nhật** | YYYY-MM-DD |
| **Author** | <SA> (skill sa-conformance) |
| **Nguồn quét** | *(liệt kê file + version đã đọc)* |
| **Artifact 🟡 Draft bị tách riêng** | *(liệt kê — không tính vào coverage chặn gate)* |
> Ma trận **trống trung thực tốt hơn ma trận đầy do suy diễn**. Ô trống là danh sách việc;
> ô điền bừa là cảm giác an toàn giả.
---
## 1. Báo cáo coverage
| Chuỗi | Tỉ lệ | % | Mức | ID bị đứt | Chặn gate |
|---|---|---|---|---|---|
| `DRV` → `ASR`/`QAS` | / | | | | AG2 |
| `ASR` → `ADR` | / | | | | AG2 |
| `ADR` → nguồn (`DRV`/`CON`/`QAS`/`ASR`) | / | | | | — |
| `ADR` → `CMP` | / | | | | AG2 |
| `QAS` (Must) → bài đo | / | | | | AG3 |
| `QAS` (Must) → kết quả đo thật | / | | | | AG3 |
| Ràng buộc `AGD` → `FIT` hoặc nhãn khuyến nghị | / | | | | AG3 |
| `CMP` → `ASR` hoặc nhu cầu chức năng | / | | | | — |
| `IF` → chủ sở hữu contract | / | | | | AG2 |
| Thực thể dữ liệu → đúng một chủ | / | | | | AG2 |
| `THR` → biện pháp → cách kiểm chứng | / | | | | AG2 |
| Phụ thuộc ngoài process → `FM` | / | | | | AG2 |
**Luôn ghi danh sách ID, không chỉ tỉ lệ.** "85%" không hành động được.
## 2. `DRV` × `ASR` / `QAS`
| | `ASR-001` | `ASR-002` | … | `QAS-001` | `QAS-002` | … | **Đứt** |
|---|---|---|---|---|---|---|---|
| `DRV-01` | ● | | | ● | | | |
| `DRV-02` | | | | | | | 🔴 |
**Đọc ngược** — `ASR`/`QAS` không sinh từ `DRV`/`CON` nào:
| ID | Sinh từ đâu | Hợp lệ? |
|---|---|---|
| | *(có thể hợp lệ: ràng buộc kỹ thuật nội tại, chuẩn doanh nghiệp)* | |
## 3. `ASR` × `ADR`
| `ASR` | Phát biểu ngắn | `ADR` hiện thực hoá | Trạng thái ADR | Đứt |
|---|---|---|---|---|
| `ASR-001` | | `ADR-005` | Accepted | |
| `ASR-004` | | — | — | 🔴 |
🔴 `ASR` không có `ADR` = yêu cầu định hình kiến trúc mà không ai quyết định gì. **Chặn AG2.**
**Đọc ngược** — `ADR` không phục vụ `ASR`/`QAS` nào:
| `ADR` | Quyết định gì | Nguồn ghi trong §1 | Hợp lệ? |
|---|---|---|---|
| `ADR-006` | | *(trống)* | 🟠 — sở thích cá nhân? hạ xuống `DEC-nn`? |
## 4. `ADR` × `CMP`
| | `CMP-01` | `CMP-02` | … | **Không hiện ở đâu** |
|---|---|---|---|---|
| `ADR-001` | ● | ● | | |
| `ADR-008` | | | | 🟠 |
**Đọc ngược** — `CMP` không phục vụ `ASR` nào và không có nhu cầu chức năng rõ:
| `CMP` | Trách nhiệm | Sinh từ | Hợp lệ? |
|---|---|---|---|
| `CMP-07` | | *(trống)* | 🟠 — có ai cần nó không? |
## 5. `QAS` × kiểm chứng
| `QAS` | Mức | Bài đo (`FIT`/tên bài) | Đã chạy | Kết quả | Nguồn kết quả | Đứt |
|---|---|---|---|---|---|---|
| `QAS-001` | Must | `FIT-05` / `perf/api.js` | ✅ | p95 240ms | `CONF` 2026-09 | |
| `QAS-009` | Must | — | — | — | — | 🔴 |
🔴 `QAS` mức Must không có bài đo ⇒ **chặn AG3**. Cam kết không kiểm chứng được không phải cam kết.
## 6. Ràng buộc `AGD` × `FIT`
| Ràng buộc `AGD` | Nguồn | `FIT` | Nhãn `⚠️ Khuyến nghị` | Đứt |
|---|---|---|---|---|
| §3.1-1 | `ADR-002` | `FIT-01` | — | |
| §3.2-2 | `DAT` §1 | — | — | 🔴 |
| §3.4-2 | `SEC` §3 | — | ✅ có nhãn + cách kiểm thủ công | |
🔴 Không có `FIT` **và** không có nhãn ⇒ chặn AG3 (quy tắc `D8`).
## 7. Kiểm tra chuyên biệt
### 7.1 Interface
| `IF-nnn` | Chủ sở hữu contract | Contract tồn tại | Versioning policy | `FM` khi hỏng | Đứt |
|---|---|---|---|---|---|
### 7.2 Dữ liệu
| Thực thể | Số chủ sở hữu | Hợp lệ | Ghi chú |
|---|---|---|---|
| | 1 / **2** / 0 | | 🔴 nếu ≠ 1 |
### 7.3 Bảo mật
| `THR-nn` | Có biện pháp | Có cách kiểm chứng | Đứt |
|---|---|---|---|
### 7.4 Đường lỗi
| Phụ thuộc ngoài process *(từ `SAD`+`ICD`)* | Có `FM-nn` | Trả lời đủ 4 câu | Đứt |
|---|---|---|---|
## 8. Đối chiếu chéo với bộ BA
| Kiểm | Kết quả | Hành động |
|---|---|---|
| Mọi `NFR-nn` của BA có `QAS` tương ứng | / | |
| Mọi endpoint trong `API` của BA có `IF-nnn` | / | |
| Mọi `ROLE-nn` trong `RBAC` map xuống `SEC` §3.1 | / | |
| `BR-nnn` ép ràng buộc kiến trúc đã có `ADR` | / | |
## 9. ID trùng lặp
*Lỗi nghiêm trọng hơn mọi chỗ đứt — hai thứ khác nhau mang cùng một tên.*
| ID | Xuất hiện ở | Mức |
|---|---|---|
| | file A §… và file B §… | 🔴 |
## 10. Tham chiếu gãy
| Từ | Trỏ tới | Vấn đề |
|---|---|---|
| `SAD` §4.1 | `ADR-014` | Không tồn tại |
| `AGD` §3.1 | `ADR-002` | ADR đã `Superseded by ADR-011` |
## 11. Phát hiện — xếp theo mức
### 🔴 Chặn gate
| # | Phát hiện | File · mục | Hành động | Skill sửa | Chặn |
|---|---|---|---|---|---|
| 1 | | | | | AG2 |
### 🟠 Nợ — phải trả trước gate sau
| # | Phát hiện | File · mục | Hành động | Skill sửa |
|---|---|---|---|---|
### 🟡 Cải thiện
| # | Phát hiện | File · mục | Hành động |
|---|---|---|---|
## 12. Kết luận gate
```
AG2: 🔴 CHẶN / ✅ QUA — <lý do một dòng>
AG3: 🔴 CHẶN / ✅ QUA / — chưa tới
AG4: — chưa tới
```
**Việc gần nhất:** `<lệnh>`
## 13. Chấp nhận có ý thức
*Chỗ đứt được chấp nhận có ghi chép. Khác hoàn toàn với bỏ qua.*
| Chỗ đứt | Vì sao chấp nhận | Ai chấp nhận · ngày | Hạn xử lý | `DEC` |
|---|---|---|---|---|