Archify là gì? Biến codebase thành sơ đồ tương tác bằng AI

Có một chuyện mình gặp khá thường xuyên khi làm việc với AI coding agent: AI có thể đọc và hiểu cả một codebase rất nhanh, nhưng mình thì không.

Bạn có thể hỏi Claude Code, Cursor hay Codex rằng project này hoạt động thế nào, frontend gọi API nào, dữ liệu chạy qua đâu… và nhận lại vài đoạn giải thích khá chi tiết. Nhưng khi project bắt đầu lớn lên, đọc chữ thôi vẫn khó hình dung được toàn cảnh.

Đó là lúc mình thấy Archify khá thú vị.

Archify là một dự án mã nguồn mở giúp biến ý tưởng, quy trình hoặc cả một codebase thành sơ đồ HTML tương tác. Nó hoạt động như một Skill cho các AI coding agent như Claude Code, Cursor, Codex CLI và OpenCode.

Điểm hay là mình gần như không phải học thêm một công cụ vẽ diagram mới. Cứ nói với AI thứ mình muốn hiểu, phần còn lại để Archify xử lý.

Archify là gì? Thay vì giải thích bằng chữ, hãy vẽ nó ra

Giả sử mình muốn mô tả một flow khá quen thuộc:

Browser gọi API → API kiểm tra Redis → nếu cache miss thì query PostgreSQL → sau đó ghi dữ liệu trở lại cache.

Bình thường mình có thể mở Figma, FigJam hoặc một công cụ diagram nào đó rồi tự vẽ. Với Archify thì chỉ cần nói với agent:

Use Archify to diagram a web request:

Browser calls the API,
the API checks Redis,
and a cache miss queries PostgreSQL and fills the cache.

Archify sẽ tạo một file HTML chứa sơ đồ tương tác.

Điều thú vị là cuộc trò chuyện chưa dừng ở đó. Mình có thể tiếp tục yêu cầu:

Add authentication.

hoặc:

Highlight the cache-miss path.

hay đơn giản:

Switch to the light theme.

Agent sẽ tiếp tục chỉnh diagram dựa trên yêu cầu mới.

Cảm giác sử dụng vì vậy khá khác với các công cụ vẽ sơ đồ truyền thống. Mình không trực tiếp ngồi chỉnh từng box và connector, mà đang nói cho AI biết mình muốn người xem hiểu điều gì.

Đây cũng là điểm mình thích nhất ở Archify.

Không chỉ vẽ architecture

Tên Archify dễ khiến mình nghĩ đây đơn thuần là tool tạo architecture diagram, nhưng thực tế phạm vi sử dụng rộng hơn.

Bạn có thể dùng nó để mô tả workflow của một tính năng, data flow, AI pipeline, quan hệ giữa các service, learning map, quy trình làm việc, thậm chí cả itinerary cho một chuyến đi.

Nói đơn giản, thứ gì có thành phần + mối quan hệ + luồng đi thì đều khá phù hợp để trực quan hóa.

Và output không phải một tấm ảnh tĩnh.

Các node có thể click, một thành phần có thể được focus, route có thể highlight và dependency có thể lần theo upstream hoặc downstream.

Với những architecture tương đối lớn, điều này rất hữu ích.

Thay vì nhìn vào một “bát mì” với vài chục đường connector chạy ngang dọc, mình có thể chọn một service và chỉ xem những thứ liên quan đến nó.

Archify là gì? Biến codebase thành sơ đồ tương tác bằng AI - 1

Dùng Archify để đọc một codebase

Đây có lẽ là use case mình thích nhất.

Archify không bắt buộc phải có repository. Chỉ cần mô tả bằng chữ là nó đã có thể tạo diagram.

Nhưng khi đang làm việc trong một project thật, mình có thể yêu cầu AI đọc code trước rồi mới dựng architecture.

Ví dụ:

Analyze this repository first.

Use Archify to create a high-level
runtime architecture diagram.

Show the core components,
primary runtime path,
external dependencies
and authentication boundaries.

AI sẽ phân tích project rồi dùng Archify để dựng lại cách hệ thống hoạt động.

Điểm đáng chú ý hơn là Archify hỗ trợ source-backed diagram.

