테마 전환
Repomix는 프로젝트 폴더나 GitHub 저장소 전체를 훑어 디렉터리 구조와 파일 내용을 하나의 파일로 합쳐 주는 무료 오픈소스 CLI 도구입니다. npm 패키지 repomix로 배포되며, 생성된 결과물(repomix-output.xml)을 ChatGPT, Claude, Gemini 같은 AI 서비스에 그대로 붙여 넣으면 코드베이스 전체를 컨텍스트로 삼아 대화할 수 있습니다.
이 가이드는 공식 저장소의 문서와 README를 바탕으로, 한국어 사용자가 핵심을 빠르게 파악하고 바로 실무에 적용할 수 있도록 재구성했습니다. 본문은 npm 기준 v1.19.0 계열을 설명합니다.
Repomix는 어떤 도구인가
쉽게 말해 Repomix는 "AI가 읽기 가장 좋은 형태로 저장소를 압축·정렬해 주는 인쇄기"입니다. 원본 파일은 전혀 건드리지 않고, 오직 읽어 들인 내용을 바탕으로 새로운 요약 파일을 만들어 낼 뿐입니다.
- 언어 제약 없는 범용성: 파일 내용을 직접 읽어 포맷하므로 C#, Python, Java, Go, Rust 등 어떤 언어로 된 저장소든 묶을 수 있습니다. (단, Tree-sitter 기반의 코드 압축 같은 고급 기능은 언어별 파서 지원 여부에 따라 결과가 달라질 수 있습니다.)
- 구독형 AI 서비스 최적화: CLI는 설치 후 완전히 오프라인으로 동작하며, 저장소 정보나 텔레메트리를 외부로 전송하지 않습니다. 별도의 API 키 설정 없이, 이미 사용 중인 AI 서비스의 채팅창에 결과물을 붙여 넣는 것이 기본 사용법입니다.
- 일관된 결과물: 같은 저장소와 설정을 사용하면 항상 동일한 구조의 파일이 생성됩니다. 팀 전체가 동일한 컨텍스트를 공유하고 싶다면 설정 파일을 저장소에 함께 커밋해 두는 것이 좋습니다.
왜 파일 하나로 묶어서 넘기는가
AI 코딩 도구가 파일 하나씩 열어보는 방식은 두 가지 큰 비용을 발생시킵니다.
첫째는 탐색 비용입니다. 관련 코드를 찾기 위해 AI가 디렉터리를 나열하고, 파일을 하나씩 열어보는 과정이 반복되면 대화가 길어지고 컨텍스트 창이 불필요하게 채워집니다. Repomix는 이 탐색 단계를 완전히 제거하여 분석 속도를 높이고 정확도를 향상시킵니다.
둘째는 판단 근거의 범위입니다. 아주 작은 이름 변경 작업이라도 실제 영향은 API 계약, 테스트 코드, 문서 전체에 걸쳐 있을 수 있습니다. 전체 구조가 한눈에 들어와야 AI가 기존 패턴과 일치하는 최적의 방법을 제안할 수 있습니다.
이런 장점 덕분에 Repomix를 활용하면 구현 계획 수립, 버그 원인 추적, 보안 점검, 문서 생성, 신규 멤버 온보딩 같은 작업을 훨씬 효율적으로 처리할 수 있습니다.
핵심 기능 다섯 가지
Repomix가 제공하는 핵심 기능은 다음과 같습니다.
| 기능 | 설명 |
|---|---|
| AI 최적화 출력 | AI가 구조를 빠르게 파악할 수 있도록 최적화된 XML 태그 구조로 정리합니다. |
| 토큰 계산 | 파일별·전체 토큰 수를 계산하여 AI의 컨텍스트 한도를 미리 가늠하게 합니다. |
| Git 인식 | .gitignore와 .git/info/exclude 규칙을 존중하여 불필요한 파일을 자동으로 제외합니다. |
| 보안 검사 | Secretlint를 통해 API 키, 토큰, 비밀번호 같은 민감 정보가 포함되었는지 탐지합니다. |
| 다양한 출력 형식 | 사용 환경에 따라 평문, XML, Markdown, JSON 중에서 포맷을 선택할 수 있습니다. |
여기에 더해 Git diff와 커밋 로그를 포함하거나, 파일 변경을 감지하는 워치 모드, 코딩 에이전트가 직접 요청할 수 있는 MCP 서버 연동 기능 등이 포함되어 있습니다.
네 갈래로 나뉜 사용 방법
상황에 맞는 최적의 경로를 선택해 보세요.
| 경로 | 추천 대상 | 특징 |
|---|---|---|
CLI (npx repomix) | 터미널 사용 개발자 | 모든 기능을 지원하는 가장 강력한 방법. 로컬·원격 저장소, MCP 서버, 설정 파일 모두 활용 가능 |
| 웹사이트 (repomix.com) | 빠른 체험 희망자 | 공개 저장소 주소나 ZIP 파일을 업로드해 즉시 생성. 설치 과정 없음 |
| 브라우저 확장 | GitHub 헤비 유저 | GitHub 저장소 페이지에서 버튼 클릭 한 번으로 즉시 묶기 가능 |
| VSCode 확장 | 에디터 내 작업 선호자 | 클릭 몇 번으로 폴더 묶기 및 결과 정리. 기존 repomix.config.json 설정 그대로 사용 |
팁: 보안이 중요한 비공개·사내 저장소라면 반드시 CLI를 사용하세요. 웹 서비스가 업로드 파일을 즉시 삭제한다고 안내하지만, 데이터 외부 유출을 원천 차단하는 것이 가장 안전합니다.
첫 명령 한 줄과 그 결과
프로젝트 폴더에서 다음 명령어를 실행하는 것으로 시작합니다.
bash
npx repomix@latest잠시 후 repomix-output.xml 파일이 생성됩니다. 이 파일을 AI 대화창에 붙여 넣을 때, 다음과 같이 요청해 보세요.
text
이 파일은 내 저장소의 모든 파일을 하나로 합친 것입니다.
전체적인 구조를 먼저 파악하고, [원하는 작업: 예: 리팩터링 방향]에 대해 제안해 주세요.그러면 AI가 개별 파일을 탐색하는 번거로움 없이 코드베이스 전체를 읽고 종합적인 의견을 냅니다.
다른 도구와 언제 갈리나
Repomix는 상황에 따라 다음과 같은 선택지를 제안합니다.
- 범용적인 파일 한 장이 필요할 때 $\rightarrow$ CLI. ChatGPT, Claude, Gemini 등 거의 모든 AI 서비스와 로컬 LLM에서 사용할 수 있습니다.
- 에이전트가 직접 컨텍스트를 제어하게 할 때 $\rightarrow$ MCP 서버 또는 플러그인. Claude Code 사용자라면
/plugin marketplace add yamadashy/repomix를 통해 공식 플러그인을 설치하는 것이 가장 효율적입니다. - Python 생태계 중심의 워크플로라면 $\rightarrow$ Gitingest 검토. 저장소를 다이제스트 형태로 변환한다는 목표가 유사한 훌륭한 대안입니다.
이 가이드의 학습 순서
총 13편의 글이 설정 없이 바로 실행하는 단계부터 팀 파이프라인 구축 및 에이전트 연동까지 단계별로 구성되어 있습니다.
| 그룹 | 편 | 주요 내용 |
|---|---|---|
| 소개 · 개념 | 1~2 | Repomix 소개 및 동작 원리, 출력 파일 구조 |
| 사용법 | 3~8 | 설치, 명령줄 옵션, 설정 파일, 출력 포맷, 원격 저장소, 워치 모드 |
| 메뉴얼 | 9~12 | 토큰 절감, 보안과 프라이버시, MCP 서버, 에이전트·CI 연동 |
| 예제 | 13 | 실전 프롬프트 템플릿 및 활용 사례, 라이브러리 API |
다음 편에서는 Repomix가 저장소를 어떤 순서로 훑어 출력 파일을 구성하는지, 그 동작 원리를 자세히 살펴봅니다.