sys-analysis-design/.claude/skills/ba-3-specification/GUIDE.md

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

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

Đầu vào là BACKLOG đã qua G2. Đầu ra là tài liệu mà dev code được không phải đoán và QA test được không phải hỏi.

Đây là sản phẩm chính của nghề BA, và là gate nghiêm nhất. Một chỗ mơ hồ lọt qua G3 sẽ thành bug hoặc CR — đắt hơn nhiều so với việc hỏi cho rõ ở đây.

Không làm ở giai đoạn này: quyết kiến trúc, chọn thư viện, viết test case chi tiết (QA làm từ AC), ước lượng công sức.

Khi nào gọi

Tình huống	Có nên gọi
US đã qua G2, cần viết spec cho dev	✅ Chạy đầy đủ
Dev hỏi "field này bao nhiêu ký tự" liên tục	✅ Bảng field đang thiếu — chạy Bước 3
QA bảo "AC này không test được"	✅ Chạy Bước 4 để viết lại AC
Cần bảng mã lỗi thống nhất cho module	✅ Chạy Bước 5
Chỉ cần NFR hoặc chỉ cần API contract	✅ Dùng --only nfr / --only api
Backlog chưa chốt, PO còn đang đổi ý	❌ Quay lại GĐ2 — viết SRS bây giờ là viết để vứt

PART 2 thay đổi theo loại sản phẩm

🔴 Điểm khác biệt lớn nhất của giai đoạn này. PART 1 và PART 3–8 của SRS dùng chung cho mọi loại; PART 2 được nạp từ biến thể theo PRODUCT trong profile:

PRODUCT	PART 2 mô tả gì	Tiêu chí G3 riêng
screen	Màn hình, bảng thành phần, bảng field 10 cột	Hai trạng thái rỗng khác nhau; mọi thành phần có điều kiện ẩn/khoá
api-service	Người tiêu thụ, khả năng, hợp đồng dữ liệu	Idempotency · tương thích ngược · phân trang đã chốt
data-pipeline	Luồng, data contract, chất lượng	Có mục đối soát nguồn–đích; chạy lại/backfill/đến muộn đã trả lời
ml-model	Bài toán, nhãn, metric + ngưỡng	Tập test cách ly; mọi ngưỡng truy về chi phí nghiệp vụ; có fallback
batch-job	Job, lịch, idempotency	Idempotency và thất bại giữa chừng đã trả lời; có cảnh báo "job không chạy"
process-only	—	Không có PART 2

Một US thường có nhiều loại (màn hình + API, hoặc màn hình + job đêm) ⇒ skill nạp nhiều biến thể, mỗi cái một mục con 2.A, 2.B, 2.C.

Loại chưa có biến thể (nhúng/IoT/firmware): skill sẽ nói thẳng là PART 2 phải tự viết và đề xuất khung dựa trên biến thể gần nhất — không im lặng nhét vào biến thể sai.

Cú pháp

/ba-3-specification <US-id...> [--product <loại>] [--only srs|ac|nfr|api|uiconv|wf] [--proto <path|url>] [--lang vi,en,ko] [--out <path>] [go]

Tham số	Ý nghĩa
<US-id...>	Một hoặc vài US. Quá 3 US một lần thì chất lượng giảm rõ rệt
--product	Ghi đè PRODUCT của profile cho lần chạy này. Nhiều loại: --product screen,api-service
--only	Chỉ sinh một loại tài liệu. uiconv và wf chỉ có với screen
--proto	Prototype tham chiếu: thư mục ảnh, file HTML, link Figma, hoặc mục SAD (docs/sections/07-giao-dien.md). Không có ⇒ skill tự tìm; vẫn không có ⇒ WF là đề xuất của BA
--lang	Ngôn ngữ text hiển thị. Bỏ qua nếu PRODUCT không có giao diện
go	Bỏ bước dừng xác nhận input

Ví dụ:

/ba-3-specification US011
/ba-3-specification US011 US012 --lang vi,ko
/ba-3-specification US011 --only api

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

Bắt buộc:

• BACKLOG chứa US cần đặc tả
• BR — quy tắc nghiệp vụ đã chốt
• RBAC — ma trận phân quyền

Rất nên có (với screen):

• Prototype tham chiếu — Figma, HTML, ảnh, hoặc mục Thiết kế giao diện của SAD. Có nó, WF của BA là bản ghi lại + đối chiếu, và đội design không phải làm lại phần bố cục
• Design system dự án dùng (tên + version) — để UICONV §11 map thành phần
• Quy ước UI sẵn có của dự án — UICONV chỉ bổ khuyết, không chép lại
• Danh sách mã lỗi đã dùng — để tiếp số, không mở dãy mới
• Glossary — để dùng đúng thuật ngữ

