Claude Code·Codex에 Archify Skill을 쓰는 이유: 코드 구조를 눈으로 확인하는 방법
Claude Code나 Codex가 코드를 잘 읽고 수정해 주는 것은 분명 편리합니다. 하지만 프로젝트가 커질수록 “AI가 지금 내 코드베이스를 제대로 이해하고 있는가?”를 사람이 확인하기가 어려워집니다. Archify는 이 문제를 시각적으로 확인하는 데 도움을 주는 Agent Skill입니다.
- Archify는 Claude Code·Codex가 분석한 코드베이스를 Architecture, Sequence, Workflow, Data Flow 다이어그램으로 보여주는 Agent Skill입니다.
- 단순히 예쁜 그림을 만드는 것이 아니라, AI가 프로젝트 구조를 어떻게 이해했는지 사람이 확인하는 데 유용합니다.
- 실제 저장소 분석, 신규 프로젝트 온보딩, API 흐름 확인, PR Architecture Diff, 기술 블로그용 다이어그램 제작 등에 활용할 수 있습니다.
- 특히 Claude Code나 Codex처럼 저장소 전체를 다루는 Coding Agent에서는 Code Diff + Test + Architecture Diff 방식으로 검증하는 데 도움이 됩니다.
Archify는 단순한 다이어그램 생성기가 아니다
Archify를 처음 보면 Mermaid의 예쁜 버전 정도로 생각하기 쉽습니다. 하지만 핵심은 단순히 그림을 만드는 데 있지 않습니다.
일반적인 AI 다이어그램 생성은 보통 코드 읽기 → 구조 추측 → 그림 생성 순서로 진행됩니다. 문제는 AI가 실제 코드에는 없는 Redis, Queue, Load Balancer 같은 요소를 그럴듯하게 추가할 수 있다는 점입니다.
Archify는 구조화된 데이터를 기반으로 Architecture, Workflow, Sequence, Data Flow, Lifecycle 다이어그램을 만들고, self-contained HTML이나 SVG 같은 결과물로 출력할 수 있도록 설계되어 있습니다. 따라서 발표용 그림보다 실제 코드베이스 분석과 검증에 더 잘 어울립니다.
1. Claude Code·Codex가 이해한 코드 구조를 사람이 확인할 수 있다
Claude Code나 Codex에게 “이 프로젝트 구조를 분석해줘”라고 요청하면 보통 긴 텍스트 설명이 나옵니다. 작은 프로젝트라면 충분하지만, 서비스 수가 늘어나면 텍스트만으로는 전체 관계를 머릿속에 유지하기 어렵습니다.
Archify를 사용하면 이런 흐름을 실제 다이어그램으로 변환할 수 있습니다. Agent가 코드베이스를 어떻게 이해했는지를 사람이 시각적으로 확인할 수 있다는 점이 큰 장점입니다.
Analyze this repository, then use Archify to create a high-level runtime architecture diagram. Show 8–12 core components, the primary request path, external dependencies, and trust boundaries.
 |
| 칸반 보드 아키텍처 생성 요청 |
 |
