설정 및 환경변수

읽는 시간: 12분 | 난이도: 중급

Claude Code의 설정 파일 구조, 권한 시스템, 환경변수를 이해하고 프로젝트와 팀에 맞게 최적화하는 방법을 알아봅니다.

설정 스코프 시스템

Claude Code는 5단계 스코프 시스템으로 설정을 관리합니다. 각 스코프는 적용 범위와 우선순위가 다릅니다.

스코프 종류

스코프별 용도

Managed 스코프는 다음에 적합합니다:

• 조직 전체에 적용해야 하는 보안 정책
• 재정의할 수 없는 컴플라이언스 요구사항
• IT/DevOps가 배포하는 표준화된 설정

User 스코프는 다음에 적합합니다:

• 모든 프로젝트에서 원하는 개인 설정
• 프로젝트 전반에서 사용하는 플러그인
• API 키 및 인증 정보

Project 스코프는 다음에 적합합니다:

• 팀이 공유하는 설정 (권한, 훅, MCP 서버)
• 팀 전체가 사용해야 하는 플러그인
• 협업자 간 툴링 표준화

Local 스코프는 다음에 적합합니다:

• 특정 프로젝트에서의 개인 재정의
• 팀과 공유하기 전 설정 테스트
• 다른 사람에게는 작동하지 않는 머신 고유 설정

스코프 우선순위

동일한 설정이 여러 스코프에 설정된 경우, 더 구체적인 스코프가 우선합니다:

1. Managed (최고) — 어떤 것으로도 재정의 불가
2. CLI 플래그 — 특정 세션에 대한 임시 재정의
3. Local (.claude/settings.local.json) — 프로젝트 및 사용자 설정을 재정의
4. Project (.claude/settings.json) — 사용자 설정을 재정의
5. User (~/.claude/settings.json) (최저) — 다른 설정이 없을 때 적용

예를 들어, 사용자 설정에서 권한이 허용되었지만 프로젝트 설정에서 거부되었다면, 프로젝트 설정이 우선하여 해당 권한이 차단됩니다.

설정 파일 구조

settings.json은 Claude Code를 계층적으로 설정하는 공식 메커니즘입니다.

파일 위치 요약

~/.claude/
├── settings.json          # User 스코프 (모든 프로젝트에 적용)
└── CLAUDE.md              # 전역 지침 파일

프로젝트/
├── .claude/
│   ├── settings.json      # Project 스코프 (팀과 공유, git 커밋)
│   ├── settings.local.json # Local 스코프 (개인용, gitignore)
│   └── agents/            # 프로젝트 서브에이전트 정의
├── CLAUDE.md              # 프로젝트 지침
└── .claudeignore          # 파일 제외 설정

settings.json 기본 형식

{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm run *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Read(./.env)"
    ],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_ENV": "development"
  },
  "hooks": {
    "PostToolUse": [...]
  }
}

권한 설정 (Permissions)

권한 설정은 Claude가 어떤 도구를 어떤 조건으로 사용할 수 있는지 제어합니다.

permissions 구조

권한 규칙 문법

규칙은 Tool 또는 Tool(specifier) 형식을 따릅니다. 규칙 평가 순서: deny 먼저, 그 다음 ask, 마지막으로 allow. 첫 번째로 매칭되는 규칙이 적용됩니다.

기본 예시:

도구별 패턴 예시:

{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm run *)",
      "Bash(pytest *)",
      "Read(**)",
      "WebFetch(domain:github.com)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(git merge *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "WebFetch",
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  }
}

MCP 도구 패턴:

{
  "permissions": {
    "allow": [
      "mcp__filesystem__read_file",
      "mcp__github__*"
    ],
    "deny": [
      "mcp__dangerous-server__*"
    ]
  }
}

Skill 도구 패턴:

{
  "permissions": {
    "allow": [
      "Skill(deploy *)",
      "Skill(test *)"
    ]
  }
}

서브에이전트(Task) 제한:

{
  "permissions": {
    "deny": [
      "Task(dangerous-agent)"
    ]
  }
}

/permissions 명령어

Claude Code 내부에서 /permissions 명령어로 현재 권한 설정을 확인하고 대화형으로 관리할 수 있습니다. /allowed-tools 명령어도 권한 규칙 설정에 사용할 수 있습니다.

현재 설정 확인

/status 명령어로 활성화된 설정 소스와 출처를 확인할 수 있습니다. 각 설정 레이어(managed, user, project)와 함께 출처 정보(Enterprise managed settings (remote), Enterprise managed settings (plist) 등)가 표시됩니다. 설정 파일에 오류가 있으면 /status가 문제를 보고합니다.

