10.7k 스타짜리 저장소를 클론해서 열었는데, 본체가 마크다운 한 장이다. Archify는 Claude Code·Cursor·Codex CLI 같은 코딩 에이전트에게 아키텍처 다이어그램을 그리게 하는 “에이전트 스킬”이고, 에이전트가 실제로 읽는 지시문인 SKILL.md는 104줄이 전부다. 저장소 생성 2026년 4월 15일, 넉 달이 안 돼 스타 10,751개, 포크 833개, 6월 30일 GitHub 트렌딩 9위. 기여자는 두 명이다.
마크다운 한 장이 만 개의 스타를 받는 시대구나, 하고 넘기면 이 저장소의 재미를 놓친다. SKILL.md 뒤에는 JSON 스키마 6장과 2만 5천 줄의 자바스크립트가 있고, 그 대부분이 그림을 그리는 코드가 아니라 그림을 검증하는 코드다. 사람들이 여기에 스타를 누른 이유를 나는 그 검증 구조에서 찾는다.
믿을 수 있는 그림이라는 수요
코딩 에이전트에게 “이 시스템 아키텍처 그려줘”라고 해본 사람은 결과를 안다. 십중팔구 Mermaid가 나온다. 화살표가 노드를 뚫고 지나가고, 라벨이 겹치고, 조금 복잡한 토폴로지에서는 문법 오류로 렌더링 자체가 깨진다. 더 나쁜 건 그다음이다 — 그림이 그럴듯하게 나와도, 이 그림이 맞는지를 확인할 방법이 없다. 다이어그램은 코드와 달리 테스트가 없으니까.
Archify가 파고든 게 정확히 이 지점이다. 저장소 설명은 “beautiful”과 나란히 “verifiable”을 내걸고, 제품 원칙 문서의 첫 줄은 “스펙터클보다 진실(Truth before spectacle)“이다. 에이전트는 다이어그램을 그림으로 그리지 않는다. 타입이 지정된 JSON 중간표현으로 쓰고, 로컬 CLI가 그걸 스키마와 레이아웃 규칙으로 검사하고, 통과한 것만 자체 완결 HTML로 렌더링된다. 검사는 엣지가 무관한 노드를 관통하는지, 라벨이 다른 경로를 가리는지 같은 기하학 규칙까지 내려간다.
SKILL.md에서 제일 눈에 걸린 문장은 이거다.
A non-zero exit can never be described as success. (0이 아닌 종료 코드는 어떤 경우에도 성공으로 서술될 수 없다.)
에이전트를 굴려본 사람이라면 이 문장이 왜 있는지 안다. 에이전트는 검증 명령이 실패해도 “다이어그램을 성공적으로 생성했습니다!“라고 보고하는 동물이다. 이 스킬은 그 습성을 알고, 거짓 보고를 막는 문장을 지시문에 박아 뒀다. 출력 규정에도 같은 문장이 반복된다 — 하지 않은 시각 검토를 했다고 주장하지 마라, 실패한 진단은 정직하게 보고하라.
#17에서 트렌딩 레포 네 개를 읽고 사람들이 원하는 건 더 똑똑한 모델이 아니라 모델 주변 — 덜 헤매게, 한 번만 세팅, 내가 통제 — 이라고 썼다. Archify는 그 세 번째 수요의 순도 높은 표본이다. 모델은 이미 다이어그램을 그릴 만큼 똑똑하다. 없던 건 그 산출물에 대한 신뢰였고, 신뢰는 프롬프트가 아니라 검증기에서 나왔다.
해부: SKILL.md 104줄 뒤에 있는 것
구조를 뜯어보면, 이건 다이어그램 도구라기보다 한 작업만을 위한 하네스다. #35에서 하네스는 “모델 빼고 전부” — 에이전트가 원치 않는 결과를 내기 전에 막고, 냈을 때 스스로 고치게 만드는 제어 장치 일체라고 정리했는데, 그 제어 장치가 스킬 패키지 크기로 줄어든 모양새다.
첫째, 계약이 먼저다. 다이어그램 타입은 아키텍처·워크플로우·시퀀스·데이터플로우·라이프사이클 다섯 개뿐이고, 각각 JSON 스키마가 계약으로 존재한다. 에이전트의 자유도를 스키마가 미리 좁혀 놨다 — 컴포넌트 타입은 7종, 변형은 4종, 주 노드는 12개까지. #24에서 다룬 계약 우선 설계가 생성 작업에 적용된 사례로 이만한 게 없다. 자연어로 “예쁘게 그려줘”가 아니라, 타입 시스템이 허용하는 것만 표현할 수 있게 만든 것이다.
둘째, 생성-검증-수정 루프에 예산이 있다. 후보 JSON을 쓰면 validate가 9개 검사 항목을 돌리고, 실패하면 에이전트는 진단이 지목한 subject와 evidence만 고쳐서 재검증한다. 여기에 정지조건이 붙어 있다 — 두 라운드 연속으로 오류 수가 줄지 않으면 멈추고, 남은 진단을 그대로 보고하라. 고치기가 무한 루프로 빠지며 토큰을 태우는 대신, 실패를 인정하게 만드는 회계다. #51에서 본 “예산 차감은 검증된 작업에만”과 같은 사상이 작업 하나 크기로 축소돼 있다.
셋째, 컨텍스트에도 예산이 있다. SKILL.md는 에이전트에게 뭘 읽으라고 지시하는 만큼 뭘 읽지 말라고 지시한다. 스키마 한 장과 예제 한 장만 읽어라, 첫 후보를 쓰기 전에 렌더러 소스·검증기 소스·테스트를 열지 마라, 뷰어 런타임 문서는 사용자가 그 기능을 물을 때만 읽어라. 참조 문서 세 장이 필요할 때만 열리는 계층으로 분리돼 있다. #30의 언어로 말하면, 이 스킬은 프롬프트가 아니라 컨텍스트 예산표다. 2만 5천 줄짜리 코드베이스에서 에이전트가 실제로 읽는 건 몇백 줄로 통제된다.
넷째, 스킬이 자기 벤치마크를 들고 다닌다. 저장소에는 Ordinary-Model Floor라는 벤치마크가 들어 있다. 측정하는 질문이 구체적이다 — “평범한 코딩 에이전트가 사람 손 안 대고 첫 시도에 쓸 만한 다이어그램을 뽑는가.” 모델 리더보드가 아니라 출시 게이트라고 스스로 명시하고, 렌더링은 통과했지만 의미가 틀린 다이어그램도, 예쁘지만 검증에 실패한 다이어그램도 실패로 센다. 스킬의 품질을 평범한 모델의 첫 통과율로 정의했다. #44의 “모델은 빌리는 것이고 eval은 소유하는 것”이라는 명제를, 스킬 저장소가 문자 그대로 구현하고 있다.
마지막 전달 단계까지 결이 같다. deliver 명령은 스펙 바이트를 스냅샷으로 동결하고, 렌더링하고, HTML을 원자적으로 커밋한 뒤 스펙과 산출물 양쪽의 SHA-256과 바이트 수를 영수증으로 보고한다. 에이전트의 “다 됐습니다”를 해시로 대체하는 설계다.
계보: 스킬이 제품이 됐다
이 저장소가 소재로 흥미로워지는 두 번째 이유는 계보다. SKILL.md 메타데이터에 based_on: Cocoon-AI/architecture-diagram-generator (MIT, v1.0)이라고 적혀 있다. 원본은 2025년 12월에 나온 Claude 스킬로, 6.8k 스타를 받고 올해 5월부터 커밋이 멈췄다. Archify는 4월에 그 포크로 시작해 — 첫 버전 번호부터 v2.0.0이다 — 검증기·타입 렌더러·내보내기·벤치마크를 얹었고, 넉 달 만에 원본을 추월했다.
이 계보가 매끄럽기만 한 건 아니다. 8월 4일 커밋 로그에는 “docs: remove attribution section”이 있다 — README에서 원본을 소개하던 문단이 지워졌고, 지금은 SKILL.md 메타데이터 한 줄만 남아 있다. MIT 라이선스 안에서 합법이고, 추가한 것이 원본보다 많은 것도 사실이다. 다만 스킬 생태계에 포크·추월·출처 흐리기 같은 오픈소스의 오래된 드라마가 그대로 옮겨오고 있다는 신호로는 기록해 둘 만하다.
생태계 쪽 사실관계는 이렇다. Vercel이 올해 1월 skills CLI를 내놨고, npx skills add tt-a1i/archify -g 한 줄이면 Claude Code든 Cursor든 스킬이 설치된다. skills.sh 디렉토리에서 Archify의 설치 수는 8.7k. 저장소에는 유료 스폰서가 둘 붙어 있고 — API 리셀러 하나, 에이전트 메모리 스타트업 하나 — 버전은 v2.13.0, 체인지로그와 로드맵과 기여 가이드가 갖춰져 있다.
늘어놓고 보면 여느 소프트웨어 제품 소개와 다를 게 없다. 버전, 체인지로그, 벤치마크, 스폰서, 설치 수, 포크 경쟁. #17에서 ECC 같은 250개짜리 스킬 번들을 보며 “에이전트 설정은 결국 가볍고 표준화된 포맷으로 수렴할 것”이라고 썼다. 반은 맞았다 — 포맷은 SKILL.md로 수렴했다. 못 본 반쪽은 그 포맷 위에 제품 계층이 생긴다는 것이었다. 스킬은 이제 설정 파일이 아니라, 자기 검증기와 자기 벤치마크와 자기 스폰서를 가진 배포 단위다.
실전: 쓸 것인가, 베낄 것인가
쓰는 쪽부터. 설치는 위의 한 줄이고, 에이전트에게 “archify로 이 저장소 런타임 아키텍처 그려줘”라고 하면 된다. 결과물은 브라우저에서 열리는 자체 완결 HTML 한 파일 — 다크/라이트 테마, 노드 검색, 업스트림/다운스트림 추적, PNG·SVG·WebM 내보내기가 들어 있다. 아키텍처 리뷰에 특히 쓸 만한 게, 검증된 스냅샷 두 개를 Before/Delta/After로 비교해 추가·삭제·변경·이동된 것만 뽑아주는 델타 기능이 있다. PR에 “아키텍처가 이렇게 바뀝니다”를 첨부하는 용도로는 Mermaid보다 명백히 낫다.
한계도 분명하다. 주 노드 12개 권장이라는 상한이 말해주듯, 마이크로서비스 수십 개짜리 전사 지도가 아니라 한 시스템의 한 이야기를 그리는 도구다. 기여자 두 명에 사실상 1인 프로젝트라는 지속성 리스크도 있다. 다이어그램의 사실 정확성은 여전히 에이전트가 코드를 제대로 읽었는지에 달려 있다 — 검증기가 보장하는 건 구조와 기하학의 정합성이지, 그림이 코드와 일치한다는 보증까지는 아니다. 저장소 증거 연동(노드에 리비전 고정 소스 링크를 붙이는 기능)이 그 간극을 줄이는 장치인데, 옵트인이다.
베끼는 쪽이 사실 더 값지다. 사내에서 에이전트 스킬을 만들고 있다면 — 릴리스 노트 생성이든, 마이그레이션 스크립트든, 보고서 작성이든 — Archify에서 옮겨갈 설계는 다섯 가지다.
- 산출물을 타입 있는 중간표현으로. 에이전트가 최종 포맷을 직접 쓰게 하지 말고, 스키마로 검증 가능한 IR을 거치게 하라. 검증할 수 없는 산출물은 개선도 할 수 없다.
- 검증기를 로컬 CLI로. 게이트는 프롬프트 속 체크리스트가 아니라 종료 코드가 있는 명령이어야 한다. “검증했는가”의 대답을 모델의 양심 대신 exit code에 맡겨라.
- 수정 예산을 명시하라. “통과할 때까지 고쳐”는 토큰 소각로다. 진단이 지목한 것만 고치고, 개선이 멈추면 실패를 보고하게 하라.
- 읽기 금지 목록을 쓰라. 좋은 스킬 지시문은 뭘 읽을지만큼 뭘 읽지 말지를 정한다. 에이전트가 첫 산출물 전에 구현 내부를 뒤지기 시작하면 컨텍스트만 타고 결과는 나빠진다.
- 평범한 모델 기준의 eval을 스킬에 동봉하라. 좋은 모델에서 되는 건 증명이 아니다. 평범한 모델의 첫 통과율이 스킬의 품질이고, 그 숫자가 있어야 모델을 갈아탈 때 스킬이 자산으로 남는다.
남는 것
- 에이전트 산출물의 신뢰는 검증기가 만든다. Archify에 스타 1만 개를 안긴 건 그림 솜씨보다 “0이 아닌 종료 코드는 성공이 아니다”라는 문장이다.
- 하네스는 앱 단위에서 작업 단위로 쪼개지고 있다. 계약(스키마), 루프(생성-검증-수정), 예산(수정 2라운드·읽기 금지 목록), eval(평범한 모델의 첫 통과율)이 스킬 패키지 하나에 다 들어간다.
- SKILL.md의 요체는 지식 주입이 아니라 권한과 예산의 설계다. 뭘 읽고 뭘 읽지 말지, 언제 멈추고 뭘 보고할지를 정하는 문서가 좋은 스킬이다.
- 스킬은 설정 파일에서 제품이 됐다. 버전과 체인지로그와 벤치마크와 스폰서가 붙고, 포크가 원본을 추월하고 출처 표기가 흐려지는 — 오픈소스의 드라마까지 포함해서.
- 도구를 쓰지 않더라도 질문은 가져갈 것. 지금 만드는 스킬의 산출물은 검증 가능한가, 게이트는 종료 코드인가, 수리에는 예산이 있는가, 실패는 정직하게 보고되는가.
넉 달 전 이 저장소는 멈춘 스킬의 포크로 시작했다. 지금은 검증기와 벤치마크와 스폰서를 갖춘 제품이고, 다음 포크가 이 저장소를 추월할 조건도 같은 생태계 안에 이미 갖춰져 있다. 스킬이 제품이 됐다는 말은, 스킬에도 제품의 운명이 적용된다는 뜻이다.
참고: tt-a1i/archify (스타·포크·커밋 수치 2026-08-09 조회, SKILL.md·DESIGN.md·PRODUCT.md·벤치마크 문서는 같은 날 클론 기준), Ordinary-Model Floor 벤치마크, Cocoon-AI/architecture-diagram-generator (원본 스킬), Vercel — Introducing skills, skills.sh의 Archify, Trendshift 이력. 스킬 번들 수요는 #17, 하네스 정의는 #35, 계약 우선은 #24 참고. 이 글은 특정 도구의 도입 권고가 아니라 스킬이라는 배포 단위의 설계 논평이다.