Archify란? 코드를 인터랙티브 아키텍처 다이어그램으로 바꾸는 AI 에이전트 스킬

목차

1. 개요
2. Archify의 동작 원리 — JSON 중간 표현과 검증 게이트
3. Archify 다이어그램 종류와 뷰어 기능
4. 코드 저장소를 아키텍처 다이어그램으로 — 소스 근거 연결
5. Archify 설치와 도입 전 체크포인트
6. 맺음말

개요

Archify가 해결하려는 문제

아키텍처 다이어그램은 그리는 순간부터 낡기 시작합니다. 코드가 바뀌어도 그림은 누군가 손으로 고치기 전까지 그대로이고, 새로 합류한 사람은 그 그림이 지금 코드와 맞는지 확인할 방법이 없습니다. Archify는 이 문제를 AI 코딩 에이전트에게 맡기는 도구입니다. Claude Code, Codex CLI, Cursor 같은 에이전트에 스킬로 설치해 두고 "이 저장소의 런타임 아키텍처를 그려 줘"라고 요청하면, 에이전트가 코드를 읽고 인터랙티브 아키텍처 다이어그램을 HTML 파일 하나로 만들어 줍니다.

이 글은 Archify v3.2.0(2026-10-18 릴리스) 저장소의 README, SKILL.md, 스키마, 예제를 읽고 정리했습니다.

제작자는 2026년 9월 초 GitHub Trending 주간 1위 화면을 공개하기도 했습니다.

기존 다이어그램 도구와 무엇이 다른가

Mermaid나 PlantUML 같은 텍스트 기반 다이어그램은 사람이 문법을 써서 그림을 그립니다. Archify는 사람이 문법을 쓰지 않습니다. 에이전트가 정해진 스키마의 JSON을 쓰고, Archify가 그 JSON을 검증한 뒤 그림으로 바꿉니다. 사람은 자연어로 요청하고 결과를 확인합니다.

Archify는 범용 드로잉 편집기도, Mermaid 테마도 아니라고 스스로 밝힙니다. 기술적 의도를 전달용 산출물로 바꾸는 도구라는 것이 프로젝트의 정의입니다.

Archify의 동작 원리 — JSON 중간 표현과 검증 게이트

타입이 정해진 JSON 중간 표현

Archify의 핵심은 **타입이 정해진 JSON 중간 표현(IR, Intermediate Representation)**입니다. 에이전트는 SVG 좌표를 바로 그리지 않고, 다이어그램 종류마다 정해진 스키마에 맞춰 노드, 관계, 경계, 레이블을 JSON으로 적습니다. 렌더러는 이 JSON만 보고 그림을 만들기 때문에 같은 JSON에서는 항상 같은 그림이 나오고, "Redis 추가해 줘" 같은 후속 요청도 JSON의 해당 부분만 고치면 됩니다.

아래는 저장소에 들어 있는 캐시 미스 시퀀스 예제(archify/examples/cache-miss-request.sequence.json)에서 y 좌표 등 일부 필드를 빼고 옮긴 것입니다. 참여자와 메시지가 각각 의미 있는 타입(backend, database, return 등)을 갖습니다.

{
  "schema_version": 1,
  "diagram_type": "sequence",
  "meta": { "title": "Cache Miss Request Sequence", "quality_profile": "showcase" },
  "participants": [
    { "id": "api",   "type": "backend",  "label": "API",      "sublabel": "request handler" },
    { "id": "redis", "type": "database", "label": "Redis",    "sublabel": "cache" },
    { "id": "db",    "type": "database", "label": "Postgres", "sublabel": "source of truth" }
  ],
  "messages": [
    { "id": "cache-read",    "from": "api",   "to": "redis", "label": "read cache", "variant": "default" },
    { "id": "cache-miss",    "from": "redis", "to": "api",   "label": "miss",       "variant": "return" },
    { "id": "profile-query", "from": "api",   "to": "db",    "label": "query profile + metrics", "variant": "emphasis" }
  ]
}

