전체 내역

[Claude Code 스킬] archify, 분석 문서를 근거 달린 한 페이지 기획서로 바꾸기

설명이나 코드를 대화형 다이어그램 HTML로 만들어 주는 스킬 archify를 회사 화면 개발 기획서에 써 봤습니다. 어떤 스킬인지, 설치와 사용법, 기획서를 만들며 자동 검사에 네 번 막힌 과정까지 정리했습니다.

회사에서 영업 관리 시스템을 새로 만들기 전에 기존 화면을 분석하는 글을 몇 편 써 두었습니다. 지금 화면이 어떻게 생겼는지, 새로 만들 기능이 무엇인지, 운영 중인 기능과 새 구현이 어디까지 맞는지를 각각 정리한 마크다운 문서입니다. 그런데 이걸 화면 개발 기획서로 넘기려니 막막했습니다. 메뉴 구조는 나무 그림으로, 업무 흐름은 순서도로, 데이터는 ERD로 다시 그려야 했기 때문입니다. 이 글에서는 이 작업에 쓴 Claude Code 스킬 archify를 다룹니다.

이 글의 적용 예시는 오늘 회사 프로젝트에서 직접 써 본 내용입니다. 다만 회사 내부 자료라서 결과물 화면은 싣지 않았습니다. 글의 이미지는 모두 archify 스킬에 들어 있는 공식 예제를 제 컴퓨터에서 열어 캡처한 것입니다.

1. 어떤 스킬인가

archify는 요구사항이나 코드를 다이어그램 HTML 파일 하나로 만들어 주는 스킬입니다. 그릴 수 있는 그림은 열 가지입니다. 아키텍처, 업무 흐름(workflow), 시퀀스, 데이터 흐름, 상태 전이(lifecycle), ERD, 클래스, 나무(tree), 타임라인, 폭포(waterfall) 차트입니다. Mermaid 코드를 넘겨도 되고, 저장소를 읽혀서 코드에 근거한 그림을 만들게 할 수도 있습니다.

결과물은 정적인 그림이 아닙니다. 브라우저로 열면 노드를 눌러 경로를 따라가거나 확대할 수 있고, 다크와 라이트 테마를 바꿀 수 있습니다. 이미지, SVG, WebM 영상으로 내보내기도 됩니다.

다이어그램 말고 설명 페이지(explainer) 모드도 있습니다. 질문에 대한 답을 결론부터 쓰고, 그 아래에 근거 패널과 다이어그램, 표를 한 페이지로 묶습니다. 제가 기획서에 쓴 것이 이 모드입니다.

이 스킬에서 가장 눈에 띈 건 검사 단계입니다. 에이전트가 쓴 초안(candidate)을 바로 HTML로 바꾸지 않고, finalize 명령이 형식 검증, 그림 배치, 결과 파일 점검을 차례로 통과해야 결과물을 내줍니다. 선이 애매하게 겹치거나 데스크톱 화면에서 읽기 어려우면 여기서 막힙니다.

2. 출처

항목 내용
AI 도구 Claude Code (저장소 설명 기준 Codex 등 다른 에이전트도 지원)
종류 스킬
만든 사람 tt-a1i (Cocoon-AI/architecture-diagram-generator에서 출발했다고 NOTICE에 적혀 있습니다)
공식 사이트 https://archify.si
저장소 https://github.com/tt-a1i/archify
설치 경로 ~/.claude/skills/archify (전역 설치)
확인한 버전 3.2.0 (설치된 SKILL.md, package.json, skill-release.json 기준, 2026년 11월 5일 확인)
필요 환경 Node.js 18 이상 (package.json의 engines 기준)
라이선스 Apache-2.0 (예전 MIT 시절 기여분은 원래 조건을 유지한다고 NOTICE에 밝혀 두었습니다)

이 글의 이미지는 설치된 스킬의 examples 폴더에 있는 예제 HTML 세 개를 브라우저로 열어 캡처한 것입니다. Apache-2.0 라이선스라 출처를 밝히고 사용했고, 내용은 고치지 않았습니다.

