Archify 입문 가이드: GitHub 스킬을 AI에 연결해 구조도 만들기

프로젝트 폴더를 열었는데 파일이 너무 많아서 어디부터 봐야 할지 막막했던 적이 있나요? 프런트엔드, API, 데이터베이스가 어떻게 연결되는지 말로만 설명하기 어려울 때도 있습니다.

Archify는 이런 상황에서 AI 코딩 에이전트가 코드 저장소나 설명을 읽고, 사람이 살펴보기 쉬운 기술 다이어그램을 만들도록 돕는 에이전트 스킬입니다. 이 글에서는 처음 접하는 사람도 따라올 수 있도록 설치부터 시작하고, 중급자를 위한 검증과 활용 방법까지 차례로 살펴봅니다.

이 글은 2026년 8월 8일 공개 저장소를 기준으로 작성했습니다. 프로젝트는 빠르게 바뀔 수 있으므로 설치 전에는 아래 GitHub 저장소의 최신 README와 변경 기록을 확인하세요.

초보자를 위한 핵심 용어 사전

용어	쉬운 뜻
AI 에이전트	질문에 답하는 데서 끝나지 않고 파일 읽기, 명령 실행, 결과물 생성 같은 작업을 수행하는 AI 도구
에이전트 스킬	AI 에이전트가 특정 작업을 일정한 절차로 처리하도록 만든 설명서와 도구 묶음
저장소 또는 리포지토리	코드와 변경 기록을 함께 보관하는 프로젝트 폴더
아키텍처	프런트엔드, 서버, 데이터베이스 같은 구성 요소와 연결 관계
다이어그램	복잡한 구조나 순서를 상자와 화살표로 표현한 그림
JSON IR	다이어그램을 그리기 전에 구성 요소와 관계를 규칙에 맞게 적어 둔 중간 데이터
검증	JSON 구조, 배치, 연결선 등이 정해진 규칙을 지켰는지 검사하는 과정
런타임	프로그램이 실제로 실행되는 동안 구성 요소가 동작하는 환경

목차

1. Archify를 한 문장으로 이해하기
2. 어떤 그림을 만들 수 있나
3. GitHub에서 설치하고 AI에 연결하기
4. 첫 번째 다이어그램 만들기
5. Archify가 결과를 만드는 과정
6. 초급에서 중급으로 가는 실전 프롬프트
7. AI 결과를 안전하게 검토하는 법
8. Mermaid와 Draw.io 중 무엇을 쓸까
9. 자주 막히는 문제
10. 마무리

1. Archify를 한 문장으로 이해하기

Archify는 코드 저장소 또는 시스템 설명을 받아, AI 에이전트가 구조화된 기술 지도를 만들도록 돕는 스킬입니다.

일반적인 이미지 생성 AI에 “우리 서비스 구조를 그려 줘”라고 하면 보기 좋은 그림은 나올 수 있습니다. 하지만 상자 이름이 바뀌거나, 실제로 존재하지 않는 연결이 추가되거나, 수정할 때 전체 구성이 흔들릴 수 있습니다.

Archify는 먼저 구성 요소와 관계를 JSON 형태로 정리하고, 규칙을 검사한 다음, 한 파일로 공유할 수 있는 HTML 다이어그램을 만듭니다. PNG와 SVG 같은 정적 이미지로도 내보낼 수 있습니다. 핵심은 단순히 예쁜 그림을 만드는 것이 아니라, 수정하고 다시 검사할 수 있는 원본 데이터를 함께 둔다는 점입니다.

2. 어떤 그림을 만들 수 있나

Archify는 목적에 따라 다섯 가지 유형을 지원합니다.

유형	알고 싶은 질문	예시
Architecture	시스템이 무엇으로 구성되어 있나?	웹 앱, API, 인증, DB, 외부 서비스
Workflow	업무가 어떤 순서로 진행되나?	승인, 배포, 실패 시 롤백
Sequence	누가 누구를 어떤 순서로 호출하나?	브라우저 → API → Redis → DB
Data Flow	데이터가 어디서 와서 어디로 가나?	수집 → 정제 → AI 분석 → 저장
Lifecycle	상태가 어떻게 변하나?	대기 → 처리 → 재시도 → 완료 또는 취소

처음에는 유형을 하나만 고르는 것이 좋습니다. 전체 서비스 구성이 궁금하면 Architecture, 로그인 요청 한 번의 흐름이 궁금하면 Sequence가 적합합니다. 모든 정보를 한 그림에 넣으면 선이 많아져 오히려 이해하기 어려워집니다.

3. GitHub에서 설치하고 AI에 연결하기

가장 간단한 전역 설치

Node.js와 npx를 사용할 수 있는 터미널에서 다음 명령을 실행합니다.

npx skills add tt-a1i/archify -g

설치 위치와 지원 에이전트, 최신 명령은 다음 공식 저장소에서 확인할 수 있습니다.

• tt-a1i/archify 공식 GitHub 저장소

