Bộ 11 skill vẽ Diagram: Dùng cả workflow để tài liệu hoá một feature thanh toán QR

Vẽ sơ đồ nghiệp vụ (use case, sequence, activity, ERD, BPMN…) là việc quen thuộc của BA và PM — nhưng ngồi nhớ cú pháp Mermaid/PlantUML/D2/BPMN thì mất thời gian và dễ sai. Diagram Skills Package là một bộ 11 skill giúp bạn chỉ cần mô tả nghiệp vụ bằng lời, skill sẽ hỏi lại chỗ thiếu, chọn đúng loại sơ đồ, sinh code, tự kiểm lỗi cú pháp rồi render ra ảnh.

Điểm hay không nằm ở một skill lẻ, mà ở chỗ dùng nhiều skill nối tiếp nhau theo một workflow để ra trọn bộ tài liệu sơ đồ cho một tính năng. Bài này minh hoạ đúng điều đó: đi lần lượt qua cả 11 skill, mỗi skill nêu cách gọi (mẫu lệnh chung) và kết quả minh hoạ bằng một feature ví dụ — Thanh toán QR VNPAY.

Lưu ý: đây là bộ skill cho Claude Code (và bản port cho Codex CLI, Google Antigravity), chạy trong workspace của bạn — khác với skill upload vào Claude Desktop. Cách cài xem ở cuối bài.

Feature ví dụ: Thanh toán QR VNPAY

Kịch bản: khách hàng quét mã QR của merchant để thanh toán; hệ thống VNPAY gọi ngân hàng trừ tiền, ghi nhận giao dịch và báo merchant. Có nhánh lỗi (số dư không đủ) và quy trình hoàn tiền qua CSKH và Kế toán. Toàn bộ sơ đồ dưới đây được các skill sinh ra cho chính feature này.

Workflow đi theo 6 nhóm: xác định phạm vi → mô tả luồng → vòng đời trạng thái → mô hình dữ liệu → kiến trúc → chuẩn hoá quy trình.

Cách gọi skill — mẫu chung

Mọi skill trong bộ đều gọi theo cùng một mẫu:

text

/<tên-skill> "<mô tả nghiệp vụ bằng lời>" --feature <tên-feature>

Sau khi gọi, skill làm việc theo cùng một luồng: hỏi lại những chỗ còn thiếu (bằng ngôn ngữ nghiệp vụ, không hỏi cú pháp) → cho xem kế hoạch ghi file để bạn duyệt (gõ Y) → rồi mới sinh sơ đồ, tự kiểm lỗi cú pháp và render. Skill không tự ghi file khi bạn chưa duyệt.

Ở mỗi skill bên dưới, phần lệnh chỉ nêu mẫu chung; phần kết quả minh hoạ bằng chính feature Thanh toán QR VNPAY để bạn thấy đầu ra thực tế.

Nhóm 1 — Xác định phạm vi hệ thống

1. /usecase-diagram — Use case diagram

Bắt đầu một feature, câu hỏi đầu tiên là: ai dùng, dùng để làm gì? Skill này vẽ use case diagram (actor + use case), hợp cho buổi kickoff và chốt phạm vi.

text

/usecase-diagram "<tên & phạm vi hệ thống>" --feature <tên-feature>

Kết quả cho thấy 3 actor (Khách hàng, Merchant, Ngân hàng) và các use case chính, kèm quan hệ <<include>> (thanh toán bắt buộc gồm xác thực và duyệt trừ tiền). Đây là "bản đồ phạm vi" để cả team nhìn chung một hướng trước khi đi sâu.

Nhóm 2 — Mô tả luồng nghiệp vụ

2. /sequence — Sequence diagram

Khi cần thể hiện ai gọi ai theo thời gian (login, thanh toán, webhook), sequence diagram là lựa chọn số một. Skill tự nhận diện các actor từ mô tả và dựng cả nhánh lỗi.

text

/sequence "<mô tả luồng: ai gọi ai, theo thứ tự thời gian>" --feature <tên-feature>

Sơ đồ thể hiện trọn luồng thanh toán QR: từ lúc khách quét mã tới khi hiện biên lai, với khối alt tách rõ hai nhánh số dư đủ và số dư không đủ. Skill đã tự chạy compile-check Mermaid trước khi báo hoàn tất.

3. /activity — Activity / flowchart

Cùng một luồng nhưng nhìn dưới góc quy trình có nhánh quyết định, activity/flowchart dễ đọc hơn cho người không kỹ thuật.

text

/activity "<mô tả quy trình có các điểm rẽ nhánh quyết định>" --feature <tên-feature>

Các ô hình thoi là điểm rẽ nhánh (xác thực sinh trắc học, ngân hàng duyệt số dư) — thể hiện rõ đường đi khi thành công và khi thất bại.

4. /activity-swimlane — Activity swimlane (đa vai trò)

Khi một quy trình có nhiều bên tham gia và bàn giao chéo, swimlane là mặc định tốt nhất: mỗi vai một lane. Ở đây minh hoạ quy trình hoàn tiền.

text

/activity-swimlane "<mô tả quy trình + các bên tham gia (lane)>" --feature <tên-feature>

Bốn lane (Khách hàng, CSKH, Kế toán, Hệ thống VNPAY) cho thấy rõ điểm bàn giao trách nhiệm giữa các bên — thứ mà một flowchart phẳng khó thể hiện.

5. /d2-activity — Activity bản hình đẹp (D2)

Khi cần một sơ đồ luồng đẹp để đưa vào slide/export (không cần swimlane thật), skill D2 cho ra hình gọn gàng, thẩm mỹ cao.

text

/d2-activity "<mô tả luồng cần bản hình đẹp cho slide>" --feature <tên-feature>

Cùng nội dung luồng thanh toán, nhưng D2 lo phần dàn layout và thẩm mỹ — hợp cho tài liệu trình bày.

Nhóm 3 — Vòng đời trạng thái

6. /state — State diagram

Với các thực thể có nhiều trạng thái (đơn hàng, tài khoản, giao dịch), state diagram thể hiện vòng đời và các sự kiện chuyển trạng thái.

text

/state "<mô tả vòng đời trạng thái của một thực thể>" --feature <tên-feature>

Vòng đời một giao dịch: từ Khởi tạo → Chờ thanh toán → rẽ sang Thành công / Thất bại / Hết hạn, và nhánh hoàn tiền sau khi thành công. Rất hữu ích để thống nhất các trạng thái hệ thống cần quản lý.

Nhóm 4 — Mô hình dữ liệu

7. /erd — ERD nhúng inline

Chuyển sang phần dữ liệu: ERD thể hiện các thực thể và quan hệ. Bản Mermaid này nhúng thẳng vào tài liệu để BA đọc.

text

/erd "<mô tả các thực thể / dữ liệu cần lưu>" --feature <tên-feature>

Bốn thực thể (Khách hàng, Merchant, Giao dịch, Hoàn tiền) với khoá chính/khoá ngoại và quan hệ một–nhiều rõ ràng.

8. /d2-erd — ERD bản hình đẹp (D2)

Cùng mô hình dữ liệu nhưng bản standalone đẹp, PK/FK nổi bật — hợp để đưa vào slide hoặc export cho stakeholder.

text

/d2-erd "<mô tả mô hình dữ liệu, bản hình đẹp>" --feature <tên-feature>

9. /dbdiagram — Schema DBML + export SQL

Khi bàn giao cho dev, skill này sinh schema DBML (mở được trên dbdiagram.io / dbdocs.io) và export thẳng ra SQL.

text

/dbdiagram --feature <tên-feature>

SQL do skill sinh ra (PostgreSQL, trích):

sql

CREATE TABLE "giao_dich" (
  "ma_gd" varchar PRIMARY KEY,
  "ma_kh" varchar,
  "ma_merchant" varchar,
  "so_tien" decimal,
  "trang_thai" varchar,
  "thoi_gian" datetime
);
CREATE INDEX ON "giao_dich" ("ma_kh");
CREATE INDEX ON "giao_dich" ("trang_thai");
ALTER TABLE "giao_dich" ADD FOREIGN KEY ("ma_kh") REFERENCES "khach_hang" ("ma_kh");

Khác với hai skill ERD ở trên (để BA đọc/trình bày), /dbdiagram thiên về bàn giao kỹ thuật: có enum, index, và file SQL chạy được.

Nhóm 5 — Kiến trúc hệ thống

10. /d2-architect — Sơ đồ kiến trúc

Để thể hiện các component/service/DB và dịch vụ ngoài lồng nhau, skill này vẽ sơ đồ kiến trúc bằng D2.

text

/d2-architect "<mô tả các thành phần & dịch vụ của hệ thống>" --feature <tên-feature>

Sơ đồ cho thấy App → API Gateway → các service (QR, Payment, Notification) → Transaction DB, và kết nối ra Ngân hàng cùng webhook báo Merchant. Đây là bức tranh "hệ thống lắp ghép thế nào".

Nhóm 6 — Chuẩn hoá quy trình

11. /bpmn — BPMN 2.0 chuẩn OMG

Khi cần một sơ đồ quy trình theo chuẩn công nghiệp để import vào Camunda/Bizagi hoặc bpmn.io, skill BPMN sinh file BPMN 2.0 XML kèm trình xem HTML, và chạy semcheck kiểm phủ actor/nhánh/lỗi so với mô tả.

text

/bpmn "<mô tả quy trình cần chuẩn hoá>" --feature <tên-feature>

Khác các skill trên, đầu ra /bpmn là file .bpmn mở trong trình xem BPMN (Camunda/Bizagi/bpmn.io) chứ không phải ảnh nhúng — phù hợp khi quy trình cần bàn giao theo chuẩn hoặc chạy trên BPM engine.

Kết quả: trọn bộ tài liệu sơ đồ cho một feature

Đi hết 11 skill, feature "Thanh toán QR VNPAY" giờ đã có: sơ đồ phạm vi (use case), các luồng (sequence, activity, swimlane, D2), vòng đời trạng thái, mô hình dữ liệu (ERD + schema SQL), kiến trúc hệ thống, và quy trình chuẩn BPMN. Mỗi skill lo một lát cắt; ghép lại thành một bộ tài liệu nghiệp vụ hoàn chỉnh — tất cả từ việc mô tả bằng lời, không phải gõ cú pháp.

Không cần dùng đủ 11 skill cho mọi feature. Điểm mạnh của bộ là có kim chỉ nam chọn sơ đồ (diagram-selection.md): tuỳ nhu cầu mà chọn đúng vài skill cần thiết.

Cách cài & dùng (Claude Code)

1. Cài công cụ render tuỳ skill: Mermaid (/sequence /activity /state /erd) cần Node + mermaid-cli + Chrome; PlantUML (/activity-swimlane /usecase-diagram) chỉ cần internet; D2 (/d2-*) cần cài binary d2; BPMN cần npm install trong engine; DBML (/dbdiagram) cần @dbml/cli.
2. Copy bộ skill vào workspace: chép .claude/skills/, agents/, rules/, scripts/, _templates/ vào thư mục .claude/ của workspace.
3. Gọi skill trong Claude Code, ví dụ: /sequence "Khách quét QR, hệ thống gọi ngân hàng trừ tiền, báo Merchant" --feature qr-payment

Bộ cũng có bản port cho Codex CLI và Google Antigravity IDE (kèm prompt cài sẵn).

Lưu ý khi dùng

• Người vẫn là trung tâm (human-in-the-loop). Skill không tự ghi file: luôn cho xem kế hoạch (L1) rồi bạn gõ Y mới ghi. Sơ đồ AI vẽ là bản nháp chất lượng cao để BA thẩm định, không phải chân lý — compile-check chỉ bắt lỗi cú pháp, còn đúng-sai nghiệp vụ là quyết định của bạn.
• Rác vào → rác ra. Chất lượng sơ đồ phụ thuộc mô tả bạn đưa vào; skill hỏi lại bằng ngôn ngữ nghiệp vụ, không tự bịa số liệu/luật khi thiếu nguồn.
• Bảo mật: khi mô tả nghiệp vụ nội bộ cho AI, tránh đưa thông tin nhạy cảm (kiến trúc chi tiết, dữ liệu khách hàng, endpoint, credential); kiểm tra quy định dùng công cụ AI của VNPAY trước. (Khuyến nghị chung; đối chiếu chính sách nội bộ hiện hành.)

Download File:

Tài liệu tham khảo

1. Bộ skill nguồn: Diagram Skills Package — công cụ thực hành của khoá AI4BA (ai4ba.com). Giấy phép MIT.
2. Anthropic Agent Skills — Claude Platform Docs. Available at: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview (Accessed: 21/07/2026).