이 도구는 잘못된 AI 다이어그램을 수정합니다

AI 에이전트는 코드베이스를 매핑할 때 종종 거짓말을 합니다. 코딩 에이전트에게 리포지토리 다이어그램을 그려달라고 요청하면, 실제로는 존재하지 않는 Kafka, Redis 또는 API 게이트웨이가 나타날 수 있습니다. 이러한 다이어그램은 그럴듯해 보이지만 구성 요소를 환각(hallucination)으로 만들어내어, 전체 시각 자료를 신뢰할 수 없고 실제 개발에 쓸모없게 만듭니다. 허구에서 탄생한 시각 자료에 의존할 수는 없습니다.

Archify는 이 문제를 정면으로 해결합니다. Archify의 AI 에이전트는 아무것도 그리지 않습니다. 대신 시스템을 구조화된 typed JSON으로 설명합니다. 이러한 근본적인 변화는 시스템에 대한 정확한 설명과 시각적 표현을 분리합니다. Archify는 다이어그램이 나타나기 전에 이 JSON을 엄격하게 검증하여 처음부터 정확성을 보장합니다.

Archify를 시스템 맵을 위한 LLVM이라고 생각하십시오. AI 코딩 에이전트는 프론트엔드 역할을 하며 초기 시스템 설명을 생성합니다. 그 설명은 엄격한 스키마를 준수해야 하는 검증된 JSON Intermediate Representation (IR)이 됩니다. 이러한 검증을 통과한 후에만 로컬 컴파일러가 IR을 최종 대화형 HTML로 변환하여, 추측이 아닌 다단계의 검증 가능한 출력을 보장합니다.

Archify는 AI가 단순히 다이어그램을 '그리도록' 두지 않습니다. 대신 AI 에이전트가 구조화된 typed JSON Intermediate Representation (IR)을 출력하도록 요구합니다. 이 IR은 엄격하고 결정론적인 검증 파이프라인으로 들어갑니다. Archify는 엄격한 스키마와 무결성을 위한 원자적 게이트(atomic gates)를 통해 시스템 설명이 유효한지 확인합니다.

중요한 점은 잘못된 JSON이 마법처럼 결함 있는 다이어그램이 되지 않는다는 것입니다. 그래프가 유효하지 않으면 Archify는 프로세스를 중단하고 명확한 진단 정보와 규칙 코드를 제공합니다. 이는 조용히 잘못된 시각적 표현을 신뢰하는 대신, 즉시 조치를 취할 수 있는 오류 메시지를 얻을 수 있음을 의미합니다. 이러한 'fail closed' 접근 방식은 근본적인 신뢰성을 구축합니다.

다음으로, Archify는 Repo Evidence 기능을 통해 검증 가능한 강력한 증거 계층을 추가합니다. 다이어그램의 노드에는 'SRC' 배지가 표시될 수 있습니다. 이를 클릭하면 구성 요소의 존재를 증명하는 특정 코드, 커밋, 심지어 리포지토리 내의 정확한 라인 범위로 직접 이동합니다. 따라서 아키텍처는 단순히 그럴듯한 것이 아니라 증명 가능한 진실이 됩니다.

Mermaid와 같은 도구를 고려해 보십시오. 구문적으로 올바른 다이어그램 코드를 작성할 수 있지만, 논리적으로 결함이 있거나 실제 코드베이스에 없는 구성 요소를 포함하는 다이어그램이 생성될 수 있습니다. Archify의 포괄적인 검증 계층과 직접적인 코드 연결 증거는 다른 도구에는 없는 semantic trust(의미론적 신뢰)라는 중요한 차원을 추가합니다.

Archify의 컴파일러가 JSON을 검증한 후, 독립형 HTML 파일을 생성합니다. 이것은 정적 이미지가 아니라 진정한 유용성을 제공하는 대화형 시스템 맵입니다. 모든 서비스를 검색하여 상위 및 하위 종속성을 즉시 확인할 수 있습니다. 그런 다음 정적 다이어그램을 보기만 하는 대신, 전체 시스템을 통해 'cache miss' 경로를 따라가는 것과 같이 복잡한 흐름을 단계별로 대화식으로 추적할 수 있습니다.

풀 리퀘스트의 경우, architecture diffing 기능이 중요한 이점을 제공합니다. Archify는 시스템의 두 가지 검증된 스냅샷을 비교하여 시각적인 '변경 전, 델타, 변경 후' 비교를 생성합니다. 이는 어떤 구성 요소가 추가, 제거 또는 경로 변경되었는지 등 모든 아키텍처 변경 사항을 명확하게 강조하여 코드 리뷰를 훨씬 더 강력하게 만들고 의도치 않은 변경을 방지합니다.

