Files

Canhchimlac 51506aabc7 update skill and docs

2026-09-22 13:46:36 +07:00

18 KiB

Raw Permalink Blame History

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:

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.
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.
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.
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ý".
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

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>/`

Lớp bàn giao dev (mới): sa-2 có thêm ba activity dom (class diagram theo bounded context), ctr (file OpenAPI 3.1/AsyncAPI 3.0 thật trong 02-architecture/contracts/, thắng mọi bảng mô tả API) và pdm (schema vật lý đủ cột + DDL/migration có rollback trong 02-architecture/schema/); sa-3 có handoff (gói bàn giao dev: mục lục đường dẫn thật + checklist đủ/thiếu + dev ký đã nhận, chạy ngay khi AG2 ký). AG2 chặn khi còn "contract dự kiến" hoặc thực thể chưa có bảng. Kiểm bằng máy: sa-2-architecture/scripts/contract-check.mjs, sa-3-enablement/scripts/handoff-check.mjs.

Sơ đồ — chuẩn Archify (mọi pipeline): mỗi sơ đồ = spec JSON Archify (diagrams/*.<type>.json, quality_profile: showcase, archify validate 0 lỗi) + mermaid có marker  + bảng đi kèm; SAD-pipeline ghi spec vào docs/diagrams/, proposal/bid nhúng <svg> từ HTML Archify đã deliver thay vì render lại Mermaid. Gói Archify đã nhúng ở .claude/skills/archify/; quy tắc ở ba-lifecycle/references/diagram-rules.md; kiểm bằng ba-lifecycle/scripts/diagram-check.mjs.

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.

18 KiB Raw Permalink Blame History Unescape Escape