설정 & 구성

Claude Code의 설정 시스템은 개인 개발자의 로컬 환경설정부터 엔터프라이즈 정책까지 다양한 소스의 설정을 일관된 인터페이스로 병합합니다. 5계층 캐스케이드, 3단계 캐시 아키텍처, chokidar 기반 변경 감지, MDM 및 원격 관리 설정을 통해 대규모 조직에서도 안전하고 효율적인 설정 관리를 제공합니다.

설정은 5개 계층에서 로드되며, SETTING_SOURCES 배열에서 나중에 오는 소스가 이전 소스를 덮어씁니다:

1. userSettings — ~/.claude/settings.json (사용자 전역 설정)
2. projectSettings — .claude/settings.json (프로젝트 범위, git 추적)
3. localSettings — .claude/settings.local.json (로컬 전용, gitignore)
4. CLI 플래그 — 명령줄 인수 (--model, --allowedTools 등)
5. policySettings — 정책 설정 (가장 높은 우선순위)

// settingsSources.ts — 소스 순서 (나중이 우선)
const SETTING_SOURCES = [
  'userSettings',
  'projectSettings',
  'localSettings',
  'flagSettings',
  'policySettings',
] as const

policySettings 내부 우선순위

policySettings 계층 내부에서도 4개 소스가 존재하며, first-source-wins 방식으로 평가됩니다:

1. remote — 원격 관리 설정 (최우선)
2. MDM — macOS plist / Windows 레지스트리
3. file — managed-settings.json 파일
4. HKCU — Windows 사용자 레지스트리

설정 값의 타입에 따라 병합 전략이 다릅니다:

• 객체 (Object): 딥 병합 — 중첩된 키가 재귀적으로 병합됩니다
• 배열 (Array): 중복 제거 연결 — 두 배열을 연결한 후 중복 항목을 제거합니다
• 스칼라 (Scalar): 덮어쓰기 — 나중 소스의 값이 이전 값을 완전히 대체합니다

// settingsManager.ts — 배열 병합: 중복 제거 연결
// userSettings.allow = ["Read(**)", "Bash(git *)"]
// projectSettings.allow = ["Bash(git *)", "Write(src/)"]
// 병합 결과: ["Read(**)", "Bash(git *)", "Write(src/)"]

function mergeArrays(a: string[], b: string[]): string[] {
  return [...new Set([...a, ...b])]
}

위 예시에서 userSettings의 ["Read(**)", "Bash(git *)"]와 projectSettings의 ["Bash(git *)", "Write(src/)"]가 중복 제거 연결되어 ["Read(**)", "Bash(git *)", "Write(src/)"]가 됩니다. 중복된 "Bash(git *)"는 한 번만 포함됩니다.

설정 읽기 성능을 최적화하기 위해 3단계 캐시 아키텍처를 사용합니다:

• Session 캐시: 세션 전체에서 유효한 병합된 최종 설정. 모든 소스가 변경되지 않는 한 재계산하지 않습니다.
• Per-Source 캐시: 각 소스(user, project, local 등)별로 파싱된 결과를 캐시합니다. 특정 소스만 변경되면 해당 소스만 재파싱합니다.
• Parse-File 캐시: 파일 시스템 읽기와 JSON 파싱 결과를 캐시합니다. 파일 mtime이 변경되지 않으면 디스크를 다시 읽지 않습니다.

설정 파일 변경은 두 가지 메커니즘으로 감지됩니다:

• chokidar 감시: 로컬 설정 파일(settings.json, settings.local.json)의 실시간 변경 감지
• 30분 MDM 폴링: MDM 정책은 chokidar로 감시할 수 없으므로 30분 간격으로 폴링합니다

내부 쓰기 억제 (markInternalWrite)

Claude Code가 자체적으로 설정 파일을 수정할 때(예: 마이그레이션), 변경 알림이 불필요한 리로드를 트리거하지 않도록 억제합니다:

// settingsWatcher.ts — 내부 쓰기 시 5초간 이벤트 억제
function markInternalWrite(): void {
  internalWriteTimestamp = Date.now()
}

function onFileChange(path: string): void {
  if (Date.now() - internalWriteTimestamp < 5000) {
    return // 5초 윈도우 내 변경 무시
  }
  invalidateCache(path)
}

markInternalWrite()를 호출하면 이후 5초 이내의 chokidar 이벤트가 억제됩니다. 이 윈도우는 파일 쓰기와 파일시스템 이벤트 전파 사이의 타이밍 차이를 커버하기에 충분합니다.

MDM (모바일 디바이스 관리)

엔터프라이즈 환경에서는 macOS plist 또는 Windows 레지스트리를 통해 정책을 배포합니다. Claude Code는 plutil(macOS) 또는 reg query(Windows) 서브프로세스를 실행하여 MDM 설정을 읽습니다.

파일 기반 관리 설정

managed-settings.json 파일은 MDM을 사용할 수 없는 환경에서 정책을 배포하는 대안입니다. MDM과 파일 모두 존재할 경우, policySettings 내 first-source-wins 규칙에 따라 MDM이 파일보다 우선합니다.

원격 관리 설정

원격(remote) 관리 설정은 HTTP 엔드포인트에서 가져오며, ETag 기반 캐싱으로 네트워크 비용을 최소화합니다. 서버 응답이 304 Not Modified이면 캐시된 값을 사용합니다.

설정 동기화 (CCR)

CCR(Claude Code Remote) 환경에서는 로컬과 원격 설정을 동기화하여 일관된 동작을 보장합니다.