Archify: 소스 구조를 탐색형 다이어그램과 설명서로 만드는 도구
아이디어나 소스 구조를 AI에게 설명하면 클릭하고 탐색할 수 있는 다이어그램과 한 페이지 설명서를 만드는 도구예요.
주요 기능
- 아키텍처·워크플로·시퀀스·데이터 흐름·생명주기·ERD·클래스·트리·타임라인·워터폴의 10가지 도표 유형을 제공한다.
- 노드 검색·집중 보기, 상하위 연결 추적, 경로 강조, 역할 비교, 테마·발표 모드를 제공한다.
- v3.2.0의 explainer는 결론, 근거, 표·절차·코드·도표를 결합한 한 페이지 답변을 만든다.
- 요청한 코드 근거는 공개 저장소의 특정 커밋·파일·줄과 연결할 수 있다. 그림은 실제 실행 구조를 자동 감시하는 대시보드가 아니다.
- HTML 단일 파일과 이미지·SVG·WebM 등 내보내기를 지원하며, 편집 가능한 JSON 원본을 함께 보존한다.
구조
에이전트가 스키마에 맞는 JSON IR 또는 explainer Markdown을 만들고 Node CLI가 검증·렌더링·전달한다. 실제 bin/archify.mjs에는 유형 분기와 파일 잠금·전달 부속 기록 처리가 있다. 스키마·레이아웃·경로·라벨 검사를 통과한 후보만 최종 파일을 교체하여 이전 정상 결과를 보존하는 구조다. 패키지 매니페스트 버전은 3.2.0, Node 요구사항은 >=18이다.
누구에게 쓸모 있나요
기획·설계 내용을 설명하거나 실제 코드의 구조를 근거와 함께 공유하려는 개발자·설계자·학습자. 저장소 없이 일상 계획·절차 설명에도 쓸 수 있다.
설치 전 준비
지원 AI 에이전트, Node.js 18 이상과 npx 설치용 npm·GitHub 네트워크가 필요하다. 생성 HTML 열람은 브라우저에서 한다. 에이전트 샌드박스에 Node 접근이 없으면 정식 렌더러 기능은 제한된다. 렌더러의 일반 경로는 별도 런타임 패키지 설치가 없는 CLI로 안내되며 개발·전체 테스트 의존성은 별도다.
- Node.js >=18을 실행할 수 있는 에이전트 환경
- Cursor·Claude Code·Codex CLI·OpenCode 등 문서에 열거된 호스트
- HTML 결과: 브라우저; 모바일/브라우저별 내보내기·가독성은 직접 검증하지 않음
- DeepSeek Harness 통합은 독립된 호스트·번들 버전 계약을 확인해야 함
설치 방법
- 문서상 기본 설치 예시: npx skills add tt-a1i/archify -g — 전역 설치이므로 사용할 계정·에이전트 범위를 먼저 선택한다. 이번 작업에서 실행하지 않았다.
- Cursor·Claude Code·Codex CLI·OpenCode는 README Installation options에 맞는 스킬 경로를 사용한다. 설치 후 에이전트가 Archify를 인식하는지 확인한다.
- DeepSeek Harness 통합은 별도 버전 채널이므로 기본 스킬 버전과 혼동하지 않는다. README 공개 설치는 1.0.0을 안내하지만 현재 커밋의 release.json은 3.2.0 번들과 DSH 0.2.1-rc.2를 준비한 상태다. 준비된 소스가 npm에 배포되었다고 단정할 수 없다.
- 도구 자체의 업데이트 알림을 원하지 않으면 문서의 ARCHIFY_UPDATE_CHECK_DISABLED=1 설정을 적용할 수 있다. 업데이트는 자동 설치하지 않는다.
사용 방법
- 에이전트에 ‘브라우저 → API → Redis, 캐시 미스는 PostgreSQL 조회로 이어지는 흐름을 Archify로 그려줘’처럼 입력한다.
- 실제 저장소를 분석할 때는 핵심 구성요소·주요 경로·외부 의존성·신뢰 경계와 커밋 근거를 요청한다. 원본 JSON과 최종 HTML을 함께 보존한다.
- HTML에서 노드를 선택하여 연결 경로를 살피고 색상·설명을 조정한다. 소스나 수치를 바꾸면 검증·전달 절차를 다시 거친다.
- 여러 내용을 설명하려면 ‘한 페이지 설명서로 정리해줘’라고 요청하고 인용·결론·도표를 확인한다. 도표 검증 통과와 사람이 수행하는 시각 검토를 구분한다.
비용과 API 키
Archify 자체는 무료 오픈소스이며 전용 모델 API 키를 요구하지 않는다. 생성에 쓰는 에이전트의 구독·API 호출은 별도다. README가 소개하는 제3자 유료 서비스는 각 운영자의 상품이며 Archify 공식 무료 소프트웨어와 구분해야 한다.
라이선스
LICENSE 원문과 archify/package.json에서 Apache-2.0을 확인했다. 배포 시 라이선스 사본, 관련 고지와 변경 표시 등의 조건을 검토해야 하며 상표 사용 권한은 별도다.
주의사항과 알려진 이슈
- AI가 읽지 않은 구조나 잘못 이해한 연결도 그릴 수 있다. 스키마·형상 검사는 원자료의 사실성이나 보안성을 보장하지 않는다.
- 일반 자동 레이아웃 도구, 임의 Mermaid 자동 파서, WYSIWYG 편집기, 호스팅 공유 서비스는 현재 범위 밖이라고 README가 명시한다.
- 업데이트 확인은 고정된 안정 버전 매니페스트에 GET 요청을 하며 서버는 IP·시간 등 HTTP 정보를 볼 수 있다. 문서상 프로젝트·프롬프트·계정 ID를 보내지 않지만 네트워크가 완전히 없는 구성은 아니다.
- 도표 원본과 근거 링크에 내부 저장소 이름·시스템 구성이 포함될 수 있으므로 HTML 공유 전에 공개 범위를 확인해야 한다.
- DSH 플러그인의 배포 버전과 저장소 준비 소스가 다를 수 있다. 기본 스킬이 3.2.0이라고 모든 통합이 같은 기능을 제공하는 것은 아니다.
#1154 느린 회선에서 설치 clone 시간 초과
사용자가 npx skills 설치의 300초 timeout을 보고했다. 저장소가 커서 느린 연결에서는 실패할 수 있다는 보고이며 본 환경 재현은 하지 않았다.
#1153 DSH 채널 동기화 요청
DSH 1.0.0은 Archify 3.0.1 번들이라는 공개 보고가 있으며 기본 스킬과 별도 배포·호스트 승인이 필요하다. 현재 커밋의 준비 메타데이터와 실제 공개 설치 안내를 구분했다.
확인 범위
확인 날짜: 2026-10-29
확인한 범위: 공식 GitHub의 지정 커밋 README·매니페스트·주요 구현/안전 문서·라이선스와 릴리스/열린 이슈를 읽은 정적 분석. 설치·실행·로그인·API 호출은 하지 않음.
확인 한계: 아래 설치·사용 절차는 공식 문서에 기재된 방법을 재정리한 것이며 직접 실행 검증 결과가 아님. 모든 OS·모델·브라우저 조합, 전체 의존성 보안, 모든 이슈를 검증하지 않음. 안정 릴리스 v3.2.0(2026-10-19 게시)과 현재 main 소스는 같다고 가정하지 않았다.
확인 커밋: e3920894b0f30db7d5fc7d7d4ece57b304c17015