3. 언제 쓰면 좋은가

  • 이미 써 둔 분석 문서나 명세를 근거로 기획서, 설계 문서를 그림과 함께 다시 정리해야 할 때
  • 메뉴 구조, 업무 흐름, 데이터 모델처럼 종류가 다른 그림을 한 문서에 모아야 할 때
  • 코드를 읽혀서 실제 구조에 맞는 아키텍처 그림을 만들고 싶을 때
  • 문서의 주장마다 어느 자료에서 나왔는지 출처를 붙여 두고 싶을 때

손으로 그림을 세밀하게 다듬어야 하는 발표 자료라면 맞지 않을 수 있습니다. archify는 배치를 자동으로 잡고 검사로 통과 여부를 정하기 때문에, 원하는 모양을 정확히 지정하기보다는 검사를 통과하는 모양을 찾아가는 쪽에 가깝습니다.

4. 사용법

설치는 skills 도구로 합니다. 처음에는 프로젝트에만 설치하려다가, 다른 프로젝트에서도 쓰고 싶어서 전역으로 설치했습니다. 설치 명령은 저장소의 안내를 따랐습니다.

# 설치할 스킬 목록만 확인합니다.
npx -y skills@latest add https://archify.si --list --full-depth
 
# Claude Code에 전역으로 설치합니다.
npx -y skills@latest add https://archify.si --skill archify --agent claude-code --global --copy --yes

외부 패키지를 내려받아 실행하는 명령이라 Claude Code가 자동 권한 검사에서 멈췄습니다. 그래서 프롬프트에 !를 붙여 제가 직접 실행했습니다. 설치 도구도 마지막에 스킬은 에이전트 권한 그대로 실행되니 검토하고 쓰라는 안내를 띄웁니다. 설치 뒤에 doctor 명령을 돌려 열 가지 다이어그램과 explainer가 모두 준비됐다는 결과를 확인했습니다.

node ~/.claude/skills/archify/bin/archify.mjs doctor

쓸 때는 따로 명령을 외울 필요가 없습니다. 대화창에 "Archify로 그려 줘"나 "한 페이지로 답해 줘"라고 쓰면 스킬이 붙습니다. 문서를 근거로 그릴 때는 이렇게 요청하는 편이 좋았습니다.

docs/feature-spec.md 를 근거로 메뉴 구조를 Archify Tree 다이어그램으로 그려 줘. 문서에 없는 내용은 넣지 마.

결과물은 작업 폴더 아래 .archify/<종류>-<이름>-<날짜시간>/ 폴더에 쌓입니다. 에이전트가 쓴 초안 파일, 완성된 HTML, 검사 결과를 담은 영수증(receipt) JSON이 같이 남아서, 나중에 다시 고칠 때 이 폴더를 그대로 씁니다.

5. 적용 예시

5-1. 공식 예제로 본 그림 종류

에이전트가 도구를 호출하는 업무 흐름도. 사용자 화면, 에이전트 실행, 정책과 복구, 도구 실행 네 구역으로 나뉘고 승인 관문에서 거절되면 재시도 경로로 빠진다

출처: archify 스킬 examples 폴더의 workflow-agent-tool-call-rendered.html

업무 흐름 예제입니다. 구역을 가로줄로 나누고, 승인이 거절되면 재시도로 빠지는 예외 경로는 점선 구역으로 따로 보여 줍니다. 오른쪽 위에서 테마와 움직임을 바꾸고, 아래쪽 ROUTE와 LENS로 경로를 강조해 볼 수 있습니다.

주문 관리 ERD. 고객, 주문, 결제, 재고, 상품, 주문 항목 표가 업무 영역별 색 띠로 묶여 있고 각 열의 PK, FK, UK 표시와 SQL 타입이 보인다

출처: archify 스킬 examples 폴더의 erd-orders-rendered.html

ERD 예제입니다. 표를 업무 영역(ACCOUNTS, CHECKOUT, CATALOG, LINE ITEMS)별로 묶고, 열마다 키 역할과 SQL 타입을 그대로 보여 줍니다. 그림 아래에는 키와 관계를 읽는 법을 적은 설명 카드가 붙습니다.

