# 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_.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 ` 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// ├── 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_.html, FIGMA_/ (svg, tokens.dtcg.json, png/, README-import.md), DSPEC_.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 ``` __v..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--nn` | Acceptance criteria | 3 | | `FLD--nn` | Field spec | 3 | | `NFR--nn` | Yêu cầu phi chức năng | 3 | | `E--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/_..json`, `quality_profile: showcase`) là nguồn sự thật về topology; mermaid có marker `` 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 ` 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.