Archify

$ npx skills add tt-a1i/archify -g copy

tt-a1i가 만든 오픈소스 스킬(tt-a1i/archify).

왜 필요한가?

시스템 구조를 남에게 설명해야 할 때, 손으로 그리면 코드가 바뀔 때마다 어긋나고 자동 배치 도구에 맡기면 화살표가 한곳에 몰려 읽기 어려워집니다. 에이전트에게 다이어그램을 그려 달라고 하면 그럴듯하지만 실제 구조와 다른 연결선이 섞여 들어오기도 합니다.

Archify는 이 사이를 갈라 놓습니다. 에이전트는 타입이 정해진 JSON만 쓰고, 그림을 그리는 일은 Archify가 맡습니다. JSON은 스키마 검사, 배치 검사, 경로 검사, 라벨 겹침 검사를 모두 통과해야 하고, 하나라도 실패하면 이전에 통과한 결과물이 그대로 남습니다. 검사에 걸리면 Node.js 오류 대신 어디를 어떻게 고쳐야 하는지가 기계가 읽을 수 있는 JSON으로 돌아옵니다.

결과물은 HTML 파일 하나입니다. 열어서 발표하고, 링크로 공유하고, PNG나 SVG로 내보낼 수 있습니다.

무엇을 만들 수 있나

다섯 가지 다이어그램을 지원하며, 각각 프롬프트에 넣으면 좋은 정보가 정해져 있습니다.

종류	어떤 때 쓰나	프롬프트에 넣을 것
아키텍처	구성 요소, 서비스, 저장소, 경계	범위, 핵심 구성 요소, 주 경로
워크플로	CI/CD, 승인 절차, 도구 호출, 런북	참여자, 순서, 분기, 예외
시퀀스	API 호출, 캐시 폴백, 인증, 비동기 추적	호출자, 피호출자, 반환, 타이밍
데이터 흐름	파이프라인, 데이터 계보, 개인정보, 소비자	출처, 변환, 저장소, 경계
라이프사이클	상태, 재시도, 대기, 종료 결과	상태, 이벤트, 재시도와 취소 경로

저장소 없이 대화창에 설명만 해도 됩니다.

Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback.

코드를 근거로 삼으려면 저장소를 연 채로 요청합니다.

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.

만든 뒤에는 add Redis, move auth to the left, highlight the rollback path처럼 부분만 고쳐 달라고 이어서 요청할 수 있습니다. 원본 JSON이 남아 있어 나머지 구조는 그대로 유지됩니다.

공식 사이트의 Proof Lab에 검증을 통과한 11가지 시나리오가 JSON 원본, 이름 붙은 뷰, 검증 기록과 함께 공개되어 있습니다. 실제 공개 저장소(mco-org/mco)를 특정 커밋 기준으로 분석해 만든 아키텍처 맵도 사례로 올라와 있습니다.

근거: tt-a1i/archify README, 공식 사이트 Proof Lab.

핵심 기능

타입이 정해진 JSON을 거치는 2단 구조

에이전트가 만드는 것은 그림이 아니라 JSON입니다. 렌더러가 붙은 모든 모드에 스키마가 있어 같은 입력이면 같은 결과가 나옵니다. 그림을 그리는 단계는 Archify가 결정적으로 처리합니다.
통과해야만 교체되는 전달 절차

전달 전에 스키마, 배치, HTML/SVG, 경로, 라벨과 경로의 간격 검사를 모두 통과해야 합니다. 실패하면 마지막으로 통과한 결과물이 그대로 남습니다. 실패 시 validate --json과 deliver --json이 규칙 코드, 문제가 된 대상, 측정된 근거, 지원되는 수정 방법을 함께 돌려줍니다.
없는 연결을 만들지 않는 상호작용

노드 검색, 상류와 하류로의 도달 범위 추적, 두 지점 사이의 경로 확인, 역할 비교, 이야기 재생이 모두 작성된 노드와 관계만 사용합니다. README는 이를 두고 실행 시점의 영향을 주장하지 않는다고 명시합니다.
변경분 비교 (Architecture Delta)

검증된 두 스냅숏을 Before, Delta, After로 비교해 추가, 삭제, 변경, 이동, 경로 변경 사실을 정확히 보여줍니다. 설계 검토나 PR 리뷰에 쓰는 기능이며, 영향도나 병합 안전성을 판단해 주지는 않습니다.
```
node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json
```
근거가 있는 노드만 표시

아키텍처 노드는 요청했을 때만 SRC n 표시를 달고, 하나의 공개 커밋에 고정된 파일과 줄 범위를 엽니다. 일반 결과물에는 소스 연결이 들어가지 않습니다.
내보내기와 공유

Export 메뉴에서 PNG를 클립보드로 복사하거나 정적, 동영상 형식으로 내려받습니다. README나 릴리스에 넣을 1200x630 공유 카드를 만들 수 있고, 경로를 추적한 뒤에는 그 경로만 강조한 공유 카드도 뽑을 수 있습니다. 내보낸 결과에는 보고 있던 화면 상태가 섞이지 않습니다.
어떤 다이어그램을 쓸지 물어보는 CLI

종류를 고르기 어려우면 의존성 없는 명령으로 물어볼 수 있습니다.
```
node archify/bin/archify.mjs guide "Show an API request with Redis cache miss"
```

