Development

Archify 사용법: 코드와 시스템 설명을 검증 가능한 아키텍처 지도로 바꾸기

Archify가 코드베이스와 시스템 설명을 어떤 방식으로 인터랙티브 아키텍처 지도로 바꾸는지, 설치부터 첫 프롬프트·다이어그램 선택·검증·내보내기까지 따라 해본다.

오래된 코드베이스를 처음 열었을 때 가장 먼저 필요한 것은 파일 목록이 아니라 ‘이 시스템이 어떻게 움직이는가’에 대한 지도다. 요청이 어디에서 시작해 어떤 서비스와 저장소를 거치는지, 실패하면 어느 경로로 빠지는지, 데이터가 어느 경계를 넘는지를 한눈에 보고 싶다. 하지만 손으로 그린 다이어그램은 코드와 빠르게 어긋나고, 자동 생성 도구는 읽기 어려운 상자와 화살표를 쏟아내기 쉽다.

Archify는 이 간극을 겨냥한 오픈소스 에이전트 스킬이다. 코드베이스 또는 자연어 시스템 설명을 입력하면 에이전트가 타입이 있는 JSON 중간 표현(IR)을 만들고, Archify가 이를 결정적으로 렌더링하고 검증해 하나의 인터랙티브 HTML 시스템 지도로 완성한다. Cursor, Claude Code, Codex CLI, OpenCode에서 사용할 수 있으며 MIT 라이선스로 공개돼 있다.

이 글에서는 Archify가 무엇을 해결하는지부터 설치, 첫 다이어그램 만들기, 유형 선택, 수정과 검증, 공유까지 실제 사용 흐름을 차례로 살펴본다. 본문은 2026년 8월 30일 기준 안정 릴리스 v2.15.0과 공식 문서를 기준으로 작성했다. 저장소의 개발 버전은 v2.16.0-dev.0이므로 명령과 기능은 이후 달라질 수 있다.

Archify는 단순한 Mermaid 테마가 아니다

Archify의 입력은 두 가지다. 이미 존재하는 저장소를 분석하게 하거나, 저장소 없이 채팅에서 시스템을 설명할 수 있다. 출력은 단순 스크린샷이 아니라 검색·경로 추적·업스트림과 다운스트림 탐색·역할 비교·발표 모드를 포함한 자체 완결형 HTML이다. 필요하면 PNG, SVG, WebM, 1200×630 공유 카드로도 내보낼 수 있다.

핵심은 ‘그럴듯한 그림’보다 재현 가능한 구조에 있다.

타입이 있는 JSON IR: 다이어그램의 노드, 관계, 뷰와 메타데이터를 구조화된 원본으로 유지한다.
결정적 렌더링: 같은 검증된 입력은 같은 결과로 컴파일된다. 수정할 때도 전체 그림을 매번 새로 상상하는 대신 필요한 사실만 바꿀 수 있다.
원자적 검증: 스키마, 레이아웃, HTML·SVG, 경로, 라벨과 선의 충돌을 검사한다. 실패한 후보가 마지막 정상 산출물을 덮어쓰지 않는다.
사실에 묶인 상호작용: 경로와 영향 범위를 즉석에서 추측하지 않고 작성된 노드와 관계만 재사용한다.
휴대 가능한 결과: 결과물이 하나의 HTML 파일이므로 별도 호스팅 서비스 없이 열고 전달할 수 있다.

Archify가 Signal Flow, Blueprint, Classic 프리셋의 검증된 시스템 지도를 순서대로 재생하는 애니메이션 — Archify가 만든 실제 인터랙티브 산출물 세 가지를 순서대로 재생한 모습. 공식 원본 보기

반대로 Archify는 범용 드로잉 편집기, WYSIWYG 캔버스, 자동 Mermaid 변환기, 호스팅 공유 서비스가 아니다. 사람이 직접 픽셀 단위로 배치하는 도구가 아니라, 에이전트가 기술적 의도를 구조화하고 검증된 전달물로 만드는 작업 흐름에 가깝다.

설치 전에 준비할 것

기본 렌더러와 검증기는 Node.js로 동작한다. 또 Archify는 독립형 챗봇이 아니라 에이전트 스킬이므로 Cursor, Claude Code, Codex CLI, OpenCode처럼 스킬을 읽고 로컬 명령을 실행할 수 있는 환경이 필요하다. 다이어그램을 만들 대상 저장소가 없어도 시작할 수 있지만, 코드 근거가 필요한 문서라면 해당 저장소를 에이전트가 읽을 수 있어야 한다.

가장 간단한 전역 설치 명령은 다음과 같다.

npx skills add tt-a1i/archify -g

설치하지 않고 Codex에서 시험하려면 다음 명령을 사용할 수 있다.

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

Cursor에 묻지 않고 명시적으로 전역 복사하려면 에이전트와 설치 범위를 함께 지정한다.

npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes

Claude Code는 ~/.claude/skills/, Codex CLI는 ~/.agents/skills/, OpenCode는 ~/.config/opencode/skills/ 또는 프로젝트별 스킬 경로를 사용할 수 있다. 환경마다 설치 위치가 다르므로 공식 에이전트별 빠른 시작에서 현재 사용하는 도구를 선택하는 편이 안전하다.

1분 만에 첫 시스템 지도 만들기

저장소가 없다면 시스템을 문장으로 설명하고 Archify 사용을 명시하면 된다.

Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback.

실제 저장소에서는 무엇을 분석하고 어느 수준으로 요약할지 알려주는 편이 결과가 좋다.

Analyze this repository, then use Archify to create a high-level runtime architecture diagram.
Show 8–12 core components, one primary path, external dependencies, and trust boundaries.
Put supporting detail in cards instead of adding more edges.

좋은 요청에는 네 가지가 들어간다. 범위, 핵심 구성요소 수, 주요 실행 경로, 반드시 보여야 할 경계나 예외다. “이 저장소를 예쁘게 그려줘”처럼 목표가 모호하면 세부 파일과 관계가 과도하게 늘어나기 쉽다. 반대로 노드를 정확히 10개로 고정하는 식의 지나친 제약은 중요한 사실을 누락시킬 수 있다.

목적에 맞는 다이어그램 유형 고르기

Archify는 다섯 가지 유형을 제공한다. 같은 시스템이라도 어떤 질문에 답하려는지에 따라 선택이 달라진다.

Architecture: 서비스, 저장소, 외부 시스템, 신뢰 경계를 한 장에 볼 때 사용한다. “구성요소가 무엇이고 어떻게 연결되는가”에 답한다.
Workflow: CI/CD, 승인, 도구 호출, 운영 절차처럼 참여자별 순서와 분기·예외를 보여준다.
Sequence: API 요청, 인증, 캐시 미스, 비동기 호출처럼 시간 순서가 중요한 한 번의 상호작용을 설명한다.
Data Flow: 데이터의 출처, 변환, 저장, 소비자, 개인정보 경계를 추적한다.
Lifecycle: 작업 상태, 대기, 재시도, 취소와 성공·실패 같은 종료 상태를 표현한다.

예를 들어 “웹 요청이 Redis에서 캐시 미스 난 뒤 PostgreSQL을 조회하고 캐시를 갱신하는 과정”은 전체 구조를 보여주려면 Architecture, 호출 순서를 검토하려면 Sequence가 적합하다. 어떤 유형인지 확신하기 어렵다면 CLI 가이드에 질문할 수 있다.

node archify/bin/archify.mjs guide "Show an API request with Redis cache miss"
node archify/bin/archify.mjs guide "Map Kafka topics, consumer groups, replay, and DLQ" --json

Archify Sequence 다이어그램에서 Web App부터 API와 Postgres까지 캐시 미스 요청 경로를 강조한 화면 — Cache Miss Request Sequence에서 PATH 기능으로 Web App → API → Postgres의 작성된 최단 경로를 추적한 실제 화면. 공식 원본 보기

채팅으로 수정할 때는 한 번에 한 가지를 바꾼다

첫 결과가 나온 뒤에는 “Redis를 추가해”, “인증 서비스를 왼쪽으로 옮겨”, “롤백 경로를 강조해”처럼 좁은 요청으로 다듬는다. Archify는 JSON 원본을 유지하므로 관련 없는 구조를 그대로 둔 채 목표 부분을 수정하기 좋다.

특히 코드 근거가 필요한 경우에는 ‘추측하지 말고 확인한 소스만 표시하라’고 요청한다. 증거 기반 Architecture는 노드에 소스 참조를 붙이고 공개 Git 커밋에 고정된 파일과 줄 범위를 열 수 있다. 다만 이 기능은 요청했을 때만 적용되며, 로컬의 수정 중인 코드나 실행 중인 인프라를 자동으로 사실로 간주하지 않는다.

설계 변경이나 PR을 검토할 때는 검증된 두 스냅샷을 Before / Delta / After로 비교할 수 있다.

node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json

Delta는 추가·삭제·변경·이동·경로 변경처럼 작성된 사실을 비교한다. 위험도, 영향 범위, 병합 가능성을 자동으로 추론해 주는 도구는 아니므로 최종 판단은 리뷰어가 해야 한다.

Archify Architecture Delta가 병합 전 추가·삭제·변경된 구성요소를 비교하는 화면 — 검증된 두 Architecture 스냅샷을 Before / Delta / After로 비교하는 실제 화면. 추가 2개, 삭제 2개, 변경 5개처럼 작성된 차이를 검토한다. 공식 원본 보기

검증하고 전달하는 로컬 CLI 흐름

에이전트가 만들어 준 산출물을 더 엄격하게 다루려면 저장소 안의 CLI를 직접 사용할 수 있다.

cd archify
node bin/archify.mjs doctor
node bin/archify.mjs demo /tmp/archify-demo
node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json
node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --open --json