주요 설정 항목

전체 settings.json 설정 키

샌드박스 설정 (sandbox)

샌드박싱은 Bash 명령을 파일시스템 및 네트워크에서 격리합니다. 파일시스템/네트워크 제한은 Read, Edit, WebFetch 권한 규칙으로 설정합니다.

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"],
    "allowUnsandboxedCommands": false
  }
}

저작자 표기 설정 (attribution)

git 커밋 및 PR에 대한 Claude Code 저작자 표기를 커스터마이징합니다.

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <ai@company.com>",
    "pr": ""
  }
}

기본 커밋 저작자 표기:

Generated with [Claude Code](https://claude.com/claude-code)

   Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

저작자 표기를 완전히 숨기려면 commit과 pr 모두 빈 문자열로 설정하세요.

파일 제안 설정 (fileSuggestion)

@ 파일 경로 자동완성에 커스텀 명령을 설정합니다. 대규모 모노레포에서 유용합니다.

{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  }
}

커맨드는 훅과 동일한 환경변수(CLAUDE_PROJECT_DIR 포함)로 실행됩니다. stdin으로 JSON이 입력됩니다:

{"query": "src/comp"}

stdout으로 줄바꿈 구분 파일 경로를 출력합니다 (최대 15개):

src/components/Button.tsx
src/components/Modal.tsx
src/components/Form.tsx

민감한 파일 제외 (.claudeignore)

Claude Code가 API 키, 시크릿, 환경 파일 등 민감한 정보가 포함된 파일에 접근하지 못하도록 하려면 .claude/settings.json의 permissions.deny 설정을 사용합니다:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.json)",
      "Read(./build)"
    ]
  }
}

프로젝트 루트에 .claudeignore 파일을 생성하여 파일 탐색에서 제외할 파일과 디렉토리를 지정할 수도 있습니다. .gitignore와 동일한 패턴 문법을 사용합니다:

# .claudeignore 예시
.env
.env.*
secrets/
*.key
*.pem
node_modules/
dist/
build/
__pycache__/
.pytest_cache/

이러한 패턴과 일치하는 파일들은 파일 탐색 및 검색 결과에서 제외되고, 해당 파일에 대한 읽기 작업이 거부됩니다.

시스템 프롬프트

Claude Code의 내부 시스템 프롬프트는 공개되지 않습니다. 커스텀 지침을 추가하려면 CLAUDE.md 파일 또는 --append-system-prompt 플래그를 사용하세요.

서브에이전트 설정

Claude Code는 사용자 및 프로젝트 수준에서 커스텀 AI 서브에이전트를 지원합니다. 서브에이전트는 YAML 프론트매터가 있는 Markdown 파일로 저장됩니다:

• User 서브에이전트: ~/.claude/agents/ — 모든 프로젝트에서 사용 가능
• Project 서브에이전트: .claude/agents/ — 프로젝트에 한정, 팀과 공유 가능

플러그인 설정

Claude Code는 스킬, 에이전트, 훅, MCP 서버로 기능을 확장하는 플러그인 시스템을 지원합니다.

enabledPlugins

어떤 플러그인을 활성화할지 제어합니다. 형식: "plugin-name@marketplace-name": true/false

{
  "enabledPlugins": {
    "formatter@acme-tools": true,
    "deployer@acme-tools": true,
    "analyzer@security-plugins": false
  }
}

extraKnownMarketplaces

저장소에서 사용 가능한 추가 마켓플레이스를 정의합니다. 팀 편의를 위해 저장소 수준 설정에서 주로 사용합니다.

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    }
  }
}

저장소에 extraKnownMarketplaces가 포함된 경우:

1. 팀원은 폴더를 신뢰할 때 마켓플레이스 설치를 요청받습니다.
2. 해당 마켓플레이스의 플러그인 설치를 요청받습니다.
3. 원하지 않는 마켓플레이스나 플러그인은 건너뛸 수 있습니다.

/plugin 명령어

/plugin 명령어로 플러그인을 대화형으로 관리합니다:

• 마켓플레이스에서 사용 가능한 플러그인 탐색
• 플러그인 설치/제거
• 플러그인 활성화/비활성화
• 플러그인 세부 정보 보기 (제공하는 명령, 에이전트, 훅)
• 마켓플레이스 추가/제거

환경변수 레퍼런스

Claude Code는 동작을 제어하는 다양한 환경변수를 지원합니다. 환경변수는 settings.json의 env 키로도 설정할 수 있습니다.

