Archify 쓰는 법

Archify(tt-a1i/archify)는 코드베이스나 시스템 설명을 검증 가능한 인터랙티브 HTML 다이어그램으로 바꿔 주는 에이전트 스킬이다. 코딩 에이전트가 타입이 잡힌 JSON IR을 내고, Archify가 그걸 HTML/SVG로 결정적으로(deterministic) 컴파일한다. Cursor·Claude Code·Codex CLI·OpenCode 하네스에서 바로 쓰는 검색형 가이드다.

이 글은 “Archify 쓰는 법”만 따라간다. 설치 → 설명/레포 분석 → 에이전트에게 Archify 사용 요청 → 채팅으로 다듬기, 그리고 레포 CLI의 doctor/validate/deliver까지 README·프로젝트 페이지 기준으로만 적는다.

핵심 요약 (TL;DR)

• 무엇인가: 에이전트가 쓴 typed JSON IR → 검증 후 self-contained HTML/SVG 시스템 맵. Architecture·Workflow·Sequence·Data Flow·Lifecycle 다섯 타입.
• 누구용: Cursor 등 코딩 에이전트로 아키텍처·워크플로를 “말로 그려” 공유하고 싶은 사람. 레포 없이도 설명만으로 시작 가능.
• 요구사항: Node.js >=18 (archify/package.json engines).
• 설치(글로벌 스킬): npx skills add tt-a1i/archify -g
• Cursor 명시 설치: npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes
• 설치 없이 체험: npx skills use tt-a1i/archify@archify --agent codex
• 버전(작성 시점): README·package.json 기준 개발판 2.17.0-dev.1 (README가 development로 표시, Changelog 참고). 라이선스 MIT.

할 수 있는 일

먼저 용어만 짧게 풀어 둔다.

• 코딩 에이전트: Cursor, Claude Code, Codex CLI, OpenCode처럼 에디터·터미널 안에서 코드를 쓰고 명령을 실행하는 AI 조수.
• 스킬(agent skill): 에이전트가 읽는 짧은 지침·도구 묶음. Archify를 스킬로 넣으면 “시스템 맵 그려줘” 요청이 검증·렌더 워크플로로 간다.
• JSON IR: Intermediate Representation. 다이어그램의 노드·엣지·메타를 타입이 있는 JSON으로 적어 둔 중간 표현. 에이전트가 쓰고 Archify가 읽는다.
• Deterministic(결정적) 컴파일: 같은 JSON IR이면 같은 HTML/SVG가 나오도록 검증·렌더 게이트를 통과한 뒤만 산출물을 교체한다.
• 하네스: 에이전트가 도구·스킬·CLI를 붙잡고 작업을 돌리는 실행 틀. Raven은 ZIP 수동 설치 경로도 README에 있다.

공식 README가 말하는 산출물·기능이다.

• 컴포넌트·서비스·경계가 보이는 Architecture 맵
• CI/CD·승인·툴 호출 같은 Workflow
• API·캐시 미스·인증 흐름의 Sequence
• 파이프라인·민감 데이터 경계의 Data Flow
• 상태·재시도·종료를 나누는 Lifecycle
• 비주얼 프리셋 Classic / Signal Flow / Blueprint / Editorial, 다크·라이트 전환
• self-contained HTML 한 장 + PNG·SVG·WebM·1200×630 공유 카드보내기
• 두 스냅샷을 Before / Delta / After로 비교하는 Architecture Delta (머지 전 리뷰용)

필요한 것

레포가 없어도 된다. README는 “시스템만 설명하면 어떤 에이전트 채팅에서든 시작”이라고 적는다. 프로젝트 페이지·시나리오 가이드·Proof Lab도 공개되어 있다.

• 프로젝트: tt-a1i.github.io/archify
• 시나리오 가이드: guide.html
• Proof Lab: gallery.html
• Cursor 빠른 시작: start.html?agent=cursor&type=architecture

단계

1) 설치

글로벌 스킬(README 기본):

npx skills add tt-a1i/archify -g

Cursor를 비대화형·명시적으로 맞출 때:

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

설치 없이 Codex로 한 번 써 보기:

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

에이전트 스위처(cursor/codex/claude-code/opencode)는 프로젝트 start 페이지가 담당한다. Raven은 스위처 대상이 아니고, archify.zip을 ~/.raven/workspace/skills에 풀어 .../skills/archify가 나오게 한다.

선택 업데이트 확인: Archify는 안정 매니페스트에 optional GET만 하고 자동 설치는 하지 않는다. 네트워크·리마인더를 끄려면 ARCHIFY_UPDATE_CHECK_DISABLED=1.

2) 설명만으로 그리기 — 레포 불필요

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

한국어로 말해도 된다. 예: “브라우저 → API → Redis 캐시 → PostgreSQL 폴백을 Archify로 그려줘.”

3) 레포를 근거로 맵 만들기

워크스페이스에 레포를 연 뒤 README가 권장하는 프롬프트 예:

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.

4) 채팅으로 다듬기

add Redis, move auth to the left, highlight the rollback path처럼 짧게 이어서 요청한다. typed source가 남아 있어서 관련 없는 구조는 흔들리지 않게 반복한다고 README가 설명한다.

5) 레포 사용자용 CLI — doctor → validate → deliver

클론한 뒤 archify 디렉터리에서 README Useful repository commands:

cd archify
node bin/archify.mjs doctor
node bin/archify.mjs demo /tmp/archify-demo
node bin/archify.mjs guide "Show CI/CD checks, approval, deploy, and rollback"
node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json
node bin/archify.mjs preview workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase
node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --open --json

타입 고르기 힌트:

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

Architecture Delta 비교:

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

validate --json / deliver --json 실패 시에는 스택 트레이스 대신 규칙 코드·대상·측정 증거·허용된 수리 컨트롤이 나온다. Skill은 수정 라운드를 두 번까지로 두고, 시각 리뷰는 별도라고 README가 적는다.

막히는 지점

버전 확인

# 클론한 패키지 버전
node -p "require('./archify/package.json').version"
# 또는
cat archify/package.json | grep '"version"'

이 글을 쓰는 시점(2026-09-18, Asia/Seoul)에 README 배지·archify/package.json에서 확인한 값: 개발판 2.17.0-dev.1 (README가 Current development version으로 표시, Changelog Unreleased 참고), license MIT, engines.node >=18. 숫자·플래그는 설치본과 공식 README·Changelog가 최종 권위다.

마치며

Archify 쓰는 법은 단순하다. 스킬을 심고, 시스템을 말하거나 레포를 분석시킨 뒤 “Archify로 그려줘”라고 하면 된다. 레포를 깊게 쓰면 doctor → validate --json → deliver --open --json으로 같은 게이트를 CLI에서 돌린다. 검색으로 “에이전트 아키텍처 다이어그램 스킬”을 찾는 사람에게는 이 루프면 충분하다.

더 볼 곳: tt-a1i/archify, 프로젝트 페이지, Proof Lab, 시나리오 가이드.

이 글은 AI가 작성하여 자동 발행된 콘텐츠입니다.