Nếu dự án có sẵn guideline (như GLOBAL_UI_CONVENTION.md, GLOBAL_NFR.md của Berriz), nói rõ đường dẫn khi gọi. Skill sẽ tuân thủ thay vì tự định nghĩa.

UICONV và WF — phần "thay design" của bộ skill

Hai artifact chỉ sinh khi PRODUCT = screen:

Artifact	Ở đâu	Sinh khi nào	Trả lời câu gì
UICONV_<PROJECT>.md	00-index/	Một lần ở lần chạy ba-3 đầu tiên; các lần sau bổ sung	Toàn project phân trang, toast, định dạng, trạng thái rỗng, từ vựng thành phần… thế nào
WF_<US>.md + .html	03-specification/	Mỗi US, sau bảng thành phần và bảng text	Từng màn hình: vùng nào chứa thành phần nào, trông ra sao ở từng trạng thái, khác prototype ở đâu

Mức độ "thay design" tuỳ đầu vào:

Đầu vào	WF là gì	Đội design còn làm gì
Prototype đã duyệt + design system	Bản ghi lại và đối chiếu — dev dựng UI từ WF + SRS + design system	Chỉ xử lý dòng lệch ở WF §5
Prototype đã duyệt, chưa có design system	Như trên, nhưng UICONV §11 chưa map được component	Chọn/dựng design system, visual
Chỉ có mô tả UI dạng văn bản (SAD §7)	Bản ghi lại ở mức vùng; kích thước, thứ tự là đề xuất BA	Duyệt WF, làm visual
Không có gì	Đề xuất của BA, đánh dấu ✏️	Thiết kế bố cục thật, hoặc duyệt đề xuất BA rồi làm visual

WF không bao giờ thay phần visual (màu, font, icon, motion). Mục §6 của WF ghi rõ phần Designer còn phải làm — để không ai tưởng "có WF là xong design".

Quy trình 7 bước — bạn tham gia ở đâu

Bước	Skill làm	Bạn làm
1. Khung + tóm tắt	Dựng khung đủ mục, viết tóm tắt cho PO	Duyệt phần tóm tắt
2. Chọn & nạp biến thể PART 2	Xác định PRODUCT, nạp biến thể, nêu tiêu chí G3 riêng	Xác nhận loại sản phẩm
3. Điền biến thể	Dựng bảng ràng buộc, đánh dấu chỗ thiếu	Đi hỏi giới hạn, mặc định, nguồn giá trị
4. AC	Viết 4 nhóm, sinh bảng dữ liệu biên	Đưa QA review sớm
5. Mã lỗi & text	Sinh bảng, đòi nguyên văn từng chuỗi	Chốt giọng văn với PO/thiết kế
6. NFR	Rà 7 nhóm, đòi số đo + cách verify	Hỏi người dùng ngưỡng chấp nhận được
7. API contract	Đề xuất contract, đánh dấu điểm cần BE chốt	Gửi BE xác nhận
8. UICONV (screen, lần đầu)	Điền quy ước từ design system / prototype, đánh dấu ô chưa chọn	Chốt với Designer, ký
9. WF (screen)	Bản đồ prototype ↔ màn hình, bảng vùng, HTML low-fi, bảng lệch §5	Đưa Designer duyệt (✏️) hoặc PO xác nhận bảng lệch (🎨)

🔴 Bước 3 và Bước 5 là hai bước cần bạn đi hỏi nhiều nhất. Skill sẽ liệt kê chính xác những gì còn thiếu dưới dạng OQ — đó là danh sách việc của bạn.

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

ba-output/<PROJECT>/00-index/
└── UICONV_<PROJECT>_v1.0.md  ← quy ước giao diện, một lần cho cả project (screen)
ba-output/<PROJECT>/03-specification/
├── SRS_<US-id>_v1.0.md      ← tài liệu chính
├── AC_<US-id>_v1.0.md        ← nếu tách riêng
├── NFR_<US-id>_v1.0.md
├── API_<US-id>_v1.0.md
├── WF_<US-id>_v1.0.md        ← bố cục từng màn hình + bảng lệch prototype ↔ SRS (screen)
└── WF_<US-id>_v1.0.html      ← render low-fi, mở bằng trình duyệt, đổi khung nhìn/trạng thái (screen)

Cộng năm bảng in ra màn hình: truy vết US→AC→BR→field→mã lỗi · tự chấm G3 · checklist W1–W13 (có chạy lệnh quét thật) · danh sách TBD còn lại · OQ mở.

Danh sách TBD là thứ đáng nhìn nhất. Còn TBD trong bảng field hoặc bảng mã lỗi thì G3 không pass được — skill sẽ nói thẳng điều đó thay vì để bạn phát hiện ở buổi họp duyệt.

Ví dụ hội thoại

Bạn:    /ba-3-specification US011

