말 한 줄로 시스템 지도를 — 코드와 설명을 탐색 가능한 다이어그램으로 바꾸는 에이전트 스킬 Archify | DAKER 커뮤니티

새 프로젝트에 합류해서 코드를 처음 열었을 때, 제일 먼저 찾게 되는 건 “이 시스템 전체 그림이 어떻게 생겼지?”를 보여 주는 한 장짜리 그림입니다. 그런데 그런 그림은 대개 없거나, 있어도 몇 달 전 버전이라 지금 코드와 다릅니다. 이번에 GeekNews에 올라온 Archify는 바로 그 그림을 AI 코딩 에이전트에게 그리게 하는 오픈소스 도구입니다. 저장소 README를 꼼꼼히 읽어 보니 단순히 “그림을 그려 준다”보다 한 걸음 더 나간 부분이 있어서 정리해 봤습니다.

말 한 줄로 시스템 지도 — Archify 동작 흐름 설명용 생성 이미지
설명용 생성 이미지입니다.

Archify가 뭔가요

Archify는 에이전트 스킬입니다. 에이전트 스킬이란 Claude Code, Codex CLI, Cursor, OpenCode 같은 AI 코딩 에이전트에 설치해 두는 일종의 작업 설명서 묶음으로, 특정 일을 어떻게 해야 하는지 에이전트에게 알려 줍니다. Archify를 설치하면 에이전트에게 코드 저장소를 읽게 하거나, 시스템을 말로 설명하는 것만으로 클릭해서 탐색할 수 있는 시스템 다이어그램을 만들 수 있습니다. 결과물은 HTML 파일 하나라서 브라우저로 열기만 하면 되고, 그 파일을 동료에게 보내면 클릭·탐색 기능까지 그대로 따라갑니다.

설치는 명령어 한 줄입니다. README에 나온 기본 방법은 npx skills add tt-a1i/archify -g입니다. 특히 반가웠던 건 저장소가 없어도 된다는 점입니다. README의 첫 예시가 이렇습니다. “브라우저가 API를 부르고, API가 Redis 캐시를 확인하고, 캐시에 없으면 PostgreSQL에서 찾아와 캐시를 채운다”를 다이어그램으로 그려 달라고 에이전트에게 말하는 겁니다. Redis는 자주 쓰는 데이터를 빠르게 꺼내 쓰려고 메모리에 잠깐 담아 두는 저장소이고, PostgreSQL은 데이터를 오래 보관하는 데이터베이스입니다. 이렇게 말로만 설명해도 그림이 나오고, 이어서 “인증 추가해 줘”, “캐시 미스 경로 강조해 줘”, “밝은 테마로 바꿔 줘”처럼 대화로 다듬어 나갈 수 있습니다.

그림을 바로 그리지 않고, 설계도부터 씁니다

이 도구에서 가장 마음에 든 부분이 여기입니다. 보통 AI에게 다이어그램을 부탁하면 그림이나 그림용 코드를 곧장 뱉어 냅니다. Archify는 순서가 다릅니다. 먼저 에이전트가 구조화된 JSON(어떤 구성 요소가 있고 무엇과 무엇이 어떻게 연결되는지를 정해진 형식으로 적은 데이터 파일)을 씁니다. 그다음 Node.js로 만든 렌더러가 이 JSON을 읽어서 HTML과 SVG(확대해도 깨지지 않는 벡터 그림 형식)로 그려 줍니다.

이렇게 나누면 좋은 점이 분명합니다. 그림을 고치고 싶을 때 그림 전체를 새로 그리는 게 아니라 원본 JSON의 해당 부분만 고치면 됩니다. README도 대화로 수정할 때 관련 없는 구조는 그대로 유지된다고 설명합니다. “인증 서버를 왼쪽으로 옮겨 줘”라고 했는데 나머지 배치까지 다 흐트러지는 일을 줄이려는 설계입니다.

틀리면 ‘어디를 왜’ 고쳐야 하는지 알려 줍니다

두 번째로 눈에 띈 건 검사 단계입니다. 그림을 완성하기 전에 데이터 구조가 형식에 맞는지, 상자 배치가 겹치지 않는지, 연결선과 글자 사이에 간격이 충분한지를 검사합니다. 여기서 문제가 나오면 알아보기 힘든 에러 메시지를 던지는 대신 어느 요소가, 어떤 규칙에, 어떤 수치로 걸렸는지와 고칠 수 있는 방법을 JSON으로 돌려줍니다. README는 이걸 ‘수리 영수증’처럼 표현하는데, 에이전트가 이 결과를 읽고 스스로 고치게 하려는 구조입니다. 스킬 설명에 따르면 자동 수정은 두 번까지만 시도하고, 눈으로 보는 최종 점검은 따로 합니다.

검사를 모두 통과한 결과만 기존 파일을 바꾸는 점도 좋았습니다. 중간에 저장이 덜 됐거나 오류가 있으면 마지막으로 검증을 통과한 그림이 그대로 남습니다. 선택 기능인 미리보기 모드도 같은 원칙으로 동작해서, JSON 파일 하나를 지켜보다가 검사를 통과한 버전만 화면에 새로 띄웁니다.

다섯 가지 그림, 그리고 ‘보는’ 기능들

