Archify: 코드베이스를 검증된 대화형 시스템 맵으로 바꾸는 에이전트 스킬

9bow · 8월 6, 2026, 9:30오전

Archify 소개

시스템 구조를 남에게 설명해야 하는 순간은 자주 찾아옵니다. 신규 입사자에게 서비스 전체 흐름을 알려줄 때, 설계 리뷰에서 변경 범위를 좁혀 보여줄 때, 장애 회고에서 요청이 어느 경로로 흘러갔는지 짚을 때가 그렇습니다. 그런데 이때 쓸 수 있는 그림은 대체로 두 갈래입니다. 그리기 도구로 만든 도형은 보기 좋지만 코드와 따로 살다가 금방 낡고, 텍스트로 정의하는 다이어그램은 갱신은 편하지만 배치를 엔진에 맡기기 때문에 노드가 늘어나면 화살표가 한 지점에 몰려 읽기 어려워집니다. 어느 쪽이든 "이 그림이 실제 구조와 맞는가", "화살표가 라벨을 덮지 않았는가" 같은 확인은 결국 사람이 눈으로 합니다.

Archify는 그 확인 작업을 검증기가 대신하도록 만든 에이전트 스킬(Agent Skill)입니다. 에이전트가 저장소나 시스템 설명을 읽어 타입이 정의된 JSON 중간 표현(Typed JSON IR) 을 만들고, 저장소에 함께 들어 있는 검증기가 스키마·레이아웃·HTML/SVG·경로·라벨과 경로 사이 간격을 차례로 검사합니다. 모든 검사를 통과한 결과물만 기존 산출물을 원자적으로 교체하며, 검사에 걸리면 Node 스택 트레이스 대신 규칙 코드와 문제가 된 대상, 측정값, 지원되는 수정 방법이 담긴 JSON 이 돌아옵니다. 최종 산출물은 의존성 없이 혼자 열리는 HTML 파일 하나이고, 여기서 PNG·SVG·WebM·1200×630 공유 카드를 내보낼 수 있습니다.

Archify 는 Raven, Cursor, Claude Code, Codex CLI, opencode 에서 동작하는 스킬 형태로 배포됩니다. 아키텍처, 워크플로, 시퀀스, 데이터 흐름, 생명주기 다섯 가지 다이어그램 유형과 네 종류의 시각 프리셋, 다크·라이트 테마, 선택적인 유한 모션을 지원합니다. 현재 안정 버전은 v2.13.0 입니다. 이 글에서는 Archify 가 기존 다이어그램 도구와 다르게 잡은 지점, 다섯 가지 다이어그램 유형, 타입 IR 과 검증 파이프라인의 동작 방식, 그리고 설치와 사용 방법을 정리합니다.

Archify와 자동 레이아웃 방식의 차이

다이어그램을 코드로 정의하는 도구들은 배치 결정을 레이아웃 엔진에 위임합니다. 정의만 고치면 그림이 따라오는 편의를 얻는 대신, "무엇을 위에 둘지, 어떤 경로를 강조할지" 같은 판단은 엔진의 기본값에 맡겨집니다. Archify 는 그 판단을 에이전트에게 되돌려 놓았습니다. 저자는 이 설계를 "generic auto-layout 대신 layout judgment" 라고 표현하면서, 계층·간격·경로·강조를 에이전트가 고르고 공유되는 자동 연결점은 한 중점에 화살표가 쌓이지 않도록 결정적으로 분산된다고 설명합니다.

항목	자동 레이아웃에 맡기는 방식	Archify
배치 결정	레이아웃 엔진의 기본 규칙	에이전트가 계층·간격·경로·강조를 직접 선택
산출물 검사	렌더 성공 여부 중심	스키마·레이아웃·HTML/SVG·경로·라벨 간격 검사를 모두 통과해야 교체
실패 시 응답	스택 트레이스 또는 재시도	규칙 코드·대상·측정 근거·지원되는 수정 방법을 담은 JSON
결과물 형태	렌더된 이미지 또는 코드 블록	자체 완결 HTML 한 개 + PNG·SVG·WebM·공유 카드

표의 왼쪽 열은 Archify 저자가 대비 대상으로 제시한 특성이고, 오른쪽 열은 저장소 문서에서 확인할 수 있는 Archify 의 동작입니다. 한 가지는 분명히 해 둘 필요가 있습니다. Archify 는 자동 Mermaid 파싱과 범용 자동 레이아웃, 호스팅 기반 공유, WYSIWYG 편집을 현재 범위 밖으로 명시하고 있습니다. 기존 Mermaid 문서를 그대로 예쁘게 바꿔주는 렌더러가 아니라, 기술적 의도를 전달용 산출물로 바꾸는 다른 종류의 도구입니다.