doctor는 실행 환경을 점검하고, validate는 JSON 원본의 규칙 위반을 구조화된 진단으로 돌려준다. deliver는 같은 디렉터리에 후보를 렌더링해 검사를 통과한 경우에만 최종 HTML을 교체한다. 실패 시에는 스택 트레이스 대신 규칙 코드, 문제가 된 대상, 측정값과 지원되는 수정 방법을 JSON으로 받을 수 있다.

수정하면서 결과를 계속 확인하려면 preview를 쓴다.

node bin/archify.mjs preview workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase

Preview는 임의의 127.0.0.1 포트에서 한 JSON 파일을 감시한다. 새 저장본이 검증을 통과할 때만 화면을 새로 고치고, 잘못된 후보가 들어오면 마지막 정상 결과를 유지한다. 테스트나 원격 환경에서는 --no-open으로 브라우저 자동 실행을 끌 수 있다.

완성된 지도를 읽고 공유하는 방법

HTML을 열면 단순 확대·축소 외에도 구조를 탐색하는 기능을 사용할 수 있다.

/: 노드를 검색하고 포커스한다.
R: 두 노드 사이에 작성된 방향 경로를 추적한다.
L: 백엔드와 데이터베이스처럼 의미 역할을 비교한다.
M: 전체 구조를 보는 오버뷰 지도를 연다.
P: 미리 작성한 설명 순서를 재생한다.
F: 발표 모드로 전환한다.
S, T, E: 시각 스타일, 테마, 내보내기 메뉴를 연다.

포커스, 업스트림·다운스트림 범위, 관계, 경로, 뷰는 URL 해시로 복원할 수 있다. 예를 들어 #route=web~db는 작성된 Web에서 DB까지의 경로를 연다. 내보내기 메뉴에서는 정적 이미지뿐 아니라 현재 경로나 도달 범위를 문맥과 함께 담은 1200×630 공유 카드를 만들 수 있다.

Archify 시스템 지도에서 공유 카드와 PNG·JPEG·WebP·SVG·WebM을 선택하는 Export 메뉴 — 완성된 시스템 지도에서 공유 카드 복사와 PNG·JPEG·WebP·SVG·WebM 내보내기를 선택하는 실제 메뉴. 공식 원본 보기

실무에서 잘 맞는 사용처

온보딩: 새 팀원이 저장소를 읽기 전에 핵심 런타임 경로와 외부 의존성을 파악한다.
PR·설계 리뷰: 변경 전후에 어떤 노드와 관계가 달라졌는지 사실 단위로 비교한다.
장애 회고: 요청 경로, 재시도, 폴백과 병목을 Sequence나 Workflow로 정리한다.
데이터 거버넌스: 개인정보와 이벤트가 어느 저장소와 소비자를 지나가는지 Data Flow로 확인한다.
운영 런북: 대기·재시도·취소·종료 상태를 Lifecycle로 명시한다.

다만 다이어그램은 코드와 운영 상태 자체가 아니다. Archify가 저장소에서 읽은 관계는 정적 근거이며, 실제 트래픽·권한·배포 위치·장애 영향은 별도의 관측 데이터와 검증이 필요하다. 보기 좋은 그림이 만들어졌다는 이유로 운영 사실까지 확인됐다고 간주하면 안 된다.

업데이트 확인과 네트워크 설정

Archify는 선택적 업데이트 알림을 위해 고정된 안정 버전 매니페스트를 조회할 수 있다. 공식 설명에 따르면 이 요청은 업데이트를 자동으로 내려받거나 설치하지 않으며, 버전·에이전트·프로젝트 데이터·프롬프트·계정 또는 장치 식별자를 보내지 않는다. 서버에는 일반적인 HTTP 메타데이터인 IP와 시각이 보일 수 있다.

네트워크 조회와 알림 상태 기록을 모두 끄려면 다음 환경 변수를 설정한다.

export ARCHIFY_UPDATE_CHECK_DISABLED=1

보안이 엄격한 저장소에서는 설치 전 보안 문서와 스킬이 실행하는 로컬 명령을 검토하고, 공개 링크에 소스 경로와 내부 구성 정보가 포함되지 않는지 확인해야 한다.

마무리: 다이어그램 생성보다 검증 가능한 대화가 중요하다

Archify의 장점은 에이전트에게 “아키텍처 그림 하나 만들어줘”라고 말할 수 있다는 데만 있지 않다. 자연어 요청을 구조화된 원본으로 남기고, 렌더링 전에 규칙을 검사하며, 완성된 지도에서 실제로 작성된 관계만 탐색하게 만든다는 점이 더 중요하다.

처음에는 작은 범위로 시작하는 편이 좋다. 저장소 전체보다 하나의 요청 경로를 골라 8~12개 핵심 구성요소로 Architecture를 만들고, 캐시 미스나 인증처럼 시간이 중요한 부분만 Sequence로 분리해 보자. 결과를 팀과 검토한 뒤 틀린 관계를 JSON 원본에서 고치고 검증을 다시 통과시키면, 한 번 보고 버리는 그림이 아니라 코드와 함께 관리할 수 있는 시스템 지도로 발전시킬 수 있다.