Claude Code 공식문서 리뷰-Configuration[1] : Claude Code 설정(Claude Code settings)

안녕하세요! 갓대희입니다. 

Claude Code Docs 공식 문서 >> [설정] 섹션의 내용 중 [Claude Code 설정(Claude Code settings)]를 살펴 보려고 합니다.

이번 섹션 부터는 영문, 한글번역본이 모두 공식문서로 존재하는 섹션이니 한글 문서를 편하게 참고 하셔도 될 것 같습니다.

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

Claude Code settings - Claude Code Docs

 

이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.

저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서 클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다.

 

Claude Code 설정 가이드

개요

• 설정 범위: Enterprise, User, Project, Local 4단계
• 주요 설정 파일: settings.json (사용자/프로젝트), .claude.json
• 커스터마이징: 권한, 모델, MCP, 환경 변수 등 다양한 옵션
• 우선순위: Enterprise > CLI 인수 > Local > Project > User

Claude Code는 다양한 설정 파일과 환경 변수를 통해 동작을 커스터마이징할 수 있다. 이 가이드에서는 설정의 범위, 파일 위치, 주요 옵션들을 설명한다.

왜 설정을 알아야 할까?

Claude Code를 기본 상태로 사용해도 되지만, 설정을 이해하면 다음과 같은 이점이 있다:

• 보안 강화: .env, 비밀 키 등 민감한 파일을 Claude가 읽지 못하도록 차단
• 생산성 향상: 자주 사용하는 명령을 자동 승인하여 권한 요청 최소화
• 팀 협업: 프로젝트 설정을 Git으로 공유하여 팀원 모두 동일한 환경 사용
• 비용 관리: 모델 선택, 토큰 제한 등으로 API 비용 통제

 

설정 범위 (Configuration Scopes)

Claude Code는 범위 시스템을 사용해 설정이 어디에 적용되고 누구와 공유되는지 결정한다.

사용 가능한 범위

범위	위치	영향 범위	팀 공유
Enterprise	managed-settings.json	해당 머신의 모든 사용자	Yes (IT 배포)
User	~/.claude/ 디렉토리	본인, 모든 프로젝트	No
Project	저장소의 .claude/	저장소의 모든 협업자	Yes (git 커밋)
Local	.claude/*.local.* 파일	본인, 이 저장소만	No (gitignore)

우선순위 (높음 - 낮음)

1. Enterprise (최상위) - 재정의 불가
2. 명령줄 인수 - 임시 세션 재정의
3. Local - 프로젝트/사용자 설정 재정의
4. Project - 사용자 설정 재정의
5. User (최하위) - 다른 설정이 없을 때 적용

초보자 팁: 개인 설정은 ~/.claude/settings.json, 팀과 공유할 설정은 .claude/settings.json에 저장한다.

나에게 맞는 설정 범위는?

상황 1: "혼자 개발하고 있어요"

~/.claude/settings.json (User 범위)만 사용하면 충분하다. 모든 프로젝트에 동일하게 적용된다.

상황 2: "팀 프로젝트에서 사용해요"

.claude/settings.json (Project 범위)를 Git에 커밋한다. 팀원 모두 동일한 권한 설정과 규칙을 공유한다.

상황 3: "팀 설정은 따르되 개인 설정도 필요해요"

.claude/settings.local.json (Local 범위)을 사용한다. 프로젝트 설정을 재정의하면서 Git에는 포함되지 않는다.

상황 4: "회사에서 보안 정책을 강제해야 해요"

Enterprise 설정을 사용한다. IT 관리자가 배포하며 사용자가 재정의할 수 없다.

 

빠른 시작 

처음 시작하는가?

모든 설정을 이해할 필요 없다. 아래 최소 설정만으로 안전하고 편리하게 시작할 수 있다.

1. 사용자 설정 파일 생성

# 설정 디렉토리 생성 (없으면)
mkdir -p ~/.claude

# 설정 파일 생성
cat > ~/.claude/settings.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(npm run lint:*)",
      "Bash(npm run test:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(**/*credentials*)",
      "Bash(rm -rf:*)"
    ]
  }
}
EOF

2. 설정 확인

# 파일이 올바르게 생성되었는지 확인
cat ~/.claude/settings.json

# Claude Code 실행하여 테스트
claude "안녕, 설정이 잘 적용되었는지 확인해줘"

위 설정이 하는 일:

