Claude Code 설정

​

구성 범위

​

사용 가능한 범위

​

각 범위를 사용할 때

• 조직 전체에서 적용해야 하는 보안 정책
• 재정의할 수 없는 규정 준수 요구 사항
• IT/DevOps에서 배포한 표준화된 구성

• 모든 곳에서 원하는 개인 설정 (테마, 편집기 설정)
• 모든 프로젝트에서 사용하는 도구 및 플러그인
• API 키 및 인증 (안전하게 저장됨)

• 팀 공유 설정 (권한, hooks, MCP servers)
• 전체 팀이 가져야 할 플러그인
• 협업자 간 도구 표준화

• 특정 프로젝트에 대한 개인 재정의
• 팀과 공유하기 전에 구성 테스트
• 다른 사용자에게는 작동하지 않을 머신 특정 설정

​

범위가 상호 작용하는 방식

1. Managed (최고): 아무것도 재정의할 수 없음
2. 명령줄 인수: 임시 세션 재정의
3. Local: 프로젝트 및 사용자 설정 재정의
4. Project: 사용자 설정 재정의
5. User (최저): 다른 것이 설정을 지정하지 않을 때 적용

​

범위를 사용하는 것

​

설정 파일

• 사용자 설정은 ~/.claude/settings.json에 정의되며 모든 프로젝트에 적용됩니다.
• 프로젝트 설정은 프로젝트 디렉토리에 저장됩니다:
  • 소스 제어에 체크인되고 팀과 공유되는 설정을 위한 .claude/settings.json
  • 체크인되지 않은 설정을 위한 .claude/settings.local.json으로, 개인 설정 및 실험에 유용합니다. Claude Code는 .claude/settings.local.json이 생성될 때 git을 구성하여 이를 무시하도록 합니다. 파일을 직접 생성하는 경우 gitignore에 수동으로 추가합니다. 이 파일은 저장소가 아닌 사용자의 파일이므로 allow 권한 규칙이 .claude/settings.json 허용 규칙이 요구하는 작업 공간 신뢰 단계 없이 적용됩니다. 저장소가 파일을 제공하는 경우 (예: 커밋하여) 작업 공간 신뢰가 여전히 적용됩니다.
• Managed 설정: 중앙 집중식 제어가 필요한 조직의 경우 Claude Code는 managed 설정을 위한 여러 전달 메커니즘을 지원합니다. 모두 동일한 JSON 형식을 사용하며 사용자 또는 프로젝트 설정으로 재정의할 수 없습니다:
  • 서버 관리 설정: Anthropic의 서버에서 claude.ai 관리 콘솔을 통해 또는 자체 호스팅 Claude apps gateway에서 원격으로 전달됩니다. 서버 관리 설정을 참조하세요.
  • MDM/OS 수준 정책: macOS 및 Windows의 기본 장치 관리를 통해 전달됩니다:
    • macOS: com.anthropic.claudecode managed preferences domain. plist의 최상위 키는 managed-settings.json을 반영하며, 중첩된 설정은 딕셔너리이고 배열은 plist 배열입니다. Jamf, Iru (Kandji) 또는 유사한 MDM 도구의 구성 프로필을 통해 배포합니다.
    • Windows: HKLM\SOFTWARE\Policies\ClaudeCode 레지스트리 키와 JSON을 포함하는 Settings 값 (REG_SZ 또는 REG_EXPAND_SZ) (그룹 정책 또는 Intune을 통해 배포)
    • Windows (사용자 수준): HKCU\SOFTWARE\Policies\ClaudeCode (최저 정책 우선순위, 관리자 수준 소스가 없을 때만 사용)
  • 파일 기반: 시스템 디렉토리에 배포된 managed-settings.json 및 managed-mcp.json:
    • macOS: /Library/Application Support/ClaudeCode/
    • Linux 및 WSL: /etc/claude-code/
    • Windows: C:\Program Files\ClaudeCode\
    레거시 Windows 경로 C:\ProgramData\ClaudeCode\managed-settings.json은 v2.1.75부터 더 이상 지원되지 않습니다. 해당 위치에 설정을 배포한 관리자는 파일을 C:\Program Files\ClaudeCode\managed-settings.json으로 마이그레이션해야 합니다.
    파일 기반 managed 설정은 managed-settings.json과 동일한 시스템 디렉토리에 managed-settings.d/ 드롭인 디렉토리도 지원합니다. 이를 통해 별도의 팀이 단일 파일 편집을 조정하지 않고 독립적인 정책 조각을 배포할 수 있습니다. systemd 규칙을 따르면 managed-settings.json이 먼저 기본으로 병합되고, 드롭인 디렉토리의 모든 *.json 파일이 알파벳순으로 정렬되어 위에 병합됩니다. 스칼라 값의 경우 나중 파일이 이전 파일을 재정의합니다. 배열은 연결되고 중복 제거됩니다. 객체는 깊게 병합됩니다. .로 시작하는 숨겨진 파일은 무시됩니다. 병합 순서를 제어하려면 숫자 접두사를 사용합니다 (예: 10-telemetry.json 및 20-security.json).
  managed 설정 및 Managed MCP 구성을 참조하세요. 이 저장소에는 Jamf, Iru (Kandji), Intune 및 그룹 정책에 대한 시작 배포 템플릿이 포함되어 있습니다. 이를 시작점으로 사용하고 필요에 맞게 조정합니다.
  Managed 배포는 strictKnownMarketplaces를 사용하여 플러그인 마켓플레이스 추가를 제한할 수도 있습니다. 자세한 내용은 Managed 마켓플레이스 제한을 참조하세요.
