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

7.7 KiB Raw Blame History

Hướng dẫn sử dụng — sa-conformance (xuyên suốt)