• allow: git 조회 명령과 lint/test 실행을 자동 승인 (권한 요청 없이 바로 실행)
• deny: 환경변수 파일, 비밀 정보, rm -rf 같은 위험한 명령 차단

 

설정 파일 위치

파일 목록

파일	용도
~/.claude/settings.json	사용자 설정
.claude/settings.json	프로젝트 설정 (팀 공유)
.claude/settings.local.json	로컬 설정 (개인용, gitignore)
~/.claude.json	기타 설정 (테마, OAuth, MCP, 캐시)
.mcp.json	프로젝트 MCP 서버

기업 관리형 설정 파일 위치

플랫폼	경로
macOS	/Library/Application Support/ClaudeCode/
Linux/WSL	/etc/claude-code/
Windows	C:\Program Files\ClaudeCode\

설정 파일 예시

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  },
  "companyAnnouncements": [
    "Acme Corp에 오신 것을 환영합니다! docs.acme.com에서 코드 가이드라인을 확인하세요.",
    "알림: 모든 PR에 코드 리뷰가 필요합니다"
  ]
}

 

주요 설정 옵션

일반 설정

키	설명	예시
apiKeyHelper	API 요청 인증값 생성 스크립트	/bin/generate_temp_api_key.sh
cleanupPeriodDays	비활성 세션 삭제 기간 (기본: 30)	20
companyAnnouncements	시작 시 표시할 공지사항	["환영 메시지"]
env	모든 세션에 적용할 환경 변수	{"FOO": "bar"}
model	기본 모델 재정의	"claude-sonnet-4-5-20250929"
outputStyle	출력 스타일 설정	"Explanatory"
alwaysThinkingEnabled	확장 사고 기본 활성화	true

인증 설정

키	설명
forceLoginMethod	로그인 방법 제한 (claudeai 또는 console)
forceLoginOrgUUID	로그인 시 조직 자동 선택

MCP 설정

키	설명
enableAllProjectMcpServers	모든 프로젝트 MCP 서버 자동 승인
enabledMcpjsonServers	승인된 MCP 서버 목록
disabledMcpjsonServers	거부된 MCP 서버 목록
allowedMcpServers	(기업) MCP 서버 허용 목록
deniedMcpServers	(기업) MCP 서버 거부 목록

 

권한 설정

permissions 객체에서 도구 및 파일 접근 권한을 설정한다.

{
  "permissions": {
    "allow": [
      "Bash(git diff:*)",
      "Bash(npm run:*)"
    ],
    "ask": [
      "Bash(git push:*)"
    ],
    "deny": [
      "WebFetch",
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ],
    "additionalDirectories": ["../docs/"],
    "defaultMode": "acceptEdits",
    "disableBypassPermissionsMode": "disable"
  }
}

권한 옵션

키	설명	예시
allow	도구 사용 허용 규칙	["Bash(git diff:*)"]
ask	확인이 필요한 규칙	["Bash(git push:*)"]
deny	도구 사용 거부 및 파일 접근 차단	["Read(./.env)"]
additionalDirectories	추가 작업 디렉토리	["../docs/"]
defaultMode	기본 권한 모드	"acceptEdits"

보안 주의사항: .env, 자격 증명, 비밀 키 등 민감한 파일은 반드시 deny 규칙에 추가하여 Claude가 접근하지 못하도록 한다.

실전 권한 설정 예시

Frontend 프로젝트 (React/Vue)

{
  "permissions": {
    "allow": [
      "Bash(npm run:*)", "Bash(yarn:*)", "Bash(pnpm:*)",
      "Bash(npx prettier:*)", "Bash(npx eslint:*)"
    ],
    "deny": [
      "Read(./.env*)", "Bash(npm publish:*)"
    ]
  }
}

Backend 프로젝트 (Python/Node)

{
  "permissions": {
    "allow": [
      "Bash(pytest:*)", "Bash(python -m pytest:*)",
      "Bash(pip install:*)", "Bash(poetry:*)"
    ],
    "deny": [
      "Read(./.env*)", "Read(./config/secrets/**)",
      "Bash(python manage.py migrate:*)"
    ]
  }
}

DevOps / 인프라 작업

{
  "permissions": {
    "allow": [
      "Bash(docker build:*)", "Bash(docker-compose up:*)",
      "Bash(kubectl get:*)", "Bash(terraform plan:*)"
    ],
    "deny": [
      "Bash(terraform apply:*)", "Bash(kubectl delete:*)",
      "Read(**/*credentials*)", "Read(**/*.pem)"
    ]
  }
}

 

샌드박스 설정

고급 샌드박싱 동작을 설정한다 (macOS/Linux 전용).

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker"],
    "allowUnsandboxedCommands": false,
    "network": {
      "allowUnixSockets": ["/var/run/docker.sock"],
      "allowLocalBinding": true,
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    },
    "enableWeakerNestedSandbox": false
  }
}

키	설명
enabled	bash 샌드박싱 활성화
autoAllowBashIfSandboxed	샌드박스 시 bash 자동 승인
excludedCommands	샌드박스 외부에서 실행할 명령
network.allowUnixSockets	접근 가능한 소켓 경로
enableWeakerNestedSandbox	권한 없는 Docker용 약한 샌드박스 (Linux)

 

환경 변수

핵심 인증

변수	용도
ANTHROPIC_API_KEY	Claude SDK API 키
ANTHROPIC_AUTH_TOKEN	커스텀 Authorization 헤더 값
ANTHROPIC_CUSTOM_HEADERS	Name: Value 형식의 커스텀 헤더

모델 설정

변수	용도
ANTHROPIC_MODEL	사용할 모델 설정 이름
ANTHROPIC_DEFAULT_HAIKU_MODEL	Haiku 모델 재정의
ANTHROPIC_DEFAULT_SONNET_MODEL	Sonnet 모델 재정의
ANTHROPIC_DEFAULT_OPUS_MODEL	Opus 모델 재정의
CLAUDE_CODE_SUBAGENT_MODEL	서브에이전트용 모델

대체 제공자

변수	용도
CLAUDE_CODE_USE_BEDROCK	AWS Bedrock 사용
CLAUDE_CODE_USE_FOUNDRY	Microsoft Foundry 사용
CLAUDE_CODE_USE_VERTEX	Google Vertex 사용

사고 및 출력

변수	용도
MAX_THINKING_TOKENS	확장 사고 활성화 및 토큰 예산 설정
CLAUDE_CODE_MAX_OUTPUT_TOKENS	대부분의 요청에 대한 최대 출력 토큰
DISABLE_PROMPT_CACHING	프롬프트 캐싱 비활성화 (모든 모델)

 

Claude에게 제공되는 도구

도구	설명	권한 필요
Bash	셸 명령 실행	Yes
Edit	파일 편집	Yes
Write	파일 생성/덮어쓰기	Yes
Read	파일 내용 읽기	No
Glob	패턴으로 파일 찾기	No
Grep	파일 내용 검색	No
WebFetch	URL 콘텐츠 가져오기	Yes
WebSearch	웹 검색 수행	Yes
Task	서브에이전트 실행	No
NotebookEdit	Jupyter 셀 수정	Yes

 

Bash 도구 동작

지속성 모델

• 작업 디렉토리 유지: cd 변경이 후속 명령에 영향
• 환경 변수 유지 안 됨: 한 명령에서 설정한 변수가 다음 명령에서 사용 불가

환경 변수 지속 방법

방법 1: Claude Code 시작 전 활성화 (가장 간단)

conda activate myenv
# 또는: source /path/to/venv/bin/activate
claude

방법 2: CLAUDE_ENV_FILE 설정 (지속적 설정)

export CLAUDE_ENV_FILE=/path/to/env-setup.sh
claude

/path/to/env-setup.sh 내용:

conda activate myenv
# 또는: source /path/to/venv/bin/activate
# 또는: export MY_VAR=value

방법 3: SessionStart 훅 사용 (프로젝트별)

{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup",
      "hooks": [{
        "type": "command",
        "command": "echo 'conda activate myenv' >> \"$CLAUDE_ENV_FILE\""
      }]
    }]
  }
}

실전 팁: Python 가상환경을 자주 사용한다면 CLAUDE_ENV_FILE을 셸 프로필(.bashrc, .zshrc)에 설정해두면 편리하다.

 

플러그인 설정

enabledPlugins

활성화할 플러그인을 설정한다. 형식: "plugin-name@marketplace-name": true/false

{
  "enabledPlugins": {
    "code-formatter@team-tools": true,
    "deployment-tools@team-tools": true,
    "experimental-features@personal": false
  }
}

extraKnownMarketplaces

