같은 내용이라도 어떤 그릇에 담느냐에 따라 AI의 해석 능력과 정확도가 달라집니다. Repomix는 네 가지 출력 포맷을 제공하며, 기본값은 XML입니다. 단순히 "취향"의 문제가 아니라 AI 모델의 학습 특성에 기반한 선택입니다.

네 가지 포맷과 선택 기준

상황에 맞는 포맷을 선택해 보세요.

포맷	설정 플래그	추천 상황	핵심 가치
XML (기본)	--style xml	Claude, Gemini 등 최신 LLM 사용 시	파싱 정확도, 구조적 명확성
Markdown	--style markdown	사람이 직접 검토하거나 편집할 때	가독성, 문서 친화적
JSON	--style json	다른 프로그램과 연동하거나 자동화할 때	기계 판독성, 데이터 처리
평문 (Plain)	--style plain	포맷팅을 지원하지 않는 단순한 도구 사용 시	범용성, 최소한의 오버헤드

왜 기본값이 XML인가

Repomix가 XML을 기본으로 채택한 이유는 AI 모델 제조사들의 공식 권장 사항을 따랐기 때문입니다.

제조사	권장 사항 및 근거
Anthropic (Claude)	프롬프트 구조화에 XML 태그 사용을 강력히 권장합니다. Claude는 학습 과정에서 이러한 구조화된 데이터에 많이 노출되어, 태그 기반의 지시사항을 매우 정확하게 이해합니다.
Google (Gemini)	복잡한 문맥을 다룰 때 XML과 같은 구조화된 포맷을 사용하면 정보 누락이 줄고 정확도가 올라간다고 밝히고 있습니다.
OpenAI (GPT)	최신 프롬프팅 가이드에서 복잡한 시나리오일수록 구조화된 데이터 형식을 사용할 것을 권장합니다.

결국 XML이 특별히 더 좋아서라기보다, "주요 LLM들이 태그 구조를 더 잘 이해하도록 훈련되었다"는 실증적 근거에 기반한 선택입니다.

XML 출력: 구조화된 분석의 표준

XML 포맷은 AI가 파일 간의 경계와 메타데이터를 가장 명확하게 구분할 수 있게 합니다.

<!-- 파일 상단: AI를 위한 기본 가이드라인 -->

<file_summary>
(전체 파일 개수, 토큰 수, 주요 대형 파일 목록 등)
</file_summary>

<directory_structure>
src/
  index.ts
  utils/
    helper.ts
</directory_structure>

<files>
<file path="src/index.ts">
// 실제 파일 내용이 들어갑니다.
</file>
</files>

<git_logs>
2025-08-20 00:47:19 +0900|feat(cli): Add --include-logs option...
README.md
</git_logs>

특히 <file path="..."> 속성 덕분에 AI가 "어느 파일의 몇 번째 줄을 수정하라"고 정확하게 지칭할 수 있습니다. 만약 출력 내용 중에 XML 태그와 겹치는 특수문자가 많아 포맷이 깨진다면, --parsable-style 옵션을 켜서 이스케이프 처리를 하세요.

Markdown 출력: 가독성과 편집성

Markdown 포맷은 사람이 읽기에 가장 편하며, 필요한 부분만 빠르게 수정해서 AI에게 전달하고 싶을 때 유용합니다.

# File Summary
(메타데이터 및 가이드)

# Directory Structure
```
src/
  index.ts
```

# Files

## File: src/index.ts
```typescript
// 파일 내용
```

주의사항: 파일 내용 중에 코드 펜스(```)가 포함된 경우, 마크다운 구조가 깨질 위험이 있습니다. 이런 경우에는 XML 포맷을 사용하거나 --parsable-style을 적용하는 것이 안전합니다.

JSON 출력: 자동화와 데이터 처리

JSON 포맷은 사람이 읽기보다는 프로그램이 소비하기 위해 설계되었습니다. jq 같은 명령줄 도구를 사용하면 필요한 정보만 빠르게 추출할 수 있어 자동화 파이프라인 구축에 최적입니다.

💡 Power User를 위한 jq 활용 팁:

# 1. 모든 파일 경로 목록만 뽑기
cat repomix-output.json | jq -r '.files | keys[]'

# 2. 특정 파일(예: README.md)의 내용만 추출
cat repomix-output.json | jq -r '.files["README.md"]'

# 3. 특정 확장자(.ts) 파일만 필터링
cat repomix-output.json | jq -r '.files | keys[] | select(endswith(".ts"))'

# 4. 파일 내용 중 "function"이라는 단어가 포함된 파일 찾기
cat repomix-output.json | jq -r '.files | to_entries[] | select(.value | contains("function")) | .key'

# 5. 파일 크기순으로 상위 10개 파일 목록 뽑기
cat repomix-output.json | jq -r '.files | to_entries[] | [.key, (.value | length)] | @tsv' | sort -k2 -nr | head -10

평문 출력: 극강의 호환성

평문(Plain) 포맷은 별도의 마크업 없이 구분선으로만 블록을 나눕니다.

================
File Summary
================
(내용...)

================
Files
================
================
File: src/index.ts
================
// 내용...

가장 단순한 형태이므로 어떤 텍스트 편집기나 오래된 도구에서도 깨짐 없이 읽을 수 있습니다. 다만, 저장소 규모가 매우 클 경우 AI가 구조를 파악하는 능력이 XML이나 JSON보다 떨어질 수 있습니다.

요약: 나에게 맞는 포맷 선택하기

고민된다면 다음 기준표를 참고하세요.

내 상황	추천 포맷	이유
Claude / Gemini를 사용 중이다	XML	모델의 학습 특성상 파싱 정확도가 가장 높음
결과물을 직접 읽고 수정하고 싶다	Markdown	인간에게 가장 친숙한 문서 형식
CI/CD 파이프라인에 연동하고 싶다	JSON	기계적 처리가 쉽고 자동화에 최적
포맷팅이 전혀 없는 순수 텍스트가 필요하다	Plain	범용성과 단순함이 최우선인 경우

다음 편에서는 로컬 저장소를 넘어 GitHub 원격 저장소를 직접 겨냥해서 묶는 방법을 알아보겠습니다.