230 lines
13 KiB
Markdown
230 lines
13 KiB
Markdown
# 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`
|