인터랙티브 HTML 파일이 Archify의 핵심 결과물이자 가장 강력한 기능이지만, 강력한 내보내기 기능도 제공합니다. PNG, JPEG, WebP, SVG, WebM과 같은 형식으로 정적 이미지를 쉽게 생성할 수 있습니다. 또한 빠른 커뮤니케이션을 위해 1200x630 크기의 공유 카드도 생성합니다. 하지만 이러한 내보내기 기능은 부차적인 것이며, 진정한 가치는 동적이고 탐색 가능한 HTML에 있다는 점을 유념하세요. Archify의 기능에 대해 더 자세히 알아보려면 GitHub 저장소를 방문하세요: tt-a1i/archify: Agent skill for beautiful, verifiable architecture, workflow, sequence, data-flow, and lifecycle diagrams—self-contained HTML with motion and crisp export. - GitHub.

Archify는 구체적이고 제한된 질문을 할 때 가장 뛰어난 성능을 발휘합니다. "이 저장소를 매핑해줘"와 같은 모호한 지시는 피하세요. 보통 쓸모없는 결과만 돌아옵니다. 대신 "캐시 미스에 대한 사용자 인증 흐름을 다이어그램으로 그려줘"와 같이 명확한 질문을 하고, 명확성과 집중도를 높이기 위해 노드를 8~12개로 제한하는 것이 좋습니다. 이러한 타겟팅 접근 방식은 의미 있고 검증된 결과물을 보장합니다.

하지만 Archify가 만능 해결책은 아닙니다. GitHub는 인터랙티브 HTML 출력을 렌더링하지 않으므로 GitHub README에 직접 삽입되는 간단한 다이어그램에는 적합하지 않습니다. 또한 이 도구는 독립형 앱이 아닌 에이전트 스킬로 통합되어 Claude Code 또는 Cursor와 같은 플랫폼을 사용하는 기존 AI 에이전트 워크플로우가 필요합니다.

중요한 상황에서 Archify는 진가를 발휘합니다. 검증된 인터랙티브 출력은 다음과 같은 중요한 개발 단계를 위한 검증 가능한 아티팩트를 생성합니다:

• PR 리뷰를 위한 아키텍처 다이어그램을 생성하여 변경 사항의 차이를 명확하게 제공합니다.
• 설계 문서 내에서 새로운 기능을 설계합니다.
• 저장소 내 시스템 구성 요소에 대한 신뢰할 수 있고 커밋 준비가 완료된 단일 진실 공급원(source of truth)을 구축합니다.

이러한 접근 방식은 다이어그램을 정적 이미지에서 신뢰할 수 있고 편집 가능한 시스템 맵으로 변환하여 엔지니어링 프로세스에서 없어서는 안 될 부분으로 만듭니다.

Archify란 무엇인가요?

Archify는 Claude와 같은 AI 코딩 에이전트가 검증 가능하고 인터랙티브한 아키텍처 다이어그램을 생성할 수 있도록 지원하는 오픈 소스 에이전트 스킬입니다. 에이전트가 시스템의 구조화된 JSON 표현을 생성하면, Archify가 이를 검증하고 독립형 HTML 파일로 컴파일하는 방식으로 작동합니다.

Archify는 어떻게 부정확한 다이어그램을 방지하나요?

AI가 단순히 이미지를 '그리게' 하는 대신, Archify는 엄격한 검증 파이프라인을 적용합니다. AI는 스키마를 준수하는 타입이 지정된 JSON 그래프를 출력해야 합니다. JSON이 유효하지 않거나 불가능한 상태를 설명하는 경우, 프로세스는 명확한 진단과 함께 실패하여 오해의 소지가 있는 다이어그램 생성을 방지합니다.

어떤 AI 에이전트가 Archify와 함께 작동하나요?

Archify는 에이전트 스킬로 설계되었으며 Claude Code, Cursor, Codex CLI, OpenCode, DeepSeek Harness를 포함한 여러 인기 코딩 어시스턴트와 통합됩니다.

Archify가 Mermaid를 대체하나요?

PR이나 디자인 리뷰에 사용되는 AI 생성, 인터랙티브 및 검증 가능한 다이어그램의 경우 Archify가 더 뛰어난 기능을 제공합니다. 그러나 GitHub README에 직접 삽입되는 간단한 다이어그램의 경우, GitHub에서 기본적으로 렌더링되므로 Mermaid가 더 간단한 선택인 경우가 많습니다.