| Archify Skill로 생성된 칸반보드 아키텍처 |
2. Architecture뿐 아니라 Sequence와 Data Flow까지 볼 수 있다
Archify는 하나의 그림만 만드는 도구가 아닙니다. 프로젝트 상황에 따라 여러 종류의 다이어그램을 사용할 수 있습니다.
| 유형 | 유용한 상황 |
|---|---|
| Architecture | 서비스, DB, Queue, 외부 시스템 구조 |
| Workflow | CI/CD, 승인 절차, Agent workflow |
| Sequence | API 요청, 인증, cache fallback 흐름 |
| Data Flow | ETL, 데이터 이동, PII, lineage |
| Lifecycle | Retry, Wait, Failure, 종료 상태 |
예를 들어 로그인 오류를 분석할 때 전체 시스템 아키텍처보다 Sequence Diagram이 훨씬 유용할 수 있습니다.
3. Claude Code와 Codex에서 같은 Skill을 활용할 수 있다
Archify의 또 다른 장점은 특정 AI 모델 하나에 강하게 묶이지 않는다는 것입니다. Claude Code에서 쓰던 워크플로를 Codex에서도 비슷한 방식으로 활용할 수 있습니다.
Claude Code용 설치 예시
npx skills add tt-a1i/archify -gCodex용 설치 예시
npx -y skills add tt-a1i/archify \
--skill archify \
--agent codex \
--global \
--copy \
--yes설치 자체보다 더 인상적이었던 부분은 사용 후였습니다. 이전에는 Claude Code나 Codex가 “전체 구조를 분석했다”고 말해도 긴 설명을 믿고 넘어가는 경우가 많았는데, Archify를 붙이고 나서는 그 이해 결과를 실제 그림으로 확인할 수 있었습니다. 코드베이스가 복잡할수록 이 차이가 컸고, 특히 다른 사람이 만든 프로젝트를 처음 파악할 때 전체 구조를 빠르게 이해하는 데 도움이 됐습니다.
4. PR 리뷰에 Architecture Diff를 활용할 수 있다
큰 Pull Request에서는 코드 diff만 봐서는 시스템 구조가 어떻게 바뀌었는지 놓치기 쉽습니다.
변경 전
변경 후
코드상으로는 Redis 몇 줄이 추가된 것처럼 보이지만 시스템 관점에서는 cache hit, cache miss, fallback, 장애 처리라는 새로운 경로가 생긴 것입니다. Architecture Diff를 사용하면 이런 변화를 훨씬 쉽게 파악할 수 있습니다.
5. AI가 지어낸 구조를 발견하기 쉬워진다
AI 코딩 Agent의 가장 큰 위험 중 하나는 그럴듯한 오해입니다. 실제 코드에는 존재하지 않는 Queue나 Cache가 있다고 가정한 채 설명을 이어갈 수도 있습니다.
Archify가 이런 오류를 완전히 없애는 것은 아닙니다. Agent가 저장소를 잘못 읽으면 다이어그램 역시 잘못될 수 있습니다. 하지만 결과를 구조화된 형태로 확인할 수 있으므로 AI가 어디를 잘못 이해했는지 사람이 찾기가 훨씬 쉬워집니다.
6. 다이어그램에서 다시 코드 구조로 돌아갈 수 있다
정적인 PNG 하나만 만들어 놓는 방식은 시간이 지나면 쉽게 낡습니다. 반면 Archify는 시스템 요소와 관계를 구조화해 다루기 때문에 특정 서비스의 upstream·downstream이나 주요 경로를 탐색하는 용도로도 활용할 수 있습니다.
예를 들어 PaymentService를 중심으로 다음 구조를 살펴볼 수 있습니다.
7. 블로그와 기술문서 작성에도 유용하다
개발 블로그를 쓸 때 시간이 오래 걸리는 작업 중 하나가 시스템 다이어그램입니다. Claude Code나 Codex로 코드를 분석한 뒤 Archify로 다이어그램을 만들면 코드 분석 → 구조 추출 → 다이어그램 → 블로그 삽입 흐름을 훨씬 단순하게 만들 수 있습니다.
Analyze this Next.js project and create an Archify sequence diagram showing Browser → App Router → Server Action → API → Database.
 |
| Sequence Diagram 생성 요청 |
 |
