Archify: 다이어그램을 그리고 검증하는 에이전트 스킬

출처: GitHub (tt-a1i/archify README)
원문: https://github.com/tt-a1i/archify
작성자: 팔복소프트-김팔복

한눈에 보기

• Archify는 코딩 에이전트에게 말로 설명하면 아키텍처·흐름도를 인터랙티브 HTML 파일 하나로 만들어 주는 오픈소스 에이전트 스킬입니다.
• Claude Code, Codex CLI, Cursor, OpenCode에서 쓸 수 있고 라이선스는 MIT입니다.
• 아키텍처, 워크플로, 시퀀스, 데이터 플로, 라이프사이클 다섯 가지 다이어그램을 지원합니다.
• 그림을 바로 그리지 않습니다. 타입이 정해진 JSON을 먼저 만들고, 스키마·레이아웃·경로 검증을 통과해야 결과물을 내놓습니다.
• 저장소를 분석해 만든 아키텍처에는 노드마다 특정 커밋의 파일과 라인 근거를 붙일 수 있습니다.
• 현재 버전은 개발판(v2.17.0-dev.1)이고, 뷰어 UI 언어는 영어와 중국어 간체만 지원합니다.

배경

요즘 코딩 에이전트는 '스킬(Skill)'로 기능을 확장합니다. 작업 지침(SKILL.md)과 스크립트를 묶은 폴더를 설치해 두면 에이전트가 필요한 순간에 그 절차대로 도구를 실행하는 방식입니다. 텍스트로 다이어그램을 그리는 영역은 Mermaid와 PlantUML이 이미 자리를 잡고 있습니다. Archify는 문법을 사람이 쓰는 대신 에이전트가 쓰고, 도구가 검증하는 방향을 택했습니다.

주요 내용

생성보다 검증에 무게를 둔 구조

처리 흐름은 네 단계입니다. 에이전트가 설명을 JSON 중간 표현(IR)으로 바꾸면, 내장 검증기가 스키마와 레이아웃, 화살표 경로, 라벨과 경로의 간격까지 검사합니다. 모든 검사를 통과한 결과물만 기존 파일을 교체하고, 실패하면 이전 정상본이 그대로 남습니다.

실패 시에는 Node 스택 트레이스 대신 규칙 코드, 문제 대상, 측정값, 허용되는 수정 방법을 JSON으로 돌려줍니다. 에이전트가 이 정보를 보고 스스로 고치되, 자동 수정은 두 번까지로 제한됩니다. 로컬에서 JSON 파일 하나를 감시하며 검증된 버전만 반영하는 미리보기 모드(127.0.0.1에서만 동작)도 있습니다.

사용은 간단합니다. npx skills add tt-a1i/archify -g로 설치한 뒤 에이전트에게 이렇게 요청하면 됩니다.

Archify로 결제 흐름을 시퀀스 다이어그램으로 그려줘.
앱 → API Gateway → 주문 서비스 → PG사 승인, 실패 시 주문 취소 경로도 표시.

다섯 가지 유형, 국내 실무에 대입하면

결과물은 HTML 한 파일

뷰어 쪽에 Archify를 설치할 필요가 없습니다. 파일을 열면 노드 검색, 상·하류 연결 추적, 두 지점 사이 경로 강조, 챕터별 설명 재생, 발표 모드, 다크/라이트 테마 전환을 쓸 수 있습니다. PNG·영상 내보내기와 1200×630 공유 카드를 지원하고, 특정 노드에 초점을 맞춘 상태를 URL 해시 링크로 공유할 수도 있습니다.

설계 리뷰용 기능도 있습니다. Architecture Delta는 변경 전후 두 JSON 스냅샷을 비교해 추가·삭제·변경된 요소를 보여줍니다. 다만 영향도나 머지 안전성은 판단하지 않는다고 명시되어 있습니다.

기존 도구와 비교

제작자는 스스로 위치를 이렇게 정리합니다.

Archify is not a general-purpose drawing editor or a Mermaid theme.
— Archify README

실제로 Mermaid 자동 변환, 범용 오토레이아웃, 호스팅 공유, WYSIWYG 편집은 현재 범위 밖으로 명시되어 있습니다.

팔복소프트 관점

• 가장 잘 맞는 자리는 인수인계와 온보딩입니다. 국내 팀에서 흔한 문제는 Confluence에 올린 draw.io 구성도가 몇 달 뒤 실제 코드와 어긋나는 것입니다. 노드마다 커밋 고정 근거가 붙는 방식은 "이 그림이 언제 기준인가"라는 질문에 답을 줍니다. 레거시 시스템을 처음 파악하는 상황에서 특히 쓸모가 있습니다.
• 한국어 환경은 직접 확인해야 합니다. 뷰어 UI 현지화는 영어와 중국어만 지원합니다. 노드 라벨을 한국어로 쓰는 것 자체는 가능하지만, 긴 한글 라벨이 레이아웃 검증과 내보낸 이미지에서 어떻게 나오는지는 원문에 근거가 없습니다. 도입 전에 실제 서비스 구성도로 한 번 뽑아 보는 게 안전합니다.
• 인터랙션의 가치는 공유 경로에서 반감됩니다. Confluence나 Notion 페이지에 HTML 인터랙션을 그대로 넣기 어려운 조직이 많습니다. 현실적으로는 PNG를 본문에 넣고 HTML을 첨부하는 조합이 될 텐데, 그러면 경로 추적이나 스토리 재생을 보는 사람은 줄어듭니다.
• 보안 검토는 Archify보다 에이전트 쪽 문제입니다. 저장소 분석 기능을 쓰면 사내 코드가 에이전트의 모델 제공사로 넘어갑니다. 금융·공공처럼 외부 LLM 사용 규정이 있는 곳은 이 지점부터 확인해야 합니다. 폐쇄망이라면 72시간 주기 업데이트 확인 요청을 ARCHIFY_UPDATE_CHECK_DISABLED=1로 꺼 두면 됩니다.
• 팀 표준으로 삼기엔 이릅니다. 아직 개발판이고 커밋 속도가 빠릅니다. 커뮤니티 채널도 WeChat·QQ 중심이라 국내 사용자는 GitHub 이슈와 Discord에 의존해야 합니다. 스타 7만여 개는 관심의 크기이지 성숙도의 증거는 아닙니다. 개인이나 소규모 팀의 설명 자료, 발표 자료용으로 먼저 써 보는 정도가 적당합니다.
• Mermaid를 대체하기보다 보완하는 도구입니다. README 안의 간단한 흐름은 Mermaid로 충분합니다. 리뷰나 발표처럼 "설명해야 하는" 다이어그램에 Archify를 쓰는 식으로 나누면 됩니다.

정리

Archify에서 기억할 지점은 예쁜 그림이 아니라 "LLM이 만든 다이어그램을 검증한 뒤에 내놓는다"는 설계입니다. 에이전트 산출물을 그대로 믿기 어려운 영역에서 중간 표현과 기계적 검증을 끼워 넣는 방식은 다이어그램 밖에서도 참고할 만한 패턴입니다. 도구 자체는 지금 가볍게 시험해 보고, 정식 버전과 한국어 환경 품질을 확인한 뒤 팀 도입을 판단하면 됩니다.

• Archify
• 에이전트스킬
• 아키텍처다이어그램
• ClaudeCode
• 문서화