Archify với AI Agent: từ source code đến năm loại sơ đồ

Archify không phải một app tự chạy quanh repository rồi đoán mọi thứ. Nó là một skill và toolchain giúp AI Agent biến facts hoặc một bản thiết kế thành nguồn JSON có cấu trúc, kiểm tra nguồn đó, rồi render thành HTML có thể review.

Hãy hình dung AI Agent là người khảo sát, còn Archify là bộ quy chuẩn bản vẽ. Agent vẫn phải đọc source, phân biệt điều biết và chưa biết, chọn góc nhìn rồi author nội dung. Archify kiểm tra schema, cấu trúc, geometry và việc giao artifact; nó không thay agent hiểu hệ thống.

Trả lời ngắn cho hai câu hỏi phổ biến

“Nó đọc source code rồi vẽ flow hay mình thiết kế flow?” Cả hai.

• Với hệ thống có sẵn, agent đọc repository evidence rồi mô tả hiện trạng.
• Với ý tưởng chưa code, bạn đưa brief và agent tạo một thiết kế đề xuất.

Hai chế độ phải được gắn nhãn khác nhau. CURRENT là điều source hiện tại thể hiện. OBSERVED là điều log hoặc thử nghiệm cho thấy. PROPOSED là thiết kế tương lai. UNKNOWN là chỗ chưa đủ bằng chứng.

“Làm sao gắn cho AI?” Cách ngắn nhất là dùng Skills CLI, sau đó mở agent tại project và gọi tên Archify trong prompt:

npx skills add tt-a1i/archify -g

Với Codex, có thể cài project-local, không hỏi tương tác:

npx -y skills add tt-a1i/archify --skill archify --agent codex --copy --yes
node .agents/skills/archify/bin/archify.mjs doctor

Đổi codex thành agent được official switcher hỗ trợ hoặc thêm --global nếu muốn dùng ở mọi project. Codex tìm skill tại ~/.agents/skills/ hoặc .agents/skills/; Claude Code dùng ~/.claude/skills/ hoặc .claude/skills/. Bạn cũng có thể thử với Codex mà không cài lâu dài bằng npx skills use tt-a1i/archify@archify --agent codex.

Các keyword hữu ích để tự tìm hiểu: Agent Skills, SKILL.md, skill discovery, Archify typed JSON IR, architecture diagram, workflow diagram, sequence diagram, data lineage, state machine.

Một ví dụ xuyên suốt: Tiệm bánh Mây

Ta dùng một hệ thống giả định: khách đặt bánh trên website; 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.

Đây là PROPOSED, không phải application đã chạy. Cùng một câu chuyện được nhìn qua năm câu hỏi khác nhau.

Câu hỏi	Mode phù hợp
Hệ thống có những phần 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, ai gọi ai 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

Sai lầm phổ biến là cố nhét cả năm câu hỏi vào một hình. Kết quả có thể đầy đủ nhưng không còn dễ đọc. Với Archify, hãy bắt đầu bằng một câu hỏi của người đọc, không bắt đầu bằng “vẽ cho tôi một sơ đồ thật chi tiết”.

Scenario 1: đọc repository và vẽ hiện trạng

Dùng khi onboarding, điều tra một request path hoặc cập nhật tài liệu đã lệch code.

Agent nên đọc entrypoint, route, service, persistence, queue, infrastructure config và test liên quan. Mỗi node và relationship quan trọng cần có evidence. Tên file không tự chứng minh runtime behavior; nếu một service được khai báo nhưng không được gọi, đừng tự nối edge.

Prompt:

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, validate ở quality showcase và deliver HTML.
- Báo riêng verification của sơ đồ và test status của ứng dụng.

Đầu ra tốt không chỉ là HTML. Nó gồm JSON để review, artifact HTML, receipt và danh sách chỗ chưa đủ evidence.

Scenario 2: thiết kế flow trước khi code

Dùng khi discovery, review proposal hoặc thống nhất cách một feature nên hoạt động.

Trong case Tiệm bánh Mây, bạn có thể cho agent brief: khách chọn bánh, hệ thống kiểm tra món, gọi payment, rồi gửi đơn tới bếp. Agent giúp tìm actor, decision và state còn thiếu. Nhưng mọi thứ vẫn là PROPOSED cho tới khi được implement và test.

Prompt:

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ử flow” theo nghĩa gọi API, database hoặc payment sandbox. Muốn chứng minh thiết kế hoạt động, bạn vẫn cần prototype, unit test, integration test hoặc end-to-end test phù hợp.

Scenario 3: Architecture — bản đồ các khối