Claude: [Bước 0]
        Input:
        | BACKLOG_Settlement_v1.0.md | US-011 định nghĩa | ✅ Baselined |
        | BR_Settlement_v1.0.md      | BR-021, BR-022    | ✅ Baselined |
        | RBAC_Settlement_v1.0.md    | 4 vai trò         | ✅ Baselined |
        | Wireframe                  | Không tìm thấy    | — |

        G2: đã qua (PO 2026-08-28, Tech Lead 2026-08-29). ✅

        Guideline dự án tôi tìm thấy:
        - Chưa thấy quy ước UI hay bộ mã lỗi. Tôi sẽ mở dãy E-STL-0001,
          cần bạn xác nhận không trùng với module khác.

        Ngôn ngữ hiển thị: bạn muốn VI, hay VI+KO?

Bạn:    VI+KO. Mã lỗi thì dùng dãy E-STL, chưa ai dùng.

Claude: [sinh SRS, in danh sách TBD]

        ⚠️ Còn 6 TBD chặn G3:
        - F01 độ dài mã cửa hàng — chưa ai chốt (OQ-021, hỏi chị Lan)
        - F04 nguồn dropdown "Loại" — lấy từ API nào? (OQ-022, hỏi anh Huy)
        - Múi giờ hiển thị createdAt (OQ-023)
        - 3 thông điệp lỗi chưa có bản KO

Lỗi thường gặp

"Skill để trống nhiều ô quá, tôi điền đại được không?" Không. Bịa một giá trị nghe hợp lý (255 ký tự, timeout 30s, giữ log 90 ngày) là cách phổ biến nhất tạo bug — vì nghe hợp lý nên không ai chất vấn, và sai thì phát hiện rất muộn. Mỗi ô trống là một OQ có người chịu trách nhiệm trả lời.

"AC của tôi chỉ có luồng thành công, vậy đủ chưa?" Chưa. Bốn nhóm là bắt buộc: thành công · validation · lỗi hệ thống · phân quyền. Nhóm "lỗi hệ thống" phải có AC "lưu thất bại thì dữ liệu đã nhập được giữ nguyên" — AC bị quên nhiều nhất và gây bực bội nhất.

"Hành vi tôi mô tả trong wireframe rồi, khỏi ghi lại nhé?" Không được (quy tắc W11). Ảnh nói bố cục, bảng nói hành vi. Viết "xem hình" ở cột hành vi là chưa đặc tả — và ảnh thì không grep được, không diff được, không dịch được.

"Field này giống US trước, tôi copy sang." Copy được, nhưng phải rà lại từng cột. Độ dài, default và thông điệp là ba thứ hay bị mang theo sai nhất. Mỗi field phải truy về một BR hoặc một câu trả lời cụ thể.

"Đặc tả 8 US một lượt cho nhanh." Quá 3 US thì các bảng bắt đầu sơ sài, và mâu thuẫn chéo giữa các US không ai phát hiện. Chia nhỏ, làm kỹ.

"NFR thì copy bộ chuẩn công ty vào là xong." Copy cả bộ làm loãng và không ai kiểm. Chỉ giữ cái áp dụng cho US này, mỗi cái phải có số đo + điều kiện đo + cách verify.

"API contract tôi tự viết, dev cứ thế code." Phải ghi rõ ⚠️ BA đề xuất — chờ BE xác nhận ở đầu file, và liệt kê điểm cần BE chốt. Contract BA đề xuất là giả định, không phải sự thật.

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

Đủ cả năm:

1. Không còn TBD trong bảng ràng buộc của PART 2 và bảng mã lỗi
2. Không còn OQ mở ảnh hưởng tới hành vi hệ thống
3. Bảng tự chấm G3 toàn ✅ — gồm cả tiêu chí riêng của biến thể PART 2 đã nạp
4. QA xác nhận mọi AC đều test được — chữ ký hay bị bỏ qua nhất (bỏ được ở RIGOR = light)
5. Đã ký đủ theo RIGOR: light chỉ PO · standard PO + Tech Lead + QA · strict thêm Bảo mật/Pháp chế, và API phải do BE xác nhận
6. (screen) WF §5 không còn lệch Tồn tại/Hành vi chưa quyết; tập C-id khớp hai chiều với SRS; UICONV và WF (chế độ ✏️) có chữ ký Designer

Rồi bàn giao cho dev và chuyển sang /ba-4-delivery-support.

Liên quan

• Chọn PRODUCT: ../ba-lifecycle/references/domain-profiles.md §1
• Tiêu chí gate G3 + bảng bớt/thêm theo RIGOR: ../ba-lifecycle/references/workflow.md §2
• Quy tắc viết W1–W13: ../ba-lifecycle/references/writing-rules.md
• Ví dụ ở nhiều domain và nhiều PRODUCT: examples.md
• Template: templates/srs.md · templates/srs-part2/<loại>.md · templates/acceptance-criteria.md · templates/nfr-checklist.md · templates/api-contract.md