결제 플랫폼 기능을 나무 모양으로 쪼갠 그림. 맨 위 결제 플랫폼 아래에 주문, 결제, 운영 세 가지가 있고 각각 두 개의 하위 기능을 가진다

출처: archify 스킬 examples 폴더의 tree-payment-platform-rendered.html

나무 예제입니다. 기획서의 메뉴 구조를 그릴 때 이 형태를 썼습니다. 아래쪽에 노드 목록이 단계별로 따로 정리되어서, 그림이 커져도 글로 찾아볼 수 있습니다.

5-2. 분석 문서로 화면 개발 기획서 만들기

여기부터는 제가 직접 쓴 내용입니다. 미리 써 둔 분석 문서 다섯 개(현재 화면 분석, 새 기능 명세, 운영 기능 대조, 화면 개선 제안, 검증 기록)를 근거로 넘기고, 화면 개발을 위한 기획서를 explainer 페이지로 만들어 달라고 했습니다.

에이전트가 쓴 초안은 마크다운에 가까운 형식입니다. 맨 위에 결론과 그 근거가 오고, 문장마다 [](source:spec) 같은 표시로 어느 문서에서 나온 주장인지 연결합니다. 그 아래로 열두 개 절이 이어지는데, 메뉴 구조는 @tree, 영업 단계와 견적 처리는 @workflow, 요청과 승인 사이 주고받는 순서는 @sequence, 데이터 모델은 ERD로 그렸습니다. 확인이 더 필요한 부분은 @callout으로 따로 표시했습니다.

첫 결과물은 한 번에 나오지 않았습니다. finalize가 네 번 실패하고 다섯 번째에 통과했습니다. 검사가 잡은 것은 이런 것들이었습니다.

  • 초안의 다이어그램을 읽거나 그리지 못한 경우(explainer/parse-diagram, explainer/diagram-render)
  • 선이 지나가는 통로가 애매한 경우(composition/ambiguous-corridor)와 선끼리 교차하는 경우(composition/proper-crossing)
  • 데스크톱 화면에서 글자가 너무 작아지는 경우(composition/desktop-readability)

걱정했던 것보다 고치는 일은 어렵지 않았습니다. 검사 결과에 어떤 그림의 어떤 문제인지 코드로 나와서, 에이전트가 그 부분만 고치고 다시 돌리면 됐습니다. 사람이 그림을 보고 "선이 좀 이상한데"라고 말하는 단계를 검사가 먼저 걸러 준 셈입니다.

통과한 뒤에는 운영 중인 사이트와 기획서를 한 번 더 맞춰 봤습니다. Playwright로 내부 계정과 파트너 계정의 메뉴를 모두 열어 보고, 빠진 기능을 분석 문서와 기획서에 다시 넣었습니다. 이때도 같은 폴더의 초안만 고치고 finalize를 다시 돌리면 돼서, 문서를 처음부터 다시 만들 필요가 없었습니다. 마지막 검사 결과는 형식 검증, 결과 파일 생성, 결과물 점검이 모두 통과였고, 걸린 시간은 2초가 안 됐습니다. 같은 방식으로 데모 요청과 승인 흐름만 따로 다룬 여섯 절짜리 기획 페이지도 하나 더 만들었습니다.

6. 써 본 소감

가장 좋았던 점은 기획서의 문장마다 출처가 붙는다는 것입니다. 기획서를 만들다 보면 분석 문서에 없던 내용이 슬쩍 들어가기 쉬운데, 근거 표시가 있으니 어느 주장이 어디서 왔는지 바로 되짚을 수 있었습니다.

아쉬운 점도 있었습니다. 결과 HTML은 자바스크립트와 스타일을 모두 품은 파일 하나라서 기획서는 2MB, 데모 기획 페이지는 1MB 가까이 됐습니다. 그리고 자동 검사는 형식과 배치를 보는 것이지 내용이 맞는지까지 보지는 않습니다. 실제로 첫 판에서 빠진 기능은 검사가 아니라 운영 사이트를 다시 열어 보면서 찾았습니다. 브라우저에서 화면을 직접 보는 browser-check도 이번에는 돌리지 않았는데, 다음 기획서부터는 이 단계까지 넣어 볼 생각입니다.

Comments (0)