Claude Code를 처음 쓰다 보면 "설정을 어디에 저장해야 하지?"라는 질문이 금방 생깁니다. 테마나 단축키 같은 개인 취향은 내 컴퓨터 전체에 적용하고 싶고, 팀이 함께 쓰는 권한 규칙은 저장소에 올려야 하고, 실험 중인 설정은 나만 갖고 싶을 때가 있습니다. Claude Code는 이 세 가지 요구를 스코프(Scope) — 설정이 적용되는 범위 체계로 깔끔하게 해결합니다. 이 글을 읽고 나면 settings.json 파일을 어디에 두어야 하는지, 같은 설정이 여러 곳에 있을 때 무엇이 이기는지 명확히 알 수 있습니다. 설정 파일을 직접 열어 보는 데까지 약 10분이면 충분합니다.
이 글로 할 수 있게 되는 것
- settings.json 파일이 어디에 있는지(또는 없으면 어디에 만들어야 하는지) 파악하기
- 전역·프로젝트·로컬 설정을 목적에 맞게 나눠 쓰기
/config명령으로 설정 화면 열고 값 바꾸기- 같은 설정이 여러 스코프에 겹칠 때 어느 값이 최종 적용되는지 이해하기
시작 전 준비물
- Claude Code가 설치되어 있어야 합니다. (패키지명:
@anthropic-ai/claude-code) - 터미널(Terminal / 명령 프롬프트)을 열 수 있으면 됩니다. 코딩 경험이 없어도 괜찮습니다.
- 운영체제는 macOS·Linux·Windows 모두 지원합니다. Windows에서는 문서에 나오는
~/.claude경로가%USERPROFILE%\.claude로 대응됩니다.
용어 빠른 풀이
- 스코프(Scope) — 설정이 적용되는 범위. '나만', '이 저장소 팀 전체', '회사 전체' 식으로 나뉩니다.
- settings.json — Claude Code 설정을 담는 텍스트 파일. 중괄호(
{ })로 된 JSON 형식입니다. - 저장소(Repository) — 프로젝트 파일 묶음. Git으로 관리하는 폴더라고 생각하면 됩니다.
- 관리형(Managed) — 회사 IT 부서가 중앙에서 강제로 배포하는 설정. 일반 개인 사용자는 거의 접할 일이 없습니다.
- gitignore — Git이 추적하지 않을 파일 목록. 이 목록에 있으면 팀 저장소에 올라가지 않습니다.
설정 파일이 어디에 있나요?
Claude Code는 설정 파일을 스코프별로 서로 다른 위치에 둡니다. 아래 표를 참고하세요.
- 사용자(User) 설정:
~/.claude/settings.json— 내 컴퓨터의 모든 프로젝트에 적용됩니다. 테마, 에디터 취향처럼 어디서든 쓰고 싶은 값을 여기에 둡니다. - 프로젝트(Project) 설정: 프로젝트 폴더 안의
.claude/settings.json— Git에 커밋하면 팀원 모두가 같은 설정을 씁니다. 팀 공통 권한 규칙, MCP 서버 주소 등을 여기에 둡니다. - 로컬(Local) 설정: 프로젝트 폴더 안의
.claude/settings.local.json— Git에 올라가지 않습니다. "이 프로젝트에서만, 나만" 쓸 값을 실험할 때 유용합니다. - 관리형(Managed) 설정: 서버·MDM·레지스트리 등 조직 IT가 배포합니다. 가장 높은 우선순위이며 개인이 덮어쓸 수 없습니다.
파일이 아직 없어도 걱정하지 않아도 됩니다. Claude Code가 처음 .claude/settings.local.json을 만들 때 자동으로 gitignore에 추가합니다. 직접 만들었다면 gitignore에 수동으로 추가하세요.
단계별 실행 — /config 명령으로 설정하기
-
터미널에서 Claude Code를 실행합니다.
-
Claude Code 대화창 안에서 아래 명령을 입력하고 Enter를 누릅니다.
/config이렇게 보이면 성공: 탭이 있는 설정 인터페이스 화면이 열립니다. 상태 정보와 설정 옵션을 탭별로 볼 수 있습니다.
-
특정 값 하나만 바꾸고 싶다면, 화면을 열지 않고 바로 적용할 수도 있습니다. 공식 문서에 따르면 v2.1.181부터 다음과 같이 쓸 수 있습니다.
/config verbose=trueverbose=true자리에 바꾸고 싶은 키와 값을키=값형식으로 넣으면 됩니다. 정확한 키 이름은 설정 화면(/config)에서 확인하세요.
같은 설정이 여러 곳에 있으면? — 우선순위 이해하기
예를 들어 사용자 설정에서 어떤 옵션을 true로 놓고, 프로젝트 설정에서 같은 옵션을 false로 놓았다면 어떤 값이 적용될까요? 공식 문서에 따르면 더 좁은 범위(로컬 > 프로젝트 > 사용자)가 더 넓은 범위를 덮어씁니다. 즉, 프로젝트 설정의 false가 사용자 설정의 true를 이깁니다.
단, 권한(Permission) 규칙은 예외입니다. 권한 규칙은 덮어쓰지 않고 모든 스코프의 규칙이 합쳐집니다(merge). 팀 전체 허용 목록과 개인 허용 목록이 모두 살아있다고 이해하면 됩니다.
어떤 설정을 어느 스코프에 두어야 할까?
- 사용자 스코프에 두기 좋은 것: 터미널 테마, 즐겨 쓰는 단축키, 모든 프로젝트에서 쓰는 API 키나 플러그인
- 프로젝트 스코프에 두기 좋은 것: 팀 공통 권한 규칙, 팀이 함께 쓰는 MCP 서버 설정, 팀 전체에 강제할 플러그인
- 로컬 스코프에 두기 좋은 것: 이 프로젝트에서만 나 혼자 실험 중인 설정, 다른 팀원 환경에서는 동작하지 않는 머신별 값
- 관리형 스코프(Managed): 개인이 직접 설정하지 않습니다. 조직 IT·DevOps 팀이 보안 정책이나 컴플라이언스 요구사항을 회사 전체에 강제할 때 씁니다.
자주 막히는 지점 & 해결
settings.local.json이 Git에 올라가 버렸어요
Claude Code가 파일을 직접 만들면 gitignore에 자동 추가되지만, 사용자가 직접 만들었다면 자동 추가되지 않습니다. .gitignore 파일에 아래 줄을 추가하세요.
.claude/settings.local.json/config 명령이 보이지 않거나 동작하지 않아요
Claude Code 버전이 오래되었을 가능성이 있습니다. 터미널에서 패키지를 최신 버전으로 업데이트한 뒤 다시 시도해 보세요. 정확한 업데이트 방법은 화면에 안내되는 명령을 따르거나 공식 문서(code.claude.com)를 확인하세요.
같은 설정이 여러 파일에 있는데 어느 값이 실제로 적용됐는지 모르겠어요
공식 문서에 따르면 활성 설정 검증(Verify active settings) 기능이 있습니다. 설정 화면(/config)에서 현재 실제로 적용 중인 값을 확인할 수 있습니다. 화면 안의 관련 항목을 직접 눈으로 확인하는 것이 가장 확실합니다.
응용 — 팀 설정 표준화하기
팀 저장소의 .claude/settings.json에 공통 권한 규칙과 MCP 서버 설정을 작성해 두면, 팀원이 저장소를 클론하는 순간 동일한 환경에서 시작할 수 있습니다. 레시피 카드를 저장소에 넣어두는 셈입니다. 개인 취향(테마·단축키)은 각자 ~/.claude/settings.json에 별도로 관리하면, 팀 설정과 충돌 없이 공존합니다.
서브에이전트(Subagent — Claude Code가 하위 작업을 위해 띄우는 별도 Claude 인스턴스) 설정도 같은 스코프 구조를 따릅니다. 사용자 레벨 서브에이전트는 ~/.claude/agents/에, 프로젝트 레벨은 .claude/agents/에 둡니다.