313 lines
18 KiB
Markdown
313 lines
18 KiB
Markdown
# Bộ skill BA — Business Analyst Toolkit
|
||
|
||
Bảy skill bao trọn năm giai đoạn công việc của một BA trong dự án, từ lúc nhận ý tưởng
|
||
mơ hồ đến lúc đo hiệu quả sau release.
|
||
|
||
Mỗi skill làm **đúng một giai đoạn**, có đầu vào rõ, đầu ra rõ, và một **gate** phải qua
|
||
trước khi sang giai đoạn sau. Không skill nào được lấn sân skill khác.
|
||
|
||
---
|
||
|
||
## 0. Project Profile — khai trước khi làm bất cứ việc gì
|
||
|
||
Bộ skill **không phụ thuộc ngành nghiệp vụ** (bán lẻ, y tế, logistics, ngân hàng, HR, giáo
|
||
dục… dùng chung khung). Nhưng nó phụ thuộc **ba trục khác**, khai trong
|
||
`00-index/PROFILE_<PROJECT>.md` ngay lần chạy đầu:
|
||
|
||
```
|
||
PROFILE = PRODUCT × LIFECYCLE × RIGOR
|
||
```
|
||
|
||
| Trục | Giá trị | Quyết định |
|
||
|---|---|---|
|
||
| **PRODUCT** | `screen` · `api-service` · `data-pipeline` · `ml-model` · `batch-job` · `process-only` | **GĐ3 viết cái gì** — nạp biến thể SRS PART 2 tương ứng |
|
||
| **LIFECYCLE** | `greenfield` · `brownfield` · `enhancement` | **GĐ1 và GĐ2 nặng ở đâu** — AS-IS, dữ liệu cũ, phân tích tác động |
|
||
| **RIGOR** | `light` · `standard` · `strict` | **Gate chặt tới đâu và ai ký** |
|
||
|
||
Khai sai ⇒ skill đòi bạn điền mục không tồn tại trong loại sản phẩm của bạn, hoặc bỏ qua mục
|
||
sống còn. Chi tiết và cách chọn khi lưỡng lự: [`ba-lifecycle/references/domain-profiles.md`](ba-lifecycle/references/domain-profiles.md).
|
||
|
||
`/ba-lifecycle <PROJECT>` sẽ đề xuất profile và hỏi xác nhận nếu chưa có.
|
||
|
||
---
|
||
|
||
## 1. Bản đồ skill
|
||
|
||
| # | Skill | Giai đoạn | Câu hỏi nó trả lời | Output chính | Gate |
|
||
|---|---|---|---|---|---|
|
||
| 0 | `ba-lifecycle` | *Điều phối* | "Tôi đang ở đâu, làm gì tiếp?" | Bảng trạng thái pipeline | — |
|
||
| 1 | `ba-1-discovery` | Khởi tạo | "Bài toán là gì, của ai, thành công là gì?" | `BRIEF`, `STAKEHOLDER`, `ELICITATION` | **G1** |
|
||
| 2 | `ba-2-analysis` | Phân tích | "Nghiệp vụ chạy thế nào, cần những gì?" | `PROCESS`, `BACKLOG`, `BR`, `RBAC`, `IMPACT` | **G2** |
|
||
| 3 | `ba-3-specification` | Đặc tả | "Dev code cái gì, QA test cái gì, màn hình bố cục ra sao?" | `SRS`, `AC`, `API`, `NFR` (+ `UICONV`, `WF` khi `screen`) | **G3** |
|
||
| 4 | `ba-4-delivery-support` | Đồng hành dev | "Câu hỏi/thay đổi/UAT xử lý ra sao?" | `QLOG`, `CR`, `TCREVIEW`, `UAT` | **G4** |
|
||
| 5 | `ba-5-post-release` | Sau release | "Có đạt mục tiêu không, cải tiến gì?" | `RELNOTE`, `MANUAL`, `BENEFIT` | **G5** |
|
||
| ⊕ | `ba-traceability` | *Xuyên suốt* | "Có sót yêu cầu nào không?" | `RTM`, báo cáo coverage | Chặn G2–G4 |
|
||
| ⊕ | `ba-design` | *Song song GĐ3 (screen)* | "Giao diện trông thế nào, Dev FE dựng theo gì, Designer sửa ở đâu?" | `DS`, `HIFI`, `FIGMA`, `DSPEC` | Ký cùng G3 |
|
||
|
||
`ba-lifecycle` và `ba-traceability` không phải giai đoạn — chúng chạy **ở mọi lúc**. `ba-design` là **vai Design**
|
||
của bộ skill: chạy sau `wf` của ba-3 khi `PRODUCT = screen`, sinh design system, mockup hi-fi, gói nhập Figma
|
||
(SVG + token + PNG + HTML — không có `.fig`) và redline bàn giao; dự án không có Designer thì nó đóng vai đề xuất, PO ký thay.
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
ROUTER(["ba-lifecycle — router, gọi bất cứ lúc nào"])
|
||
GD1["1 · Discovery"]
|
||
GD2["2 · Analysis"]
|
||
GD3["3 · Specification"]
|
||
GD4["4 · Delivery"]
|
||
GD5["5 · Post-release"]
|
||
RTM(["ba-traceability — RTM cập nhật liên tục"])
|
||
|
||
ROUTER -.-> GD1
|
||
ROUTER -.-> GD5
|
||
GD1 -->|G1| GD2
|
||
GD2 -->|G2| GD3
|
||
GD3 -->|G3| GD4
|
||
GD4 -->|G4| GD5
|
||
GD5 -->|G5| DONE(["Đóng / mở vòng mới"])
|
||
|
||
GD2 -.-> RTM
|
||
GD3 -.-> RTM
|
||
GD4 -.-> RTM
|
||
GD3 -.->|screen, sau wf| DSN(["ba-design — DS · HIFI · FIGMA · DSPEC"])
|
||
DSN -.->|ký cùng G3| GD3
|
||
```
|
||
|
||
---
|
||
|
||
## 2. Cấu trúc thư mục
|
||
|
||
```
|
||
D:\Kakao\Docs\.claude\skills\
|
||
├── README.md ← file này
|
||
├── ba-lifecycle/
|
||
│ ├── SKILL.md ← quy trình cho Claude
|
||
│ ├── GUIDE.md ← hướng dẫn sử dụng cho người
|
||
│ └── references/
|
||
│ ├── domain-profiles.md ← 🔴 ba trục PRODUCT × LIFECYCLE × RIGOR
|
||
│ ├── workflow.md ← 5 gate, tiêu chí pass theo từng mức, ai duyệt
|
||
│ ├── artifact-map.md ← artifact nào ở đâu, tên file, version
|
||
│ ├── writing-rules.md ← 13 quy tắc viết tài liệu BA (bắt buộc mọi skill)
|
||
│ └── diagram-rules.md ← 🔴 mermaid: loại nào dùng khi nào, quy ước, mẫu chuẩn
|
||
├── ba-1-discovery/
|
||
│ ├── SKILL.md · GUIDE.md · examples.md
|
||
│ └── templates/
|
||
├── ba-2-analysis/ … (tương tự)
|
||
├── ba-3-specification/
|
||
│ ├── SKILL.md · GUIDE.md · examples.md
|
||
│ └── templates/
|
||
│ ├── srs.md ← PART 1,3–8 dùng chung mọi loại sản phẩm
|
||
│ ├── srs-part2/ ← 🔴 PART 2 cắm được theo PRODUCT
|
||
│ │ ├── screen.md · api-service.md · data-pipeline.md
|
||
│ │ └── ml-model.md · batch-job.md
|
||
│ ├── acceptance-criteria.md · nfr-checklist.md · api-contract.md
|
||
│ ├── ui-convention.md ← (screen) quy ước UI cấp project, một lần
|
||
│ └── wireframe.md · wireframe.html ← (screen) bố cục từng màn hình + render low-fi, đối chiếu prototype
|
||
├── ba-4-delivery-support/ …
|
||
├── ba-5-post-release/ …
|
||
├── ba-traceability/ …
|
||
└── ba-design/ ← (screen) vai Design: chạy sau wf
|
||
├── SKILL.md · GUIDE.md
|
||
├── templates/ design-system.md · tokens.json (DTCG) · tokens.css · ds-components.css · components.html
|
||
│ hifi.html · design-spec.md · figma-package/{SCR-xx.desktop.svg, README-import.md}
|
||
└── scripts/ design-check.mjs (kiểm token/C-id/text/màu/SVG) · render-figma.sh (chụp PNG bằng Chrome headless)
|
||
```
|
||
|
||
**SKILL.md** = quy trình Claude thực thi, viết trung lập về ngành. **GUIDE.md** = tài liệu
|
||
bạn đọc: khi nào dùng, cần chuẩn bị gì, ví dụ hội thoại, lỗi thường gặp. **examples.md** =
|
||
ví dụ minh hoạ cùng một quy tắc ở nhiều ngành và nhiều loại sản phẩm. **templates/** = khung
|
||
tài liệu để điền.
|
||
|
||
---
|
||
|
||
## 3. Nơi ghi output
|
||
|
||
Mặc định mọi artifact ghi vào thư mục làm việc hiện tại:
|
||
|
||
```
|
||
ba-output/<PROJECT>/
|
||
├── 00-index/ PROFILE, RTM, glossary, decision log, open questions, UICONV (screen), DS + ds/{tokens.json,tokens.css,components.html} (screen)
|
||
├── 01-discovery/ BRIEF, STAKEHOLDER, ELICITATION, RISK
|
||
├── 02-analysis/ PROCESS, BACKLOG, BR, RBAC, IMPACT
|
||
├── 03-specification/ SRS, AC, API, NFR, WF (.md + .html, screen)
|
||
│ └── design/ HIFI_<US>.html, FIGMA_<US>/ (svg, tokens.dtcg.json, png/, README-import.md), DSPEC_<US>.md (screen)
|
||
├── 04-delivery/ QLOG, CR, TCREVIEW, UAT
|
||
└── 05-post-release/ RELNOTE, MANUAL, BENEFIT
|
||
```
|
||
|
||
Muốn nơi khác thì nói rõ khi gọi skill, ví dụ `/ba-1-discovery Settlement --out .docs/output`.
|
||
Skill **luôn hỏi xác nhận đường dẫn trước khi ghi file đầu tiên** của một project mới.
|
||
|
||
### Quy ước đặt tên file
|
||
|
||
```
|
||
<LOẠI>_<PHẠM_VI>_v<major>.<minor>.md
|
||
```
|
||
|
||
`BRIEF_Settlement_v1.0.md` · `SRS_US059_v1.2.md` · `CR_US059-003_v1.0.md`
|
||
|
||
Sửa nhỏ `+0.1`, tái cấu trúc `+1.0`. Mọi file có Change Log ở đầu. Không bao giờ ghi đè
|
||
mất version cũ — bản cũ chuyển vào `archive/`.
|
||
|
||
---
|
||
|
||
## 4. Quy ước ID (dùng chung toàn bộ skill)
|
||
|
||
| Tiền tố | Nghĩa | Sinh ở giai đoạn |
|
||
|---|---|---|
|
||
| `STK-nn` | Stakeholder | 1 |
|
||
| `GOAL-nn` | Mục tiêu kinh doanh + KPI | 1 |
|
||
| `RQ-nnn` | Yêu cầu mức nghiệp vụ | 1 |
|
||
| `RISK-nn` | Rủi ro | 1 |
|
||
| `ASM-nn` | Giả định | 1 |
|
||
| `PRC-nn` | Quy trình nghiệp vụ | 2 |
|
||
| `US-nnn` | User story | 2 |
|
||
| `BR-nnn` | Business rule | 2 |
|
||
| `ROLE-nn` | Vai trò trong RBAC | 2 |
|
||
| `AC-<US>-nn` | Acceptance criteria | 3 |
|
||
| `FLD-<màn>-nn` | Field spec | 3 |
|
||
| `NFR-<nhóm>-nn` | Yêu cầu phi chức năng | 3 |
|
||
| `E-<DOMAIN>-nnnn` | Mã lỗi | 3 |
|
||
| `OQ-nnn` | Open question | mọi giai đoạn |
|
||
| `DEC-nn` | Quyết định đã chốt | mọi giai đoạn |
|
||
| `CR-nnn` | Change request | 4 |
|
||
|
||
ID **không bao giờ tái sử dụng**. Yêu cầu bị bỏ ⇒ đánh dấu `[DROPPED]`, giữ nguyên số.
|
||
|
||
---
|
||
|
||
## 5. Cách gọi
|
||
|
||
```
|
||
/ba-lifecycle Settlement # xem đang ở đâu, nên làm gì tiếp
|
||
/ba-1-discovery Settlement # chạy giai đoạn 1
|
||
/ba-2-analysis US059 # phân tích một US
|
||
/ba-3-specification US059 # viết SRS
|
||
/ba-4-delivery-support US059 # xử lý câu hỏi dev / CR / UAT
|
||
/ba-5-post-release Settlement 2026-09 # review sau release
|
||
/ba-traceability Settlement # kiểm tra coverage, tìm yêu cầu bị sót
|
||
/ba-design Settlement ds # (screen) design system một lần cho project
|
||
/ba-design US059 hifi # (screen) mockup hi-fi sau khi WF xong; rồi figma, dspec
|
||
```
|
||
|
||
Không nhớ tên skill thì cứ mô tả việc cần làm — skill tự kích hoạt theo mô tả.
|
||
|
||
**Mọi skill đều có Bước 0 "chốt input rồi dừng"**: liệt kê input tìm được, nêu input còn
|
||
thiếu, tóm tắt cách hiểu, rồi *chờ bạn xác nhận* mới làm. Thêm chữ `go` vào lệnh để bỏ
|
||
bước dừng — khi đó phần tự đánh giá input được ghi thẳng vào mục Open Questions.
|
||
|
||
---
|
||
|
||
## 6. Quan hệ với bộ `ba:*` của berriz-platform-docs
|
||
|
||
Hai bộ **không thay thế nhau**:
|
||
|
||
| | Bộ này (`ba-*`) | Bộ `ba:*` trong `berriz-platform-docs` |
|
||
|---|---|---|
|
||
| Phạm vi | Chung cho mọi dự án | Riêng dự án Berriz, gắn với `.agents/ba_rules.md` |
|
||
| Trọng tâm | Toàn bộ nghề BA, kể cả elicitation/UAT/post-release | Pipeline tài liệu Berriz (brainstorm→blueprint→wbs→srs→deck) |
|
||
| Output | `ba-output/` | `.docs/output/` |
|
||
|
||
Đang làm Berriz thì dùng `ba:*` cho pipeline tài liệu. Bộ này bổ khuyết những phần
|
||
`ba:*` không có: khai thác yêu cầu, phân tích tác động, quản lý CR, UAT, đo hiệu quả.
|
||
Ánh xạ chi tiết: `ba-lifecycle/references/workflow.md` §6.
|
||
|
||
---
|
||
|
||
## 6b. Sơ đồ trong tài liệu — chuẩn Archify
|
||
|
||
Mọi sơ đồ của bộ BA (và bộ SA, SAD) tuân **tiêu chuẩn và phong cách [Archify](https://github.com/tt-a1i/archify)**
|
||
(gói MIT đã nhúng ở `archify/`, không cần cài thêm). Toàn bộ quy tắc ở
|
||
[`ba-lifecycle/references/diagram-rules.md`](ba-lifecycle/references/diagram-rules.md). Ba câu chốt:
|
||
|
||
1. **Một sơ đồ = spec JSON Archify + mermaid trong `.md` + bảng đi kèm.** Spec
|
||
(`diagrams/<ARTIFACT>_<slug>.<type>.json`, `quality_profile: showcase`) là nguồn sự thật về topology;
|
||
mermaid có marker `<!-- archify: <type> · <spec> -->` là bản chiếu để GitHub/Confluence render và
|
||
`git diff` đọc được; bảng để truy vết và test (W13).
|
||
2. **Một đường chính, ≤ 12 node, nhãn cạnh là điều kiện/giao thức/sync-async, không màu.** Quá 12 node
|
||
⇒ tách sơ đồ.
|
||
3. **Kiểm bằng máy:** `archify validate … --quality showcase` 0 lỗi, rồi
|
||
`node .claude/skills/ba-lifecycle/scripts/diagram-check.mjs --md <artifact>` xanh trước khi trình gate.
|
||
|
||
| Sơ đồ | Loại Archify | Mermaid | Sinh ở |
|
||
|---|---|---|---|
|
||
| Ranh giới hệ thống | `architecture` | `flowchart LR` + `subgraph` | `BRIEF` §5.3 |
|
||
| Quy trình AS-IS / TO-BE | `workflow` | `flowchart TD` | `PROCESS` A1, B1 |
|
||
| Vòng đời trạng thái | `lifecycle` | `stateDiagram-v2` | `BR` §3 |
|
||
| Điều hướng màn hình | `workflow` | `flowchart LR` | `srs-part2/screen` §2.2 |
|
||
| **Sequence** *(có nhánh lỗi)* | `sequence` | `sequenceDiagram` | `srs-part2/screen` §2.3.4, `api-service` §2.3 |
|
||
| Data lineage | `dataflow` | `flowchart LR` | `srs-part2/data-pipeline` §2.2 |
|
||
| Phụ thuộc job | `workflow` | `flowchart LR` | `srs-part2/batch-job` §2.2 |
|
||
| Phân loại Defect/CR/Spec gap | `workflow` | `flowchart TD` | `CR` §0 |
|
||
| Use case · cây RQ→US · 5-Why · ERD khái niệm · ma trận 2×2 | `mermaid-only` | `flowchart` · `erDiagram` · `quadrantChart` | `BACKLOG` §0–§1 · `ELICITATION` §A9 · `BR` §4 · `STAKEHOLDER` §2 |
|
||
|
||
Spec mẫu đã validate pass: `ba-2-analysis/templates/diagrams/` (workflow, lifecycle),
|
||
`ba-3-specification/templates/diagrams/` (dataflow), `sa-2-architecture/templates/diagrams/` (architecture, sequence).
|
||
|
||
**Không thuộc phạm vi BA:** C4, ADR, class diagram (`DOM`), threat model, schema vật lý + DDL/migration (`PDM`),
|
||
file OpenAPI/AsyncAPI (`CTR`) — đó là việc của Solution Architect, làm bằng bộ `sa-*` (xem §6c).
|
||
|
||
## 6c. Quan hệ với bộ skill SA (`sa-*`)
|
||
|
||
Bộ `sa-*` ([README-SA.md](README-SA.md)) làm phần kiến trúc kỹ thuật. Hai bộ **chạy đan xen**,
|
||
không nối tiếp:
|
||
|
||
| Mốc của bộ BA | Cần bộ SA đã qua | Vì sao |
|
||
|---|---|---|
|
||
| **G2** Solution sign-off | **AG1** | Tech Lead ký "khả thi kỹ thuật" dựa trên `OPT` + `ARISK` của SA |
|
||
| **G3** Ready for Dev | **AG2** | `API` trong SRS phải khớp `ICD`; `NFR` phải khớp `QAS` |
|
||
| **G4** UAT pass | **AG3** | UAT không nên chạy trên kiến trúc chưa đo được NFR |
|
||
| **G5** Benefit review | **AG4** | Đo hiệu quả nghiệp vụ đi cùng conformance kỹ thuật |
|
||
|
||
Bốn chỗ hai bộ giao nhau, và bên nào thắng khi lệch:
|
||
|
||
| Artifact BA | Artifact SA | Thắng khi lệch |
|
||
|---|---|---|
|
||
| `NFR` | `QAS` | **`QAS`** — BA ghi nhu cầu, SA chốt con số và cách đo |
|
||
| `API` (BA đề xuất, "chờ BE xác nhận") | `ICD` → `CTR` (file OpenAPI/AsyncAPI) | **File contract trong `CTR`** — SA xác nhận qua `ICD` rồi sinh file; `API` ghi `operationId` |
|
||
| `SRS` PART 2 bảng field `FLD-*` | `PDM` (schema vật lý) | Cùng kiểu/độ dài/null — lệch ⇒ `OQ`, không im lặng chọn một bên |
|
||
| `BR` ràng buộc dữ liệu / tính toán | `DOM` (domain model) | `BR` là nguồn; `DOM` nói invariant sống ở class nào |
|
||
| `RBAC` | `SEC` §3.1 | Bổ sung nhau — `SEC` map vai trò nghiệp vụ xuống cơ chế kỹ thuật |
|
||
| `BR` ép ràng buộc kiến trúc | `ADR` | `BR` là nguồn, `ADR` là quyết định |
|
||
|
||
🔴 **Không copy nội dung giữa hai bộ** — tham chiếu bằng đường dẫn + ID. Copy là cách chắc chắn
|
||
nhất để hai tài liệu lệch nhau sau ba lần sửa.
|
||
|
||
Ánh xạ chi tiết: [`sa-lifecycle/references/artifact-map.md`](sa-lifecycle/references/artifact-map.md) §7.
|
||
|
||
## 6d. Bộ BA thay được bao nhiêu phần việc design?
|
||
|
||
Chỉ áp dụng khi `PRODUCT = screen`. Hai artifact `UICONV` (quy ước toàn project) và `WF`
|
||
(bố cục từng màn hình, `.md` + `.html` low-fi) được thiết kế để **nhận prototype làm đầu vào
|
||
tham chiếu**:
|
||
|
||
| Đầu vào có sẵn | BA làm được | Design còn phải làm |
|
||
|---|---|---|
|
||
| Prototype đã duyệt + design system | Ghi lại bố cục, map thành phần, đối chiếu với SRS, liệt kê lệch (`WF` §5) — dev dựng UI từ SRS + WF + design system | Xử lý các dòng lệch ở `WF` §5 |
|
||
| Prototype đã duyệt, chưa có design system | Như trên | Chọn/dựng design system, visual |
|
||
| Chỉ có mô tả UI dạng văn bản (SAD §7) | Bố cục mức vùng; thứ tự, kích thước là đề xuất | Duyệt WF, làm visual |
|
||
| Không có gì | `WF` chế độ ✏️ — **đề xuất của BA**, Designer bắt buộc ký | Thiết kế bố cục thật hoặc duyệt đề xuất, rồi visual |
|
||
|
||
BA **không bao giờ** làm visual (màu, font, icon, motion). Designer là người ký `UICONV` và
|
||
`WF` ở G3; dự án không có Designer ⇒ PO ký thay và ghi `DEC-nn`.
|
||
|
||
## 7. Phạm vi áp dụng — cái gì chuyển được, cái gì không
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Ngành nghiệp vụ** | ✅ Chuyển được nguyên vẹn. Ví dụ trong `examples.md` cố tình trải trên nhiều ngành để chứng minh điều đó |
|
||
| **Loại sản phẩm** | ✅ Sáu loại có sẵn qua `PRODUCT`. Loại khác cần viết thêm biến thể PART 2 |
|
||
| **Nhúng / IoT / firmware** | 🔴 **Chưa hỗ trợ.** GĐ1, GĐ2, GĐ4, GĐ5 dùng được; PART 2 của GĐ3 phải tự viết (NFR khác hẳn: điện năng, nhiệt độ, thời gian thực cứng). Skill sẽ nói rõ điều này thay vì nhét vào biến thể gần đúng |
|
||
| **Không phải phần mềm** | ✅ Dùng `PRODUCT = process-only` — GĐ3 gần như bỏ, trọng tâm ở `PROCESS` và `MANUAL` |
|
||
|
||
## 8. Nguyên tắc bất di bất dịch
|
||
|
||
Bốn quy tắc này ghi trong mọi SKILL.md và không skill nào được vi phạm:
|
||
|
||
1. **Không bịa yêu cầu.** Thông tin thiếu ⇒ ghi `OQ-nnn`, không tự điền giá trị hợp lý.
|
||
2. **Không quyết định thay PO.** Ưu tiên, scope, trade-off nghiệp vụ là việc của PO — BA
|
||
trình phương án kèm khuyến nghị, không tự chốt.
|
||
3. **Mọi phát biểu phải truy vết được.** Mỗi dòng trong SRS chỉ về một `RQ`/`BR`/`DEC`
|
||
hoặc một câu trả lời của stakeholder. Không nguồn ⇒ là giả định, phải ghi `ASM-nn`.
|
||
4. **Không ghi đè tài liệu đã ký.** Tài liệu qua gate chỉ được sửa qua `CR-nnn` có Change Log.
|