Archify가 지원하는 다섯 가지 다이어그램 유형

Archify 는 목적이 다른 다섯 가지 유형을 각각 별도의 렌더링 모드로 다룹니다. 유형마다 프롬프트에 담아야 하는 정보가 다르고, 저장소는 그 목록을 표로 정리해 두었습니다.

유형	적합한 대상	프롬프트에 담을 내용
아키텍처(Architecture)	컴포넌트, 서비스, 저장소, 경계	범위, 핵심 컴포넌트, 주 경로
워크플로(Workflow)	CI/CD, 승인 절차, 도구 호출, 런북	참여자, 순서, 분기, 예외
시퀀스(Sequence)	API 호출, 캐시 폴백, 인증, 비동기 추적	호출자, 피호출자, 반환, 타이밍
데이터 흐름(Data Flow)	파이프라인, 계보, 개인정보, 소비자	소스, 변환, 저장소, 경계
생명주기(Lifecycle)	상태, 재시도, 대기, 종료 결과	상태, 이벤트, 재시도와 취소 경로

각 유형이 실제로 어떻게 그려지는지는 저장소의 docs/assets 디렉토리에 예시 이미지로 들어 있습니다. 워크플로는 레인을 나눠 정상 경로를 또렷하게 유지하고, 시퀀스는 하나의 상호작용을 시간 축으로 풀어내며, 데이터 흐름은 이동과 민감도 경계를 함께 드러내고, 생명주기는 진행·대기·재시도·종료 결과를 구분합니다.

어떤 유형을 골라야 할지 애매할 때는 저장소에 포함된 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

아키텍처 유형에는 deployment-ownership 이라는 엔지니어링 프로필을 선택적으로 켤 수 있습니다. 소유자 정보, 단일 리전 배치, 데이터베이스의 사설 범위, 이름이 명시된 경계 교차 중 빠진 것이 있으면 통과시키지 않고 실패로 처리합니다. 조용히 켜지는 일은 없으며, 검사 대상은 실제 인프라가 아니라 문서에 기술된 사실입니다.

Archify의 동작 원리: 타입 IR과 결정적 검증

Archify 의 파이프라인은 다섯 단계로 나뉩니다. 생성 단계에서 에이전트가 설명을 타입 JSON IR 로 옮기고, 검증 단계에서 번들된 검증기와 레이아웃 규칙이 원본을 검사합니다. 선택적인 미리보기 단계는 127.0.0.1 에만 바인딩된 로컬 세션이 지정한 JSON 파일 하나를 감시하면서, 검증을 통과한 개정본이 나올 때만 화면을 갱신하고 실패하면 마지막으로 정상이던 산출물을 그대로 남겨 둡니다. 전달 단계는 같은 디렉토리에 후보 파일을 만들어 검사한 뒤 통과한 것만 원자적으로 목표 파일과 교체하고, 반복 단계에서는 관련 없는 구조를 흔들지 않고 원본만 수정합니다.

단계	하는 일
생성(Generate)	에이전트가 설명으로부터 타입 JSON IR 을 만듭니다.
검증(Validate)	번들 검증기와 레이아웃 규칙이 원본을 검사하고, 실패는 수정 지점을 기계가 읽을 수 있는 JSON 으로 지목합니다.
미리보기(Preview, 선택)	루프백 전용 세션이 원본 하나를 감시하며 검증된 개정본만 반영합니다.
전달(Deliver)	후보 산출물을 검사해 통과한 것만 원자적으로 교체하고, 필요하면 `--open` 으로 그 파일을 엽니다.
반복(Iterate)	에이전트가 원본을 갱신하는 동안 무관한 구조는 안정적으로 유지됩니다.

검사에 걸렸을 때 돌아오는 응답이 이 도구의 성격을 잘 보여줍니다. validate --json 과 deliver --json 은 실패하더라도 JSON 객체 하나만 출력하며, diagnostics[] 에 담긴 대상과 supportedFixes 를 읽어 그 부분만 고치는 것이 권장 흐름입니다. 다이어그램 전체를 다시 쓰거나 스킬이 정한 두 번의 집중 수정 라운드를 넘기지 않도록 안내합니다. 노드에 근거를 붙이는 기능도 요청할 때만 동작합니다. 근거가 붙은 아키텍처 노드는 SRC n 표시를 달고 하나의 공개 커밋에 고정된 파일과 줄 범위를 열어 주며, 일반 산출물은 소스 참조 없이 유지됩니다.

Archify의 아키텍처 델타 리뷰

