# Hướng dẫn sử dụng — Bộ skill SAD (System Analysis & Design)

Tài liệu này giới thiệu và hướng dẫn sử dụng toàn bộ hệ thống skill/agent/workflow đã xây dựng trong dự án, dùng để đi từ **một mô tả dự án còn sơ sài** đến **tài liệu phân tích thiết kế hệ thống (SAD)**, rồi từ SAD ra **proposal gửi khách hàng**, **hồ sơ dự thầu hoàn chỉnh (kèm slide và PDF)**, và (khi cần đặc tả sâu tới mức code/test được) **quy trình BA/SA có gate ký duyệt**.

Đối tượng đọc: bất kỳ ai vận hành Claude Code trong dự án này (bạn, hoặc đồng nghiệp kế nhiệm) và cần biết gọi skill nào, theo thứ tự nào, cần chuẩn bị gì trước.

---

## 1. Triết lý thiết kế — đọc trước khi dùng

Toàn bộ hệ thống tuân theo 5 nguyên tắc xuyên suốt. Hiểu 5 nguyên tắc này quan trọng hơn nhớ tên từng agent:

1. **Một stage/agent = một trách nhiệm.** Không agent nào vừa viết nội dung vừa tính toán vừa duyệt. Ví dụ: `bid-estimator` chỉ ước lượng, không cộng tổng; workflow tính tổng bằng code thuần; `bid-reviewer` chỉ đọc và chấm, không sửa.
2. **Con số quan trọng không do LLM tính.** Effort (MM), chi phí, timeline, headcount trong hồ sơ thầu được tính bằng JavaScript thuần trong workflow, từ dữ liệu thô do agent cung cấp. LLM không cộng, không quy đổi, không làm tròn — tránh sai số cộng dồn và đảm bảo tái lập được.
3. **Có cổng phê duyệt giữa các bước (stage-gated).** Không skill nào chạy toàn bộ pipeline một lần không dừng (trừ khi bạn chủ động chọn chế độ `all` và được cảnh báo rõ). Mỗi bước dừng lại, trình bày kết quả trung thực, và chờ bạn **Duyệt / Sửa / Dừng**.
4. **Thiếu thông tin → hỏi hoặc để placeholder, không bịa.** Số liệu chưa có (đơn giá, ngày, tên người, chứng chỉ) luôn hiện dưới dạng `[[CẦN ĐIỀN: ...]]` hoặc `null`, không bao giờ được điền giá trị "nghe hợp lý".
5. **Tài liệu nội bộ và tài liệu gửi ra ngoài tách biệt tuyệt đối.** SAD, ghi chú rà soát, mã yêu cầu nội bộ (FR/NFR/OQ...) không bao giờ lọt vào proposal hay hồ sơ thầu — có agent `reviewer` chuyên rà soát rò rỉ trước khi bàn giao.

---

## 2. Bản đồ toàn hệ thống

```mermaid
flowchart TD
    BRIEF["Ý tưởng / mô tả dự án\n(có thể rất sơ sài)"] --> SADP["/sad-pipeline/\nintake → requirements → architecture\n→ (api ∥ data ∥ uiux) → detailed\n→ security → testops → consolidate"]
    SADP --> SAD["docs/SAD.md\n(tài liệu SAD đã duyệt)"]

    SAD --> PROP["/sad-proposal/\ncontent → build → review"]
    PROP --> PROPOUT["docs/proposal/\nindex.html · artifact.html"]

    SAD --> BID["/sad-bid/\nintake → technical → estimate → plan\n→ financial → assemble → deck → export → review"]
    BID --> BIDOUT["bid/\nHO-SO-THAU.pdf · deck.pdf"]

    SAD -.seed & đối chiếu.-> BAP["/ba-pipeline/\ndiscovery → analysis → specification\n→ delivery → post-release"]
    SAD -.seed & đối chiếu.-> SAP["/sa-pipeline/\ncontext → architecture → enablement → evolution"]
    BAP <-.NFR↔QAS · API↔ICD· RBAC↔SEC.-> SAP
    BAP --> DEVREADY["Đặc tả dev-ready\n(SRS, AC, mã lỗi, ADR, threat model...)"]
    SAP --> DEVREADY
```

