Tạo technical diagram với AI với Diagram Design

Đối với các công việc kỹ thuật, phát triển phần mềm, việc thiết kế luôn gắn liền với tài liệu và đặc tả. Phần quan trọng nhất có lẽ là các diagram. Nó vừa giúp chúng ta có thể miêu tả chính xác các đặc tả thiết kế một cách ngắn gọn cũng như giúp cả team có thể "nói cùng một ngôn ngữ".

Nhiều năm trước đây, việc vẽ diagram rất vất vả, phải căn chỉnh nhiều và có thể mất rất nhiều thời gian. Ngoài ra, đối với các dự án với yêu cầu cao, chúng ta phải vẽ theo một tiêu chuẩn nào đó, và "tiêu chuẩn ngành" là UML.

UML là một "ngôn ngữ" cho việc vẽ technical diagram trong ngành phát triển phần mềm. Nó rất rõ ràng, tường minh, có thể vẽ mọi đặc tả kĩ thuật có thể có của một phần mềm.
Nhưng, nó phức tạp.

Tôi vừa phát hiện ra một agent skill "Diagram Design", giúp chúng ta có thể vẽ các technical diagrams một cách nhanh chóng tiết kiệm thời gian. Skill này có thể tích hợp với nhiều agent khác nhau.

Trong bài viết này, chúng ta sẽ thử tìm hiểu cách sử dụng nó.

Ví dụ minh họa

Tôi lấy một webapp điểm danh học sinh tên ClassRoll. Giáo viên chọn lớp và buổi học, rồi mở sơ đồ chỗ ngồi. Tên học sinh nằm ngay trên ghế của em đó. Khi đọc tên, giáo viên bấm Có mặt hoặc Vắng mặt tại ghế tương ứng. Trạng thái đổi ngay trên sơ đồ và được lưu cho buổi học đó. Nếu bấm nhầm, giáo viên có thể sửa lại.

Bài toán này có đủ giao diện, xử lý và dữ liệu để thử nhiều kiểu diagram. Tôi sẽ vẽ thành phần của hệ thống, một lần bấm điểm danh và quan hệ giữa lớp, học sinh, ghế, buổi học với bản ghi điểm danh.

Tích hợp Diagram Design vào Codex

Ở bài này, chúng ta sẽ tích hợp Diagram Design vào Codex.

Làm theo hướng dẫn của dự án:

codex plugin marketplace add cathrynlavery/diagram-design
codex plugin add diagram-design@diagram-design

Sau khi cài, tôi mở một chat Codex mới và gọi tên Diagram Design ngay trong yêu cầu. Phần thiết kế dưới đây được làm trong chat đó: tôi đưa bài toán, xem hình Codex xuất ra, rồi yêu cầu sửa những chỗ chưa đúng.

Thực hiện việc thiết kế diagram cho ClassRoll

Như đã nói ở trên, UML là "ngôn ngữ tiêu chuẩn" của các technical diagram trong ngành phát triển phần mềm. Tôi sẽ thử tạo ra các diagram theo chuẩn này. Tuy nhiên, ngày nay tôi thấy người ta cũng đang chuyển hướng tới các việc thoát khỏi sự giới hạn của UML, nên tôi cũng sẽ tạo ra một phiên bản "khác UML" cho từng diagram.

Tôi bắt đầu chat với yêu cầu này (rút gọn):

Use Diagram Design to design ClassRoll as three pairs of diagrams: UML component and three-tier architecture; UML sequence and a flowchart for marking attendance; UML class and ER for the data model. Export each diagram as self-contained HTML and a PNG. Use only the classroom seating-chart attendance example.

Sau khi xem ảnh, tôi yêu cầu sửa nhánh “ghế trống” của flowchart vì nó ban đầu đi ra từ sai ô.

Thành phần và kiến trúc ba lớp

UML component cho thấy giao diện chọn lớp, sơ đồ ghế, hai phần API và kho dữ liệu phụ thuộc vào nhau như thế nào. Bản ba lớp gom chúng thành Trình duyệt → Attendance API → PostgreSQL. Tôi dùng bản component khi cần bàn về ranh giới giữa các phần; bản ba lớp phù hợp để giải thích đường đi chính của một lần điểm danh.

