Archify — 채팅에서 아키텍처 다이어그램을 만들어 봤다

아키텍처 그림은 늘 낡는다. 그려 둔 다음에 코드가 바뀌기 때문이다. 그래서 대부분은 발표 직전에 손으로 다시 그린다.

Archify는 그 작업을 에이전트에게 넘긴다. 스타 65,734개, MIT, 최신 정식 릴리스는 2026년 8월 30일 v2.16.0이다. Mermaid 테마도 다이어그램 편집기도 아니다. Node 기반 렌더링·검증 시스템이다.

직접 만들어 봤다

이 사이트의 접근 등급 구조를 다이어그램으로 만들었다. 아래가 실제 결과다.

설치는 스킬 형태다.

npx -y skills add tt-a1i/archify --skill archify --agent claude-code --global --copy --yes
node ~/.claude/skills/archify/bin/archify.mjs doctor    # 준비 상태 점검

만드는 순서는 셋이다.

# 1) 어떤 다이어그램이 맞는지 물어보기
node bin/archify.mjs guide "Show an API request with Redis cache miss"

# 2) 검증 — 스키마·레이아웃·라벨 간격까지
node bin/archify.mjs validate architecture site-arch.json --quality showcase --json

# 3) 렌더 + 인수
node bin/archify.mjs deliver architecture site-arch.json out.html --quality showcase --json

다이어그램 타입은 다섯 개다. 아키텍처, 워크플로, 시퀀스, 데이터 흐름, 라이프사이클. CLI가 내는 건 자기완결 HTML 한 장이다. PNG·SVG·WebM 영상·1200×630 공유 카드는 그 HTML을 브라우저로 열어 Export 메뉴에서 뽑는다. CLI 명령은 없어서 자동화하려면 크롬을 직접 조작해야 했다.

명세에 animation: "trace" 한 줄을 넣으면 연결선 위로 점이 흐른다. 뷰어의 WebM 녹화로 뽑아 MP4로 바꾼 게 아래다.

요청 한 건을 순서대로 따라가는 연출은 아니다. 모든 연결선에 점이 시차를 두고 흐르며 반복된다. 구조를 설명할 때 "어디로 흐르는지"를 보여 주는 용도다.

실패가 스택 트레이스로 오지 않는다

처음 쓸 때 스키마를 대충 짚어 썼다. kind, boundary 같은 필드를 임의로 넣었다. 돌아온 건 에러 로그가 아니라 수리 지시서였다. 이걸 제대로 보여 주려고 일부러 틀린 JSON을 다시 만들어 넣었다.

진단마다 위치(path), 측정값(evidence), 허용되는 수정(supportedFixes)이 붙어 온다. 모르는 필드는 무시하지 않고 거부한다(additionalProperties: false).

써 보니 두 가지는 글로만 읽었을 때와 달랐다.

검증이 단계별로 멈춘다. 스키마 오류가 있으면 거기서 끝난다. 없는 노드를 가리키는 연결이나 좌표 누락은 스키마를 고친 다음 회차에야 나왔다. 한 번에 다 알려 주지 않으니 두세 번 돌린다고 생각해야 한다.

수리 지시가 전부 구조화돼 있지는 않다. 스키마와 구성 진단은 evidence, supportedFixes 가 채워져 오는데, 라벨이 노드와 겹친다는 layout/constraint 진단은 둘 다 비어 있다. "labelDy +24" 같은 제안은 메시지 문자열 안에만 있다. 에이전트가 파싱해서 자동으로 고치게 하려면 이 차이를 알아야 한다.

에이전트 출력을 신뢰 가능하게 만드는 방법으로 이 구조는 참고할 만하다. 모델이 그림을 그리는 게 아니라, 모델이 타입 있는 데이터를 쓰고 결정적 컴파일러가 그림을 만든다. 검증을 전부 통과하지 못하면 기존 산출물을 갈아치우지 않는다.

그런데 validate 통과가 끝이 아니었다. 처음 짠 4행 배치는 검사 9개를 다 통과했는데, 브라우저 검사(visual-check)가 1440×900 화면에서 세로로 넘친다며 실패를 냈다. 3행으로 다시 짜서 통과시켰다. 산출물 검사와 화면 검사가 서로 다른 주장이라는 설계를 직접 겪은 셈이다.

코드와 일치함을 증명하는 방식

