Archify
Archify 详解：为 AI 编程代理生成可验证的架构图
了解 Archify 如何把类型化 JSON 编译为可验证的 HTML/SVG，并运行一次最小代理技能实验。
你将学会
- Explain the JSON-IR-to-render pipeline
- Create a bounded, source-traceable architecture map
- Preserve revisions and validation evidence for review
开始前需要
- Basic Git and command-line usage
- Comfort reading a project README
You can explain the project, run its documented first step, and decide what to verify before adopting it.
先看结论
- Archify compiles typed JSON IR into deterministic, exportable diagrams.
- Validation and source tracing make the visual output reviewable rather than purely decorative.
- Pin the release and preserve the input revision when using generated maps in engineering work.
The short answer
Archify 是面向 Cursor、Claude Code、Codex CLI 和 OpenCode 的 Node.js 渲染与校验系统。README 定义了清晰边界：代理生成类型化 JSON 中间表示，Archify 再把它确定性地编译为 HTML 和 SVG。
That boundary matters for engineering teams. Archify is designed for architecture, workflow, sequence, data-flow, and lifecycle diagrams, with search, route tracing, guided stories, and Before/Delta/After comparison between validated snapshots. The project page reports stable version v2.16.0 for the captured snapshot, so article examples should pin the version they actually test.
How the workflow is grounded
The agent-facing workflow starts with a description or codebase context and produces an explicit JSON IR. Validation then becomes a gate before rendering. Interactions such as opening revision-verified source, tracing upstream and downstream reach, and comparing roles are useful because they expose the authored facts behind a visual edge instead of hiding them in a screenshot.
The README advertises five diagram types, four presets, dark and light themes, finite motion, and self-contained output. It also lists PNG, SVG, WebM, and 1200×630 share-card exports. These are output contracts to verify in a local run, not a reason to assume every input is semantically complete; a polished render can still describe an incomplete model if the source facts were missing.
Run the smallest useful experiment
The documented global installation path is `npx skills add tt-a1i/archify -g`. You can use the skill from a supported agent without cloning a target repository, then ask for a small architecture map with named nodes and explicit relationships. Keep the input bounded: a checkout, a service boundary, or one request flow is easier to validate than an entire organization.
For repeatable work, record the Archify release, agent host, input commit, selected diagram type, and export format. Compare the rendered output with the JSON IR and inspect one or two source links. If a node or route cannot be traced back to authored input, mark it as an unresolved fact instead of filling the gap with a plausible arrow.
When Archify is a good fit
Use Archify when a team needs architecture communication that remains inspectable during review: onboarding, design proposals, incident follow-up, or a before/after comparison of a refactor. The deterministic compiler is especially useful when diagrams are generated repeatedly in CI or attached to a change review.
It is less suitable as a substitute for a system inventory. A diagram is only as complete as the codebase context and authored JSON supplied to it, and a share card is not an audit trail. Keep the input revision, validation output, and rendered artifact together so a future reader can reproduce the map rather than trusting the image alone.
如何选择
| 比较维度 | 方案 A | 方案 B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
实施步骤
- 1
Install the skill with `npx skills add tt-a1i/archify -g`.
- 2
Give the agent one bounded codebase flow with named components and relationships.
- 3
Inspect validation results and trace representative nodes back to source.
- 4
Export the format you need and archive the input revision beside the artifact.
可复制示例
npx skills add tt-a1i/archify -g
# In a supported agent, request a bounded map:
# "Map the request flow from API gateway to worker and database; cite each edge."常见问题
Does Archify require a repository?
The README says no repository is required for a described system, but repository context and revision metadata improve verifiability when you are mapping real code.
Is the diagram itself proof that the architecture is correct?
No. Treat validation, source traces, and the preserved input revision as the evidence; the rendered diagram is the readable projection.
资料来源
- Archify README (captured 2026-08-31)来源核查 2026-08-31
- Archify repository来源核查 2026-08-31