Archify: 코드와 시스템 설명을 검증 가능한 다이어그램으로 바꾸려면

코드베이스나 업무 시스템의 구조를 설명해야 하는 개발자·기획자라면, 보기 좋은 그림을 만드는 것보다 어떤 관계가 실제 근거를 갖는지 확인하는 일이 먼저입니다. Archify는 Cursor, Claude Code, Codex CLI, OpenCode 같은 코딩 에이전트에서 시스템 설명이나 저장소를 바탕으로 typed JSON 중간 표현을 만들고, 이를 검증된 HTML·SVG·PNG 등으로 내보내는 오픈소스 스킬입니다. 이 글에서는 어떤 설명 업무에 맞는지, 공식 README에서 확인한 범위와 도입 전에 사람이 확인할 한계를 정리합니다.

다이어그램을 만들 때 무엇이 가장 자주 빠지나요?

에이전트에게 “이 시스템을 그려 달라”고 요청하면 구성 요소는 그럴듯하게 나와도 실제 코드의 호출 관계, 데이터 경계와 예외 흐름이 섞일 수 있습니다. 다이어그램이 발표 자료로는 보이지만 변경 검토나 인수인계의 근거로 쓰기 어려운 이유입니다.

Archify를 볼 때의 핵심 질문은 “얼마나 예쁘게 그리나요?”가 아닙니다. 다음 세 가지를 구분할 수 있는지가 더 중요합니다.

설명에 직접 적은 관계와 저장소에서 확인한 관계가 구분되는가요?
자동 배치 결과를 사람이 수정하고 다시 검증할 수 있나요?
다이어그램 파일과 생성 근거를 Git이나 문서 저장소에 남길 수 있나요?

이 기준이 필요하지 않은 단순한 회의용 스케치라면 일반 화이트보드나 기존 다이어그램 도구가 더 빠를 수 있습니다.

어떤 업무에 맞나요?

구조·흐름·변경을 서로 다른 그림으로 나눕니다

공식 README는 다음 다섯 유형을 안내합니다.

Architecture: 서비스·저장소·외부 시스템과 경계를 설명합니다.
Workflow: 승인, 도구 호출, 배포와 같은 순서·분기를 보여 줍니다.
Sequence: 한 요청이 어떤 순서로 호출되고 응답하는지 나타냅니다.
Data Flow: 자료가 어디서 들어와 변환·저장·전달되는지 정리합니다.
Lifecycle: 상태, 재시도, 대기와 종료 조건을 나눕니다.

같은 시스템을 다섯 그림으로 한꺼번에 만들기보다, 질문에 맞는 한 유형을 먼저 고르는 편이 검수하기 쉽습니다. 예를 들어 API 호출 순서를 설명하려면 Architecture보다 Sequence가 적합합니다. 개인정보가 어느 단계에서 이동하는지 확인하려면 Data Flow에 경계를 명시하는 편이 낫습니다.

변경 전·후를 PR 검토 자료로 남깁니다

Archify는 검증된 Before·Delta·After 스냅샷을 비교하는 기능도 안내합니다. 비교 결과는 추가·삭제·변경·이동·경로 변경처럼 작성된 사실의 차이를 보여 주는 방식입니다.

이 기능은 “이번 변경이 안전하다”는 결론을 대신 내리지 않습니다. PR을 검토하는 사람은 변경된 구성 요소와 경로를 읽고, 실제 테스트·권한·운영 조건을 별도로 확인해야 합니다. 다이어그램 비교는 검토할 범위를 줄이는 자료이지 승인 자체가 아닙니다.

공식 README에서 확인한 사용 방식은 무엇인가요?

Archify는 일반적인 그래픽 편집기보다 에이전트 스킬과 Node.js 렌더러·검증기에 가깝습니다. 에이전트가 typed JSON 중간 표현을 만들면 Archify가 스키마·레이아웃·HTML/SVG·경로·라벨 간격을 검사한 뒤 결과를 렌더링합니다. 최신 후보가 검사를 통과하지 못하면 이전에 확인된 결과를 유지하는 흐름도 README에 설명되어 있습니다.

저장소 전체를 먼저 설치하지 않고도 시스템 설명만으로 시작할 수 있습니다.

npx skills add tt-a1i/archify -g

저장소를 읽는 작업에서는 다음처럼 범위와 근거를 요청하는 방식이 공식 예시에 가깝습니다.

이 저장소를 분석한 뒤 런타임 아키텍처 다이어그램을 만들어 주세요.
핵심 구성 요소는 8~12개로 제한하고, 주 경로·외부 의존성·신뢰 경계를 표시해 주세요.
세부 내용은 카드에 넣고 관계선을 과도하게 늘리지 마세요.

