[Claude Code] CLAUDE.local.md란? 팀 설정과 개인 설정을 분리하는 법

 

Claude Code로 팀 프로젝트를 진행할 때 개인 로컬 환경에 맞는 설정을 CLAUDE.md에 적어뒀다가 팀원 전체에게 영향을 준 경험이 있다. 내 PC에만 있는 도구 경로나 개인 선호 설정이 공용 파일에 섞이는 문제다.

Claude Code는 이 문제를 .local 파일로 해결한다. CLAUDE.local.md와 settings.local.json은 팀과 공유되지 않는 개인 전용 설정 파일이며, 생성 시 자동으로 .gitignore 처리된다.

 

Claude Code 설정은 세 가지 범위(Scope)로 계층화되어 있다. 모든 프로젝트에 적용되는 User 범위 (~/.claude/), 팀이 공유하는 Project 범위 (.claude/settings.json, CLAUDE.md), 나만 사용하는 Local 범위 (.claude/settings.local.json, CLAUDE.local.md)다. 같은 설정이 여러 범위에 정의됐을 때 우선순위는 Local > Project > User 순으로 적용된다.

 

사용 방법

 

1단계: 파일 구조 파악

Claude Code 프로젝트에서 설정 관련 파일 위치는 다음과 같다.

~/.claude/ # 모든 프로젝트 적용 (User 범위)
├── settings.json # 개인 선호 설정 (전역)
└── CLAUDE.md # 개인 메모리 (전역)

project-root/
└── .claude/ # 팀 공유 설정 (Project 범위)
├── settings.json # 팀 설정 ✅ Git 커밋
├── settings.local.json # 개인 오버라이드 ❌ gitignore
├── CLAUDE.md # 팀 컨텍스트 ✅ Git 커밋
└── CLAUDE.local.md # 개인 메모 ❌ gitignore

 

.local이 붙은 파일은 Claude Code가 자동으로 .gitignore에 추가한다. 별도 설정 없이도 실수로 커밋되지 않는다.

 

2단계: CLAUDE.md vs CLAUDE.local.md

두 파일의 차이를 정리하면 다음과 같다.

항목	CLAUDE.md	CLAUDE.local.md
위치	CLAUDE.md 또는 .claude/CLAUDE.md	.claude/CLAUDE.local.md
Git 커밋	✅ 커밋	❌ gitignore
적용 대상	팀 전체	나 혼자
우선순위	낮음	높음
용도	코딩 표준, 아키텍처 규칙, 공용 컨텍스트	개인 메모, 로컬 환경 특이사항, 실험 내용

 

CLAUDE.md에는 팀이 공유해야 할 규칙과 컨텍스트를 적는다. CLAUDE.local.md는 나만 아는 로컬 경로, 개인적인 Claude 사용 노트, 실험 중인 설정을 자유롭게 적는 공간이다.

 

3단계: settings.json vs settings.local.json

settings 파일도 동일한 구조로 분리된다.

항목	settings.json	settings.local.json
위치	.claude/settings.json	.claude/settings.local.json
Git 커밋	✅ 커밋	❌ gitignore
적용 대상	팀 전체	나 혼자
우선순위	낮음	높음 (Project 덮어씀)
용도	팀 공통 권한, hooks, MCP 서버	개인 에디터 설정, 로컬 DB 경로 등

 

settings.local.json의 값이 settings.json의 값을 덮어쓴다. Claude Code는 설정 파일 변경을 감지하면 자동으로 리로드한다. 대부분의 설정은 재시작 없이 적용되며 model과 outputStyle은 예외적으로 재시작이 필요하다.

 

적용 전후 비교

 

Before: local 파일 없이 팀 settings.json에 개인 설정 혼재

// .claude/settings.json (팀 공유)
{
"permissions": { "allow": ["Bash(npm run test *)"] },
"editorMode": "vim", // 팀원들에게 강제됨 ❌
"spinnerTipsEnabled": false // 개인 선호가 팀에 적용 ❌
}

 

After: 팀 설정과 개인 설정 분리

// .claude/settings.json (팀 공유) ✅ Git 커밋
{
"permissions": { "allow": ["Bash(npm run test *)"] }
}

// .claude/settings.local.json (개인용) ❌ gitignore
{
"editorMode": "vim",
"spinnerTipsEnabled": false
}

 

팀 설정과 개인 설정이 명확히 분리되어 Git 이력이 깔끔해지고 팀원 간 설정 충돌이 사라진다.

 

기대 효과

 

1. 팀 설정 오염 방지

개인 로컬 환경에 맞는 경로, 에디터 설정, 실험적 내용이 팀 공용 파일에 섞이지 않는다. Git 커밋이 팀에 실제 의미 있는 변경사항만 담게 된다.

 

2. 자동 gitignore로 관리 부담 없음

settings.local.json과 CLAUDE.local.md는 Claude Code가 생성 시 자동으로 .gitignore에 추가한다. 실수로 커밋할 걱정이 없다.

 

3. 개인 오버라이드 자유도

Local 범위 설정이 Project 범위보다 우선순위가 높다. 팀 설정을 건드리지 않고 나만의 워크플로우로 Claude Code를 실행할 수 있다.

 

4. 보안 원칙 유지

API 키, 토큰, 비밀번호는 .local 파일이라도 절대 저장하지 않는다. 개인 파일도 실수로 공유될 수 있으므로 환경 변수를 사용하는 것이 올바른 방법이다.

 

참고 자료:

https://code.claude.com/docs/en/settings

https://israynotarray.com/en/ai/2026/03/31/which-claude-code-files-should-you-commit/

https://inventivehq.com/knowledge-base/claude/where-configuration-files-are-stored