LLM Wiki

tt-a1i/archify — 2026-09-12 요약

Properties3
description평문 설명에서 검증 가능한 대화형 아키텍처·워크플로우·시퀀스·데이터흐름·라이프사이클 다이어그램을 자체 완결 HTML로 생성하는 에이전트 스킬 — GitHub 저장소, 5가지 다이어그램 유형, 기능, 설치, SKILL.md 작성 원칙까지 종합 정리.
tagsdev-tools, open-source, diagrams, agent-skills, software-architecture
aliases아키파이 요약, archify 요약

18 min read

개요

Archify(tt-a1i/archify)는 평문 설명으로부터 검증 가능한 대화형 기술 다이어그램을 생성하는 에이전트 스킬이다.^[https://tt-a1i.github.io/archify/] Cursor, Claude Code, Codex CLI, OpenCode에서 사용할 수 있으며, 시스템 설명을 입력하면 브라우저에서 바로 열어볼 수 있는 자체 완결 HTML 파일로 출력한다.^[https://tt-a1i.github.io/archify/]

아키텍처, 워크플로우, 시퀀스, 데이터 흐름, 상태 머신(라이프사이클) 등 5가지 다이어그램 유형을 지원하며, MAP → READ → FULL로 진행되는 점진적 상세도, 의미론적 색상 체계, 어두운/밝은 테마, 선택적 모션, PNG·SVG·WebM 등 다양한 export를 제공한다.^[https://tt-a1i.github.io/archify/]

핵심 가치는 “truth before spectacle” — 모든 포커스·경로·스토리·소스 링크가 authored 또는 검증된 증거에서 도출되며, “one spatial narrative first”로 주요 경로를 먼저 읽기 쉽게 만든 후 보조 관계를 드러낸다.^[https://github.com/tt-a1i/archify/blob/main/PRODUCT.md]

저장소 메타 (2026-09-12 기준)

항목값
전체 이름tt-a1i/archify
설명Agent skill for beautiful, verifiable architecture, workflow, sequence, data-flow, and lifecycle diagrams—self-contained HTML with motion and crisp export.
별점67,400
포크4,506
기본 브랜치main
주 언어JavaScript
라이선스MIT
생성일2026-04-15
마지막 업데이트2026-09-19
이슈140 open
위키있음
GitHub Pages있음 (https://tt-a1i.github.io/archify/)
크기약 250MB
개발 버전v2.17.0-dev.1

Topics (20개)

architecture-diagram, claude-skill, developer-tools, diagram-as-code, mermaid-alternative, system-design, agent-skills, codex, data-flow-diagram, opencode, sequence-diagram, deepseek-harness, dsh-plugin, architecture-as-code, code-visualization, coding-agents, diagrams, diagrams-as-code, software-architecture, text-to-diagram

5가지 다이어그램 유형

T·01 Architecture diagram

시스템 구성요소, 클라우드 리소스, 데이터베이스, 캐시, 서비스, 보안 그룹 및 그 연결 관계를 표현한다.^[https://tt-a1i.github.io/archify/]

  • AWS / GCP / Azure 인프라 시각화
  • 마이크로서비스 토폴로지
  • 보안 경계
  • 네트워크 레이아웃

T·02 Workflow diagram

프로세스, 승인 게이트, 도구 호출, 런북, CI/CD 파이프라인을 표현한다.^[https://tt-a1i.github.io/archify/]

T·03 Sequence diagram

API 호출 체인, 요청 라이프사이클, 비동기 추적, 리턴 흐름을 표현한다.^[https://tt-a1i.github.io/archify/]

T·04 Dataflow diagram

파이프라인, ETL/ELT, 데이터 계보(lineage), 거버넌스, 소비자를 표현한다.^[https://tt-a1i.github.io/archify/]

T·05 Lifecycle diagram

상태 머신, 객체 라이프사이클, 실행/주문/배포 상태 전이를 표현한다. 대기 상태, 재시도, 취소, 터미널 결과를 포함한다.^[https://tt-a1i.github.io/archify/]

주요 기능

점진적 상세 (Progressive MAP → READ → FULL)

독자는 먼저 전체 맵을 보고, 세부 내용을 읽은 뒤, 필요 시 전체 디테일로 깊이 들어갈 수 있다.^[https://tt-a1i.github.io/archify/]

의미론적 색상 언어

인프라 구성요소에 의미론적 색상 체계를 적용하여 직관적 이해를 돕는다.^[https://tt-a1i.github.io/archify/]

시각 프리셋과 테마

4가지 시각 프리셋 + 어두운/밝은 테마 + 선택적 모션(경로 추적 애니메이션)을 제공한다.^[https://tt-a1i.github.io/archify/]

Zero dependency 단일 HTML

생성된 다이어그램은 단일 HTML 파일로, 서버나 런타임 의존성이 전혀 없다. 어떤 브라우저에서든 열면 바로 동작하며, 이메일 첨부나 PR 댓글로 공유할 수 있다.^[https://tt-a1i.github.io/archify/]

Export

PNG, JPEG, WebP, SVG, WebM(브라우저 네이티브 녹화) 및 1200×630 공유 카드를 지원한다.^[https://tt-a1i.github.io/archify/]

대화형 뷰어 기능

  • Semantic camera: 의미론적 카메라
  • Path-aware stories: 경로 인식 스토리
  • Guided views: 가이드 뷰
  • 검색/초점: 노드·경로 엔드포인트 검색
  • 관계 추적: upstream/downstream 추적
  • 의미론적 뷰: 역할 비교 등
  • 프레젠테이션 스테이지: F 키
  • 딥 링크: 특정 노드·스토리의 안정 링크 공유
  • Share Cards / Route·Reach Cards^[https://tt-a1i.github.io/archify/]

키보드 단축키

  • ?: 다이어그램 가이드
  • T: 테마 전환
  • /: 노드/경로 엔드포인트 검색
  • R: 경로 추적·조사·재생
  • M: 의미론적 레이더
  • L: 의미론적 종류 비교
  • F: 프레젠테이션 스테이지

설치 (3단계)

Step 1 — 스킬 설치^[https://tt-a1i.github.io/archify/]

npx skills add tt-a1i/archify -g

또는 Cursor / Claude Code / Codex 용 에이전트 인식 빠른 시작 페이지를 열어 정확한 명령어를 받는다: https://tt-a1i.github.io/archify/start.html?agent=<agent>&type=architecture

Raven은 switcher 대상이 아니므로 수동 ZIP 설치를 사용한다: archify.zip을 ~/.raven/workspace/skills에 압축 해제하면 ~/.raven/workspace/skills/archify가 된다.^[https://tt-a1i.github.io/archify/]

배포 타겟별 설치 위치

서피스설치 위치/방법capability
Raven수동 ZIP → ~/.raven/workspace/skills/archify전체 렌더러 + 검증 워크플로
Claude Code~/.claude/skills/ 또는 .claude/skills/전체 렌더러 + 검증 워크플로
Codex CLI~/.agents/skills/ 또는 .agents/skills/전체 렌더러 + 검증 워크플로
opencode~/.config/opencode/skills/, .opencode/skills/, .agents/skills/전체 렌더러 + 검증 워크플로
Claude.aiSettings → Capabilities → Skills에 archify.zip 업로드샌드박스 내 Node.js 접근에 의존
Project Knowledge프로젝트에 archify.zip 업로드프롬프트 기반 아키텍처 폴백
DeepSeek Harnessdsh plugin --profile web add @tt-a1i/archify-dsh@0.1.0 (옵트인) / 제거: dsh plugin --profile web remove @tt-a1i/archify-dsh커뮤니티 통합 (개발자 미리보기 @deepseek-ai/dsh@0.1.0-rc.6, Node `^22.19.0

^[https://github.com/tt-a1i/archify/blob/main/README.md]

Step 2 — 에이전트에게 Archify 사용 지시
에이전트에게 “Archify를 써줘”라고 말하면, 에이전트가 자체 완결 HTML 파일을 생성해준다.^[https://tt-a1i.github.io/archify/]

Step 3 — 브라우저에서 열고 채팅으로 정제
생성된 HTML을 브라우저에서 열고, 채팅을 통해 다이어그램을 수정·보완할 수 있다.^[https://tt-a1i.github.io/archify/]

저장소 실례: mco-org/mco 런타임 아키텍처

Archify는 공개 저장소 mco-org/mco를 9f1a1cf에서 추적(trace)해 검증된 맵을 생성한 사례가 있다.^[https://github.com/tt-a1i/archify/blob/main/README.md]

  • 아키텍처 다이어그램: 공유 카드 및 대화형 뷰 (view: dispatch-path)
  • downstream 도달 가능성(reach) 추적
  • 타입드 JSON 소스: docs/cases/mco-runtime.architecture.json

스폰서

후원

이메일로 연락: 2801884530@qq.com^[https://github.com/tt-a1i/archify/blob/main/README.md]

설계 원칙 (PRODUCT.md)

PRODUCT.md에 명시된 두 가지 핵심 설계 원칙:^[https://github.com/tt-a1i/archify/blob/main/PRODUCT.md]

  1. Truth before spectacle: 모든 포커스, 도달 가능성 쿼리, 경로, 스토리, 소스 링크, 수령(receipt)은 authored 또는 검증된 증거에서 도출되어야 한다.
  2. One spatial narrative first: 주요 경로를 읽기 쉽게 만든 후에 보조 관계와 상세를 드러낸다.

대상 사용자

소프트웨어 엔지니어, 아키텍트, 기술 리드, 리뷰어, 그리고 코드베이스·시스템·워크플로우·요청 경로·데이터 파이프라인·라이프사이클을 이해하거나 설명해야 하는 AI 코딩 에이전트.^[https://github.com/tt-a1i/archify/blob/main/PRODUCT.md]

제품 목적

저장소 증거 또는 제한된 시스템 설명을 에이전트 대화에서 바로 볼 수 있는 정제된 대화형 기술 맵으로 변환하는 것.^[https://github.com/tt-a1i/archify/blob/main/PRODUCT.md]

성공 기준: 독자가 주요 스토리를 빠르게 이해하고, 필요할 때 정확한 authored 관계와 증거를 조사하며, 완전한 아티팩트 또는 명시적으로 범위가 지정된 Route/Reach Share Card를 리뷰·문서화·프레젠테이션에 활용할 수 있어야 한다.^[https://github.com/tt-a1i/archify/blob/main/PRODUCT.md]

SKILL.md — 작성 원칙과 워크플로우

타입 라우터

타입용도
architecture구성요소, 서비스, 클라우드/보안 경계, 인프라
workflow프로세스, 승인 게이트, 도구 호출, 런북, CI/CD
sequenceAPI 호출 체인, 요청 라이프사이클, 비동기 추적, 리턴
dataflow파이프라인, ETL/ELT, 계보, 거버넌스, 소비자
lifecycle상태/상태 전이, 재시도, 대기 및 터미널 상태

애매할 때는 node bin/archify.mjs guide "<질문>" --json으로 참고할 수 있다.^[https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md]

Mermaid 입력 변환

  • flowchart / graph → workflow, 또는 구성요소 맵이면 architecture
  • sequenceDiagram → sequence (참가자가 의미론적 참가자로, 화살표가 메시지로 변환)
  • stateDiagram → lifecycle (상태와 전이의 의미를 유지, Mermaid 스타일은 무시) ^[https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md]

빠른 작성 경로 (Fast authoring path)

  1. 질문에서 architecture, workflow, sequence, dataflow, lifecycle 중 선택
  2. schemas/에서 매칭 스키마 + examples/에서 JSON 예시 읽기 (사실은 복사하지 않고 필드 모양만 참고)
  3. 아티팩트 우선: 후보를 먼저 작성한 후 렌더러 내부를 조사. 정확한 좌표를 사전에 계획하지 않는다.
  4. 매 편집 후 + 핸드오프 전 validate 실행
  5. deliver로 최종 승인

새 워크플로우 소스는 schema_version: 2와 읽기 쉬운 레이아웃 계약을 사용하고, 기존 워크플로우의 고정 기하를 보존할 때만 schema_version: 1을 유지한다.^[https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md]

작성 불변 원칙 (Authoring invariants)

  • 하나의 명확한 주요 경로: 부차적 브랜치는 가장 가까운 주요 경로 노드에서 분기. 라우팅 제어 추가 전에 낮은 가치 에지를 제거.
  • meta.visual_preset 기본 생략: 모든 다이어그램은 classic으로 열린다. 색상 모드와 시각 프리셋은 독립적 — Light/Dark 전환 시 현재 프리셋 보존. signal-flow, blueprint, editorial은 사용자가 명시적으로 요청할 때만 설정.
  • meta.subtitle 기본 생략: 제목·노드·카드를 재진술하는 부제를 임의로 만들지 않는다. 사용자가 명시적으로 요청한 경우에만 짧은 보조 라인 포함.
  • 데스크톱 뷰어는 1차 화면 아티팩트로 기본: 좁거나 모바일 레이아웃은 포함이 요구할 때만 세로로 스크롤. 반응형 아티팩트는 노트북·외부 디스플레이용으로 생성 (장치별 HTML이나 대체 토폴로지 금지).
  • meta.animation: "trace"는 옵트인: 기본 비활성화, 데모·프레젠테이션 요청 시에만 활성화.
  • meta.views 선택적: 최대 5개 큐레이션된 챕터 포함.
  • meta.legend 기본 auto: 필요 시 mode: auto|all|hidden과 렌더러 지원 entries..label|visible만 사용, 라벨은 의미를 바꾸지 않음.
  • 기본 언어: 명시적 사용자 선택 또는 대화 우세 언어. meta.locale은 렌더러 소유 Viewer UI만 제어 ("en" / "zh-CN"). 그 외 언어는 meta.locale 생략하고 Viewer UI·고정 텍스트가 영어로 폴백됨을 명시. 렌더러는 authored 콘텐츠를 번역하지 않는다.^[https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md]

Validation

validate 명령으로 9가지 아티팩트 검사를 실행한다.^[https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md]

  • 기본 유효성 검사: 4개 아티팩트 검사만 있는 receipt는 기본 검증일 뿐, showcase 승인 아님.
  • Showcase 통과: 9개 아티팩트 검사 전부 통과 + 구성 오류 0 + 경고 0 필요.
  • meta.quality_profile 필드가 누락되거나 철자 오류면 기하보다 먼저 수정.
  • 워크플로우 v2 기하 진단: node bin/archify.mjs validate workflow --layout-json 실행 후 컴파일러 receipt 사용 (솔버 내부는 작성 제어 아님).

Delivery

deliver는 최종 승인 명령 — spec 바이트를 동일 디렉토리의 비공개 스냅샷으로 동결, 그 스냅샷을 렌더·검증, HTML을 원자적으로 커밋, spec/아티팩트 양쪽의 SHA-256 + 바이트 수를 보고한다.^[https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md]

이는 결정적 아티팩트 증거이며, 브라우저에서 뷰어를 실행하지 않는다.

visual-check는 전달된 정확한 HTML에서 자동 브라우저 증거를 수집하며, HTML을 수정하거나 재렌더하지 않는다. 기계 판독 측정과 스크린샷은 지각적 완성도를 승인하지 않는다.^[https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md]

세 가지 주장을 분리해서 보고할 것:

  • deliver: 결정적 아티팩트 검사 증명
  • visual-check: 실제 브라우저에서 제한된 동작 증명
  • 지각적 시각 검토: 실제 인간 또는 이미지 가능 리뷰어 필요

--open은 사용자가 즉시 로컬 미리보기를 원할 때만 추가.^[https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md]

Update awareness

첫 후보 생성 후 scripts/check-update.mjs를 Node로 한 번 실행.^[https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md]

  • silent: 업데이트 체크 언급 없이 계속
  • update_available: 사용자 대화 언어로 간결한 공지 (설치 버전, 최신 버전, 체커 고정 로컬 요약, 공식 릴리스 노트 링크). severity가 security면 보안 업데이트임을 명확히 표시하되, 사용자 자율성을 바꾸지 않음.
  • 공지는 정보일 뿐 허가가 아님. 설치 버전은 그대로 유지. v0.1 워크플로우는 업데이트 다운로드·설치·실행을 절대 하지 않으며, 무응답은 동의가 아님.

Setup & fallback

스킬 패키지 안에서는 설치가 필요 없다.^[https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md]

node bin/archify.mjs --version

셸 접근이 불가능할 때는 수동 배치: architecture SVG를 assets/template.html에 넣고, 인라인 색상 대신 CSS 의미론적 클래스를 사용하며, references/delivery-contract.md의 시각 검토 계약을 따른다.^[https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md]

기반 (lineage)

Archify는 Cocoon-AI/architecture-diagram-generator v1.0의 포크 및 리라이트다.^[https://github.com/tt-a1i/archify] 원본 시각적 언어는 Cocoon AI에 귀속되며, Archify 2.x는 테마, export, 타입드 렌더러, 검증, 접근성, 상호작용, 통합 CLI를 추가했다. 두 프로젝트 모두 MIT 라이선스.^[https://github.com/tt-a1i/archify]

벤치마크·갤러리

공식 갤러리에서 실 artifacts를 확인할 수 있다: https://tt-a1i.github.io/archify/ — 여러 preset·type 조합의 라이브 아티팩트와 9/9 검증 검사 통과 예시를 제공한다.^[https://tt-a1i.github.io/archify/]

관련 페이지

출처

백링크