Claude Code 설정

Claude Code는 귀하의 요구사항에 맞게 동작을 구성할 수 있는 다양한 설정을 제공합니다. 대화형 REPL을 사용할 때 /config 명령을 실행하여 Claude Code를 구성할 수 있습니다.

​

설정 파일

settings.json 파일은 계층적 설정을 통해 Claude Code를 구성하는 공식 메커니즘입니다:

• 사용자 설정은 ~/.claude/settings.json에 정의되며 모든 프로젝트에 적용됩니다.
• 프로젝트 설정은 프로젝트 디렉토리에 저장됩니다:
  • .claude/settings.json은 소스 제어에 체크인되어 팀과 공유되는 설정용입니다
  • .claude/settings.local.json은 체크인되지 않는 설정으로, 개인 선호도와 실험에 유용합니다. Claude Code는 .claude/settings.local.json이 생성될 때 git이 이를 무시하도록 구성합니다.
• Claude Code의 엔터프라이즈 배포의 경우, 엔터프라이즈 관리 정책 설정도 지원합니다. 이는 사용자 및 프로젝트 설정보다 우선합니다. 시스템 관리자는 다음 위치에 정책을 배포할 수 있습니다:
  • macOS: /Library/Application Support/ClaudeCode/managed-settings.json
  • Linux 및 WSL: /etc/claude-code/managed-settings.json
  • Windows: C:\ProgramData\ClaudeCode\managed-settings.json

{
  "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"
  }
}

​

사용 가능한 설정

settings.json은 여러 옵션을 지원합니다:

​

권한 설정

​

설정 우선순위

설정은 우선순위 순서로 적용됩니다 (높음에서 낮음):

1. 엔터프라이즈 관리 정책 (managed-settings.json)

   • IT/DevOps에서 배포
   • 재정의할 수 없음

2. 명령줄 인수

   • 특정 세션에 대한 임시 재정의

3. 로컬 프로젝트 설정 (.claude/settings.local.json)

   • 개인 프로젝트별 설정

4. 공유 프로젝트 설정 (.claude/settings.json)

   • 소스 제어의 팀 공유 프로젝트 설정

5. 사용자 설정 (~/.claude/settings.json)

   • 개인 전역 설정

이 계층 구조는 엔터프라이즈 보안 정책이 항상 적용되도록 하면서도 팀과 개인이 경험을 사용자 정의할 수 있도록 합니다.

​

구성 시스템의 주요 사항

• 메모리 파일 (CLAUDE.md): Claude가 시작 시 로드하는 지침과 컨텍스트를 포함합니다
• 설정 파일 (JSON): 권한, 환경 변수 및 도구 동작을 구성합니다
• 슬래시 명령: /command-name으로 세션 중에 호출할 수 있는 사용자 정의 명령
• MCP 서버: 추가 도구와 통합으로 Claude Code를 확장합니다
• 우선순위: 상위 수준 구성(엔터프라이즈)이 하위 수준 구성(사용자/프로젝트)을 재정의합니다
• 상속: 설정이 병합되며, 더 구체적인 설정이 더 광범위한 설정에 추가되거나 재정의됩니다

​

시스템 프롬프트 가용성

​

민감한 파일 제외

민감한 정보(예: API 키, 비밀, 환경 파일)가 포함된 파일에 Claude Code가 액세스하지 못하도록 하려면, .claude/settings.json 파일에서 permissions.deny 설정을 사용하세요:

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

이는 더 이상 사용되지 않는 ignorePatterns 구성을 대체합니다. 이러한 패턴과 일치하는 파일은 Claude Code에서 완전히 보이지 않게 되어 민감한 데이터의 우발적 노출을 방지합니다.

​

서브에이전트 구성

Claude Code는 사용자 및 프로젝트 수준에서 구성할 수 있는 사용자 정의 AI 서브에이전트를 지원합니다. 이러한 서브에이전트는 YAML 프론트매터가 있는 Markdown 파일로 저장됩니다:

• 사용자 서브에이전트: ~/.claude/agents/ - 모든 프로젝트에서 사용 가능
• 프로젝트 서브에이전트: .claude/agents/ - 프로젝트별이며 팀과 공유 가능

서브에이전트 파일은 사용자 정의 프롬프트와 도구 권한을 가진 전문 AI 어시스턴트를 정의합니다. 서브에이전트 생성 및 사용에 대한 자세한 내용은 서브에이전트 문서에서 확인하세요.

​

환경 변수

Claude Code는 동작을 제어하기 위해 다음 환경 변수를 지원합니다:

​

구성 옵션

구성을 관리하려면 다음 명령을 사용하세요:

• 설정 목록: claude config list
• 설정 보기: claude config get <key>
• 설정 변경: claude config set <key> <value>
• 설정에 추가 (목록용): claude config add <key> <value>
• 설정에서 제거 (목록용): claude config remove <key> <value>

기본적으로 config는 프로젝트 구성을 변경합니다. 전역 구성을 관리하려면 --global (또는 -g) 플래그를 사용하세요.

​

전역 구성

전역 구성을 설정하려면 claude config set -g <key> <value>를 사용하세요:

​

Claude가 사용할 수 있는 도구

Claude Code는 코드베이스를 이해하고 수정하는 데 도움이 되는 강력한 도구 세트에 액세스할 수 있습니다:

권한 규칙은 /allowed-tools를 사용하거나 권한 설정에서 구성할 수 있습니다.

​

훅으로 도구 확장

Claude Code 훅을 사용하여 도구가 실행되기 전후에 사용자 정의 명령을 실행할 수 있습니다.

예를 들어, Claude가 Python 파일을 수정한 후 Python 포매터를 자동으로 실행하거나, 특정 경로에 대한 Write 작업을 차단하여 프로덕션 구성 파일의 수정을 방지할 수 있습니다.

​

참고 항목

• 신원 및 액세스 관리 - Claude Code의 권한 시스템에 대해 알아보세요
• IAM 및 액세스 제어 - 엔터프라이즈 정책 관리
• 문제 해결 - 일반적인 구성 문제에 대한 해결책