저장소에서 사용할 추가 마켓플레이스를 정의한다.

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    },
    "security-plugins": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/security/plugins.git"
      }
    }
  }
}

마켓플레이스 소스 유형:

• github: GitHub 저장소 (repo 사용)
• git: 임의의 git URL (url 사용)
• directory: 로컬 파일시스템 경로 (path 사용)

 

설정 우선순위 상세

1. 관리형 설정 (Enterprise) - Claude.ai 관리 콘솔
2. 파일 기반 관리형 설정 (managed-settings.json)
3. 명령줄 인수 - 임시 세션 재정의
4. 로컬 프로젝트 설정 (.claude/settings.local.json)
5. 공유 프로젝트 설정 (.claude/settings.json)
6. 사용자 설정 (~/.claude/settings.json)

주의: Enterprise 설정은 다른 모든 설정보다 우선하며, 사용자가 재정의할 수 없다.

 

흔한 문제 해결

설정 관련 문제가 발생하면?

대부분 JSON 문법 오류, 파일 위치 오류, 권한 규칙 오타가 원인이다.

문제 1: "설정이 적용되지 않아요"

증상

allow 규칙을 추가했는데도 계속 권한을 묻거나, deny 규칙이 작동하지 않음

확인할 것

1. JSON 문법 검사: 쉼표, 따옴표, 괄호 확인

   cat ~/.claude/settings.json | python -m json.tool

2. 파일 위치 확인: ~/.claude/settings.json (User) 또는 .claude/settings.json (Project)
3. Claude Code 재시작: 설정 변경 후 새 세션 시작 필요

문제 2: "권한 규칙이 매칭되지 않아요"

증상

Bash(npm run test:*) 규칙이 있는데 npm run test:unit 실행 시 권한 요청이 뜸

해결 방법

• 와일드카드 사용법 확인: *는 공백까지 포함한 전체 매칭
• 정확한 형식: Bash(명령어:인수패턴)
• 디버깅: 더 넓은 패턴으로 시작 후 좁히기

  "Bash(npm:*)"  // 모든 npm 명령 허용하고 테스트

문제 3: "환경 변수가 유지되지 않아요"

증상

conda activate나 export로 설정한 환경 변수가 다음 명령에서 사라짐

해결 방법

Claude Code는 명령마다 새 셸을 생성하므로 환경 변수가 유지되지 않는다. 다음 방법을 사용하자:

1. Claude Code 시작 전 활성화: 가상환경을 먼저 활성화하고 claude 실행
2. CLAUDE_ENV_FILE 사용: 환경 설정 스크립트 경로 지정

   export CLAUDE_ENV_FILE=/path/to/env-setup.sh

문제 4: "프로젝트 설정과 사용자 설정이 충돌해요"

해결 방법

우선순위를 이해하자: Enterprise > CLI 인수 > Local > Project > User

• 프로젝트 설정이 사용자 설정을 재정의함
• 개인 설정이 필요하면 .claude/settings.local.json 사용
• Local 설정은 .gitignore에 자동 추가됨

 

관련 문서

문서	설명
권한 관리	권한 시스템 상세
Hooks 가이드	도구 확장
플러그인	플러그인 시스템
MCP	Model Context Protocol
모델 설정	모델 구성 옵션

핵심 요약 - 설정 체크리스트

빠르게 확인하자

아래 항목들을 체크하면 Claude Code 설정이 완료된 것이다.

항목	설정 내용
사용자 설정	~/.claude/settings.json 생성 모든 프로젝트에 적용되는 개인 설정
보안 설정	deny 규칙에 민감 파일 추가 .env, credentials, secrets 등
생산성 설정	allow 규칙에 자주 쓰는 명령 추가 git, npm run, pytest 등
팀 프로젝트	.claude/settings.json을 Git에 커밋 팀원 모두 동일한 규칙 사용
개인 재정의	필요시 .claude/settings.local.json 사용 Git에 포함되지 않는 개인 설정

다음 단계

기본 설정이 완료되었다면, 다음 기능들도 살펴보자:

• Hooks: 도구 실행 전후에 커스텀 스크립트 실행
• MCP: 외부 서비스와 연동 (Slack, GitHub 등)
• CLAUDE.md: 프로젝트별 컨텍스트 제공

Claude Code 한국어 문서
번역 기준일: 2025-12-23 | 원본: code.claude.com/docs