예제 설정 파일

예제 설정 파일 (Example settings files)

개발자·팀·조직 각각을 위한 현실적인 settings.json 예시입니다. 원하는 키만 골라 값을 바꿔 복사해서 쓰면 됩니다. 각 예시는 해당 독자에게 그럴듯한 파일이며 권장 기준값은 아닙니다. 모든 값은 설정 레퍼런스의 해당 키 항목(타입·기본값·설정 위치)에서 왔습니다. 설정 파일은 주석을 허용하지 않으므로, 복사할 때는 첫 탭(주석 없는 JSON)을 사용하세요.

출처: 공식문서

본문

개인 설정 (~/.claude/settings.json)

한 개발자의 개인 설정입니다. 모델과 노력 수준을 고르고, 터미널을 조정하며, 읽기 전용 명령 하나와 파일 읽기 하나를 미리 승인합니다. 안 적은 키는 기본값을 유지합니다. ~/.claude/settings.json에 두면 열어 보는 모든 프로젝트에 적용됩니다.

{
  "model": "claude-sonnet-5",
  "effortLevel": "xhigh",
  "editorMode": "vim",
  "theme": "light-daltonized",
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'",
    "padding": 2
  },
  "spinnerTipsEnabled": false,
  "preferredNotifChannel": "terminal_bell",
  "permissions": {
    "allow": [
      "Bash(git diff *)",
      "Read(~/.zshrc)"
    ]
  },
  "autoUpdatesChannel": "stable",
  "cleanupPeriodDays": 20
}

각 키가 하는 일: model(세션마다 Sonnet 5로 시작), effortLevel(모델에 저장된 수준이 없을 때 기본 high보다 깊게 추론), editorMode(vim 키바인딩), theme(색각 친화형 라이트 테마 light-daltonized), statusLine(프롬프트 아래 상태줄: 모델명·컨텍스트 사용량), spinnerTipsEnabled(스피너 아래 팁 숨김), preferredNotifChannel(완료·권한 대기 등 알림을 터미널 벨로), permissions.allow(git diff와 .zshrc 읽기를 묻지 않고 실행), autoUpdatesChannel(stable 채널 업데이트), cleanupPeriodDays(20일 지난 세션 기록 삭제).

팀 공유 설정 (.claude/settings.json)

저장소에 커밋해 클론하는 모두가 같은 권한·훅·텔레메트리·플러그인 마켓플레이스를 받게 하는 팀 설정입니다. 저장소 최상위 .claude/settings.json에 둡니다. 커밋 전 알아둘 점 — 클라우드 세션도 이것을 읽습니다. allow 규칙과 extraKnownMarketplaces는 각 사람이 이 폴더 자체를 신뢰한 뒤 적용되지만, deny·ask 규칙은 신뢰 여부와 무관하게 모든 세션에 적용됩니다. Bash(git push *)는 git -C . push를 매치하지 않으며, Read(./.env) 단독은 cat .env 같은 파일 도구·명령은 막지만 디렉토리 전체 grep -r는 막지 못합니다 — 아래 sandbox 블록이 그 간극을 메웁니다.

{
  "permissions": {
    "allow": [
      "Bash(npm run *)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317"
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  },
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "code-formatter@acme-tools": true
  },
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": [
        "/tmp/build"
      ]
    },
    "network": {
      "allowedDomains": [
        "registry.npmjs.org",
        "*.example.com"
      ]
    }
  },
  "plansDirectory": "./plans"
}

각 키가 하는 일: permissions.allow(npm 스크립트를 묻지 않고 실행), ask(git push 전 확인), deny(파일 도구·파일 읽기 명령의 env·secrets 읽기 차단), env(gRPC로 팀 콜렉터에 OpenTelemetry 메트릭 전송 — 엔드포인트 교체), hooks(모든 Bash 명령 전 저장소의 block-rm.sh 실행), extraKnownMarketplaces(클론마다 팀 마켓플레이스 등록), enabledPlugins(해당 마켓플레이스의 플러그인 활성), sandbox(쓰기 가능 빌드 디렉토리 + npm·example.com 사전 허용, 나머지 호스트는 질문), plansDirectory(플랜 파일을 저장소 안에 보관).

조직 관리 설정 (managed-settings.json)

관리 키들의 형태를 보여주는 managed-settings.json 예시입니다. 권장 정책이 아니며 요구사항에 맞는 키만 골라 값을 정하세요. 관리자가 이 JSON을 managed-settings.json으로, 또는 MDM·server-managed settings를 통해 배포합니다. 배포된 파일 하나는 도달하는 모든 머신·계정에 적용됩니다 (server-managed settings는 아직 그룹별 정책을 지원하지 않습니다).

{
  "forceLoginMethod": "claudeai",
  "forceLoginOrgUUID": [
    "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  ],
  "availableModels": [
    "opus",
    "sonnet"
  ],
  "enforceAvailableModels": true,
  "permissions": {
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./secrets/**)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "allowManagedPermissionRulesOnly": true,
  "allowedMcpServers": [
    {
      "serverUrl": "https://api.githubcopilot.com/*"
    }
  ],
  "allowManagedMcpServersOnly": true,
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    }
  ],
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false,
    "network": {
      "allowedDomains": [
        "registry.npmjs.org",
        "github.com"
      ],
      "allowManagedDomainsOnly": true
    }
  },
  "requiredMinimumVersion": "2.1.150",
  "cleanupPeriodDays": 7,
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.example.com"
  ]
}

이 예시가 설정하는 키: forceLoginMethod·forceLoginOrgUUID(로그인 방식·조직 고정), availableModels·enforceAvailableModels(세션 사용 모델을 Opus·Sonnet으로 제한, Default 옵션도 목록을 따름), permissions.deny + disableBypassPermissionsMode(curl과 env·secrets 읽기 거부, bypass 권한 모드 제거), allowManagedPermissionRulesOnly(유저·프로젝트·로컬의 권한 규칙 무시), allowedMcpServers·allowManagedMcpServersOnly(URL로 MCP 서버 고정, 관리 목록만 적용), strictKnownMarketplaces(플러그인은 한 마켓플레이스에서만), sandbox(모든 명령 샌드박스 + 샌드박스 불가 시 기동 거부 + 차단 명령의 비샌드박스 재시도 금지 + npm·GitHub 네트워크만), requiredMinimumVersion(2.1.150 미만 기동 거부), cleanupPeriodDays(세션 기록 7일 후 삭제), companyAnnouncements(시작 시 공지 메시지).

더 알아보기