설계 리뷰나 PR 리뷰를 위해 검증된 두 스냅샷을 Before / Delta / After 로 비교하는 기능이 따로 있습니다. 추가·삭제·변경·이동·재경유된 사실을 정확한 ID 단위로 대조하고 기계가 읽는 영수증(receipt)을 함께 남깁니다. 뷰어 전용 기능이라 영향도나 위험도, 병합 안전성을 추론하지는 않습니다.

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

실제 저장소를 매핑한 결과

저장소에는 공개 저장소 mco-org/mco 를 커밋 9f1a1cf 기준으로 추적해 만든 런타임 아키텍처 맵이 사례로 포함되어 있습니다. 제품 목업이 아니라 Archify 가 생성한 산출물이며, 같은 저장소의 docs/cases 디렉토리에 타입 원본 JSON 이 함께 들어 있어 결과와 입력을 대조해 볼 수 있습니다.

생성된 HTML 뷰어에서는 키보드로 탐색합니다. / 로 노드를 찾고, 노드에 초점을 맞춘 뒤 상류·하류로 문서에 기술된 도달 범위를 추적하고, R 로 방향이 있는 경로를 조사하고, L 로 두 개의 의미 역할을 비교하고, P 로 저자가 만든 이야기를 재생합니다. #focus=, #route=, #lens=, #view= 같은 딥 링크로 특정 상태를 그대로 공유할 수 있고, 이 상호작용은 모두 문서에 기술된 노드와 관계만 사용합니다. 저자는 이 성질을 "truthful interaction" 이라고 부르며, 토폴로지를 발명하거나 런타임 영향을 주장하지 않는다는 점을 반복해서 강조합니다.

Archify는 누구에게 유용한가

지원되는 에이전트(Raven, Cursor, Claude Code, Codex CLI, opencode)를 이미 쓰고 있고 설계 리뷰나 온보딩 문서에 붙일 구조 그림이 반복적으로 필요한 팀이라면 도입 비용이 낮습니다. 스킬을 설치하면 채팅 안에서 요청하고 다듬는 흐름으로 끝나며, 산출물이 파일 하나여서 저장소나 위키에 그대로 커밋할 수 있습니다. 검증기가 규칙 코드로 실패 이유를 돌려주는 구조도, 다이어그램을 CI 나 리뷰 절차에 끼워 넣으려는 경우에 유리한 조건입니다.

반대로 이미 Mermaid 로 정리해 둔 문서를 자동 변환하려는 목적이라면 맞지 않습니다. 자동 Mermaid 파싱은 현재 범위 밖이고, 마우스로 도형을 옮기는 WYSIWYG 편집이나 호스팅 기반 공유도 지원하지 않습니다. Claude.ai 에 archify.zip 을 업로드하는 경로는 샌드박스에서 Node.js 를 쓸 수 있는지에 따라 결과가 달라지므로, 렌더러와 검증 흐름을 온전히 쓰려면 로컬 CLI 환경이 필요합니다.

Archify 설치 및 사용 방법

전역 설치는 한 줄입니다.

npx skills add tt-a1i/archify -g

에이전트를 명시하거나 대화형 프롬프트 없이 설치하려면 다음 형태를 사용합니다.

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

영구 설치 없이 한 번만 시험해 볼 수도 있습니다.

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

설치 후에는 에이전트에게 범위를 좁혀 요청하는 편이 결과가 좋습니다. 저장소가 제시하는 예시 프롬프트는 컴포넌트 개수와 주 경로를 함께 못박습니다.

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.

이후에는 add Redis, move auth to the left, highlight the rollback path 처럼 초점을 좁힌 요청으로 다듬어 나갑니다. 타입 원본이 남아 있기 때문에 전체를 다시 만들지 않고 해당 부분만 수정됩니다. 저장소를 직접 클론했다면 환경 점검과 데모 생성도 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

모션과 프리셋은 명시적으로만 켜집니다. IR 의 meta 에 animation 과 visual_preset 을 지정하는 방식이며, animation 을 생략하면 완전히 정적인 다이어그램이 됩니다. 기본 프리셋은 classic 이고 editorial 은 출판물에 가까운 느낌을 더합니다. 생성과 뷰어의 전체 계약은 저장소의 archify/SKILL.md 에 정리되어 있습니다.

Archify의 라이선스

Archify 는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

Archify 생성 결과물을 모아 둔 Proof Lab

Archify 공식 프로젝트 페이지

Archify 다이어그램 유형 선택 가이드

Archify 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다.

이 도구를 직접 설치해 사용해보셨다면, 파이토치 한국 사용자 모임 회원들을 위해 경험이나 팁을 댓글로 남겨주세요!