결과는 하나의 HTML 파일로 공유할 수 있고, PNG·SVG·WebM·1200×630 공유 카드로 내보낼 수 있다고 안내합니다. 소스 근거가 필요한 경우에는 공개 커밋에 고정한 파일과 줄 범위를 표시할 수 있습니다. 반대로 일반 산출물은 요청하지 않으면 소스 근거를 붙이지 않는 방식입니다.

2026년 9월 13일 GitHub API에서 tt-a1i/archify는 별 59,428개, 주 언어 JavaScript, MIT 라이선스로 확인했습니다. 공식 README의 현재 개발 버전 표시는 v2.17.0-dev.1입니다. 별 수와 개발 버전은 공개 활동과 현재 변경 상태를 보여 주는 정보이며, 결과의 정확도나 팀 적용 가능성을 보증하지 않습니다.

선택 전에 어떤 한계를 확인해야 하나요?

일반 편집기는 아닙니다. 공식 README는 Archify를 일반적인 드로잉 편집기나 Mermaid 테마로 설명하지 않습니다. 자동 Mermaid 파싱, 호스팅 공유, WYSIWYG 편집은 현재 범위 밖이라고 명시합니다.
실제 인프라를 읽지는 않습니다. 배포 환경이나 실행 중인 시스템을 직접 조사하지 않으므로, 작성한 설명이나 에이전트가 읽은 저장소 범위가 틀리면 결과도 틀릴 수 있습니다.
검증이 설계 판단을 대신하지 않습니다. 검증기는 스키마와 렌더링·경로 규칙을 검사하지만, 아키텍처가 조직의 보안 정책에 맞는지, 변경 위험이 어느 정도인지, PR을 병합해도 되는지를 판정하지 않습니다.
범위를 작게 잡아야 합니다. 시스템 전체를 한 장에 넣으면 읽기와 검수가 어려워집니다. 핵심 구성 요소와 주 경로를 먼저 정하고 필요한 경우 여러 유형으로 나누는 편이 낫습니다.
버전을 고정해 확인해야 합니다. 현재 README는 개발 버전을 안내합니다. 팀의 문서나 자동화에 연결하기 전에는 사용할 버전의 설치 방법과 생성 결과를 고정해 다시 시험해야 합니다.
업데이트 확인 요청이 있습니다. 공식 README는 고정된 안정 매니페스트를 확인하는 선택적 업데이트 알림이 있으며, ARCHIFY_UPDATE_CHECK_DISABLED=1로 끌 수 있다고 설명합니다. 외부 통신을 제한하는 환경에서는 이 설정과 조직의 허용 범위를 먼저 확인해야 합니다.

이 저장소를 직접 설치하거나 대규모 코드베이스의 정확도·처리 시간·토큰 비용을 측정한 것은 아닙니다. README의 기능 설명과 공개 예시를 기준으로 도입 판단 기준을 정리한 글입니다.

처음에는 어떻게 시험할까요?

첫 시험은 운영 저장소가 아닌 복제본이나 공개 예시에서 시작하는 편이 좋습니다.

시스템 설명 또는 작은 저장소 하나를 고릅니다. 구성 요소를 8~12개 안팎으로 제한하고, 먼저 주 경로와 외부 경계를 적습니다.
Architecture, Workflow, Sequence, Data Flow, Lifecycle 중 한 유형을 선택합니다. 어떤 질문에 답하려는지 제목에 적어 둡니다.
에이전트가 만든 JSON과 HTML을 함께 확인합니다. 구성 요소·관계·라벨이 실제 원문과 맞는지 대조하고, 필요한 경우 공개 커밋 기준의 소스 근거를 요청합니다.
validate --json과 deliver --json 결과의 진단 내용을 읽습니다. 통과했다는 사실만 기록하지 말고, 어떤 항목을 검사했는지도 남깁니다.
코드 변경 검토에 사용할 때는 Before·Delta·After를 만든 뒤 테스트 결과와 사람이 확인할 권한·보안·운영 항목을 별도 표로 둡니다.

에이전트의 역할·참고 자료·도구·승인 단계를 함께 정리하려면 AI 에이전트 설정과 활용 과정의 실습 범위를 확인해 보세요. Archify 설치를 대신하는 과정은 아니며, 도구를 업무에 연결할 때 무엇을 맡기고 어떤 결과를 사람이 확인할지 정하는 데 초점을 둡니다.