Repomix 설정 파일과 무시 규칙

Repomix 설정 파일을 상징하는 이미지

매번 수많은 명령줄 옵션을 입력하는 것은 비효율적일 뿐 아니라, 팀원마다 서로 다른 컨텍스트를 AI에게 제공하게 되어 결과의 일관성이 떨어집니다. Repomix의 설정 파일은 "우리 팀이 AI에게 제공할 코드의 표준"을 정의하는 장치입니다.

형식과 탐색 순서

Repomix는 다음과 같은 우선순위로 설정 파일을 검색하여 적용합니다.

우선순위	지원 형식	파일명 예시
1순위	TypeScript	`repomix.config.ts`, `.mts`, `.cts`
2순위	JavaScript	`repomix.config.js`, `.mjs`, `.cjs`
3순위	JSON 계열	`repomix.config.json`, `.json5`, `.jsonc`

설정 파일은 로컬(프로젝트 루트)과 전역(사용자 홈 디렉터리) 두 곳에서 찾습니다.

로컬 경로: 현재 작업 디렉터리 (프로젝트별 특화 설정)
전역 경로: macOS/Linux ~/.config/repomix/, Windows %LOCALAPPDATA%\Repomix\ (개인 기본 설정)

최종 결정 우선순위는 명령줄 옵션 $\rightarrow$ 로컬 설정 $\rightarrow$ 전역 설정 순입니다. 로컬 설정이 없다면 전역 설정을 따르며, 명령줄 옵션은 이 모든 것을 덮어씁니다.

참고로 JSON 계열 설정에서는 JSON5 문법을 지원하므로, 설정 파일 내에 주석을 달거나 마지막 쉼표를 남겨두어도 오류 없이 작동합니다.

초기화와 전역 설정, 스키마

설정 파일을 빠르게 생성하려면 다음 명령어를 사용하세요.

bash

repomix --init            # 프로젝트 루트에 repomix.config.json 생성 (팀 공유 권장)
repomix --init --global   # 사용자 홈 디렉터리에 전역 설정 생성 (개인 기본값)
repomix -c my.config.json # 실행 시 특정 설정 파일 강제 지정

IDE에서 자동완성과 타입 검사 기능을 활용하려면 설정 파일 상단에 스키마 경로를 추가하세요.

json

{
  "$schema": "https://repomix.com/schemas/latest/schema.json",
  "output": {
    "filePath": "repomix-output.xml",
    "style": "xml"
  }
}

TypeScript 설정과 defineConfig

더욱 정밀한 제어가 필요하다면 TypeScript 설정을 사용하세요. defineConfig를 쓰면 타입 안정성을 확보할 수 있습니다.

bash

npm install -D repomix

typescript

// repomix.config.ts
import { defineConfig } from 'repomix';

export default defineConfig({
  output: {
    filePath: 'output.xml',
    style: 'xml',
    removeComments: true,
  },
  ignore: {
    customPatterns: ['**/node_modules/**', '**/dist/**'],
  },
});

TypeScript 설정의 최대 강점은 동적 값 적용이 가능하다는 점입니다. 예를 들어 출력 파일명에 타임스탬프를 자동으로 붙이거나, 환경 변수에 따라 설정을 다르게 적용할 수 있습니다.

⚠️ 보안 경고: 설정 파일은 "실행 가능한 코드"입니다..ts나 .js 설정 파일은 Repomix가 읽는 순간 즉시 실행됩니다. 따라서 신뢰할 수 없는 저장소의 설정 파일을 그대로 실행하는 것은 매우 위험합니다. 이는 마치 npm install 시 실행되는 라이프사이클 스크립트와 같으므로, 항상 내용을 확인하고 신뢰할 수 있는 파일만 사용하세요. (상세 내용은 보안 편 참조)

무시 규칙 다섯 갈래와 우선순위

Repomix는 다음 다섯 가지 출처에서 제외 규칙을 수집하여 최종 대상 파일을 결정합니다.

제외 규칙 출처	제어 방법	특징
`ignore.customPatterns`	`-i, --ignore` 옵션	설정 파일에 정의한 전용 제외 패턴
`.repomixignore`	파일 생성	Repomix 전용 무시 파일 (프로젝트 루트)
`.ignore`	`ignore.useDotIgnore`	ripgrep 등과 호환되는 범용 무시 파일
`.gitignore` / `.git/info/exclude`	`ignore.useGitignore`	Git의 표준 무시 규칙 적용
기본 내장 패턴	`ignore.useDefaultPatterns`	`node_modules`, `.git`, `dist` 등 공통 제외 대상

무시 규칙 적용 우선순위:

ignore.customPatterns (가장 우선)
무시 파일들 (.repomixignore $\rightarrow$ .ignore $\rightarrow$ .gitignore)
- 더 깊은 디렉터리에 있는 설정 파일이 우선합니다.
- 같은 경로에 여러 파일이 있다면 병합하여 적용합니다.
기본 내장 패턴 (가장 마지막에 적용)

.repomixignore는 Git 설정은 건드리지 않으면서, 오직 Repomix 출력에서만 제외하고 싶은 파일(예: 대용량 로그 파일, 임시 캐시 등)을 관리할 때 매우 유용합니다.