Architecture trả lời hệ thống gồm những thành phần nào, ranh giới ở đâu và quan hệ chính là gì. Với Tiệm bánh Mây, main path có thể là Khách → Website → Order API → Dữ liệu đơn; payment và bếp là nhánh hỗ trợ.

Dùng cho system overview, onboarding, dependency review, deployment ownership hoặc architecture delta. Không dùng nó để kể chi tiết từng message.

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.

Test đọc nhanh: người xem có thể chỉ vào từng khối và nói nó chịu trách nhiệm gì không?

Scenario 4: Workflow — bản đồ công việc

Workflow trả lời một công việc đi qua actor, action và decision nào. Nó phù hợp cho business process, CI/CD, incident response, approval và runbook.

Ở Tiệm bánh Mây, happy path là kiểm tra món → thanh toán → gửi bếp. Hết món, payment declined và hoàn tiền là exception. Main path cần dễ thấy 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.

Test đọc nhanh: tại mỗi decision, người xem có biết điều kiện và bước tiếp theo không?

Scenario 5: Sequence — bản ghi thứ tự message

Sequence trả lời ai gọi ai, message nào đến trước và kết quả quay về thế nào. Nó hữu ích cho API contract, distributed tracing và debug integration.

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.

Test đọc nhanh: một engineer có thể đối chiếu các message trên hình với trace hoặc handler không?

Scenario 6: Data Flow — theo dấu dữ liệu

Data Flow không chỉ cho biết service nào nối với service nào. Nó cho biết dữ liệu nào được thu thập, biến đổi, lưu trữ hoặc gửi ra ngoài.

Với Tiệm bánh Mây, thông tin liên hệ và chi tiết đơn có thể lưu ở Order Store; payment request đi tới provider; ticket bếp chỉ cần món và ghi chú, không nhất thiết cần 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.

Test đọc nhanh: reviewer có biết dữ liệu nhạy cảm vượt qua boundary nào không?

Scenario 7: Lifecycle — bản đồ trạng thái

Lifecycle trả lời một entity có state nào và event hoặc guard nào cho phép chuyển state. Với order: DRAFT → AWAITING_PAYMENT → CONFIRMED → IN_KITCHEN → READY → COMPLETED; các đường CANCELLED 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.

Test đọc nhanh: có state nào không thể đi vào, không thể thoát ra, hoặc terminal state vẫn có transition vô lý không?

Pipeline đáng tin cậy

Một vòng làm việc thực tế:

Câu hỏi hẹp
→ evidence hoặc brief có ranh giới
→ typed JSON
→ validate
→ deliver HTML
→ visual-check
→ con người xem screenshots

Validation showcase thành công phải có đủ chín artifact checks, không có composition error hoặc warning. deliver tạo snapshot của specification, render và commit HTML atomically. Sau đó visual-check đo containment ở nhiều viewport và chụp light/dark evidence.

Tuy nhiên, automated receipt của visual-check vẫn để visualReview: "pending". Con người phải xem screenshots trước khi gọi artifact là polished. Và toàn bộ pipeline này chỉ kiểm tra artifact sơ đồ, không kiểm tra application behavior.

Demo đã verify

Bộ Tiệm bánh Mây gồm năm JSON source và năm standalone HTML. Cả năm đã pass 9/9 showcase, 0 composition error, 0 warning và automated visual-check. Human review đã xem light/dark ở viewport nhỏ nhất và lớn nhất; Workflow pass với ghi chú nhánh hoàn tiền dài nhưng không overflow.

Đây là evidence về Archify authoring pipeline. Không có application Tiệm bánh Mây thật được dựng hoặc chạy.

Các lỗi dễ gặp

Sơ đồ đẹp nhưng bịa topology. Yêu cầu evidence cho node và edge; phần thiếu phải là UNKNOWN.

Một hình trả lời quá nhiều câu hỏi. Tách theo Architecture, Workflow, Sequence, Data Flow và Lifecycle.

Gọi planning sketch là current architecture. Gắn PROPOSED ngay trong title/subtitle và handoff.

Coi validate là test ứng dụng. Báo hai status riêng: diagram verification và application verification.

Chạy visual-check sau khi deliver fail. Artifact cũ có thể vẫn còn ở output path. Chỉ visual-check khi delivery mới 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, validate showcase, deliver HTML,
chạy visual-check và báo human-review status riêng.
Không đánh đồng diagram validation với application test.

Nguồn chính thức

• Archify trên GitHub
• Archify Guide

Câu Hỏi Chưa Rõ

• Link tải public của bộ demo sẽ được gắn sau khi artifact được duyệt và phát hành.