Một lần bấm điểm danh

Khi giáo viên bấm Vắng mặt, sơ đồ sequence xếp các thông điệp theo thời gian: giao diện gửi yêu cầu tới API, API lưu bản ghi, rồi trạng thái mới trở về ghế trên màn hình. Flowchart nhìn vào thao tác của giáo viên: chọn lớp, chọn ghế, kiểm tra ghế có học sinh, ghi nhận trạng thái. Nhánh ghế trống quay lại bước chọn ghế.

Lớp đối tượng và dữ liệu

Bản UML class ghi thuộc tính, phương thức và quan hệ giữa Classroom, Student, Seat, LessonSession, AttendanceRecord. Chẳng hạn, LessonSession có thao tác mark(s, status) và chứa các bản ghi của buổi đó. Bản ER đi vào các khóa ngoại: học sinh và ghế thuộc lớp nào, bản ghi gắn với buổi học và học sinh nào. Hai hình phục vụ hai cuộc thảo luận khác nhau trong cùng một thiết kế.

Từ đặc tả Markdown đến file HTML

Ngoài ra, nếu bạn muốn tận dụng skill hơn nữa, chúng ta có thể tạo ra các skill mở rộng từ việc dùng các file đặc tả .md để tạo ra thiết kế của mình. Tôi sẽ làm một ví dụ theo một flow như sau.

Giả dụ chúng ta muốn tạo ra sơ đồ của mô hình ba lớp:

Tôi đã viết classroll-three-tier.md:

# ClassRoll — three-tier architecture diagram

## Three tiers

1. **Presentation:** The browser displays the seating chart,
   student names, and attendance status.
2. **Application:** Attendance API loads the chart, receives changes,
   checks the teacher's access, and saves the new status.
3. **Data:** PostgreSQL stores classes, students, seats,
   lesson sessions, and attendance records.

## One action

Teacher opens a class → browser calls Attendance API →
API reads seats and statuses from PostgreSQL →
teacher marks one seat Absent → API updates the record →
browser shows the new status on that seat.

## Diagram requirements

- One three-tier diagram in English, read from left to right.
- Keep only Browser, Attendance API, and PostgreSQL.
- Export standalone HTML with inline CSS and SVG; no server.

Skill classroll-diagram-from-spec đọc đặc tả, dùng kiểu architecture của Diagram Design và tạo một file HTML tự chứa. Tôi tóm tắt chỉ dẫn trong SKILL.md như sau:

Read the supplied .md file before drawing. Use only components,
relationships, labels, and constraints present in the file.

Apply Diagram Design's architecture type to the three-tier example.

Create the requested .html file directly. Put all styling and SVG
markup inline so it opens with file:// and requires no server.

Luồng này cũng có thể vẽ thành một sơ đồ:

Sau đó tôi sẽ chạy thử và đây là các kết quả:

Trong chat Codex, tôi tiếp tục với yêu cầu:

Read classroll-three-tier.md and classroll-diagram-from-spec/SKILL.md. Use Diagram Design to create a self-contained HTML file for the three-tier diagram directly, then export a PNG. Do not create a diagram generator script.

Kết quả là một file có CSS và SVG nằm ngay trong HTML. Tôi chụp lại hình kết quả bên dưới.

Kết luận

Diagram Design giúp tôi đi từ một bài toán sang nhiều loại sơ đồ khá nhanh. Với ClassRoll, bản UML có ký pháp cần cho tài liệu thiết kế, còn bản ngoài UML dễ dùng khi muốn giải thích luồng cho người khác trong team. Luồng đặc tả Markdown → skill → HTML cũng đáng dùng khi thiết kế còn thay đổi và cần tạo lại hình.

Điểm tôi vẫn phải sửa là nội dung và bố cục cụ thể: nhánh “ghế trống” của flowchart đi sai ở lần đầu, rồi một số nhãn cần căn lại.

Skill này có vẻ hay ho. Tuy nhiên nếu bạn nghĩ chỉ cần prompt và đưa thẳng vào tài liệu dự án thì hãy cẩn thận. Hãy luôn review trước khi sử dụng bất cứ thứ gì được tạo ra bởi AI.