JSON을 거치는 구조 덕분에 사람이 다이어그램을 직접 손보지 않아도 에이전트가 고칠 지점을 정확히 짚을 수 있습니다. 반대로 말하면, 에이전트가 쓴 JSON이 틀리면 그림도 틀립니다. 그래서 다음 단계의 검증이 중요합니다.

finalize — 네 단계 검증 게이트

에이전트가 JSON 후보를 다 쓰면 finalize 명령 하나로 검증부터 전달까지 진행합니다. 네 개의 게이트를 차례로 통과해야 HTML이 나오고, 하나라도 실패하면 거기서 멈춥니다.

에이전트가 쓴 JSON은 네 게이트를 모두 통과해야 HTML이 되고, 실패하면 진단 JSON을 보고 최대 두 번 고칩니다.

SKILL.md는 통과한 영수증이 있어야만 성공으로 보라고 못 박습니다. 0이 아닌 종료 코드는 어떤 경우에도 성공이 아니며, 에이전트는 실패한 게이트의 진단을 읽고 고친 뒤 finalize를 처음부터 다시 돌립니다.

실패를 기계가 읽는 진단으로 돌려준다

에이전트 도구에서 흔히 보는 실패는 Node 스택 트레이스나 "다시 해 보세요" 같은 막연한 메시지입니다. Archify는 validate --json과 deliver --json이 실패하면 JSON 객체 하나를 돌려줍니다. 여기에는 안정적인 규칙 코드, 문제가 된 대상, 측정된 근거, 그 문제에 대해 지원하는 수정 방법(supportedFixes)이 들어 있습니다.

스킬은 수정 라운드를 두 번으로 제한합니다. 에이전트가 같은 문제를 붙잡고 무한히 재시도하지 않게 하려는 장치입니다. 앞서 다룬 LLM Tool Calling 설계 패턴 글에서 도구 응답을 구조화하면 에이전트 신뢰성이 올라간다고 정리했는데, Archify의 진단 형식이 그 원칙을 그대로 따르는 사례입니다.

원자적 교체와 마지막 정상본

deliver는 결과 파일을 바로 덮어쓰지 않습니다. 같은 디렉터리에 후보를 따로 만들고, 검사를 통과한 경우에만 기존 파일을 한 번에 교체합니다.

검사에 실패한 후보는 기존 파일을 건드리지 못하고, 실패 영수증만 남깁니다. 선택 사항인 preview 모드도 같은 원칙을 따라, JSON을 저장하다 깨진 상태가 되면 마지막 정상본을 계속 보여 줍니다.

Archify 다이어그램 종류와 뷰어 기능

열 가지 다이어그램 종류

v3.0까지는 다섯 종류였고, v3.1(2026-10-14)에서 ERD, Class, Tree, Timeline, Waterfall이 더해져 열 종류가 되었습니다. 어떤 종류를 쓸지 애매하면 guide 명령에 상황을 문장으로 주면 알맞은 종류를 골라 줍니다.

Timeline과 Waterfall은 예시 값이 들어가기 쉬운 종류입니다. README는 로그나 트레이스에서 나온 값일 때만 실측으로 다루라고 따로 적어 둡니다.

단독 HTML 뷰어에서 할 수 있는 일

결과물은 HTML 파일 하나입니다. 받는 사람이 Archify를 설치하지 않아도 브라우저로 열면 탐색 기능이 그대로 동작합니다. 키보드 단축키가 많아서 발표나 리뷰 자리에서 쓰기 좋습니다.

포커스나 경로 상태는 #focus=api&reach=downstream 같은 주소 조각으로 남기 때문에, 특정 관점을 링크 하나로 공유할 수 있습니다. 문서에 따르면 상류·하류 추적은 작성된 관계만 따라가며, 런타임 영향 범위를 추정했다고 주장하지 않습니다.

