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

Hướng dẫn sử dụng — sa-3-enablement (Giai đoạn 3)

Giai đoạn này giải quyết gì

Đầu vào là bộ thiết kế đã ký (AG2). Đầu ra là kiến trúc đó tồn tại trong code và ở lại đó — có chuẩn dev dùng được, có bài kiểm tự động, có sổ nợ khi phải lệch, có nhật ký quyết định phát sinh trong lúc thi công.

Không làm ở giai đoạn này: thiết kế lại kiến trúc, viết code sản phẩm, quản lý sprint.

Vì sao giai đoạn này quyết định thành bại

Kiến trúc trên giấy không có giá trị. Ba thứ làm nó biến mất trong 6 tháng:

1. Dev không biết ràng buộc tồn tại ⇒ AGD + reference implementation
2. Biết nhưng không ai kiểm ⇒ FIT
3. Phải lệch vì gấp, rồi quên ⇒ TDEBT

Bỏ một trong ba thì hai cái còn lại cũng vô dụng.

Khi nào gọi

Tình huống	Có nên gọi
Vừa qua AG2, dev sắp bắt đầu	✅ --focus handoff rồi --focus agd, ngay trong tuần đầu
CI chưa kiểm gì về kiến trúc	✅ --focus fit
Dev đề xuất một thay đổi chạm thiết kế	✅ --focus review
Phải lệch thiết kế vì deadline	✅ --focus debt — ghi lại ngay, đừng để nhớ sau
Codebase kế thừa, không rõ kiến trúc thật là gì	✅ --focus fit để đo hiện trạng trước
Dev hỏi "hàm này đặt tên gì"	❌ Thuộc Tech Lead
Muốn đổi một quyết định kiến trúc	❌ Sang /sa-2-architecture --focus adr

Cú pháp

/sa-3-enablement <PROJECT> [--focus handoff|agd|fit|review|debt|all] [--out <path>] [go]

--focus	Sinh ra	Khi nào chạy
handoff	HANDOFF — gói bàn giao dev: mục lục đường dẫn thật, checklist đủ/thiếu, dev ký đã nhận	Ngay khi AG2 ký, chạy lại mỗi khi mở rộng phạm vi
agd	AGD + đề cương reference implementation	Ngay sau AG2
fit	FIT — danh sách bài kiểm + cấu hình CI đề xuất	Tuần 1–2 của thi công
review	Một mục trong DREV	Mỗi lần có thay đổi chạm kiến trúc
debt	Một mục trong TDEBT	Mỗi lần chấp nhận lệch
all	Cả năm

Review một thay đổi cụ thể:

/sa-3-enablement Settlement --focus review
  "Dev đề xuất gọi trực tiếp DB của module Order từ module Report cho nhanh,
   thay vì qua API. Lý do: query join 3 bảng qua API mất 4 giây."

Chuẩn bị gì trước khi gọi

Cho bước	Chuẩn bị
handoff	Phạm vi bàn giao (US/module) · INDEX của BA và SA · quyền mở mọi artifact
agd	SAD, ADR, ICD, CTR, PDM, FAIL đã ký · quy ước code hiện có của team
fit	Cấu hình CI hiện tại · ngôn ngữ/framework · quyền sửa pipeline
review	Mô tả thay đổi + lý do dev đưa ra + code/PR nếu có
debt	Lệch cụ thể là gì · vì sao phải lệch · ai chấp nhận

Bạn sẽ nhận được gì

sa-output/<PROJECT>/03-enablement/
├── HANDOFF_<PROJECT>_<phạm vi>_v1.0.md  ← dev mở cái này ĐẦU TIÊN: đọc gì, ở đâu, bản nào, ai ký
├── AGD_<PROJECT>_v1.0.md      ← dev đọc cái này
├── FIT_<PROJECT>_v1.0.md      ← danh sách bài kiểm + trạng thái xanh/đỏ
├── DREV_<PROJECT>.md          ← nhật ký, ghi thêm liên tục, không lên version
└── TDEBT_<PROJECT>.md         ← sổ nợ, ghi thêm liên tục

DREV và TDEBT là sổ sống — ghi thêm mỗi lần, không tạo version mới.

Fitness function: bắt đầu thế nào

Đừng cố phủ hết ngay. Thứ tự đem lại giá trị nhanh nhất:

Tuần 1  ① Phụ thuộc giữa tầng/module          ← rẻ nhất, chặn được nhiều lỗi nhất
        ② Quét secret trong mã nguồn           ← rủi ro cao, công cụ có sẵn
Tuần 2  ③ Quét lỗ hổng thư viện
        ④ Lint contract (OpenAPI)
Tuần 3  ⑤ Kiểm thử hiệu năng QAS mức Must      ← tốn công dựng nhất, để sau
Tuần 4  ⑥ Kiểm tra IaC / policy hạ tầng