지원하는 다이어그램은 다섯 가지입니다. 서비스와 저장소, 경계를 보여 주는 아키텍처, 배포 파이프라인이나 승인 절차 같은 순서를 보여 주는 워크플로, API 호출이 시간 순서대로 오가는 모습을 보여 주는 시퀀스, 데이터가 어디서 와서 어디로 흘러가는지 보여 주는 데이터 흐름, 그리고 대기·재시도·완료 같은 상태 변화를 보여 주는 생명주기입니다. 어떤 걸 골라야 할지 모르겠다면 가이드 명령에 상황을 문장으로 넣어 추천받을 수도 있습니다.

만들어진 HTML에서는 단축키로 여러 가지를 할 수 있습니다. 노드(그림 속 상자 하나)를 검색해서 초점을 맞추고, 그 노드의 앞뒤로 연결된 요소를 따라가 보고, 두 요소 사이의 경로를 짚어 볼 수 있습니다. 미리 짜 둔 순서대로 단계별 설명을 재생하거나 발표 모드로 띄우는 기능도 있습니다. README는 이런 탐색이 작성된 연결 관계만 보여 줄 뿐, 실제 실행 중에 무슨 일이 일어나는지를 추측해 주지는 않는다는 점을 여러 번 강조합니다. 그림이 할 수 있는 말과 할 수 없는 말을 구분해 둔 셈이라 오히려 믿음이 갔습니다.

코드 리뷰와 근거 확인에도 쓸 수 있습니다

개발 팀에서 특히 쓸모 있어 보인 기능이 두 가지 있습니다. 하나는 변경 전후 비교입니다. 설계를 바꾸기 전과 후의 JSON을 넣으면 추가·삭제·수정된 요소, 위치가 옮겨진 요소, 연결 경로가 바뀐 부분을 표시해 줍니다. PR(코드 변경 요청) 리뷰 때 “이번 변경으로 구조가 어떻게 바뀌었나”를 그림으로 보여 주기 좋겠다는 생각이 들었습니다. 다만 이것도 변경의 영향이나 위험도, 합쳐도 안전한지까지 판단해 주지는 않는다고 명시되어 있습니다.

다른 하나는 소스 근거 연결입니다. 요청하면 다이어그램 속 노드에 특정 Git 커밋의 소스 파일과 줄 번호를 연결해 줘서, “이 상자가 정말 코드에 있는 거 맞아?”를 클릭 한 번으로 확인할 수 있습니다. README에는 공개 저장소인 mco-org/mco를 특정 커밋 기준으로 읽어 만든 실제 예시도 있습니다. 이 기능은 요청할 때만 켜지고, 평소 결과물에는 소스 정보가 들어가지 않습니다.

결과물은 PNG, SVG, 움직이는 WebM 영상으로 내보낼 수 있고, README나 SNS에 올리기 좋은 1200×630 공유용 이미지도 따로 만들 수 있습니다.

알아 두면 좋은 점

README 기준 현재 개발 버전은 v2.17.0-dev.1이고, 라이선스는 MIT라 자유롭게 쓰고 고칠 수 있습니다. 제가 확인한 시점(2026-09-26 오전)에 GitHub 저장소 별은 약 7만 1천 개였습니다. README는 이 프로젝트가 GitHub 트렌딩 주간 전체 언어 1위에 올랐다고 소개하는데, 이는 제작자가 올린 스크린샷을 근거로 한 제작자 측 설명입니다.

몇 가지 참고할 점도 있습니다. Claude Code, Codex CLI, OpenCode에서는 렌더러와 검사까지 전체 기능이 돌아가지만, Claude.ai 웹에 올려 쓰는 경우는 샌드박스에서 Node.js를 쓸 수 있는지에 따라 달라진다고 합니다. 또 Archify는 업데이트 알림을 보여 주려고 약 72시간마다 고정된 주소에 접속할 수 있는데, 버전이나 프로젝트 정보는 보내지 않고 자동 설치도 하지 않는다고 적혀 있습니다. 이것도 싫다면 ARCHIFY_UPDATE_CHECK_DISABLED=1 환경 변수로 끌 수 있습니다. 반대로 Mermaid 문법 자동 변환, 범용 자동 배치, 온라인 공유 호스팅, 마우스로 직접 편집하는 기능은 일부러 범위 밖에 두었다고 합니다.

그리고 README 상단과 중간에는 후원사 소개가 있습니다(Kimi Work, Supercode, EverMind/Raven). 일부 후원사 링크에는 제휴·추적 코드가 붙어 있어서 이 글에는 넣지 않았습니다. 도구 자체는 누구나 쓸 수 있는 오픈소스입니다.

이렇게 시작해 보세요

읽고 나서 든 생각

AI에게 그림을 그리게 하는 도구는 이미 많습니다. 그런데 Archify는 “예쁜 그림”보다 “믿을 수 있는 그림”에 공을 들였다는 인상을 받았습니다. 그림 대신 고칠 수 있는 설계도(JSON)를 먼저 남기고, 검사를 통과한 것만 결과로 내놓고, 필요하면 코드 줄 번호까지 근거로 붙입니다. GeekNews 댓글에도 개발 도중 시각화해 달라고 하면 이 스킬로 보여 줘서 쓸 만하다는 사용 후기가 있었습니다. 새로 합류한 팀원에게 시스템을 설명하거나, 내가 만든 서비스 구조를 발표해야 할 때 한 번 써 볼 만한 도구라고 생각합니다.

출처