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
• 엔터프라이즈 배포는 사용자 구성 서버를 재정의하는 관리 MCP 서버도 구성할 수 있습니다. 엔터프라이즈 MCP 구성을 참조하세요:
  • macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
  • Linux 및 WSL: /etc/claude-code/managed-mcp.json
  • Windows: C:\ProgramData\ClaudeCode\managed-mcp.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"
  }
}

​

사용 가능한 설정

​

권한 설정

​

샌드박스 설정

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker"],
    "network": {
      "allowUnixSockets": [
        "/var/run/docker.sock"
      ],
      "allowLocalBinding": true
    }
  },
  "permissions": {
    "deny": [
      "Read(.envrc)",
      "Read(~/.aws/**)"
    ]
  }
}

• Read 거부 규칙은 샌드박스에서 파일 읽기를 차단합니다
• Edit 허용 규칙은 파일 쓰기를 허용합니다(기본값(예: 현재 작업 디렉토리) 외에도)
• Edit 거부 규칙은 허용된 경로 내의 쓰기를 차단합니다

• WebFetch 허용 규칙은 네트워크 도메인을 허용합니다
• WebFetch 거부 규칙은 네트워크 도메인을 차단합니다

​

설정 우선순위

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를 확장합니다
• 우선순위: 상위 수준 구성(엔터프라이즈)이 하위 수준 구성(사용자/프로젝트)을 재정의합니다
• 상속: 설정이 병합되며, 더 구체적인 설정이 더 광범위한 설정에 추가되거나 재정의됩니다

​

시스템 프롬프트 가용성

​

민감한 파일 제외

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

​

서브에이전트 구성

• 사용자 서브에이전트: ~/.claude/agents/ - 모든 프로젝트에서 사용 가능
• 프로젝트 서브에이전트: .claude/agents/ - 프로젝트에 특정하며 팀과 공유할 수 있습니다

​

플러그인 구성

​

플러그인 설정

{
  "enabledPlugins": {
    "formatter@company-tools": true,
    "deployer@company-tools": true,
    "analyzer@security-plugins": false
  },
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": "github",
      "repo": "company/claude-plugins"
    }
  }
}

​

enabledPlugins

• 사용자 설정 (~/.claude/settings.json): 개인 플러그인 선호도
• 프로젝트 설정 (.claude/settings.json): 팀과 공유되는 프로젝트별 플러그인
• 로컬 설정 (.claude/settings.local.json): 머신별 재정의(커밋되지 않음)

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

​

extraKnownMarketplaces

1. 팀 구성원은 폴더를 신뢰할 때 마켓플레이스를 설치하라는 메시지를 받습니다
2. 팀 구성원은 그 마켓플레이스에서 플러그인을 설치하라는 메시지를 받습니다
3. 사용자는 원하지 않는 마켓플레이스 또는 플러그인을 건너뛸 수 있습니다(사용자 설정에 저장됨)
4. 설치는 신뢰 경계를 존중하고 명시적 동의가 필요합니다

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

• github: GitHub 저장소(repo 사용)
• git: 모든 git URL(url 사용)
• directory: 로컬 파일 시스템 경로(path 사용, 개발 전용)

​

플러그인 관리

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

​

환경 변수

​

Claude가 사용할 수 있는 도구

​

훅으로 도구 확장

​

참고 항목

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