한 페이지 답변(explainer) — v3.2 신규 기능

v3.2.0에서는 한 페이지짜리 설명 문서를 만드는 기능이 추가되었습니다. "P99 지연이 80ms에서 600ms로 뛰었는데 원인이 뭘까, 한 페이지로 답해 줘"처럼 요청하면 결론을 맨 앞에 두고 질문마다 패널 하나씩 표·단계·차트·다이어그램을 배치합니다. 스타일 네 가지와 라이트·다크 테마를 고를 수 있고, 긴 이미지나 PDF로 내보낼 수 있습니다.

결론 먼저, 패널 하나에 질문 하나. 장애 회고나 설계 검토처럼 "그림 + 설명"이 필요한 문서를 맡길 때 쓸 만합니다.

코드 저장소를 아키텍처 다이어그램으로 — 소스 근거 연결

저장소 근거가 노드에 붙는 과정

Archify가 다른 그림 도구와 가장 크게 갈리는 지점이 **소스 근거(source evidence)**입니다. 실제 저장소를 그릴 때 에이전트는 진입점에서 출발해 호출 지점을 따라가고, 컴포넌트와 관계마다 파일 경로와 줄 범위를 기록합니다. 근거가 붙은 노드에는 SRC n 표시가 생기고, 뷰어에서 누르면 고정된 커밋의 해당 줄을 보여 주는 소스 카드가 열립니다.

근거는 고정된 커밋의 바이트에서만 나오며, 커밋되지 않은 작업 트리 변경분은 근거로 쓰지 않습니다.

근거 없는 관계를 만들지 않는 규칙

저장소 작성 가이드(references/repository-authoring.md)에는 에이전트가 지켜야 할 규칙이 꽤 엄격하게 적혀 있습니다. 핵심은 보지 않은 것을 그리지 않는다는 것입니다.

노드나 관계 개수에 목표치가 없다는 점도 눈에 띕니다. 요청한 책임과 관계가 근거로 덮이면 탐색을 멈추라고 되어 있습니다. LLM이 그럴듯한 레이블을 지어내 빈칸을 채우는 경향을 정면으로 막으려는 설계로 읽힙니다.

변경 전후 비교 — Architecture Delta

설계 리뷰나 PR 리뷰에는 compare 명령이 있습니다. 변경전 아키텍처 JSON과 변경후 JSON을 주면 추가·삭제·변경·이동된 요소를 한 장의 델타 다이어그램으로 그리고, 기계가 읽는 영수증을 함께 남깁니다.

델타 그림은 "무엇이 바뀌었는지"만 보여 줍니다. README는 영향도, 위험도, 머지 안전성을 추론하지 않는다고 명시하며, "그래서 괜찮은지"는 여전히 리뷰어의 몫입니다.

Archify 설치와 도입 전 체크포인트

설치와 첫 요청

설치는 skills CLI로 한 줄이면 됩니다. -g를 붙이면 전역 스킬로 설치되어 모든 프로젝트에서 쓸 수 있습니다. Claude.ai에서는 설정의 Skills 메뉴에 archify.zip을 올려 쓸 수 있지만, 검증 게이트가 Node.js로 돌기 때문에 샌드박스에서 Node를 쓸 수 없으면 검증 없는 대체 경로로 떨어집니다.

# 전역 설치 (Claude Code는 ~/.claude/skills/, Codex는 ~/.agents/skills/ 아래에 들어간다)
npx skills add tt-a1i/archify -g

# 설치 없이 한 번만 써 보기
npx skills use tt-a1i/archify@archify --agent codex

설치한 뒤에는 에이전트에게 자연어로 요청하면 됩니다. 저장소가 없어도 설명만으로 그릴 수 있고, 저장소를 열어 둔 상태라면 코드 근거가 붙은 그림을 요청할 수 있습니다.

