Tóm tắt nhanh: Archify là skill giúp AI agent như Codex hay Claude Code viết sơ đồ thành JSON có kiểu, kiểm tra nó rồi xuất ra một trang HTML để bạn duyệt. Từ bản 3.1.0 (14/10/2026), Archify có mười loại sơ đồ, mỗi loại trả lời một câu hỏi khác nhau của người đọc. Agent vẫn là bên đọc code và quyết định nội dung; Archify chỉ bảo đảm bản vẽ đúng chuẩn, không chứng minh hệ thống chạy đúng.
Công khai: mình là maintainer của AgentKit và có quan hệ affiliate với nó. Phần cuối bài có gợi ý đọc bài về bộ skill trực quan hoá của AgentKit.
Bài này dành cho bạn nếu đang dùng agent viết code và muốn có sơ đồ hệ thống mà không phải tự vẽ tay. Khó nhất không phải là cài Archify mà là chọn đúng loại sơ đồ cho câu hỏi đang có, và biết khi nào sơ đồ chỉ là bản phác thảo chứ chưa phải hiện trạng. Mình dùng một ví dụ giả định, Tiệm bánh Mây, để đi qua cả mười loại, mỗi loại kèm một prompt dùng ngay.
Code hoặc bản mô tả yêu cầu đủ để vẽ cấu trúc và luồng xử lý. Riêng Timeline và Waterfall cần dữ liệu thời gian có nguồn như log hay trace; không có thì phải ghi rõ đó là số liệu minh họa. Mình sẽ tách hai việc: Archify làm gì, rồi chọn loại sơ đồ nào cho câu hỏi nào.
Archify làm gì và không làm gì
Archify không tự quét repository rồi đoán kiến trúc. Hãy hình dung agent là người khảo sát, còn Archify là bộ quy chuẩn bản vẽ. Agent đọc mã nguồn, tách điều đã biết khỏi điều chưa biết, chọn góc nhìn và viết nội dung thành JSON theo schema của từng loại sơ đồ. Archify kiểm tra schema, cấu trúc và hình học của bố cục, rồi dựng trang HTML.
Vì vậy, một sơ đồ qua mọi bước kiểm tra chỉ có nghĩa là bản vẽ hợp lệ. Nó chưa chứng minh sơ đồ mô tả đúng hệ thống, càng không chứng minh ứng dụng chạy đúng.
Archify dùng được theo hai hướng:
- Hệ thống đã có code: agent đọc bằng chứng trong repository (file, đường dẫn API (Application Programming Interface), cấu hình) để mô tả hiện trạng.
- Ý tưởng chưa có code: bạn đưa bản mô tả yêu cầu, agent phác thảo một thiết kế đề xuất.
Để người đọc không nhầm bản vẽ trên giấy với hệ thống đang chạy, mình dùng bốn nhãn cho căn cứ của từng khẳng định:
| Nhãn | Ý nghĩa |
|---|---|
CURRENT | Điều mã nguồn hiện tại thể hiện |
OBSERVED | Điều log hoặc thử nghiệm cho thấy |
PROPOSED | Thiết kế cho tương lai, chưa có trong code |
UNKNOWN | Chỗ chưa đủ bằng chứng để kết luận |
Đây là quy ước bạn yêu cầu agent tuân theo khi viết, không phải một trường mà Archify tự kiểm tra.
Cài Archify cho agent
Cách nhanh nhất là cài qua Skills CLI, rồi mở agent tại thư mục dự án và gọi tên Archify trong prompt. Lệnh dưới đây cài ở phạm vi toàn cục, dùng được cho mọi dự án:
npx skills add tt-a1i/archify -gNếu chỉ muốn cài cho một dự án, chọn đúng agent:
# Codex: skill nằm ở .agents/skills/
npx -y skills add tt-a1i/archify --skill archify --agent codex --copy --yes
# Claude Code: skill nằm ở .claude/skills/
npx -y skills add tt-a1i/archify --skill archify --agent claude-code --copy --yesSau khi cài, lệnh doctor kiểm tra môi trường của Archify (không phải ứng dụng của bạn), ví dụ với bản cài cho Codex:
node .agents/skills/archify/bin/archify.mjs doctorMuốn dùng với agent khác, đổi --agent sang tên agent đó trong danh sách của hướng dẫn cài đặt. Muốn bản cài theo agent dùng được ở mọi dự án, thêm --global. Muốn thử với Codex mà không cài lâu dài, chạy npx skills use tt-a1i/archify@archify --agent codex.
Chọn loại sơ đồ theo câu hỏi của người đọc
Tiệm bánh Mây là hệ thống giả định dùng để minh họa. Mọi sơ đồ trong ví dụ đều là PROPOSED; không có ứng dụng thật nào được dựng hay chạy.
Câu chuyện rất đơn giản: khách chọn và đặt bánh trên trang web, hệ thống kiểm tra món, tạo đơn, gửi yêu cầu thanh toán, báo bếp và cập nhật trạng thái cho khách. Cùng một câu chuyện, nhưng mỗi người đọc quan tâm một điều khác nhau, và mỗi mối quan tâm hợp với một loại sơ đồ:
| Câu hỏi của người đọc | Loại sơ đồ |
|---|---|
| Hệ thống gồm những khối nào? | Architecture |
| Một đơn được xử lý qua những bước nào? | Workflow |
| Khi khách bấm đặt bánh, thành phần nào gọi thành phần nào trước? | Sequence |
| Dữ liệu khách và đơn hàng đi đâu? | Data Flow |
| Đơn có những trạng thái nào? | Lifecycle |
| Dữ liệu đơn được lưu trong những bảng nào, khóa nối ra sao? | ERD |
| Code xử lý thanh toán gồm những class và interface nào? | Class |
| Tính năng đặt bánh được chia nhỏ thế nào? | Tree |
| Sự cố thanh toán tối qua diễn ra theo mốc thời gian nào? | Timeline |
| Một yêu cầu đặt bánh tốn thời gian ở đâu? | Waterfall |
Năm loại đầu mô tả cấu trúc và luồng xử lý. Năm loại sau trả lời câu hỏi về dữ liệu lưu trữ, code, phân cấp và thời gian. Archify không dành cho biểu đồ số liệu hay dashboard; câu hỏi kiểu doanh thu theo tháng thì dùng công cụ vẽ biểu đồ.
Lỗi hay gặp nhất là nhồi nhiều câu hỏi vào một hình. Hình đó có thể đủ thông tin nhưng người xem không biết bắt đầu đọc từ đâu. Hãy bắt đầu từ một câu hỏi cụ thể của người đọc, thay vì "vẽ cho tôi một sơ đồ thật chi tiết".
Hai cách bắt đầu: đọc code có sẵn hay thiết kế trước
Trước khi chọn loại sơ đồ, bạn cần biết agent lấy dữ kiện từ đâu. Hai tình huống dưới đây khác nhau ở nguồn đầu vào, và vì thế khác nhau ở nhãn gắn cho sơ đồ.
Tình huống 1: đọc repository và vẽ hiện trạng
Khi nào dùng: giúp người mới làm quen hệ thống, lần theo đường đi của một yêu cầu, hoặc cập nhật tài liệu kiến trúc đã lệch so với code.
Agent cần đọc điểm vào của ứng dụng, đường dẫn API, các dịch vụ, tầng lưu trữ, hàng đợi, cấu hình hạ tầng và test liên quan. Mỗi khối và đường nối quan trọng phải có bằng chứng, và loại bằng chứng phải khớp với loại quan hệ: lời gọi trực tiếp, cấu hình, sự kiện hay cơ chế tiêm phụ thuộc. Tên file không chứng minh hành vi lúc chạy. Một dịch vụ được khai báo nhưng không thấy chỗ dùng thì đừng tự nối; chưa xác định được thì ghi UNKNOWN.
Hãy dùng skill Archify để đọc repository này và vẽ Architecture.
Câu hỏi người đọc cần trả lời:
Request tạo đơn đi qua những thành phần nào?
Yêu cầu:
- Chỉ dùng facts có repository evidence.
- Liệt kê file đã đọc và evidence cho node/edge chính.
- Phân loại CURRENT và UNKNOWN; không tự thêm service.
- Author typed JSON rồi chạy finalize ở quality showcase.
- Báo riêng kết quả kiểm tra sơ đồ và trạng thái test của ứng dụng.Một đầu ra tốt gồm bốn thứ: JSON để xem lại, HTML, biên nhận của lần chạy và danh sách những chỗ còn thiếu bằng chứng.
Tình huống 2: thiết kế luồng trước khi viết code
Khi nào dùng: giai đoạn tìm hiểu yêu cầu, duyệt một đề xuất kỹ thuật, hoặc khi cả nhóm cần thống nhất một tính năng nên hoạt động thế nào.
Với Tiệm bánh Mây, bạn đưa agent một bản mô tả ngắn: khách chọn bánh, hệ thống kiểm tra món, gọi thanh toán rồi mới chuyển đơn xuống bếp. Agent giúp tìm người tham gia, điểm rẽ nhánh và trạng thái còn thiếu. Bản vẽ giữ nhãn PROPOSED cho tới khi có trong code; khi đó phần đã có code chuyển thành CURRENT, còn kết quả test và hành vi OBSERVED được báo riêng.
Hãy dùng skill Archify thiết kế PROPOSED Workflow cho tiệm bánh online.
Câu hỏi:
Một đơn đi từ lúc khách xác nhận tới lúc bếp nhận đơn thế nào?
Facts được phép dùng:
- Kiểm tra món trước thanh toán.
- Payment có thể accepted hoặc declined.
- Chỉ gửi bếp sau khi payment accepted.
Nêu assumptions và UNKNOWN trước khi author JSON.
Không trình bày planning sketch như hành vi đã test.Archify không "chạy thử luồng" theo nghĩa gọi API, cơ sở dữ liệu hay môi trường thanh toán thử. Muốn chứng minh thiết kế hoạt động, bạn vẫn cần bản mẫu chạy được và kiểm thử đơn vị, kiểm thử tích hợp hoặc kiểm thử đầu cuối phù hợp.
Năm loại sơ đồ cho cấu trúc và luồng xử lý
Năm loại này cùng mô tả hệ thống đang hoặc sẽ vận hành ra sao, chỉ khác ở góc nhìn: khối, bước, thứ tự gọi, dữ liệu hay trạng thái.
Architecture: bản đồ các khối
Architecture trả lời hệ thống gồm những khối nào, ranh giới nằm ở đâu và quan hệ chính là gì. Với Tiệm bánh Mây, đường chính có thể là Khách → Website → Order API → Dữ liệu đơn, còn thanh toán và bếp là nhánh phụ.
Loại này hợp với tài liệu tổng quan, tài liệu cho người mới, rà soát phụ thuộc, phân chia trách nhiệm khi triển khai hoặc so sánh thay đổi kiến trúc. Nó không dành cho việc kể chi tiết từng thông điệp; đó là việc của Sequence.
Dùng Archify Architecture cho Tiệm bánh Mây.
Câu hỏi: người mới cần biết các khối chính nào và chúng kết nối ra sao?
Giữ main path nổi bật. Payment và bếp là secondary path.
Gắn toàn bộ artifact là PROPOSED.Kiểm tra nhanh: người xem có chỉ vào từng khối và nói được nó chịu trách nhiệm gì không?
Workflow: bản đồ công việc
Nếu Architecture cho biết hệ thống có gì, Workflow cho biết một công việc đi qua đâu: ai làm, làm gì và rẽ nhánh ở điểm nào. Loại này hợp với quy trình nghiệp vụ, CI/CD (Continuous Integration/Continuous Delivery), xử lý sự cố, luồng phê duyệt và sổ tay vận hành.
Ở Tiệm bánh Mây, đường chính là Kiểm tra món → Thanh toán → Gửi bếp. Hết món, thanh toán bị từ chối và hoàn tiền là các nhánh ngoại lệ. Trên hình, đường chính phải nổi bật hơn nhánh lỗi.
Dùng Archify Workflow mô tả xử lý một đơn bánh.
Câu hỏi: nhân viên vận hành cần biết đơn đi tiếp hay dừng ở đâu?
Thể hiện actor, decision, happy path và failure path có trong brief.
Không thêm retry hoặc timeout nếu thiếu evidence.Kiểm tra nhanh: tại mỗi điểm rẽ nhánh, người xem có biết điều kiện và bước tiếp theo không?
Sequence: thứ tự thông điệp
Sequence đi sâu hơn Workflow một bậc: thành phần nào gọi thành phần nào, thông điệp nào đi trước và kết quả quay về thế nào. Loại này dùng khi thiết kế hợp đồng API, đọc trace phân tán hoặc gỡ lỗi một chỗ tích hợp. Thứ tự trên hình chỉ chính xác bằng bằng chứng đứng sau nó, nên phải lấy từ mã nguồn, trace hoặc bản mô tả yêu cầu.
Dùng Archify Sequence cho POST /orders.
Câu hỏi: từ lúc khách bấm đặt bánh tới lúc nhận mã đơn, ai gọi ai theo thứ tự nào?
Chỉ dùng participant có trong source hoặc brief.
Ghi rõ sync/async và nhánh payment declined nếu có evidence.Kiểm tra nhanh: một kỹ sư có đối chiếu được từng thông điệp trên hình với trace hoặc đoạn code xử lý không?
Data Flow: theo dấu dữ liệu
Data Flow không chỉ cho biết dịch vụ nào nối với dịch vụ nào. Nó tập trung vào dữ liệu nào được thu thập, biến đổi, lưu trữ và đi qua những ranh giới nào.
Trong thiết kế đề xuất của Tiệm bánh Mây, thông tin liên hệ và chi tiết đơn nằm ở Order Store, yêu cầu thanh toán đi tới nhà cung cấp thanh toán, còn phiếu gửi bếp chỉ chứa món và ghi chú, không nhất thiết mang theo toàn bộ dữ liệu khách.
Dùng Archify Data Flow cho một đơn bánh.
Câu hỏi: thông tin khách, chi tiết đơn và kết quả thanh toán đi đâu?
Phân biệt source, process, store và external sink.
Label mỗi flow bằng tên dữ liệu.
Retention, encryption hoặc PII chưa có evidence phải ghi UNKNOWN.Kiểm tra nhanh: người xem có thấy ngay dữ liệu nhạy cảm vượt qua ranh giới nào không?
Lifecycle: bản đồ trạng thái
Lifecycle trả lời một đối tượng có những trạng thái nào, và sự kiện hay điều kiện nào cho phép chuyển từ trạng thái này sang trạng thái khác. Với đơn hàng của Tiệm bánh Mây, đường chính có thể là DRAFT → AWAITING_PAYMENT → CONFIRMED → IN_KITCHEN → READY → COMPLETED, cộng với các đường sang CANCELLED, mỗi đường phải có điều kiện rõ.
Dùng Archify Lifecycle cho Order.
Câu hỏi: một đơn bánh có thể chuyển trạng thái theo những đường hợp lệ nào?
Liệt kê event/guard cho mỗi transition.
State hoặc transition chưa có evidence phải là PROPOSED hoặc UNKNOWN.Kiểm tra nhanh: có trạng thái nào không thể đi tới từ điểm khởi đầu không? Có trạng thái nào chưa phải điểm kết thúc mà lại bị kẹt, không có đường ra không?
Năm loại sơ đồ cho dữ liệu, code, phân cấp và thời gian
Năm loại này có từ Archify 3.1.0. Chúng không vẽ luồng xử lý mà trả lời những câu hỏi hẹp hơn: dữ liệu nằm ở đâu, code ghép với nhau thế nào, cái gì thuộc cái gì, và chuyện gì xảy ra khi nào.
ERD: bản đồ bảng dữ liệu
Data Flow cho biết dữ liệu đi đâu; ERD cho biết nó được lưu thế nào. ERD vẽ các bảng, từng cột với kiểu SQL, khóa chính, khóa ngoại, khóa duy nhất, cùng số lượng và tính bắt buộc ở hai đầu mỗi quan hệ (một với một, một với nhiều hay nhiều với nhiều). Với Tiệm bánh Mây, đơn giản nhất là customers, orders, order_items, products và payments, trong đó order_items nối orders với products.
Archify vẽ ERD theo kiểu bảng trước: mỗi cột thật phải xuất hiện trong bảng, không được rút gọn thành thẻ mô tả. Bảng được nhóm theo miền chức năng (đơn hàng, thanh toán, thực đơn). Một schema lớn, cỡ trên 8 bảng hoặc 50 cột, nên vẽ lần đầu ở profile standard rồi mới nâng lên showcase khi bố cục đã đọc được.
Dùng Archify ERD cho schema đơn hàng của Tiệm bánh Mây.
Câu hỏi: dữ liệu một đơn bánh nằm ở những bảng nào và nối với nhau qua khóa nào?
Liệt kê đủ cột, kiểu SQL và vai trò khóa của từng cột.
Mỗi khóa ngoại phải ghi bảng.cột được tham chiếu.
Nêu cardinality và tính tùy chọn ở cả hai đầu mỗi quan hệ.
Nhóm bảng theo miền chức năng. Gắn toàn bộ artifact là PROPOSED.Kiểm tra nhanh: từ một dòng trong payments, người xem có lần ngược ra đúng đơn và khách hàng không?
Class: hợp đồng giữa các kiểu
Class vẽ class, interface, các thuộc tính và phương thức được chọn, cùng quan hệ giữa các kiểu: phụ thuộc, liên kết, kế thừa, hiện thực interface và hợp thành. Loại này hợp khi duyệt thiết kế code, làm quen một module, hoặc khi muốn thấy nhanh một interface đang có những bản triển khai nào.
Với Tiệm bánh Mây, thiết kế đề xuất cho phần thanh toán có thể có interface PaymentGateway với hai bản triển khai cho hai nhà cung cấp, và OrderService phụ thuộc vào interface chứ không vào class cụ thể. Chỉ chọn thuộc tính và phương thức giúp trả lời câu hỏi; liệt kê hết sẽ biến hình thành bản sao của code.
Dùng Archify Class cho module thanh toán.
Câu hỏi: OrderService phụ thuộc vào những kiểu nào khi xử lý thanh toán?
Với repository thật: chỉ vẽ class/interface có trong source, kèm evidence file/line.
Với thiết kế mới: đề xuất các kiểu tối thiểu và gắn PROPOSED.
Chỉ hiện member liên quan tới câu hỏi.
Phân biệt kế thừa, hiện thực interface và phụ thuộc.Kiểm tra nhanh: người xem có chỉ ra được chỗ nào cần sửa khi thêm một nhà cung cấp thanh toán mới không?
Tree: phân cấp một cha
Tree dành cho cấu trúc chứa đựng theo một cha: có đúng một nút gốc không có cha, mỗi nút còn lại có đúng một cha. Đường nối trong Tree biểu diễn quan hệ "thuộc về", không phải lời gọi. Ví dụ điển hình là cây thư mục hoặc module của repository, cách chia nhỏ một tính năng, sơ đồ tổ chức. Nếu một phần tử có thể thuộc nhiều nhóm cùng lúc thì đó không còn là cây; khi đó Architecture hoặc Class hợp hơn.
Với Tiệm bánh Mây, Tree có thể chia tính năng "Đặt bánh online" thành chọn món, giỏ hàng, thanh toán và theo dõi đơn, rồi mỗi nhánh chia tiếp thành các phần nhỏ hơn.
Dùng Archify Tree chia nhỏ tính năng Đặt bánh online.
Câu hỏi: tính năng này gồm những phần nào và phần nào thuộc phần nào?
Một node gốc là chính tính năng; mỗi node còn lại có đúng một cha.
Gắn toàn bộ artifact là PROPOSED; nhánh chưa chắc phạm vi ghi UNKNOWN.Kiểm tra nhanh: có nút nào đáng lẽ thuộc hai nhánh cùng lúc không? Nếu có, câu hỏi này không hợp với Tree.
Timeline: chuyện gì xảy ra khi nào
Timeline đặt các sự kiện có mốc thời gian lên một trục chung, chia theo làn là nguồn của sự kiện (ứng dụng, thanh toán, người trực sự cố). Mặc định, những khoảng im lặng dài được rút gọn và đánh dấu ngắt trục; đặt layout.breaks: "none" nếu cần cả trục theo tỉ lệ liên tục. Loại này hợp với báo cáo sau sự cố, lịch sử phát hành hoặc dựng lại một chuỗi sự kiện từ log.
Giả sử Tiệm bánh Mây gặp sự cố thanh toán buổi tối: cảnh báo bắn, người trực nhận, nhà cung cấp thanh toán xác nhận lỗi, quay lui bản cũ, hệ thống hồi phục. Mỗi mốc phải có thời điểm theo ISO 8601 kèm múi giờ. Sơ đồ khai báo meta.evidence: observed khi các mốc lấy từ log, cảnh báo hoặc ghi chép sự cố; illustrative khi là số liệu minh họa, như trong ví dụ giả định này. Sự kiện chưa rõ thời điểm thì ghi vào chú thích, đừng tự đặt lên trục.
Dùng Archify Timeline cho sự cố thanh toán của Tiệm bánh Mây.
Câu hỏi: sự cố bắt đầu, được phát hiện và được xử lý vào những thời điểm nào?
Mỗi sự kiện cần timestamp ISO 8601 có múi giờ và nguồn (log, alert, ghi chép).
Chia lane theo nguồn sự kiện. Dùng meta.evidence "observed" chỉ khi mọi mốc có nguồn.
Sự kiện chưa rõ thời điểm ghi vào chú thích, không tự đặt timestamp.Kiểm tra nhanh: người xem có đọc được khoảng cách từ lúc lỗi bắt đầu tới lúc được phát hiện không, kể cả khi trục có đoạn bị rút gọn?
Waterfall: thời gian đi đâu
Timeline trả lời khi nào; Waterfall trả lời thời gian tốn ở đâu. Waterfall vẽ các span của một yêu cầu hoặc một lần chạy agent trên cùng trục thời gian: thời điểm bắt đầu, thời lượng, phần chồng lấp và quan hệ cha con. Thời lượng của span cha đã bao gồm span con, không cộng dồn.
Với yêu cầu POST /orders của Tiệm bánh Mây, Waterfall cho thấy kiểm tra món, ghi đơn, gọi thanh toán và báo bếp mỗi bước tốn bao lâu và bước nào chạy song song. Waterfall không vẽ đường găng hay thời gian chờ, vì đầu vào không nói bước nào phụ thuộc bước nào; hai span nối tiếp nhau chưa chứng minh span trước chặn span sau. Người tạo sơ đồ khai báo meta.evidence: measured khi thời lượng lấy từ trace, log, công cụ đo hiệu năng hoặc một lần chạy có đo, illustrative khi là số tự điền. Nhãn này hiện trên hình nhưng không tự chứng minh số liệu có nguồn.
Dùng Archify Waterfall cho một request POST /orders.
Câu hỏi: request tốn thời gian chủ yếu ở bước nào?
Dùng span từ trace được cung cấp; offset tính từ gốc trace.
Khai báo meta.evidence "measured" chỉ khi có số đo; không có thì dùng "illustrative".
Không suy quan hệ chặn từ thứ tự span.Kiểm tra nhanh: người xem có phân biệt được span dài, span chồng lấp và thời lượng đã bao gồm span con không?
Từ câu hỏi đến sơ đồ đã kiểm tra
Dù là loại sơ đồ nào, một vòng làm việc đáng tin vẫn đi theo thứ tự:
- Câu hỏi hẹp: một câu hỏi của người đọc, không phải "vẽ hết".
- Bằng chứng hoặc bản mô tả có ranh giới: biết rõ được phép dùng dữ kiện nào.
- JSON có kiểu: agent viết bản nháp theo schema của loại sơ đồ.
finalize: một lệnh chạy lần lượt bước kiểm tra theo profile chất lượng mà JSON khai báo ởmeta.quality_profilevà truyền qua cờ--quality(thường làshowcase; lượt đầu của một ERD dày có thể dùngstandard), dựng HTML, kiểm tra nghiêm ngặt và kiểm tra trong trình duyệt thật. Lệnh dừng ở bước đầu tiên không qua; mã thoát khác 0 nghĩa là chưa xong.- Xem bằng mắt (tùy chọn):
finalizechỉ kiểm tra tự động, không chụp ảnh sơ đồ. Muốn biết sơ đồ trông thế nào trên các kích thước màn hình, chạy thêmvisual-checkđể Archify chụp ảnh ở chế độ sáng và tối. Sơ đồ chỉ được coi là đã duyệt bằng mắt khi có người thật mở những ảnh đó ra xem; trước đó biên nhận vẫn ghi là đang chờ (visualReview: "pending").
"Qua finalize ở mức showcase" nghĩa là sơ đồ vượt đủ 9 bước kiểm tra kỹ thuật của Archify, không có lỗi hay cảnh báo về bố cục (chồng chéo, tràn khung, đường nối đè lên nhau). Cảnh báo về bản dịch giao diện (i18n/*) thì không tính. Chi tiết nằm trong quy ước bàn giao của Archify.
Các kiểm tra này chỉ trả lời câu hỏi "bản vẽ có đúng định dạng và hiển thị tốt không", chứ không trả lời "bản vẽ có đúng với hệ thống không". Một sơ đồ có thể qua hết kiểm tra mà vẫn vẽ sai một dịch vụ. Vì vậy, khi agent báo kết quả, hãy yêu cầu nó tách ba câu trả lời: kiểm tra tự động đã qua chưa, đã có người xem bằng mắt chưa, và ứng dụng đã được test chưa.
Chi tiết lệnh có thể đổi giữa các phiên bản, nên luôn đối chiếu với SKILL.md của bản bạn đang cài.
Bộ ví dụ Tiệm bánh Mây
Bộ ví dụ nằm công khai trong repository archify-tiem-banh-may-demo: JSON nguồn, HTML và ảnh sáng, tối ở 1440×900 và 2048×1320 cho cả mười loại sơ đồ.
Cả mười sơ đồ được chạy lại bằng Archify 3.1.0 ngày 17/10/2026. Tất cả qua finalize ở mức showcase mà không có lỗi hay cảnh báo nào, và visual-check không báo tràn khung. Biên nhận vẫn ghi visualReview: "pending" vì đó là việc của người xem ảnh, không phải của công cụ. Timeline và Waterfall dùng số liệu minh họa.
Khi nâng cấp Archify, đừng mặc định JSON cũ vẫn chạy. Các JSON viết cho Archify 2.16 không qua bước kiểm tra của 3.1.0 ngay: meta.output trở thành bắt buộc, còn Lifecycle chuyển sang schema mới với mainPath và bố cục tự động. Sau mỗi lần nâng cấp, hãy chạy lại finalize cho JSON cũ trước khi tin vào sơ đồ. Tất cả chỉ là bằng chứng về quy trình tạo sơ đồ, không phải về ứng dụng.
Sáu lỗi dễ gặp
| Lỗi | Cách tránh |
|---|---|
| Sơ đồ đẹp nhưng bịa cấu trúc | Yêu cầu agent dẫn bằng chứng cho từng khối và đường nối; phần thiếu ghi UNKNOWN. |
| Một hình trả lời quá nhiều câu hỏi | Mỗi câu hỏi một loại sơ đồ; bảng chọn ở trên là điểm bắt đầu. |
| Gọi bản phác thảo là kiến trúc hiện tại | Gắn PROPOSED ngay trên tiêu đề, phụ đề và trong phần bàn giao. |
| Coi kiểm tra sơ đồ là test ứng dụng | Báo hai trạng thái riêng: kiểm tra sơ đồ và kiểm tra ứng dụng. |
| Biến số minh họa thành phép đo | Không suy thời lượng từ code; khai báo đúng meta.evidence cho Timeline và Waterfall. Không suy quan hệ chặn từ thứ tự span, và không cộng thời lượng span cha với span con. |
| Đọc nhầm HTML cũ sau một lần chạy lỗi | File cũ có thể vẫn nằm ở chỗ ghi đầu ra. Chỉ tin kết quả của lần finalize mới nhất thành công. |
Template prompt dùng lại
Hãy dùng skill Archify để vẽ [TYPE] cho [PROJECT/FLOW].
Câu hỏi người đọc cần trả lời:
[MỘT CÂU HỎI HẸP]
Evidence được phép dùng:
[FILE/PATH/LOG/BRIEF]
Phân loại CURRENT / OBSERVED / PROPOSED / UNKNOWN.
Không tự thêm fact. Author typed JSON rồi chạy finalize với quality khớp
meta.quality_profile (thường là showcase).
Báo riêng: kết quả kiểm tra tự động, đã review bằng mắt hay chưa,
và bằng chứng test ứng dụng nếu có.
Không đánh đồng kiểm tra sơ đồ với test ứng dụng.Nguồn chính thức và đọc thêm
- Archify trên GitHub
- Hướng dẫn Archify
- Nhật ký thay đổi của Archify
- Ví dụ chính thức cho năm loại mới: ERD, Class, Tree, Timeline, Waterfall
Bắt đầu từ loại sơ đồ nào
Nếu chỉ chọn một tiêu chí, hãy chọn theo câu hỏi người đọc đang có: cần biết hệ thống có gì thì Architecture, cần biết việc đi qua đâu thì Workflow, cần biết dữ liệu nằm ở đâu thì ERD, cần biết thời gian tốn ở đâu thì Waterfall. Bắt đầu bằng một sơ đồ, chạy finalize, mở ảnh ra xem, rồi mới thêm sơ đồ thứ hai.
Nếu bạn cần chọn giữa các skill vẽ sơ đồ và dựng giao diện khác, xem hướng dẫn từng skill ak-preview, ak-diagram, ak-tech-graph và ak-frontend-design.
Dùng bài này trong agent của bạn
Lấy API keyChép đoạn dưới, dán vào Claude Code, Codex hay agent bạn đang dùng. Agent đọc bài rồi đối chiếu với repo đang mở.
Đọc bài "Archify với AI agent: chọn và dùng mười loại sơ đồ" trên modernEngineer rồi áp dụng vào repo này.
1. Gọi tool content_get của MCP server modernengineer với locale "vi", slug "archify-ai-agent-scenario-guide". Nếu chưa nối MCP hoặc bị từ chối quyền, đọc thẳng trang https://modernengineer.dev/vi/library/archify-ai-agent-scenario-guide.
2. Tóm tắt các bước chính của bài, chỉ ra bước nào áp dụng được cho repo này.
3. Đề xuất thay đổi cụ thể và hỏi tôi trước khi sửa file.Nối MCP cho Claude Code (một lần)
claude mcp add --transport http modernengineer \
https://api.modernengineer.dev/mcp \
--header "Authorization: Bearer <API key>"Bài mở cho mọi người: chưa nối MCP thì agent vẫn đọc được thẳng từ link bài.
- Phiên bản
- v1.0.0
- Cập nhật
- 01/09/2026
- Giấy phép
- Bảo lưu mọi quyền
- Slug
- archify-ai-agent-scenario-guide