-g는 여러 프로젝트에서 사용할 수 있도록 전역으로 설치한다는 뜻입니다. 공식 문서상 동일한 스킬을 Codex CLI, Claude Code, Cursor, OpenCode 등에서 사용할 수 있습니다. 에이전트마다 스킬을 찾는 폴더가 다를 수 있으므로, 설치가 끝난 뒤에는 사용하는 에이전트를 새 세션으로 시작하는 편이 안전합니다.

설치하지 않고 Codex에서 한 번 사용하기

먼저 기능을 시험해 보고 싶다면 다음 명령을 사용할 수 있습니다.

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

이 방식은 영구 설치 전 간단히 체험할 때 편리합니다.

Git으로 직접 내려받기

스킬의 파일 구조와 예제를 직접 살펴보려면 저장소를 복제할 수 있습니다.

git clone https://github.com/tt-a1i/archify.git
cd archify
node bin/archify.mjs doctor

• Archify 설치 및 사용 설명

doctor는 필요한 파일과 실행 환경이 준비되었는지 점검합니다. 저장소를 직접 복제한 방식과 skills add로 에이전트에 설치한 방식은 목적이 다릅니다. 전자는 내부 예제와 CLI를 연구할 때, 후자는 AI 작업 중 스킬을 바로 호출할 때 알맞습니다.

4. 첫 번째 다이어그램 만들기

설치 후 프로젝트 폴더에서 AI 에이전트를 열고 다음처럼 요청해 보세요.

이 저장소를 분석한 뒤 Archify를 사용해
상위 수준의 런타임 아키텍처 다이어그램을 만들어 줘.

조건:
- 핵심 구성 요소는 8~12개만 표시
- 브라우저, API, 인증, 데이터베이스, 외부 서비스를 구분
- 사용자의 주요 요청 경로 하나를 강조
- 코드에서 확인하지 못한 내용은 추측하지 말고 '확인 필요'로 표시
- 검증된 HTML 결과와 원본 JSON을 함께 저장

좋은 요청에는 네 가지가 들어갑니다.

1. 분석 범위: 전체 저장소인지 특정 폴더인지
2. 그림 유형: Architecture, Sequence 등
3. 꼭 보여 줄 대상: 인증, DB, 외부 API 등
4. 추측 처리 방식: 모르는 사실을 꾸며 내지 않도록 제한

“예쁘게 그려 줘”보다 “구성 요소 10개 이내, 주요 경로 하나, 확인되지 않은 연결은 표시하지 않기”처럼 경계를 정하면 훨씬 읽기 좋은 결과가 나옵니다.

5. Archify가 결과를 만드는 과정

Archify의 작업 흐름은 다음처럼 이해하면 쉽습니다.

코드 또는 시스템 설명
        ↓
AI가 구성 요소와 관계 분석
        ↓
규칙이 있는 JSON IR 작성
        ↓
스키마·배치·연결선 검증
        ↓
공유 가능한 HTML과 이미지 출력

1단계: Generate

AI가 프런트엔드, 서버, 데이터 저장소와 같은 대상을 찾고 관계를 JSON으로 기록합니다. 사람이 지도에 장소와 길을 먼저 표시하는 단계와 비슷합니다.

2단계: Validate

필수 항목이 빠지지 않았는지, 존재하지 않는 노드를 화살표가 가리키지 않는지, 라벨과 연결선이 심하게 충돌하지 않는지 검사합니다.

직접 복제한 Archify 저장소에서의 검증 명령 예시는 다음과 같습니다.

node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json

3단계: Deliver

검사를 통과한 원본으로 HTML 결과를 만듭니다.

node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json output/workflow.html --quality showcase --json

중요한 차이가 있습니다. 이 검증은 “그림에 적힌 서버와 DB가 실제 운영 환경에 존재한다”는 사실 검증이 아닙니다. 작성된 데이터가 Archify의 구조와 표현 규칙에 맞는지를 검사합니다. 실제 시스템과 일치하는지는 코드, 설정 파일, 배포 환경을 사람이 함께 확인해야 합니다.

6. 초급에서 중급으로 가는 실전 프롬프트

초급: 프로젝트 전체 지도

Archify를 사용해 이 저장소의 Architecture 다이어그램을 만들어 줘.
초보자가 이해할 수 있도록 구성 요소마다 한 줄 설명을 붙이고,
사용자 요청이 들어와 응답이 나가는 기본 경로를 강조해 줘.

초급: 로그인 순서

다음 로그인 과정을 Archify Sequence로 만들어 줘.
브라우저 → 웹 앱 → 인증 API → 세션 저장소 → 데이터베이스.
세션이 없을 때만 데이터베이스를 확인하는 보조 경로도 표시해 줘.

중급: 데이터와 보안 경계

이 저장소의 사용자 데이터 흐름을 Archify Data Flow로 분석해 줘.
입력, 변환, 저장, 외부 전송 단계를 구분하고
개인정보가 지나가는 경계와 암호화 여부를 코드 근거와 함께 표시해 줘.
근거가 없으면 사실처럼 단정하지 말고 확인 필요 항목으로 남겨 줘.

중급: 변경 전후 비교

Archify는 검증된 두 Architecture JSON을 비교해 추가, 삭제, 변경, 이동, 경로 변경을 정리하는 Architecture Delta 기능도 제공합니다.

node bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json

이 기능은 PR에서 서비스가 새로 추가되었는지, 연결 방향이 바뀌었는지 검토할 때 유용합니다. 다만 변화의 위험도나 배포 안전성을 자동으로 증명하는 기능은 아닙니다.

7. AI 결과를 안전하게 검토하는 법

AI가 만든 다이어그램은 훌륭한 초안이지만 최종 사실 자료로 바로 사용하면 안 됩니다. 다음 순서로 확인하세요.

1. 구성 요소 이름이 실제 코드와 같은지 확인합니다.
2. 화살표의 방향을 API 호출 또는 데이터 이동 방향과 비교합니다.
3. 환경 변수, 라우트, 배포 설정에서 근거를 찾습니다.
4. AI가 추론한 항목과 코드에서 확인한 항목을 구분합니다.
5. 인증 정보나 내부 주소 같은 비밀 정보가 결과물에 들어가지 않았는지 확인합니다.
6. 수정 후 다시 검증하고 HTML을 생성합니다.

중급 사용자는 프롬프트에 근거 범위를 더 구체적으로 적을 수 있습니다.

실제 파일에서 확인한 구성 요소만 다이어그램에 넣어 줘.
각 핵심 노드에는 근거 파일 경로를 기록하고,
동적 설정 때문에 확정할 수 없는 연결은 별도 확인 목록으로 분리해 줘.
비밀 키, 토큰, 개인 식별 정보는 출력하지 마.

공개 저장소의 특정 커밋을 대상으로 작업한다면, 파일과 줄 번호를 커밋에 고정하는 증거 기반 Architecture 기능도 고려할 수 있습니다. 일반 다이어그램에는 소스 링크가 자동으로 붙는다고 가정하지 말고, 필요할 때 명시적으로 요청해야 합니다.

8. Mermaid와 Draw.io 중 무엇을 쓸까

도구	강점	잘 맞는 상황
Mermaid	텍스트로 빠르게 작성하고 Git에서 변경 비교가 쉬움	README 속 간단한 흐름도
Draw.io	마우스로 자유롭게 배치하고 세밀하게 편집 가능	발표 자료, 수동 디자인
Archify	AI 분석, 타입이 있는 JSON, 검증과 대화형 HTML 출력	저장소 분석, 반복 가능한 기술 지도

서로 완전히 대체하는 도구는 아닙니다. 작은 흐름은 Mermaid가 더 빠를 수 있고, 픽셀 단위 편집은 Draw.io가 편합니다. 코드 저장소를 AI와 함께 분석하고 같은 원본으로 검증과 재생성을 반복하려면 Archify의 장점이 큽니다.

Archify는 범용 자동 배치 엔진이나 WYSIWYG 편집기가 아니며, Mermaid 문법을 자동으로 모두 변환하는 도구도 아닙니다. 큰 시스템은 한 장에 전부 넣기보다 상위 Architecture와 세부 Sequence를 나누는 편이 좋습니다.

9. 자주 막히는 문제

AI가 스킬을 찾지 못해요

에이전트를 완전히 종료한 뒤 새 세션을 열어 보세요. 전역 설치가 아니라 프로젝트 범위 설치를 했다면 현재 프로젝트의 스킬 폴더에 설치되었는지도 확인합니다.

그림이 너무 복잡해요

구성 요소 수를 8~12개로 제한하고 주요 경로를 하나만 지정하세요. 부가 설명은 선을 늘리는 대신 카드나 메모로 옮겨 달라고 요청하면 좋습니다.

검증이 실패해요

--json 결과의 diagnostics를 읽고, 표시된 노드나 연결만 좁게 수정하세요. 전체 JSON을 처음부터 다시 만들면 이미 맞던 부분까지 달라질 수 있습니다.

HTML이 만들어졌으니 내용도 정확한가요?

아닙니다. HTML 생성과 구조 검증에 성공했다는 뜻입니다. 운영 환경의 실제 구성, 장애 가능성, 보안 수준까지 보증하지는 않습니다.

최신 기능은 어디서 확인하나요?

다음 설치 명령과 공식 저장소만 기준으로 확인하는 것이 안전합니다.

npx skills add tt-a1i/archify -g

• Archify 공식 변경 기록

10. 마무리

Archify를 처음 사용할 때는 거대한 시스템 전체를 완벽하게 그리려 하지 않아도 됩니다. “로그인 요청 하나”, “배포 승인 흐름 하나”, “핵심 서비스 10개”처럼 작은 범위로 시작하세요.

익숙해지면 원본 JSON을 Git에 함께 보관하고, 변경 전후 비교와 코드 근거 확인을 작업 과정에 넣을 수 있습니다. 그러면 다이어그램은 한 번 보고 버리는 그림이 아니라, AI와 사람이 함께 업데이트하는 프로젝트 지도가 됩니다.

가장 중요한 원칙은 간단합니다. AI에게는 범위와 확인 기준을 명확히 주고, 결과의 사실 여부는 코드와 설정을 통해 사람이 마지막으로 확인하세요.