이 저장소를 분석해서 Archify로 상위 수준 런타임 아키텍처 다이어그램을 만들어 줘.
핵심 컴포넌트 8~12개, 주 경로 하나, 외부 의존성, 신뢰 경계를 보여 주고,
세부 내용은 관계선을 늘리지 말고 카드에 넣어 줘.

README의 예시 요청을 옮긴 것입니다. 컴포넌트 수, 주 경로, 경계처럼 범위를 먼저 정해 주는 것이 결과 품질을 좌우합니다. 그림이 나온 뒤에는 "인증 추가해 줘", "캐시 미스 경로 강조해 줘"처럼 이어서 다듬습니다. 에이전트에게 프로젝트 맥락을 넘기는 방식은 Cursor Rules 설계 글에서 다룬 원칙이 그대로 적용됩니다.

CLI로 직접 다루기

에이전트 없이 CLI를 직접 부를 수도 있습니다. 외부 의존성이 없는 Node 스크립트라서 저장소를 받아 바로 실행하면 됩니다. 평소에는 finalize만 알면 되고, 종류를 고르기 어려울 때 guide, 리뷰할 때 compare를 씁니다.

cd archify
node bin/archify.mjs doctor                          # 환경 진단
node bin/archify.mjs guide "Show CI/CD checks, approval, deploy, and rollback"   # 다이어그램 종류 추천
node bin/archify.mjs finalize workflow examples/agent-tool-call.workflow.json /tmp/workflow.html \
  --quality showcase --json                          # 검증부터 전달까지 한 번에
node bin/archify.mjs compare architecture base.json head.json delta.html --json  # 변경 전후 비교

한계와 범위 밖의 것

프로젝트가 스스로 밝힌 한계도 분명합니다. README는 자동 Mermaid 파싱, 범용 자동 레이아웃, 호스팅 공유, WYSIWYG 편집을 현재 범위 밖이라고 적습니다.

특히 첫 번째 항목이 중요합니다. SKILL.md도 검증 결과를 보고할 때 "자동 검사 통과, 시각 검토는 안 함"처럼 구분해서 말하라고 지시합니다. 게이트를 통과했다는 것은 스키마와 레이아웃 규칙을 지켰다는 뜻이지, 독자가 읽기 쉬운 그림이라는 뜻은 아닙니다.

네트워크 요청과 서드파티 서비스

보안 검토가 필요한 팀이라면 네트워크 동작을 확인해 둘 만합니다.

README에는 API 중계 서비스 후원 배너가 여럿 있지만, 프로젝트도 밝히듯 Archify와는 별개인 서드파티입니다. 에이전트의 API 경로를 그쪽으로 바꾸는 것은 Archify 도입과 전혀 다른 판단입니다.

맺음말

Archify는 "에이전트가 그림을 그린다"는 아이디어 자체보다, 그 그림을 믿을 수 있게 만드는 장치에 공을 들인 도구입니다. 타입이 정해진 JSON 중간 표현, 네 단계 검증 게이트, 실패 시 기계가 읽는 진단, 원자적 교체, 커밋에 고정된 소스 근거가 모두 같은 방향을 향합니다. LLM이 만든 산출물을 그대로 믿지 말고 검증 가능한 형태로 만들라는 것입니다.

온보딩용 시스템 지도, PR 리뷰용 델타 그림, 장애 회고용 타임라인이 대표적인 쓰임새입니다. 정리하면, 이미 코딩 에이전트를 쓰고 있고 코드와 함께 움직이는 아키텍처 문서가 필요하다면 먼저 써 볼 만한 도구입니다. 다만 자동 검사를 통과했다는 것과 읽기 좋은 그림이라는 것은 별개이므로, 팀에 공유하기 전에는 사람이 한 번 열어 보는 단계를 남겨 두는 편이 안전합니다.

참고: Archify GitHub 저장소 · Archify 공식 사이트와 갤러리