Nói dễ hiểu: những thành phần trên sơ đồ có thể được liên kết ngược lại source code đã dùng làm evidence. Khi cần kiểm tra “AI lấy thông tin này ở đâu?”, mình có thể quay lại đúng file hoặc đoạn code liên quan.

Điều này giải quyết một vấn đề mình khá ngại khi dùng AI để phân tích architecture: AI vẽ một thứ trông rất hợp lý không có nghĩa nó thực sự tồn tại trong code.

Có source evidence thì diagram không còn chỉ là một bức minh họa đẹp. Nó giống một lớp bản đồ trực quan nằm phía trên codebase hơn.

Nếu vừa nhận một project cũ với vài trăm file, thay vì mở từng folder rồi cố ráp architecture trong đầu, mình có thể tạo một bản đồ tổng quan trước.

Sau khi hiểu bản đồ rồi mới đào sâu xuống code.

Cách này dễ thở hơn khá nhiều.

Archify còn tạo được cả một trang giải thích

Một tính năng khác mình thấy khá hay là Explainer.

Không phải vấn đề nào cũng giải thích tốt bằng một diagram duy nhất. Đôi khi cần một chút text, một bảng so sánh, vài bước hướng dẫn và một sơ đồ đi kèm.

Archify có thể gom tất cả thành một trang HTML.

Ví dụ mình hỏi:

Use Archify to answer as one page:

Our API’s P99 went from 80 ms to 600 ms
while the mean barely moved.

What is the likely cause,
and how should we investigate?

Thay vì trả về một đoạn chat dài, Archify có thể dựng một trang giải thích với kết luận ở đầu, sau đó chia vấn đề thành từng panel, kết hợp text, bảng, code và diagram.

Mình nghĩ kiểu này khá hợp để làm technical note, onboarding, handoff hoặc giải thích một hệ thống cho những người không trực tiếp viết code.

Đặc biệt nếu bạn thường xuyên phải lấy một vấn đề kỹ thuật tương đối rối rồi biến nó thành thứ PM, designer hoặc thành viên mới trong team có thể hiểu được.

Output chỉ là HTML, và mình thích điều này

Một ưu điểm khá thực dụng của Archify là output cuối cùng có thể là một file HTML độc lập.

Không cần người nhận phải cài Archify.

Không cần tạo account chỉ để xem diagram.

Không nhất thiết phải đưa tài liệu lên một dịch vụ hosting riêng.

Gửi file HTML cho người khác, mở bằng browser và các interaction vẫn hoạt động.

Khi cần đưa vào tài liệu hoặc slide, Archify cũng hỗ trợ export sang PNG, WebP, JPG hoặc in thành PDF.

Workflow vì vậy khá gọn:

AI đọc → Archify trực quan hóa → mình kiểm tra → chia sẻ cho team.

Và quan trọng hơn, nếu architecture thay đổi, mình có thể quay lại agent và yêu cầu nó cập nhật thay vì ngồi vẽ lại từ đầu.

Cài Archify

Nếu đang sử dụng Claude Code, Cursor, Codex CLI hoặc OpenCode thì cài Archify khá đơn giản.

Yêu cầu trước tiên là máy đã có Node.js 18 trở lên.

Sau đó chạy:

npx skills add tt-a1i/archify -g

Vậy là gần như xong.

Archify không phải một ứng dụng riêng mà bạn cần mở lên mỗi lần sử dụng. Sau khi cài Skill, chỉ cần yêu cầu coding agent sử dụng Archify.

Ví dụ đơn giản:

Use Archify to diagram:

Browser -> API -> Redis -> PostgreSQL.

Hoặc khi đang mở một project:

Analyze this repository and use Archify
to create a high-level runtime architecture diagram.

Nếu muốn kiểm tra môi trường cài đặt:

node bin/archify.mjs doctor

Còn nếu chỉ muốn thử trước khi cài global, có thể dùng:

npx skills use tt-a1i/archify@archify --agent codex

Với phần lớn trường hợp, mình nghĩ chỉ cần lệnh cài đầu tiên là đủ để bắt đầu.

Đừng quá ám ảnh chuyện viết prompt

Sau khi thử những tool kiểu này một thời gian, mình thấy prompt dài chưa chắc đã tốt.

Quan trọng hơn là nói rõ mình muốn nhìn thấy điều gì.