• 기타 구성은 ~/.claude.json에 저장됩니다. 이 파일에는 OAuth 세션, MCP server 구성 (사용자 및 local 범위), 프로젝트별 상태 (허용된 도구, 신뢰 설정) 및 다양한 캐시가 포함됩니다. 프로젝트 범위 MCP 서버는 .mcp.json에 별도로 저장됩니다.

{
  "$schema": "https://json.schemastore.org/claude-code-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"
  },
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
    "Reminder: Code reviews required for all PRs",
    "New security policy in effect"
  ]
}

​

편집이 적용되는 시기

• model: 세션 중에 전환하려면 /model을 사용합니다
• outputStyle: 시스템 프롬프트의 일부로, /clear 또는 재시작 시 다시 빌드됩니다

​

Managed 설정의 유효하지 않은 항목

• 대화형 세션은 시작 시 유효하지 않은 항목을 나열하는 대화를 표시합니다.
• -p를 사용한 헤드리스 실행은 stderr에 요약을 인쇄합니다.
• claude doctor는 각 유효하지 않은 항목을 소스 및 필드와 함께 나열합니다.

​

사용 가능한 설정

​

전역 구성 설정

​

Worktree 설정

​

권한 설정

​

권한 규칙 구문

​

Sandbox 설정

​

Sandbox 경로 접두사

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
      "deniedDomains": ["uploads.github.com"],
      "allowUnixSockets": [
        "/var/run/docker.sock"
      ],
      "allowLocalBinding": true
    }
  }
}

• sandbox.filesystem 설정 (위에 표시됨): OS 수준 샌드박스 경계에서 경로를 제어합니다. 이러한 제한은 Claude의 파일 도구뿐만 아니라 모든 하위 프로세스 명령 (예: kubectl, terraform, npm)에 적용됩니다.
• 권한 규칙: Edit 허용/거부 규칙을 사용하여 Claude의 파일 도구 액세스를 제어하고, Read 거부 규칙을 사용하여 읽기를 차단하고, WebFetch 허용/거부 규칙을 사용하여 네트워크 도메인을 제어합니다. 이러한 규칙의 경로도 샌드박스 구성에 병합됩니다.

​

Attribution 설정

• 커밋은 기본적으로 git trailers (예: Co-Authored-By)를 사용하며 사용자 정의하거나 비활성화할 수 있습니다
• Pull request 설명은 일반 텍스트입니다

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

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

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

​

파일 제안 설정

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

{"query": "src/comp"}

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

#!/bin/bash
query=$(cat | jq -r '.query')
# your-repo-file-index를 자신의 파일 검색 명령으로 바꿉니다
your-repo-file-index --query "$query" | head -20

​

바닥글 링크 배지

{
  "footerLinksRegexes": [
    {
      "type": "regex",
      "pattern": "\\b(?<key>PROJ-\\d+)\\b",
      "url": "https://issues.example.com/browse/{key}",
      "label": "{key}"
    }
  ]
}

​

Hook 구성

• Managed hooks 및 SDK hooks가 로드됨
• Managed 설정 enabledPlugins에서 강제 활성화된 플러그인의 hooks가 로드됩니다. 이를 통해 관리자는 조직 마켓플레이스를 통해 검증된 hooks를 배포하면서 다른 모든 것을 차단할 수 있습니다. 신뢰는 전체 plugin@marketplace ID로 부여되므로 다른 마켓플레이스의 동일한 이름의 플러그인은 차단된 상태로 유지됩니다
• 사용자 hooks, 프로젝트 hooks 및 다른 모든 플러그인 hooks는 차단됩니다

{
  "allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"]
}

{
  "httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"]
}

​

정책 도우미로 managed 설정 계산

{
  "managedSettings": {
    "permissions": { "deny": ["Read(//etc/secrets/**)"] }
  },
  "claudeMd": "# Organization context\n...",
  "appendSystemPrompt": "Always cite the internal style guide."
}

​

설정 우선순위

1. Managed 설정 (서버 관리, MDM/OS 수준 정책 또는 managed 설정)
   • IT에서 서버 전달, MDM 구성 프로필, 레지스트리 정책 또는 managed 설정 파일을 통해 배포한 정책
   • 명령줄 인수를 포함한 다른 수준으로 재정의할 수 없음
   • Managed 계층 내에서 우선순위는: policyHelper 출력 (구성된 경우 유일한 managed 소스 사용) > 원격 (claude.ai 서버 관리 또는 Claude apps gateway 전달) > MDM/OS 수준 정책 > 파일 기반 (managed-settings.d/*.json + managed-settings.json) > HKCU 레지스트리 (Windows만). 하나의 managed 소스만 사용되며 소스는 병합되지 않습니다. 파일 기반 계층 내에서 드롭인 파일과 기본 파일이 함께 병합됩니다.
   • Agent SDK 또는 IDE 확장과 같은 embedding host는 SDK managedSettings 옵션을 통해 정책을 제공할 수 있습니다. 기본적으로 이는 관리자 배포 managed 계층이 있을 때 무시됩니다: 서버 관리 설정, MDM 또는 OS 수준 정책, 또는 managed 설정 파일. 사용자 쓰기 가능 HKCU 레지스트리 폴백은 관리자 배포 소스로 계산되지 않습니다. 관리자는 parentSettingsBehavior를 "merge"로 설정하여 옵트인할 수 있습니다. embedder의 값은 필터링되므로 managed 정책을 강화할 수 있지만 완화할 수 없습니다.
2. 명령줄 인수
   • 특정 세션에 대한 임시 재정의. --settings <file-or-json>을 통해 전달된 JSON은 파일 기반 설정과 동일한 규칙을 사용하여 병합됩니다: 여기에 설정된 키는 local, project 또는 user 설정의 동일한 키를 재정의하고, 키를 생략하면 낮은 계층 값이 유지됩니다
3. Local 프로젝트 설정 (.claude/settings.local.json)
   • 개인 프로젝트 특정 설정
4. 공유 프로젝트 설정 (.claude/settings.json)
   • 소스 제어의 팀 공유 프로젝트 설정
5. 사용자 설정 (~/.claude/settings.json)
   • 개인 전역 설정

​

활성 설정 확인

​

구성 시스템의 핵심 포인트

• 메모리 파일 (CLAUDE.md): Claude가 시작 시 로드하는 지침 및 컨텍스트를 포함합니다
• 설정 파일 (JSON): 권한, 환경 변수 및 도구 동작을 구성합니다
• Skills: /skill-name으로 호출하거나 Claude가 자동으로 로드할 수 있는 사용자 정의 프롬프트
• MCP servers: 추가 도구 및 통합으로 Claude Code를 확장합니다
• 우선순위: 높은 수준 구성 (Managed)이 낮은 수준 (User/Project)을 재정의합니다
• 상속: 설정은 범위 전체에서 병합됩니다. 스칼라 값은 높은 우선순위 범위에서 재정의되고, 배열은 연결됩니다 (예외: fallbackModel은 최고 우선순위 범위가 전체 체인을 제공합니다. v2.1.175부터 availableModels도 managed 또는 정책 값이 낮은 우선순위 항목을 완전히 대체합니다)

​

시스템 프롬프트

​

민감한 파일 제외

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

​

Subagent 구성

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

​

플러그인 구성

​

플러그인 설정

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

​

enabledPlugins

• 사용자 설정 (~/.claude/settings.json): 개인 플러그인 설정
• 프로젝트 설정 (.claude/settings.json): 팀과 공유되는 프로젝트 특정 플러그인
• Local 설정 (.claude/settings.local.json): 머신별 재정의, Claude Code가 생성할 때 gitignored됨
• Managed 설정 (managed-settings.json): 모든 범위에서 설치를 차단하고 마켓플레이스에서 플러그인을 숨기는 조직 전체 정책 재정의

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

​

pluginConfigs

{
  "pluginConfigs": {
    "deployer@acme-tools": {
      "options": {
        "api_endpoint": "https://api.example.com"
      }
    }
  }
}

​

extraKnownMarketplaces

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

{
  "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 사용, 개발 전용)
• hostPattern: 마켓플레이스 호스트와 일치하는 정규식 패턴 (hostPattern 사용)
• settings: 별도의 호스팅 저장소 없이 settings.json에 직접 선언된 인라인 마켓플레이스 (name 및 plugins 사용)

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "settings",
        "name": "team-tools",
        "plugins": [
          {
            "name": "code-formatter",
            "source": {
              "source": "github",
              "repo": "acme-corp/code-formatter"
            }
          }
        ]
      }
    }
  }
}

​

strictKnownMarketplaces

• macOS: /Library/Application Support/ClaudeCode/managed-settings.json
• Linux 및 WSL: /etc/claude-code/managed-settings.json
• Windows: C:\Program Files\ClaudeCode\managed-settings.json

• Managed 설정 (managed-settings.json)에서만 사용 가능
• 사용자 또는 프로젝트 설정으로 재정의할 수 없음 (최고 우선순위)
• 네트워크/파일 시스템 작업 전에 적용됨 (차단된 소스는 실행되지 않음)
• hostPattern 및 pathPattern을 제외한 소스 사양에 대해 정확한 일치를 사용합니다. hostPattern 및 pathPattern은 정규식 일치를 사용합니다

• undefined (기본값): 제한 없음 - 사용자는 모든 마켓플레이스를 추가할 수 있습니다
• 빈 배열 []: 완전 잠금 - 사용자는 새 마켓플레이스를 추가할 수 없습니다
• 소스 목록: 사용자는 정확히 일치하는 마켓플레이스만 추가할 수 있습니다

1. GitHub 저장소:

{ "source": "github", "repo": "acme-corp/approved-plugins" }
{ "source": "github", "repo": "acme-corp/security-tools", "ref": "v2.0" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }

2. Git 저장소:

{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }
{ "source": "git", "url": "https://bitbucket.org/acme-corp/plugins.git", "ref": "production" }
{ "source": "git", "url": "ssh://git@git.example.com/plugins.git", "ref": "v3.1", "path": "approved" }

3. URL 기반 마켓플레이스:

{ "source": "url", "url": "https://plugins.example.com/marketplace.json" }
{ "source": "url", "url": "https://cdn.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }

4. NPM 패키지:

{ "source": "npm", "package": "@acme-corp/claude-plugins" }
{ "source": "npm", "package": "@acme-corp/approved-marketplace" }

5. 파일 경로:

{ "source": "file", "path": "/usr/local/share/claude/acme-marketplace.json" }
{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }

6. 디렉토리 경로:

{ "source": "directory", "path": "/usr/local/share/claude/acme-plugins" }
{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }

7. 호스트 패턴 일치:

{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }
{ "source": "hostPattern", "hostPattern": "^gitlab\\.internal\\.example\\.com$" }

• github: 항상 github.com에 대해 일치
• git: URL에서 호스트 이름 추출 (HTTPS 및 SSH 형식 지원)
• url: URL에서 호스트 이름 추출
• npm, file, directory: 호스트 패턴 일치에 지원되지 않음

8. 경로 패턴 일치:

{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }
{ "source": "pathPattern", "pathPattern": ".*" }

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    },
    {
      "source": "npm",
      "package": "@acme-corp/compliance-plugins"
    }
  ]
}

{
  "strictKnownMarketplaces": []
}

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

• repo 또는 url이 정확히 일치해야 합니다
• ref 필드가 정확히 일치해야 합니다 (또는 둘 다 정의되지 않음)
• path 필드가 정확히 일치해야 합니다 (또는 둘 다 정의되지 않음)

// 이들은 다른 소스입니다:
{ "source": "github", "repo": "acme-corp/plugins" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main" }

// 이것도 다릅니다:
{ "source": "github", "repo": "acme-corp/plugins", "path": "marketplace" }
{ "source": "github", "repo": "acme-corp/plugins" }

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ]
}

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

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ],
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme-corp/plugins" }
    }
  }
}

• 제한은 네트워크 요청 또는 파일 시스템 작업 전에 확인됩니다
• 차단되면 사용자는 소스가 managed 정책으로 차단되었음을 나타내는 명확한 오류 메시지를 봅니다
• 제한은 마켓플레이스 추가 및 플러그인 설치, 업데이트, 새로고침 및 자동 업데이트에 적용됩니다. 정책이 설정되기 전에 추가된 마켓플레이스는 해당 소스가 더 이상 허용 목록과 일치하지 않으면 플러그인을 설치하거나 업데이트하는 데 사용할 수 없습니다
• Managed 설정은 최고 우선순위를 가지며 재정의할 수 없습니다

​

strictPluginOnlyCustomization

{
  "strictPluginOnlyCustomization": ["skills", "hooks"]
}

​

플러그인 관리

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

​

환경 변수

​

Claude가 사용할 수 있는 도구

​

참고 항목

• 권한: 권한 시스템, 규칙 구문, 도구 특정 패턴 및 관리형 정책
• 인증: Claude Code에 대한 사용자 액세스 설정
• 구성 디버깅: 설정, 훅 또는 MCP 서버가 적용되지 않는 이유를 진단합니다
• 설치 및 로그인 문제 해결: 설치, 인증 및 플랫폼 문제