Bốn nhánh **độc lập với nhau**, đều xuất phát từ `docs/SAD.md`:

| Nhánh | Trả lời câu hỏi | Dùng khi |
|---|---|---|
| **sad-pipeline** | "Hệ thống này thiết kế như thế nào?" | Luôn chạy đầu tiên — mọi nhánh khác cần `docs/SAD.md` |
| **sad-proposal** | "Trình bày giải pháp cho khách hàng thế nào?" | Cần gửi đề xuất giải pháp (presales), chưa chắc đã thắng thầu |
| **sad-bid** | "Hồ sơ dự thầu đầy đủ, có giá, có kế hoạch, nộp được chưa?" | Có gói thầu cụ thể cần nộp hồ sơ (có/không có HSMT) |
| **ba-pipeline / sa-pipeline** | "Dev/QA có đủ đặc tả để code/test mà không phải hỏi lại không?" | SAD chỉ là thiết kế mức cao (HLD) — cần đặc tả sâu trước khi giao dev |

---

## 3. Cấu trúc thư mục dự án

```
sys-analysis-design/
├── introduction.md              # khung 10 mục chuẩn của tài liệu SAD (tài liệu tham chiếu gốc)
├── HUONG-DAN-SU-DUNG.md         # chính là tài liệu này
├── docs/
│   ├── 00-project-brief.md      # do intake-analyst duy trì (brief + Q&A + profile + giả định)
│   ├── sections/01-…09-*.md     # 9 mục SAD, mỗi mục có frontmatter status/version
│   ├── SAD.md                   # bản ráp hoàn chỉnh (do doc-consolidator sinh)
│   └── proposal/                # output của sad-proposal
│       ├── proposal-config.md   # thông tin thương mại (khách hàng, giá, brand...)
│       ├── proposal-content.md
│       ├── index.html / artifact.html
├── bid/                          # output của sad-bid
│   ├── inputs/                  # HSMT/RFP nếu có
│   ├── bid-config.md            # rate card, VAT, deadline, hồ sơ năng lực...
│   ├── 00-…40-*.md, estimate.json, estimate.computed.json
│   ├── HO-SO-THAU.md / .pdf, index.html
│   └── deck.html / deck.pdf
├── ba-output/<PROJECT>/          # output của ba-pipeline (theo chuẩn ba-lifecycle)
├── sa-output/<PROJECT>/          # output của sa-pipeline (theo chuẩn sa-lifecycle)
└── .claude/
    ├── agents/                  # 24 subagent (xem mục 7)
    ├── workflows/                # 5 workflow (generate-sad.js, generate-proposal.js, generate-bid.js, ba-pipeline.js, sa-pipeline.js)
    └── skills/
        ├── sad-pipeline/, sad-proposal/, sad-bid/   # 3 skill điều phối do ta xây
        ├── ba-pipeline/, sa-pipeline/                # 2 skill điều phối (lớp gate) cho BA/SA
        └── ba-1…5-*, ba-lifecycle, ba-traceability,  # bộ skill BA/SA gốc (đã có sẵn, không sửa)
            sa-1…4-*, sa-lifecycle, sa-conformance
```

**docs/**, **bid/**, **ba-output/**, **sa-output/** đều **chưa tồn tại** — sẽ được tạo ở lần chạy đầu tiên.

---

## 4. Trước khi bắt đầu — 2 điều cần biết

### 4.1 Reload phiên sau khi thêm/sửa agent
Registry của Claude Code chỉ nạp `.claude/agents/*.md` **lúc phiên khởi động**. Sau bất kỳ lần agent mới được tạo (hoặc bạn tự sửa file agent), phải **khởi động lại phiên** (VS Code: `Ctrl+Shift+P` → *Developer: Reload Window*; CLI: thoát và mở lại `claude`) trước khi gọi agent đó — nếu không sẽ gặp lỗi `Agent type 'x' not found`. Skill và workflow thì **không cần reload**, nhận diện ngay.

### 4.2 Xuất PDF dùng trình duyệt sẵn có, không cần cài gì
Máy không có `pandoc`/`mermaid-cli`. Việc xuất PDF (proposal, hồ sơ thầu, slide) dùng **Microsoft Edge/Chrome ở chế độ headless** đã có sẵn trên máy — `bid-exporter` tự gọi, không cần bạn cài thêm phần mềm. Nếu chạy trên máy khác không có trình duyệt Chromium, agent sẽ báo `blocked` kèm hướng dẫn in thủ công (mở HTML → Ctrl+P → Save as PDF).

---

## 5. Hướng dẫn từng skill

### 5.1 `/sad-pipeline` — Sinh tài liệu SAD

**Khi nào dùng:** luôn là bước đầu tiên, khi có một ý tưởng/mô tả dự án cần chuyển thành SAD.

**8 stage** (mỗi lần gọi workflow là 1 stage, đều cần bạn duyệt trước khi sang stage kế):

| Stage | Agent | Việc chính |
|---|---|---|
| `intake` | `intake-analyst` | Đánh giá độ đủ thông tin của brief, đề xuất mô hình tham chiếu theo domain, hỏi tối đa 4 câu/vòng (≤3 vòng), ghi `docs/00-project-brief.md` |
| `requirements` | `requirements-analyst` | Mục 1–2: tổng quan, FR/NFR (mã FR-xx), use case, traceability |
| `architecture` | `architecture-designer` | Mục 3: kiến trúc, deployment, environment, tích hợp bên thứ ba |
| `fanout` | `api-designer` ∥ `data-modeler` ∥ `uiux-designer` | Mục 4/5/7 chạy **song song** vì độc lập nhau |
| `detailed` | `detailed-designer` | Mục 6: sequence/class/state diagram, business rule |
| `security` | `security-architect` | Mục 8: rà soát chéo bảo mật trên toàn bộ thiết kế |
| `testops` | `test-ops-planner` | Mục 9: test strategy, test case, CI/CD, monitoring, rollback/DR |
| `consolidate` | `doc-consolidator` | Mục 0 + ráp `docs/SAD.md` + kiểm tra nhất quán/traceability toàn tài liệu |

**Cách gọi mẫu (qua skill, không tự gọi Workflow trực tiếp):**
```
Dùng skill sad-pipeline để bắt đầu phân tích thiết kế cho: "<mô tả dự án>"
```
Claude sẽ tự chạy `intake`, hỏi bạn nếu thiếu thông tin, rồi lần lượt qua các stage, mỗi stage trình bày kết quả và hỏi Duyệt/Sửa/Dừng.

**Chế độ `all`:** workflow hỗ trợ chạy liền không dừng (không khuyến khích) — chỉ dùng khi bạn nói rõ "chạy hết không cần duyệt từng bước", có cảnh báo không kiểm soát trung gian.

---

### 5.2 `/sad-proposal` — Proposal gửi khách hàng

**Khi nào dùng:** sau khi `docs/SAD.md` đã có, cần bản trình bày giải pháp thuyết phục khách hàng (chưa chắc là hồ sơ thầu chính thức).

**3 stage:** `content` (`proposal-writer` — viết nội dung presales, loại bỏ mọi thông tin nội bộ) → `build` (`proposal-builder` — dựng `index.html` độc lập + `artifact.html` để publish Artifact xem trực quan) → `review` (`proposal-reviewer` — rà rò rỉ nội bộ, đối chiếu trung thực với SAD, kiểm chất lượng HTML).

**Thông tin cần chuẩn bị trước:** tên khách hàng, đơn vị đề xuất, ngày, mô hình giá — điền vào `docs/proposal/proposal-config.md` (skill sẽ hỏi và tạo giúp nếu chưa có).

**Chỉ được gọi là "gửi được"** khi `review` trả `canSend = true` (không leak, không placeholder còn sót).

---

### 5.3 `/sad-bid` — Hồ sơ dự thầu hoàn chỉnh

**Khi nào dùng:** có gói thầu cụ thể (có hoặc không có HSMT/RFP) cần nộp hồ sơ đầy đủ pháp lý + kỹ thuật + tài chính.

**9 stage:**

| Stage | Agent | Việc chính |
|---|---|---|
| `intake` | `bid-analyst` | Đọc HSMT (nếu có), lập bid-brief, **ma trận đáp ứng yêu cầu**, checklist tài liệu Phần A |
| `technical` | `bid-technical-writer` | Phần B: danh mục chức năng, sơ đồ hoạt động, tech stack, bảo mật, phương pháp luận (không có số MM/chi phí) |
| `estimate` | `bid-estimator` + **code tính** | WBS bottom-up + Use Case Points đối chiếu → workflow tính MD/MM/dự phòng/chi phí/timeline/staffing bằng JS thuần, ghi `bid/estimate.computed.json` |
| `plan` | `bid-planner` | B7 (Gantt ngày thật, mốc, tiêu chí nghiệm thu) + B8 (tổ chức nhân sự, staffing theo tháng) — số liệu lấy nguyên từ computed |
| `financial` | `bid-financial-writer` | Phần C: bảng effort, đơn giá, tổng giá trước/sau VAT, mốc thanh toán — không tính lại |
| `assemble` | `bid-builder` | Ráp `bid/HO-SO-THAU.md` + `bid/index.html` (A4, có bookmark/số trang khi in) |
| `deck` | `bid-deck-builder` | `bid/deck.html` — 15–25 slide 16:9 tự chứa cho buổi thuyết trình thầu |
| `export` | `bid-exporter` | Dùng Edge/Chrome headless in ra **`HO-SO-THAU.pdf`** và **`deck.pdf`**, kiểm Mermaid đã render, kiểm số trang |
| `review` | `bid-reviewer` | 6 lăng kính: đủ mục, đáp ứng yêu cầu bắt buộc, **số liệu khớp computed**, không rò rỉ, khả thi, chất lượng PDF/deck |

**Thông tin cần chuẩn bị trước** (điền `bid/bid-config.md`): rate card theo vai trò, VAT, deadline nộp/deadline thực hiện, chi phí phi nhân công đã biết, hồ sơ năng lực công ty sẵn có (`companyDocs`).

**Chỉ nộp khi** `review` trả `canSubmit = true`.

---

### 5.4 `/ba-pipeline` và `/sa-pipeline` — Đặc tả dev-ready + kiến trúc chi tiết

**Khi nào dùng:** SAD chỉ là thiết kế mức cao (HLD). Trước khi giao dev/QA thi công, cần đặc tả sâu hơn: bảng field, Acceptance Criteria 4 nhóm, mã lỗi, C4 diagram, threat model STRIDE, ADR... Đây là lớp **cổng phê duyệt (gate)** bọc quanh bộ skill BA/SA gốc đã có sẵn (`ba-1…5-*`, `sa-1…4-*`) — bộ gốc không bị sửa, chỉ được điều phối chặt chẽ hơn.

**Nguyên tắc chung của cả hai:** một lần gọi = một `stage` hoặc một `activity` cụ thể (không có chế độ chạy liền); mọi output có header chuẩn (`Version · Status · Approved by`); **agent không bao giờ tự đánh dấu ✅/🔵** — chỉ con người ký qua stage `sign`, có `role` đúng quy định (VD Gate G3 của BA cần PO + Tech Lead + QA; Gate AG2 của SA cần Tech Lead + Security + Ops/SRE).

| | `ba-pipeline` | `sa-pipeline` |
|---|---|---|
| Giai đoạn | discovery → analysis → specification → delivery → post-release | context → architecture → enablement → evolution |
| Gate | G1…G5 | AG1…AG4 |
| Auditor (chỉ đọc, chấm gate) | `ba-gate-auditor` | `sa-gate-auditor` |
| Runner (thực thi 1 activity) | `ba-stage-runner` | `sa-stage-runner` |
| Output | `ba-output/<PROJECT>/` | `sa-output/<PROJECT>/` |

**Liên kết BA ↔ SA:** Gate G2 của BA cần Gate AG1 của SA đã qua (Tech Lead ký "khả thi" dựa trên phương án kiến trúc). `QAS`/`ICD`/`SEC` của SA "thắng" `NFR`/`API`/`RBAC` do BA đề xuất — khi có lệch, quay lại BA sửa `specification` với ghi chú tương ứng.

**Đọc thêm:** `.claude/skills/README-BA.md` và `README-SA.md` giải thích chi tiết triết lý của hai bộ skill gốc (PROFILE 3 trục PRODUCT×LIFECYCLE×RIGOR, hệ ID RQ/BR/ADR/OQ...) — nên đọc trước khi dùng `ba-pipeline`/`sa-pipeline` lần đầu.

---

## 6. Kịch bản sử dụng đầu-cuối (ví dụ điển hình)

```
1. "Dùng sad-pipeline, tôi cần thiết kế hệ thống cho <ý tưởng>"
   → intake hỏi vài câu → requirements → architecture → fanout → detailed
   → security → testops → consolidate → có docs/SAD.md

2a. Cần trình bày cho khách hàng ngay:
    "Dùng sad-proposal để làm proposal từ SAD này"
    → content → build → review → docs/proposal/index.html

2b. Có gói thầu cụ thể cần nộp:
    "Dùng sad-bid, gói thầu <tên>, đây là HSMT..."
    → intake → technical → estimate (điền rate card khi được hỏi)
    → plan → financial → assemble → deck → export → review
    → bid/HO-SO-THAU.pdf + bid/deck.pdf

3. Trước khi giao dev, cần đặc tả sâu hơn:
   "Dùng ba-pipeline cho project <tên>, bắt đầu discovery"
   "Dùng sa-pipeline cho project <tên>, bắt đầu context"
   → lặp qua các gate, ký duyệt, tới khi Gate G3/AG2 (Ready for Dev/Build)
```

Ba nhánh 2a/2b/3 **độc lập**, có thể chạy song song hoặc chỉ chọn nhánh cần.

---

## 7. Bảng tổng hợp toàn bộ agent (24 agent, theo pipeline)

| Pipeline | Agent |
|---|---|
| sad-pipeline | `intake-analyst` · `requirements-analyst` · `architecture-designer` · `api-designer` · `data-modeler` · `uiux-designer` · `detailed-designer` · `security-architect` · `test-ops-planner` · `doc-consolidator` |
| sad-proposal | `proposal-writer` · `proposal-builder` · `proposal-reviewer` |
| sad-bid | `bid-analyst` · `bid-technical-writer` · `bid-estimator` · `bid-planner` · `bid-financial-writer` · `bid-builder` · `bid-deck-builder` · `bid-exporter` · `bid-reviewer` |
| ba-pipeline / sa-pipeline | `ba-stage-runner` · `ba-gate-auditor` · `sa-stage-runner` · `sa-gate-auditor` |

---

## 8. Trạng thái hiện tại & giới hạn đã biết

Trung thực về những gì **chưa** được kiểm chứng:

- Toàn bộ logic điều phối (thứ tự stage, truyền dữ liệu, tính toán số học ước lượng) đã được **kiểm thử bằng script mô phỏng** (stub test), **chưa chạy end-to-end với agent thật** trên một dự án hoàn chỉnh.
- Việc xuất PDF bằng Edge headless đã kiểm chứng thật trên máy này (render Mermaid, in ra PDF có outline) với 1 file mẫu nhỏ — chưa thử với hồ sơ dài thật.
- `ba-pipeline`/`sa-pipeline` mới build lớp điều phối; chưa chạy thử với dữ liệu SAD thật để xem chất lượng seed/đối chiếu ra sao.
- Máy không có `poppler` nên không tự xem trước nội dung PDF bằng công cụ — cần bạn mở file kiểm tra bằng mắt ở lần chạy đầu.

Khi có bản chạy thật đầu tiên, nên lưu lại nhận xét (đặc biệt về estimate/deck) để tinh chỉnh agent nếu cần.