Ví dụ thay vì:

Draw the architecture of this repository.

Mình sẽ viết:

Analyze this repository first.

Create a high-level runtime architecture diagram.

Focus on:
- 8–12 core components
- primary request path
- external dependencies
- authentication boundaries

Keep secondary details inside cards
instead of adding more connections.

Prompt thứ hai cho AI biết mục tiêu của diagram là gì, phần nào quan trọng và phần nào nên giản lược.

Nếu diagram quá phức tạp, đừng cố nhét thêm mọi thứ vào.

Hãy bảo agent:

Simplify the diagram.
Only keep the components needed
to understand the primary runtime flow.

Hoặc nếu muốn hiểu một flow cụ thể:

Highlight the authentication flow
and hide unrelated dependencies.

Mình thấy đây mới là cách Archify phát huy thế mạnh: diagram thay đổi theo câu hỏi mình đang muốn trả lời.

Một vài điều cần lưu ý

Archify không phải công cụ thay thế Figma, FigJam hay các diagram editor truyền thống.

Nếu mục tiêu là tự kéo từng node, chỉnh connector hoặc kiểm soát chính xác từng pixel thì những công cụ đó vẫn hợp lý hơn.

Archify đi theo hướng khác.

Nó phù hợp khi mình muốn AI hiểu nội dung trước, sau đó biến sự hiểu đó thành một artifact trực quan để con người khám phá.

Chất lượng kết quả vì vậy cũng phụ thuộc khá nhiều vào AI agent đang sử dụng và cách mình đặt vấn đề.

Đặc biệt khi dùng Archify để phân tích một repository lớn, mình sẽ không mặc định diagram do AI tạo ra là chân lý. Những flow quan trọng vẫn nên được kiểm tra lại với source code.

May là source-backed diagram của Archify giúp chuyện này dễ hơn.

Một chi tiết khác đáng biết nếu dùng trong project nội bộ: Archify có cơ chế kiểm tra xem có phiên bản stable mới hay không. Việc này không tự động tải hay cài update, nhưng nếu môi trường yêu cầu hạn chế network request thì có thể tắt bằng:

ARCHIFY_UPDATE_CHECK_DISABLED=1

Vậy Archify hợp với ai?

Nếu thỉnh thoảng chỉ cần vẽ một flow gồm năm box thì có lẽ Archify hơi dư.

Nhưng nếu đang sử dụng Claude Code, Cursor, Codex hoặc OpenCode hàng ngày, mình nghĩ đây là một Skill khá đáng thử.

Developer có thể dùng nó để khám phá codebase và onboarding project.

Tech lead có thể dùng để giải thích architecture hoặc chuẩn bị design review.

Designer có thể trực quan hóa system flow, AI pipeline và những dependency phía sau một tính năng mà không phải đọc hàng đống code.

PM hoặc BA cũng có thể biến những workflow phức tạp thành thứ dễ trao đổi hơn với team.

Còn với mình, điều hấp dẫn nhất đơn giản là không phải đổi context.

Đang nói chuyện với Claude Code về architecture thì bảo nó vẽ luôn architecture.

Đang debug một flow phức tạp thì bảo nó highlight flow đó.

Đang đọc một project mới thì tạo luôn một bản đồ để khám phá.

Không cần copy nội dung sang một công cụ khác rồi ngồi dựng lại từ đầu.

Archify đáng thử không?

Mình nghĩ là có, đặc biệt nếu coding agent đã trở thành một phần trong workflow hàng ngày.

Điểm thú vị của Archify không nằm ở chuyện “AI vẽ diagram đẹp đến đâu”, mà ở cách nó biến diagram thành một giao diện để khám phá thông tin.

Node có thể mở.

Route có thể highlight.

Dependency có thể lần theo.

Architecture có thể dẫn ngược về source.

Và kết quả cuối cùng vẫn chỉ là một file HTML có thể mang đi nơi khác.

Đây là hướng mình thấy thú vị hơn khá nhiều so với việc AI xuất ra một tấm PNG rất đẹp, nhưng vài tuần sau chẳng ai nhớ sơ đồ đó được tạo từ phiên bản code nào.

Nếu đã có Claude Code, Cursor, Codex hoặc OpenCode trên máy, chỉ cần: