153 lines
8.1 KiB
Markdown
153 lines
8.1 KiB
Markdown
# 13 quy tắc viết tài liệu BA
|
||
|
||
Mọi skill `ba-*` phải tuân thủ. Đây là thứ phân biệt một tài liệu dev đọc xong code được
|
||
với một tài liệu dev đọc xong phải đi hỏi lại.
|
||
|
||
## W1 — Một câu, một yêu cầu
|
||
|
||
❌ "Hệ thống cho phép người dùng tìm kiếm, lọc theo trạng thái và xuất Excel."
|
||
✅ Tách ba dòng, ba ID. Câu ghép làm test case không map được 1-1, và khi bỏ một vế thì
|
||
không biết ID nào bị ảnh hưởng.
|
||
|
||
## W2 — Cấm từ mơ hồ
|
||
|
||
Danh sách cấm, kèm cách thay:
|
||
|
||
| Cấm | Thay bằng |
|
||
|---|---|
|
||
| nhanh, mượt, tối ưu | "phản hồi ≤ 2 giây ở p95 với 1.000 bản ghi" |
|
||
| thân thiện, dễ dùng | mô tả hành vi cụ thể, hoặc đưa vào wireframe |
|
||
| v.v., các trường hợp khác, tương tự | liệt kê hết. Không liệt kê hết được ⇒ `OQ` |
|
||
| nên, có thể, thường thì | `phải` (Must) hoặc `được phép` (May) — chọn một |
|
||
| xử lý phù hợp, xử lý tương ứng | nêu đích danh hành vi |
|
||
| dữ liệu lớn, nhiều người dùng | con số + đơn vị |
|
||
|
||
Quét trước khi nộp: `grep -niE "nhanh|mượt|thân thiện|v\.v|nên |có thể |phù hợp" <file>`
|
||
|
||
## W3 — Mọi con số phải có đơn vị và nguồn
|
||
|
||
"Tối đa 40" ⇒ 40 **ký tự** hay 40 **byte**? Tiếng Hàn/tiếng Việt có dấu khác nhau ở chỗ
|
||
này. Ghi `40 ký tự (UTF-8, tính theo code point)` và nguồn: ai chốt, ngày nào.
|
||
|
||
## W4 — Luồng lỗi là bắt buộc, không phải phần thêm
|
||
|
||
Mỗi hành động phải có tối thiểu: luồng thành công · luồng validation fail · luồng hệ thống
|
||
lỗi (timeout/5xx) · luồng không đủ quyền. Thiếu luồng lỗi ⇒ dev tự bịa ⇒ mỗi màn hình một
|
||
kiểu.
|
||
|
||
## W5 — Text hiển thị viết nguyên văn, trong bảng riêng
|
||
|
||
Nhãn, placeholder, hint, thông điệp lỗi, text màn hình rỗng, nhãn trạng thái — **BA sở hữu
|
||
những chuỗi này**. Viết đúng từng ký tự vào bảng, đủ mọi ngôn ngữ hỗ trợ. Không viết
|
||
"hiển thị thông báo lỗi phù hợp".
|
||
|
||
## W6 — Trạng thái phải có sơ đồ chuyển
|
||
|
||
Thực thể có trạng thái ⇒ phải có bảng: `trạng thái nguồn | sự kiện | điều kiện | trạng thái
|
||
đích | ai được làm`. Kèm câu trả lời cho: trạng thái khởi tạo là gì, trạng thái nào là cuối,
|
||
từ trạng thái cuối có quay lại được không.
|
||
|
||
## W7 — Phân biệt "ẩn" và "khoá"
|
||
|
||
Ba trạng thái khác nhau, đừng gộp: **không hiển thị** · **hiển thị nhưng disable** ·
|
||
**hiển thị và read-only**. Mỗi field/nút trong bảng component phải chỉ rõ cái nào, theo
|
||
điều kiện gì.
|
||
|
||
## W8 — Cấm quyết định thay PO trong tài liệu
|
||
|
||
Gặp chỗ chưa rõ, viết:
|
||
|
||
```markdown
|
||
> **OQ-012** — Đơn hàng đã huỷ có được tính vào doanh thu tháng không?
|
||
> **Hỏi:** PO (chị Lan) · **Từ:** 2026-08-28 · **Chặn:** AC-US059-04, BR-021
|
||
> **Phương án BA đề xuất:** Không tính, vì … *(đề xuất, chưa phải quyết định)*
|
||
```
|
||
|
||
Không được im lặng chọn một phương án rồi viết như thể đã chốt. Đó là nguồn gốc của phần
|
||
lớn CR ở giai đoạn UAT.
|
||
|
||
## W9 — Truy vết trong chính câu văn
|
||
|
||
Mỗi AC ghi kèm US nó phục vụ; mỗi BR ghi kèm RQ nó hiện thực hoá; mỗi field ghi kèm BR
|
||
quy định nó. Truy vết nằm rải trong tài liệu, RTM chỉ tổng hợp lại — không phải ngược lại.
|
||
|
||
## W10 — Viết cho ba người đọc cùng lúc
|
||
|
||
| Người đọc | Họ tìm gì | Đáp ứng bằng |
|
||
|---|---|---|
|
||
| PO | Có đúng cái tôi cần không | Mục tóm tắt nghiệp vụ đầu tài liệu, ngôn ngữ nghiệp vụ |
|
||
| Dev | Tôi code gì | Bảng field, bảng component, mã lỗi, API |
|
||
| QA | Tôi test gì | AC Given/When/Then, bảng dữ liệu biên |
|
||
|
||
Một tài liệu, ba mục tiêu. Đừng viết SRS chỉ cho dev đọc.
|
||
|
||
## W11 — Ảnh không thay lời
|
||
|
||
Wireframe (`WF`) và prototype minh hoạ bố cục. Hành vi luôn nằm ở bảng component và AC. Khi
|
||
hình và bảng mâu thuẫn: **bảng thắng về "có tồn tại không" và "hành xử thế nào"**, hình thắng
|
||
về "nằm ở đâu, to bằng nào". Ghi rõ quy tắc này trong mỗi tài liệu có hình, và **ghi từng
|
||
mâu thuẫn vào `WF` §5** kèm người quyết — mâu thuẫn không ghi là mâu thuẫn dev sẽ tự xử.
|
||
Hệ quả: prototype có thành phần mà SRS không có ⇒ không tự thêm vào SRS; đó là scope creep
|
||
bằng hình ảnh, PO quyết.
|
||
|
||
## W12 — Ghi cả cái tài liệu KHÔNG nói
|
||
|
||
Cuối mỗi tài liệu, mục **"Ngoài phạm vi"**: những thứ người đọc có thể tưởng là có nhưng
|
||
không có. Ví dụ: *"Không xử lý đơn hàng đa tiền tệ trong phiên bản này"*. Nó ngăn dev làm
|
||
thừa và ngăn PO tưởng đã có.
|
||
|
||
## W13 — Sơ đồ theo chuẩn Archify: spec JSON + mermaid + bảng đi kèm
|
||
|
||
Ba vế, cả ba bắt buộc. Chi tiết: [`diagram-rules.md`](diagram-rules.md).
|
||
|
||
**Vế 1 — spec Archify là nguồn sự thật về topology.** Mỗi sơ đồ có kiểu Archify
|
||
(`architecture` · `workflow` · `sequence` · `dataflow` · `lifecycle`) phải có file
|
||
`diagrams/<ARTIFACT>_<slug>.<type>.json` đạt `archify validate … --quality showcase` 0 lỗi, và một
|
||
đường chính rõ ràng với ≤ 12 node chính. Sơ đồ không có kiểu Archify (ERD, class, use case, 2×2)
|
||
đánh dấu `mermaid-only`.
|
||
|
||
**Vế 2 — mermaid là bản chiếu, không ASCII art.** Ngay trên khối mermaid có marker
|
||
`<!-- archify: <type> · <spec.json> -->`; ID node và cạnh khớp spec hai chiều; không `style`/
|
||
`classDef`/màu. ASCII vỡ khi dán sang Confluence, `git diff` ra rác, ký hiệu tự chế đọc lệch.
|
||
|
||
**Vế 3 — sơ đồ để nhìn, bảng để truy vết và test.** Sơ đồ không diễn đạt được điều kiện
|
||
chính xác, ai được làm, mã lỗi nào, quy tắc nào chi phối. Sơ đồ đứng một mình là bức tranh
|
||
đẹp mà QA không viết được test case từ đó.
|
||
|
||
| Sơ đồ | Bảng bắt buộc đi kèm |
|
||
|---|---|
|
||
| Quy trình | Bảng bước: ai · input · output · công cụ · thời gian |
|
||
| Vòng đời trạng thái | Bảng chuyển + **bảng chuyển bị cấm** *(sơ đồ không vẽ được cạnh cấm)* |
|
||
| Use case | Bảng US: id · vai trò · RQ · MoSCoW |
|
||
| ERD | Bảng thực thể: trường · kiểu · khoá · ràng buộc |
|
||
| Sequence | Bảng bước: mã lỗi mỗi nhánh · timeout · hành vi khi thất bại |
|
||
|
||
Sơ đồ mâu thuẫn bảng ⇒ **bảng thắng** (hệ quả của W11).
|
||
|
||
---
|
||
|
||
## Checklist tự chấm trước khi nộp bất kỳ tài liệu nào
|
||
|
||
```
|
||
[ ] W1 Không có câu chứa 2 yêu cầu trở lên
|
||
[ ] W2 grep từ mơ hồ trả về rỗng
|
||
[ ] W3 Mọi con số có đơn vị + nguồn
|
||
[ ] W4 Mọi hành động có đủ 4 luồng
|
||
[ ] W5 Có bảng text hiển thị nguyên văn
|
||
[ ] W6 Thực thể có trạng thái đều có bảng chuyển trạng thái
|
||
[ ] W7 Mọi field/nút có điều kiện ẩn/khoá/read-only rõ ràng
|
||
[ ] W8 Mọi chỗ chưa rõ là OQ, không phải quyết định ngầm
|
||
[ ] W9 Mọi AC/BR/field có tham chiếu ngược
|
||
[ ] W10 Có tóm tắt nghiệp vụ cho PO ở đầu
|
||
[ ] W11 Có câu quy định ảnh vs bảng; (screen) mọi lệch prototype ↔ SRS nằm ở WF §5
|
||
[ ] W12 Có mục "Ngoài phạm vi"
|
||
[ ] W13 Sơ đồ theo chuẩn Archify: marker + spec validate pass + mermaid khớp spec + bảng đi kèm
|
||
```
|
||
|
||
Quét W13: `node .claude/skills/ba-lifecycle/scripts/diagram-check.mjs --md <file>` phải exit 0
|
||
(A0–A7 không 🔴). Không có Bash ⇒ tự kiểm: số marker `<!-- archify:` = số khối ` ```mermaid `;
|
||
`grep -nE '^\s*[┌└├│─▼]' <file>` rỗng; ghi `humanInputNeeded` "chạy diagram-check".
|
||
|
||
In checklist này dạng bảng ☐/✅ ở cuối mỗi lần chạy skill. Mục chưa đạt ⇒ nói rõ thiếu gì,
|
||
**không được đánh ✅ cho có**.
|