| Archify Skill로 생성된 Sequence Diagram |
8. Mermaid와 Archify는 언제 다르게 써야 할까
간단한 구조라면 Mermaid가 훨씬 빠릅니다.
graph LR
A --> B
B --> C반면 다음 상황에서는 Archify가 더 잘 맞습니다.
- 실제 repository를 읽고 시스템 구조를 만들 때
- PR 전후의 구조 변화를 비교할 때
- Architecture와 Sequence Diagram을 함께 관리할 때
- 긴 upstream/downstream 관계를 추적할 때
- 다이어그램을 반복적으로 업데이트할 때
한마디로 Mermaid가 다이어그램 문법에 가깝다면, Archify는 코딩 Agent를 위한 architecture workflow에 더 가깝습니다.
9. Agent Skills가 중요한 더 큰 이유
Archify가 흥미로운 것은 단순히 하나의 도구가 인기 있기 때문만은 아닙니다. 최근 AI 코딩 흐름은 긴 프롬프트를 잘 쓰는 단계에서 필요한 전문 능력을 Skill 형태로 Agent에 장착하는 단계로 이동하고 있습니다.
↓
Claude / GPT / Gemini
↓
Agent Harness
↓
Claude Code / Codex / Cursor
↓
Skills
↓
Architecture / Testing / Security / Deployment / Research
모델이 바뀌어도 잘 만들어진 Skill과 Workflow를 유지할 수 있다는 점이 중요합니다.
10. 직접 사용한다면 추천하는 5가지 활용법
- 새 저장소 온보딩: 처음 보는 프로젝트의 전체 runtime 구조 생성
- PR Architecture Review: 변경 전후 시스템 구조 비교
- API Debugging: 인증, 캐시, DB fallback Sequence 확인
- AI Agent Workflow 설계: Agent → Tool → MCP → API 관계 시각화
- 블로그·README 제작: 코드에서 바로 기술 다이어그램 생성
결론
Claude Code나 Codex에 Archify Skill을 쓰는 가장 큰 이유는 단순히 예쁜 다이어그램을 만들어 주기 때문이 아닙니다.
Agent가 내 코드베이스를 어떻게 이해했는지를 사람이 눈으로 확인할 수 있기 때문입니다.
실제로 설치해 사용해 보니 이 차이가 가장 크게 느껴졌습니다. 긴 설명을 읽으며 구조를 상상하는 것과 서비스·API·DB·캐시 사이의 관계를 실제 그림으로 보는 것은 이해 속도에서 차이가 컸습니다.
특히 Claude Code나 Codex가 저장소 전체를 읽고 여러 파일을 동시에 수정하기 시작하면 앞으로는 단순 Code Diff만으로 충분하지 않을 수 있습니다.
이런 방식으로 Agent가 무엇을 바꿨는지 확인하는 습관이 AI 코딩 시대에는 점점 더 중요해질 가능성이 큽니다.
FAQ
Q1. Archify는 Claude Code에서만 사용할 수 있나요?
아닙니다. Claude Code뿐 아니라 Codex 같은 Agent 환경에서도 사용할 수 있습니다. 중요한 것은 특정 모델보다 Agent Skill 형태로 워크플로를 재사용할 수 있다는 점입니다.
Q2. Mermaid를 쓰고 있는데 Archify로 바꿔야 하나요?
꼭 그럴 필요는 없습니다. 간단한 흐름이나 정적 문서에는 Mermaid가 더 빠르고 편합니다. Archify는 실제 코드베이스를 분석하거나 PR 전후 구조를 비교하고, Agent가 이해한 시스템 관계를 확인하고 싶을 때 더 유용합니다.
Q3. Archify가 AI Hallucination을 완전히 막아주나요?
아닙니다. Agent가 코드를 잘못 해석하면 다이어그램도 틀릴 수 있습니다. 다만 텍스트 설명만 있을 때보다 구조를 시각적으로 확인할 수 있어 잘못된 연결이나 빠진 컴포넌트를 사람이 발견하기 쉬워진다는 장점이 있습니다.
Q4. 어떤 프로젝트에서 가장 효과가 큰가요?
서비스, API, DB, Redis, Queue, Worker, 외부 SaaS가 여러 단계로 연결된 프로젝트에서 효과가 큽니다. 작은 단일 파일 프로젝트보다는 중대형 웹 서비스, 마이크로서비스, AI Agent 프로젝트에서 더 유용합니다.
Q5. 기존 프로젝트를 처음 분석할 때도 쓸 수 있나요?
오히려 그런 상황에서 특히 유용합니다. 직접 사용했을 때도 다른 사람이 만든 코드베이스를 처음 파악하면서 전체 구조를 다이어그램으로 확인할 수 있다는 점이 가장 편리했습니다.
Q6. Codex와 Claude Code에서 동일한 결과가 나오나요?
완전히 동일하다고 보기는 어렵습니다. 두 Agent가 코드를 탐색하고 해석하는 방식이 다를 수 있기 때문에 같은 Archify Skill을 사용하더라도 추출되는 구조에 차이가 생길 수 있습니다. 중요한 프로젝트라면 두 결과를 비교해 보는 것도 좋은 방법입니다.
Q7. 블로그용 이미지로도 사용할 수 있나요?
가능합니다. Architecture나 Sequence Diagram을 생성한 뒤 PNG, SVG 또는 HTML 형태로 활용하면 기술 블로그, GitHub README, 프로젝트 문서, 발표자료에 재사용하기 좋습니다.
Q8. Archify를 가장 먼저 어디에 써보는 것이 좋나요?
현재 작업 중인 프로젝트에서 “전체를 다 그려줘”라고 하기보다 로그인 흐름, API 요청 경로, 데이터 저장 흐름처럼 범위를 좁혀 시작하는 것을 추천합니다. 작은 범위에서 결과를 확인한 뒤 전체 Architecture로 확장하는 편이 더 안정적입니다.
참고자료 및 공식 링크
Archify의 기능, 설치 방법, Agent Skills 구조를 확인할 때 참고할 수 있는 공식 자료입니다. 설치 명령이나 지원 환경은 프로젝트 업데이트에 따라 달라질 수 있으므로 실제 설치 전에는 공식 문서를 한 번 확인하는 것을 추천합니다.
Archify의 최신 버전, 설치 방법, 지원 Agent, 예제, 변경사항을 확인할 수 있습니다. Claude Code, Codex CLI, Cursor, OpenCode 등의 지원 방식과 Architecture·Workflow·Sequence·Data Flow·Lifecycle 기능이 정리되어 있습니다.
https://github.com/tt-a1i/archify실제 Archify 다이어그램과 인터랙티브 기능을 확인하기 좋습니다. 저장소를 분석한 뒤 self-contained HTML을 만드는 기본 흐름과 Codex에서 설치 없이 시험해 보는 방법도 안내되어 있습니다.
https://tt-a1i.github.io/archify/Claude Code와 Codex CLI의 Skill 설치 위치, Archify의 typed JSON IR, Architecture Delta, HTML·PNG·SVG·WebM 출력 등에 대한 자세한 설명을 확인할 수 있습니다.
https://github.com/tt-a1i/archify/blob/main/README_EN.mdClaude Code에서 Agent Skills가 어떻게 동작하는지 확인할 수 있는 공식 문서입니다. Custom Skill은 SKILL.md 파일을 중심으로 구성되며, 개인용 Skill은 ~/.claude/skills/, 프로젝트용 Skill은 .claude/skills/에 둘 수 있습니다.
https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overviewAgent Skill의 구조와 실제 예제를 살펴보기 좋은 Anthropic 공식 저장소입니다. 개발·기술·문서 작업 등 다양한 Skill 예제와 Agent Skills specification을 제공합니다.
https://github.com/anthropics/skillsCodex에서 Skills를 반복 가능한 작업 능력으로 패키징하는 개념과 설치 방식의 기본 구조를 확인할 수 있습니다. OpenAI의 기존 skills 저장소는 현재 deprecated 상태이므로, 최신 Codex Skill·Plugin 사용 시에는 연결된 최신 문서를 함께 확인하는 것이 좋습니다.
https://github.com/openai/skills관련 글
#Archify #ClaudeCode #Codex #AgentSkills #AI코딩 #아키텍처 #시스템설계 #개발자 #OpenAI #Anthropic
댓글
댓글 쓰기