포함 패턴이 무시 규칙을 이기지 못한다

가장 많은 혼란이 발생하는 지점입니다. include 패턴은 "후보군을 좁히는 필터"이지, 무시 규칙을 무력화하는 "강제 포함" 옵션이 아닙니다.

잘못된 생각: "--include node_modules/**라고 했으니 무조건 포함되겠지?"
실제 동작: include로 후보에 올렸더라도, 이후 .gitignore나 기본 무시 패턴에 의해 제외 대상이라면 결국 출력에서 빠집니다.

만약 의존성 라이브러리 파일을 강제로 포함하고 싶다면, --no-gitignore나 --no-default-patterns 옵션을 사용해 무시 규칙 자체를 꺼야 합니다. 다만, 이는 토큰 사용량을 급격히 늘리므로 꼭 필요한 파일만 좁게 지정하여 사용하세요.

입력 제한과 바이너리 파일

항목	기본값	동작 및 의미
`input.maxFileSize`	`50,000,000` (50MB)	이 크기를 초과하는 파일은 처리 효율을 위해 통째로 건너뜁니다.
바이너리 파일 처리	내용 제외 / 경로 포함	이미지, PDF, 실행 파일 등은 본문을 출력하지 않지만, 디렉터리 트리에는 경로를 남깁니다.

AI가 파일의 존재는 알되 불필요한 바이트 데이터로 컨텍스트를 낭비하지 않게 하는 설계입니다. 또한 output.includeFullDirectoryStructure 옵션을 켜면, 일부 파일만 include 했더라도 전체 프로젝트의 뼈대(트리)를 AI에게 제공하여 분석 정확도를 높일 수 있습니다.

파일 프로세서: 외부 명령으로 내용 바꾸기

input.processors를 사용하면 파일을 합치기 전, 특정 패턴의 파일 내용을 외부 명령어를 통해 변환할 수 있습니다.

동작 방식:

패턴에 맞는 파일을 찾습니다.
파일 내용을 임시 파일에 쓰고, 그 경로를 {file} 변수에 넣어 명령어를 실행합니다.
명령의 표준 출력(stdout)을 해당 파일의 새로운 내용으로 대체합니다.

추천 패턴	추천 명령어	기대 효과
`*/.json`	`jq -c . {file}`	JSON 공백 제거 및 압축 $\rightarrow$ 토큰 절약
`*/.svg`	`npx svgo -i {file} -o -`	SVG 최적화 $\rightarrow$ 불필요한 메타데이터 제거
`*/.ipynb`	`jupyter nbconvert --to script --stdout {file}`	주피터 노트북을 일반 스크립트로 변환하여 분석 용이성 증대

주의사항:

실행 순서: 프로세서는 보안 검사 및 토큰 계산보다 먼저 실행됩니다. 따라서 변환된 결과물을 바탕으로 보안 검사가 이루어집니다.
신뢰 경계: 프로세서는 임의의 셸 명령을 실행하므로 매우 강력하지만 위험합니다. 로컬 CLI에서만 동작하며, MCP 서버나 repomix.com 웹 서비스에서는 안전을 위해 비활성화되어 있습니다. 원격 저장소의 경우 --remote-trust-config를 명시해야만 동작합니다.

바로 쓰는 예시 설정

팀에서 바로 적용할 수 있는 표준 설정 예시입니다.

json5

{
  "$schema": "https://repomix.com/schemas/latest/schema.json",
  "input": {
    "maxFileSize": 50000000, // 50MB 제한
    "processors": [
      { "pattern": "**/*.json", "command": "jq -c . {file}" } // JSON 압축
    ]
  },
  "output": {
    "filePath": "repomix-output.xml",
    "style": "xml",
    "filePathStyle": "target-relative",
    "showLineNumbers": true, // AI가 줄 번호로 지칭 가능하게 설정
    "removeComments": false,
    "removeEmptyLines": true,
    "git": {
      "sortByChanges": true, // 변경이 잦은 파일을 아래로 배치
      "includeDiffs": true,   // 현재 작업 중인 변경 사항 포함
      "includeLogs": true      // 최근 커밋 로그 포함
    }
  },
  "include": ["src/**/*", "docs/**/*"], // 핵심 소스와 문서만 포함
  "ignore": {
    "useGitignore": true,
    "useDefaultPatterns": true,
    "customPatterns": ["**/*.log", "temp/**"]
  },
  "security": {
    "enableSecurityCheck": true // 보안 검사 필수 활성화
  },
  "tokenCount": {
    "encoding": "o200k_base" // GPT-4o 기준 인코더
  }
}

이제 설정 파일을 통해 팀만의 컨텍스트 표준을 만들 수 있습니다. 다음 편에서는 AI 모델에 따라 어떤 출력 포맷을 선택하는 것이 가장 효율적인지 알아보겠습니다.

형식과 탐색 순서 ​

초기화와 전역 설정, 스키마 ​

TypeScript 설정과 defineConfig ​

무시 규칙 다섯 갈래와 우선순위 ​

포함 패턴이 무시 규칙을 이기지 못한다 ​

입력 제한과 바이너리 파일 ​

파일 프로세서: 외부 명령으로 내용 바꾸기 ​

바로 쓰는 예시 설정 ​