Archify: 에이전트가 그리는 검증된 아키텍처 다이어그램

왜 지금 Archify인가

아키텍처 문서는 종종 실제 코드보다 먼저 낡는다. 수동으로 그린 다이어그램은 배포 후 반영되지 않고, Mermaid 같은 경량 문법도 자동 배치가 붙으면 읽기 어려워진다. Archify는 그 지점에서 정확성과 공유 가능성을 동시에 잡으려고 만든 도구다.

Archify가解决하는 문제

Archify는 코드베이스나 시스템 설명을 정형 다이어그램으로 바꾸는 데 초점을 맞춘 오픈소스 프로젝트다. Cursor, Claude Code, Codex CLI, OpenCode 같은 코딩 에이전트에 스킬로 설치하고, "이 저장소 아키텍처를 그려줘" 라고 요청하면 아키텍처, 워크플로, 시퀀스, 데이터플로, 라이프사이클 다섯 가지 다이어그램 중 하나를 받을 수 있다. 결과물은 하나의 HTML 파일이고, 다이어그램 위에서 검색·확대·테마 전환·공유까지 가능하다. GitHub 저장소 tt-a1i/archify 에서 확인할 수 있다.

핵심 기능

다이어그램 유형과 보증 범위

Archify가 지원하는 다이어그램은 아키텍처, 워크플로, 시퀀스, 데이터플로, 라이프사이클 다섯 종류다. 각 유형은 용도가 분리돼 있어서, "로그인 플로우"나 "캐시 미스 시퀀스"처럼 한 가지 질문에 집중할 때 쓰기 쉽다. 생성 과정은 JSON IR를 만들고, bundled validators가 스키마·레이아웃·라우트·라벨 일관성을 검사한 뒤에 HTML/SVG를 내보낸다.

단계	내용
Generate	Agent가 typed JSON IR를 생성
Validate	스키마·레이아웃·라우트·라벨 검사
Preview	로컬에서 변경분만 다시 로드
Deliver	같은 디렉토리에 검증된 산출물을 교체
Iterate	JSON만 수정하며 범위 유지

Before / Delta / After 비교

PR 리뷰나 아키텍처 변경 검토에 쓸 수 있는 기능이다. 기준 버전과 변경 버전 두 개의 JSON IR를 넣으면 추가·삭제·변경·이동·재라우팅된 사실만 추출해 Before / Delta / After로 보여준다. 이 기능은 저장소에서 node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json 형태로 실행할 수 있다.

출처 증명 모드

Archify는 기본적으로 검증된 authored topology만 보여주고, 런타임 영향은 주장하지 않는다. Evidence-backed Architecture 모드를 쓰면 노드에 SRC n 표시가 붙고, 특정 public commit의 파일과 라인 범위까지 열 수 있다. 일반 산출물에는 출처 정보가 붙지 않아서, 문서화가 필요한 경우에만 선택적으로 켜는 구조다.

다른 도구와의 차이

Mermaid는 텍스트 기반 다이어그램 문법이지만 자동 배치가 제한적이고, 수동 드로잉 도구는 버전 관리가 어렵다. Archify는 JSON IR를 원본으로 유지하므로 diff, 검증, 재사용이 가능하다. 또 결과물이 하나의 HTML 파일이라 공유와 내보내기가 쉽다. 프로젝트 페이지 tt-a1i.github.io/archify 에서 라이브 갤러리와 시나리오 가이드를 확인할 수 있다.

실제 사용 포인트

Node.js 환경이면 npx skills add tt-a1i/archify -g 로 글로벌 설치가 가능하다. 설치 후에는 "이 저장소의 런타임 아키텍처를 그려줘" 처럼 자연어로 요청하면 된다. Diagram Guide는 ? 키로, 노드 검색은 / 키로, 경로 추적은 R 키로 열 수 있다. 제한 사항으로는 호스트 공유·자동 Mermaid 파싱·WYSIWYG 편집이 현재 범위 밖이라는 점이 README에 명시돼 있다.

마치며

Archify는 아키텍처 다이어그램을 문서가 아니라 실행 가능한 산출물로 만들고 싶은 팀에 맞는다. 단일 HTML, typed JSON IR, 검증 파이프라인이라는 세 축이 맞물려서, 수동 다이어그램이 흔히 겪는 낡음과 불일치 문제를 줄여준다. 관심이 있으면 저장소의 examples/ 디렉토리나 Proof Lab에서 실제 산출물을 먼저 확인해보는 게 좋다.