meta.repository에 40자 커밋 SHA를 적고, 각 컴포넌트에 저장소 상대 경로와 줄 번호를 붙일 수 있다. 검증할 때 작업 트리가 아니라 그 커밋의 blob을 직접 읽는다. 로컬에서만 읽고 원격 요청은 하지 않는다. 근거가 붙은 노드에만 SRC n 마커가 표시된다.

"이 다이어그램이 지금 코드와 맞나"를 기계적으로 확인하는 방법이다.

기관 AX 도입 전후를 두 장으로 그렸다

아키텍처 타입에는 스냅샷 비교(compare)가 있다. 두 시점을 Before / Delta / After로 놓고 added, removed, changed, moved, rerouted를 사실 단위로 보여 준다.

컨설팅에서 가장 자주 그리는 그림으로 해 봤다. 현재는 직원이 개인 계정으로 외부 챗봇에 문서를 복붙하고 기록이 남지 않는 구조. 도입 후는 개인정보 필터와 LLM 게이트웨이를 거쳐 외부 모델과 사내 sLLM으로 나눠 보내고, 감사 로그를 남기고, 사내 문서를 검색(RAG)하는 구조다.

차이는 추가 15, 삭제 1, 변경 3으로 나왔다. 컴포넌트 6개(감사 로그, 게이트웨이, 색인, 개인정보 필터, RAG, sLLM)가 추가됐고, 삭제된 건 "문서 복붙 · 기록 없음" 연결 하나다. 외부 챗봇 노드는 지워진 게 아니라 "외부 모델 API · 기업 계약 · 학습 제외"로 바뀐 것으로 잡혔다.

여기서 하나 배웠다. Delta는 현실이 아니라 작성된 명세를 비교한다. 처음에 외부 챗봇 ID를 chatgpt로 두었을 때는 "삭제 1 + 추가 1"로 나와 결과가 16 / 2 / 2였다. ID를 external로 맞추니 "변경"으로 잡혀 15 / 1 / 3이 됐다. 무엇을 같은 대상으로 볼지는 사람이 정해야 한다. 도구도 수령증에 "런타임 영향, 인과, 리스크, 머지 가능성은 추론하지 않는다"고 적어 둔다.

deliver(산출물 검사)와 visual-check(실제 브라우저 동작 확인), 사람이 봐야 하는 지각적 검토를 세 개의 서로 다른 주장으로 분리하는 것도 같은 태도다. 도구가 할 수 있는 말과 할 수 없는 말을 구분해 둔 것인데, AX 도입에서 에이전트 산출물을 받을 때 필요한 태도가 정확히 이거다.

제약

노드 12개까지다. 문서가 "주요 노드 12개 이하로 시작하라"고 명시하고, 데이터 흐름의 스테이지는 최대 5개, 라이프사이클 레인은 4개로 스키마에 하드 상한이 있다. 저장소 전체 지도를 그리는 도구가 아니라 한 장으로 설명하는 산출물을 만드는 도구다.

수정은 2라운드로 제한된다. Mermaid 자동 파싱, 범용 자동 레이아웃, 호스팅 공유, WYSIWYG 편집은 범위 밖이라고 문서가 못 박았다.

한국어는 라벨까지만 된다. 뷰어 UI 언어(meta.locale)는 영어와 중국어만 있어서 버튼과 범례는 영어로 나온다. Delta 공유 카드 제목은 "도입 후 — 사내 LLM 게이트웨이 Architecture Delta"처럼 두 언어가 섞인다. 세로 연결선의 라벨은 기본 위치가 출발 노드와 겹쳐서 세 번 모두 손으로 옮겼다.

어디에 쓸까

강의자료와 제안서에 들어가는 구조 그림에 바로 쓸 수 있다. 한 장에 12개 노드 제한이 오히려 도움이 된다. 발표용 그림은 그 이상 들어가면 읽히지 않는다.

기관 컨설팅의 "현재 구조 → 도입 후 구조"는 위에서 해 본 대로 바로 쓸 수 있다. 제안서에 "무엇이 바뀌는가"를 추가 15, 삭제 1, 변경 3이라는 사실 목록으로 붙일 수 있다는 게 크다. 의견이 아니라 목록이라 검토하는 쪽과 말이 덜 엇갈린다.

저장소: tt-a1i/archify · 갤러리: tt-a1i.github.io/archify · 이 사이트 구조도는 2026-09-18, 검증·Delta·영상은 2026-09-19에 v2.17.0-dev.1 로 직접 렌더했다.