API 및 인증

모델 설정

Vertex AI 지역 설정

동작 제어

업데이트 및 원격 측정

프록시 및 네트워크

MCP 설정

프롬프트 캐싱

기타

내장 도구 목록

Claude Code는 다음 내장 도구를 사용합니다:

Bash 도구 동작

Bash 도구는 다음 지속성 동작으로 셸 명령을 실행합니다:

• 작업 디렉토리는 유지됩니다: Claude가 작업 디렉토리를 변경(cd /path/to/dir)하면, 이후 Bash 명령들은 해당 디렉토리에서 실행됩니다. 각 명령 후 프로젝트 디렉토리로 재설정하려면 CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1을 사용하세요.

• 환경변수는 유지되지 않습니다: 한 Bash 명령에서 설정한 환경변수(export MY_VAR=value)는 이후 Bash 명령에서 사용할 수 없습니다. 각 Bash 명령은 새로운 셸 환경에서 실행됩니다.

환경변수를 Bash 명령에서 사용 가능하게 하는 세 가지 방법:

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

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

방법 2: CLAUDE_ENV_FILE 설정 (영속적 환경 설정)

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

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

conda activate myenv
# 또는: export MY_VAR=value

Claude Code는 각 Bash 명령 전에 이 파일을 소싱합니다.

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

.claude/settings.json:

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

엔터프라이즈 설정

Managed Settings 파일 위치

MDM/OS 수준 정책

• macOS: com.anthropic.claudecode 관리형 환경설정 도메인 (Jamf, Kandji 등 MDM 도구를 통해 설정 프로필로 배포)
• Windows: HKLM\SOFTWARE\Policies\ClaudeCode 레지스트리 키에 JSON을 포함한 Settings 값 (그룹 정책 또는 Intune으로 배포)

Managed 전용 설정

다음 설정들은 managed settings에서만 사용 가능합니다:

실전 예제

한국어 개발팀을 위한 프로젝트 설정

.claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm *)",
      "Bash(yarn *)",
      "Bash(pnpm *)",
      "Bash(python *)",
      "Bash(pytest *)",
      "Bash(ruff *)",
      "Bash(mypy *)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(git merge *)",
      "Bash(git rebase *)",
      "Bash(npm publish *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "WebFetch"
    ],
    "additionalDirectories": [
      "../shared-utils/"
    ]
  },
  "attribution": {
    "commit": "AI 보조 작성\n\nCo-Authored-By: Claude <noreply@anthropic.com>",
    "pr": ""
  },
  "env": {
    "NODE_ENV": "development",
    "PYTHONPATH": "./src"
  }
}

위험한 명령어 제한

{
  "permissions": {
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo rm *)",
      "Bash(chmod 777 *)",
      "Bash(curl * | bash)",
      "Bash(wget * | bash)",
      "Bash(> /etc/*)",
      "Bash(dd *)"
    ]
  }
}

개인 로컬 설정 예시

.claude/settings.local.json (git에 커밋되지 않음):

{
  "permissions": {
    "allow": [
      "Bash(open *)",
      "Bash(pbcopy *)"
    ]
  },
  "env": {
    "MY_LOCAL_API_KEY": "개인_테스트_키"
  }
}

트러블슈팅

설정이 적용되지 않을 때

1. /status 명령어로 현재 활성 설정 소스 확인
2. 설정 파일의 JSON 문법 확인:

   jq '.' ~/.claude/settings.json
   jq '.' .claude/settings.json
   

3. 스코프 우선순위 확인 — 더 높은 우선순위 스코프의 설정이 재정의하고 있을 수 있습니다.

권한 오류 발생 시

1. /permissions 명령어로 현재 권한 규칙 확인
2. deny 규칙이 allow 규칙보다 먼저 평가되는지 확인
3. 규칙 문법이 올바른지 확인 (예: Bash(git *), Read(./.env))

환경변수가 적용되지 않을 때

각 Bash 명령은 새로운 셸 환경에서 실행되므로, export로 설정한 변수는 다음 명령에서 사용할 수 없습니다. CLAUDE_ENV_FILE 또는 settings.json의 env 키를 사용하세요:

{
  "env": {
    "PYTHONPATH": "./src",
    "DATABASE_URL": "postgresql://localhost/mydb"
  }
}

다음 단계

• 훅 시스템 — 이벤트 기반 자동화를 추가하세요
• MCP 통합 — 외부 도구와 통합하세요

이 섹션이 도움이 되셨나요?