Mỗi bài kiểm bật ở chế độ cảnh báo trước, công bố ngày chuyển sang chặn merge, dọn nợ trước ngày đó.

FIT-01  Tầng domain không import tầng infra
        Nguồn : ADR-002
        Công cụ: ArchUnit · chạy ở CI bước `test`
        Chế độ : ⚠️ cảnh báo (từ 2026-09-01) → 🚫 chặn (từ 2026-09-20)
        Hiện tại: 🔴 12 vi phạm → TD-03, chủ: anh Nam, hạn 2026-09-18

Ví dụ hội thoại — design review

Bạn:    /sa-3-enablement Settlement --focus review
        Dev muốn gọi thẳng DB module Order từ module Report vì query qua API mất 4 giây.

Claude: Chấm điểm radar:
        - Chi phí đảo ngược:      1 (sửa được trong ~2 tuần)
        - Bán kính ảnh hưởng:     2 (phá ranh giới module, ảnh hưởng mọi thay đổi Order sau này)
        - Chạm QAS:               2 (QAS-003 p95 báo cáo ≤ 3s — đây chính là vấn đề)
        - Ràng buộc dài hạn:      2 (khi tách service, chỗ này sẽ chặn)
        - Tranh cãi:              1
        → 8/10 ⇒ cần ADR, không phải quyết định trong PR.

        Đối chiếu: ADR-004 chốt module chỉ giao tiếp qua interface công khai.
        QAS-003 yêu cầu p95 ≤ 3s — thiết kế hiện tại KHÔNG đạt. Dev đúng về vấn đề.

        Bốn phương án, không chỉ hai:
        1. Giữ ranh giới + thêm read model cho báo cáo   → đúng ADR-004, +1 tuần
        2. Giữ ranh giới + cache kết quả                 → nhanh nhất, dữ liệu trễ ≤ 5 phút
        3. Gọi thẳng DB                                  → vi phạm ADR-004
        4. Nới QAS-003 lên 5s                            → cần PO chấp nhận

        Khuyến nghị: PA-2 nếu PO chấp nhận trễ 5 phút (rẻ nhất), PA-1 nếu không.
        PA-3 chỉ chấp nhận như TDEBT có hạn, kèm FIT-01 whitelist tạm thời.

        Cần ai quyết: PO (trễ 5 phút có chấp nhận được không) → OQ-034
        Ghi vào DREV-012.

Lỗi thường gặp

"Guideline viết xong không ai đọc." Bình thường nếu nó dài. Kiểm tra: quy tắc nào không truy được về ADR/QAS thì cắt. Phần còn lại chuyển thành reference implementation — dev đọc code, không đọc văn bản.

"Bật fitness function thì CI đỏ 200 chỗ." Đúng như dự kiến với codebase đã có. Bật chế độ cảnh báo, ghi số vi phạm hiện tại làm mốc, đặt quy tắc "không tăng thêm", rồi giảm dần. Chuyển sang chặn khi về 0.

"Dev bảo kiến trúc không thực tế." Nghe kỹ trước khi bảo vệ thiết kế. Ba lần trở lên cùng một phản hồi về cùng một chỗ ⇒ khả năng cao thiết kế sai thật. Kết luận "thiết kế sai, cần ADR mới" là kết luận hợp lệ và là dấu hiệu của một SA làm việc tốt, không phải thất bại.

"Sổ nợ chỉ tăng, không bao giờ giảm." Thiếu cột "lãi suất". Viết bằng con số PM hiểu: "module này khiến mỗi tính năng mới tốn thêm 2 ngày; đã có 6 tính năng chạm nó trong quý" — 12 ngày đó sẽ tự tìm được chỗ trong sprint.

"Tôi thành nút thắt, mọi PR đều chờ tôi." Đang review quá rộng. Chấm radar: điểm < 3 trả lại Tech Lead. Và đầu tư vào FIT — bài kiểm tự động review nhanh hơn bạn và không nghỉ phép.

Ra khỏi giai đoạn này khi nào

Đủ cả năm:

1. Bảng tự chấm AG3 toàn ✅
2. Tech Lead + QA + SRE đã ký
3. Mọi FIT cho ràng buộc quan trọng đang xanh trên CI, không phải "đã viết"
4. Mọi QAS mức Must có bài đo thật đã chạy, không phải ước lượng
5. Mọi TD-nn có chủ và hạn — không còn mục "sẽ sửa sau" trống

Rồi go-live, và chạy /sa-4-evolution <PROJECT> sau kỳ vận hành đầu tiên.

Liên quan

• Tiêu chí gate AG3: ../sa-lifecycle/references/workflow.md §2
• Quy tắc D8 (ràng buộc phải verify được): ../sa-lifecycle/references/design-rules.md
• Chấm điểm thay đổi có cần ADR không: ../sa-lifecycle/references/decision-radar.md §2
• Template: templates/architecture-guidelines.md · templates/fitness-functions.md · templates/design-review-log.md · templates/tech-debt-register.md