사용 방법

스킬을 전역으로 설치합니다.

npx skills add tt-a1i/archify -g

Claude Code를 지정해 비대화형으로 설치하려면 다음과 같이 씁니다. Claude Code는 ~/.claude/skills/ 또는 프로젝트의 .claude/skills/에 설치되며, 렌더러와 검증 절차 전체를 씁니다.

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

설치하지 않고 먼저 써보려면 다음 명령을 씁니다.

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

설치 후에는 대화창에서 그리고 싶은 것을 설명하면 됩니다. 저장소 안에서 직접 다룰 때 쓰는 명령도 있습니다.

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

preview는 JSON 파일 하나를 지켜보다가 검사를 통과한 판만 새로 고치는 미리보기 모드입니다. 127.0.0.1의 임의 포트만 사용하고 Ctrl-C로 멈춥니다. 저장이 덜 됐거나 검사에 걸린 동안에는 마지막으로 통과한 다이어그램이 화면에 남습니다.

결과물 HTML에서는 단축키로 조작합니다. ?는 다이어그램 설명, /는 노드 검색, R은 경로 확인, L은 역할 비교, M은 전체 지도, F는 발표 모드, S는 시각 스타일 변경, T는 테마 전환, E는 내보내기입니다.

알아두면 좋은 점

업데이트 확인 통신이 있습니다 — Archify는 업데이트 알림을 띄우기 위해 고정된 매니페스트 주소에 GET 요청을 보냅니다. 업데이트를 내려받거나 설치하지는 않습니다. 서버는 IP와 시각 같은 일반적인 HTTP 정보만 받고 버전, 에이전트, 프로젝트 데이터, 프롬프트, 계정 식별자는 전달되지 않는다고 README가 밝히고 있습니다. 통신 자체를 끄려면 ARCHIFY_UPDATE_CHECK_DISABLED=1을 설정합니다
개발 버전이 앞서 있습니다 — README 기준 현재 개발 버전은 v2.17.0-dev.1입니다. 안정판과 차이가 있을 수 있으므로 CHANGELOG를 함께 봅니다
그리기 편집기가 아닙니다 — README는 “Archify is not a general-purpose drawing editor or a Mermaid theme”라고 선을 긋습니다. 자유롭게 도형을 배치하는 도구가 아니라, 기술적 의도를 전달용 결과물로 바꾸는 도구입니다
판단해 주지 않는 것 — 변경분 비교는 작성된 사실만 보여줍니다. 영향 범위, 위험도, 병합 안전성은 판단하지 않습니다. 아키텍처의 배포 소유권 프로필도 실제 인프라를 조회하지 않으며, 소유자나 리전 정보가 없으면 그리지 않고 실패합니다
설치수 출처 — skills.sh(npx skills) 텔레메트리 기준 약 68,000회입니다. claude.com/plugins에는 등록되어 있지 않습니다
한국어 표시는 지원하지 않습니다 — meta.locale로 페이지 제목과 범례, 접근성 문구를 현지화할 수 있지만 지원 값은 en과 zh-CN뿐입니다. 작성한 내용 자체는 번역되지 않으므로 노드 이름은 한국어로 써도 그대로 나옵니다
라이선스 — MIT

§ 6

자주 묻는 질문

§ 7.1

Archify는 무엇인가요?

시스템 설명이나 코드베이스를 인터랙티브 시스템 맵으로 만드는 에이전트 스킬입니다. 에이전트가 타입이 정해진 JSON을 작성하면 Archify가 검증을 거쳐 HTML 한 파일로 컴파일합니다.

§ 7.2

어떻게 설치하나요?

`npx skills add tt-a1i/archify -g` 한 줄이면 됩니다. Claude Code는 `~/.claude/skills/` 또는 프로젝트의 `.claude/skills/`에 설치되며 렌더러와 검증 절차 전체를 씁니다. 설치 없이 `npx skills use tt-a1i/archify@archify`로 먼저 시험해볼 수도 있습니다.

§ 7.3

저장소가 있어야 하나요?

아닙니다. "Browser -> API -> Redis cache -> PostgreSQL fallback"처럼 대화창에 시스템을 설명하기만 해도 됩니다. 저장소를 열어 두면 코드를 분석해 근거가 있는 다이어그램을 만들 수도 있습니다.

§ 7.4

어떤 종류의 다이어그램을 그릴 수 있나요?

아키텍처(구성 요소와 경계), 워크플로(CI/CD, 승인, 런북), 시퀀스(API 호출, 캐시 폴백), 데이터 흐름(파이프라인, 개인정보 경계), 라이프사이클(상태, 재시도, 종료) 다섯 가지입니다.

§ 7.5

Mermaid와 무엇이 다른가요?

README는 "Archify is not a general-purpose drawing editor or a Mermaid theme"라고 선을 긋습니다. 자동 배치 대신 에이전트가 계층과 간격, 경로를 판단하고, 전달 전에 스키마와 배치, 경로 검사를 모두 통과해야 결과물이 교체됩니다.

§ 7.6

무료인가요? 라이선스는?

MIT 라이선스 오픈소스로 무료입니다. 스킬을 구동하는 Claude Code 등 에이전트의 사용료는 별도입니다.