718 ／ 718
설명 한 줄을 검증 가능한 다이어그램으로, 오픈소스 에이전트 스킬 archify
archify는 AI 에이전트에게 시스템을 말로 설명하면 그것을 인터랙티브 HTML 다이어그램으로 바꿔 주는 오픈소스 스킬이다. MIT 라이선스로 공개돼 있고, Cursor·Claude Code·Codex CLI·OpenCode 같은 코딩 에이전트에 붙여 쓴다. 2026년 9월 기준 깃허브 스타 7만 개를 넘겼고 GitHub 트렌딩 주간 1위에 오른 적이 있으며, 현재 개발 버전은 2.17.0이다. 스스로를 범용 그림 편집기나 Mermaid 테마가 아니라 “기술적 의도를 소통 가능한 산출물로 바꾸는 도구”로 소개한다. 이 글은 저장소 문서를 바탕으로 archify의 골자를 정리한 것이다.
쓰는 방식
설치는 명령 한 줄이다.
npx skills add tt-a1i/archify -g
그다음 에이전트에게 다이어그램을 요청한다. 저장소가 반드시 필요하지는 않다. 설명만으로 시작하거나, 에이전트에게 저장소를 읽혀 근거 있는 아키텍처 지도를 만들게 할 수도 있다.
archify로 웹 요청을 그려 줘. 브라우저가 API를 호출하고,
API는 Redis를 확인하며, 캐시 미스면 PostgreSQL을 조회해 캐시를 채운다.
만든 뒤에는 대화로 다듬는다. “인증을 추가해 줘”, “캐시 미스 경로를 강조해 줘”, “라이트 테마로 바꿔 줘”처럼 이어 말하면, archify는 타입이 지정된 원본을 그대로 유지하면서 요청한 부분만 고친다.
다섯 가지 다이어그램 유형
목적에 따라 다섯 유형 중에서 고른다.
| 유형 | 쓰임 | 프롬프트에 담을 것 |
|---|---|---|
| Architecture | 구성 요소·서비스·저장소·경계 | 범위, 핵심 구성 요소, 주 경로 |
| Workflow | CI/CD, 승인, 도구 호출, 런북 | 참여자, 순서, 분기, 예외 |
| Sequence | API 호출, 캐시 폴백, 인증, 비동기 추적 | 호출자, 피호출자, 반환, 타이밍 |
| Data Flow | 파이프라인, 계보, 개인정보, 소비자 | 소스, 변환, 저장소, 경계 |
| Lifecycle | 상태, 재시도, 대기, 종료 결과 | 상태, 이벤트, 재시도·취소 경로 |
어떤 유형이 맞을지 모르면 시나리오 가이드를 쓰거나, 의존성 없는 CLI에 물어볼 수 있다. node archify/bin/archify.mjs guide "Redis 캐시 미스가 있는 API 요청을 보여 줘"처럼 실행하면 적절한 유형을 추천한다.
지어내지 않는 다이어그램
archify가 다른 도구와 갈라지는 지점은 출력을 신뢰할 수 있게 만드는 방식에 있다. 핵심은 다음과 같다.
- 모든 렌더 모드에 스키마가 있고, 재현 가능한 타입 지정 JSON을 원본으로 삼는다.
- 산출물을 내보내기 전에 스키마·레이아웃·HTML/SVG·경로·라벨 간섭 검사를 모두 통과해야 한다. 하나라도 실패하면 마지막으로 검증된 결과가 교체되지 않는다.
- 검사에 실패하면 스택 트레이스 대신 수리 영수증을 돌려준다.
validate --json·deliver --json이 안정적인 규칙 코드, 정확한 대상, 측정된 근거, 지원되는 수정 방법만 기계 판독용으로 제시한다. - 상호작용은 실제로 작성된 노드와 관계만 재사용한다. 포커스, 상류·하류 도달 범위, 정확한 경로, 역할 비교, 스토리 모두 없는 위상을 지어내거나 런타임 영향을 주장하지 않는다.
- 저장소를 읽어 만든 노드는 스스로
SRC n으로 표시되며, 하나의 공개 커밋에 고정된 파일과 줄 범위를 연다. 요청하지 않은 산출물은 출처 없이 남는다.
레이아웃도 범용 자동 배치에 맡기지 않고 에이전트가 계층·간격·경로·강조를 판단한다. 공유되는 자동 종단점은 한 점에 화살표를 몰지 않고 결정적으로 퍼진다.
자체 완결 HTML과 뷰어
출력은 하나의 자체 완결 HTML 파일이다. 내려받아 브라우저에서 열면 archify를 설치하지 않아도 노드 상세, 경로 탐색, 안내형 챕터가 그대로 동작한다. 파일을 남에게 보내면 상호작용도 함께 간다(외부 링크나 지도만 네트워크가 필요하다).
뷰어에는 여러 조작이 있다.
| 동작 | 조작 |
|---|---|
| 다이어그램 안내 열기 | ? |
| 노드 찾아 포커스 | / |
| 상류·하류 도달 범위 추적 | 노드 포커스 후 Upstream / Downstream |
| 경로를 따라가며 흐름 확인 | R |
| 역할 하나·둘 비교 | L |
| 개요 레이더 열기 | M |
| 안내 스토리 재생·챕터 이동 | P · [ ] |
| 발표 모드 | F |
| 시각 스타일·테마·내보내기 | S · T · E |
내보내기 메뉴는 PNG를 클립보드에 복사하거나 정적·모션 형식을 내려받는다. README나 릴리스, 소셜 글에 쓸 1200×630 공유 카드도 뽑을 수 있고, 추적한 경로나 도달 범위를 그대로 담은 공유 카드도 만든다. 링크에 #focus=<id>·#route=<소스>~<타깃>·#view=<뷰-id> 같은 조각을 붙이면 특정 상태를 복원할 수 있다. 독자가 만드는 움직임은 유한하고 prefers-reduced-motion을 존중하며, 정식 내보내기에는 들어가지 않는다.
저장소에서 아키텍처 지도 뽑기
설명뿐 아니라 실제 코드에서 근거 있는 지도를 만들 수 있다. 저장소를 열고 “이 저장소를 분석한 뒤 archify로 상위 수준 런타임 아키텍처를 그려 줘. 핵심 구성 요소 8~12개, 주 경로 하나, 외부 의존성, 신뢰 경계를 보여 줘”처럼 요청하면 된다. 실제로 archify는 공개 저장소 mco-org/mco를 특정 커밋에서 추적해 검증된 런타임 지도를 만들어 사례로 공개했다. 설계 검토나 PR 리뷰에는 Architecture Delta가 있어, 검증된 이전·변경·이후 스냅숏을 기계 영수증과 함께 비교한다. 다만 이 비교는 영향도나 병합 안전성을 추론하지 않는다.
설치는 에이전트별로 위치가 다르다. Claude Code는 ~/.claude/skills/, Codex CLI는 ~/.agents/skills/, OpenCode는 ~/.config/opencode/skills/ 등에 둔다. Claude.ai에는 archify.zip을 스킬로 업로드한다.
범위 밖에 둔 것
archify는 몇 가지를 의도적으로 다루지 않는다. Mermaid 자동 파싱, 범용 자동 레이아웃, 호스팅 기반 공유, WYSIWYG 편집은 현재 범위 밖이다. 대신 검증 가능하고 이식 가능한 소통용 다이어그램을 만드는 데 집중한다.
출처
- archify (github.com/tt-a1i/archify, MIT 라이선스). 본문은 저장소 README와 문서를 바탕으로 정리했다. 공식 사이트: tt-a1i.github.io/archify