settings 파일 예제 (Example settings files)

기준일: 2026-10-23
공식 기준: Example settings files

개요

이 공식 페이지는 setting을 저장하는 위치마다 하나씩, 세 개의 settings.json 예제를 담고 있습니다.

• 개발자의 ~/.claude/settings.json
• 저장소에 커밋하는 팀의 .claude/settings.json
• 조직의 managed-settings.json

각 예제는 해당 독자에게 그럴듯한 파일이라 모양을 보고 원하는 부분을 복사할 수 있습니다. 어느 것도 권장 기준선은 아닙니다. 모든 값은 settings reference의 해당 키 항목에서 가져왔으며, 타입·기본값·설정 가능 위치는 그곳에 있습니다.

각 예제는 두 가지 형태로 제공됩니다. Copyable settings file은 그대로 저장할 파일이고, What each key does는 같은 파일에 키마다 주석을 단 것입니다. Claude Code는 settings 파일의 주석을 받지 않으므로 복사는 첫 번째에서 하세요.

핵심 개념

예제	위치	적용 범위	다루는 키
개인 설정	~/.claude/settings.json	내가 여는 모든 프로젝트	모델·effort, 터미널, 읽기 전용 허용 규칙, 업데이트 채널, 보관 기간
팀 공유 설정	저장소 최상위 .claude/settings.json	저장소를 clone한 모든 사람	권한, hook, 플러그인 마켓플레이스, sandbox, 계획 파일 위치
조직 managed settings	managed-settings.json, MDM, server-managed settings	배포가 닿는 모든 기기·계정	로그인 고정, 모델 제한, 권한·MCP allowlist, 마켓플레이스, sandbox, 최소 버전, 공지

상세

개인 설정

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

Copyable settings file — ~/.claude/settings.json으로 저장합니다. 주석 없는 유효한 JSON이므로 그대로 붙여 넣고 원하지 않는 키만 지우면 됩니다.

{
  "model": "claude-sonnet-5",
  "modelSettings": {
    "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
}

What each key does — 같은 파일에 키별 주석을 단 버전입니다. 읽기용이며 복사는 위에서 하세요.

{
  // Start every session on Sonnet 5
  "model": "claude-sonnet-5",
  // Run Sonnet 5 above its default high level; /effort saves a level per model, and --effort sets one for a single session
  "modelSettings": {
    "claude-sonnet-5": { "effortLevel": "xhigh" }
  },
  // Vim keybindings in the prompt
  "editorMode": "vim",
  // The colorblind-friendly light theme
  "theme": "light-daltonized",
  // A status line below the prompt: model name and context used
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"[\\(.model.display_name)] \\(.context_window.used_percentage // 0)% context\"'",
    "padding": 2
  },
  // Hide the tips that rotate under the spinner
  "spinnerTipsEnabled": false,
  // Ring the terminal bell for notifications, such as a finished task or a waiting permission prompt
  "preferredNotifChannel": "terminal_bell",
  // Let Claude Code run git diff and read your .zshrc without asking
  "permissions": {
    "allow": [
      "Bash(git diff *)",
      "Read(~/.zshrc)"
    ]
  },
  // Take updates from the stable channel
  "autoUpdatesChannel": "stable",
  // Delete session transcripts and other local session data older than 20 days
  "cleanupPeriodDays": 20
}

키	의미
model	모든 세션을 Sonnet 5로 시작
modelSettings	Sonnet 5를 기본 high보다 높은 xhigh effort로 실행. /effort는 모델별 수준을 저장하고 --effort는 한 세션에만 적용
editorMode	프롬프트에서 Vim 키 바인딩
theme	색각 이상 친화 light 테마
statusLine	프롬프트 아래 상태 표시줄: 모델 이름과 사용 중인 컨텍스트
spinnerTipsEnabled	spinner 아래 순환 팁 숨김
preferredNotifChannel	작업 완료나 권한 프롬프트 대기 같은 알림에 터미널 벨 사용
permissions.allow	git diff 실행과 .zshrc 읽기를 묻지 않고 허용
autoUpdatesChannel	stable 채널에서 업데이트
cleanupPeriodDays	20일보다 오래된 세션 transcript와 기타 로컬 세션 데이터 삭제

팀 공유 설정

저장소에 커밋해 clone하는 모든 사람이 같은 권한, hook, 플러그인 마켓플레이스를 갖게 하는 팀 설정입니다. 저장소 최상위의 .claude/settings.json에 둡니다. 커밋하기 전에 알아 둘 점:

• project thread 밖의 cloud 세션도 이 파일을 읽습니다. 저장소 하나로 시작하는 cloud 세션은 clone 안에서 시작하므로 커밋된 파일이 그곳에도 적용됩니다.
• Telemetry는 managed 또는 개인 설정에 둡니다. Claude Code는 저장소 settings 파일의 OpenTelemetry exporter 변수를 무시합니다(telemetry를 끄는 일부 값 제외). 조직용 managed settings나 각자의 ~/.claude/settings.json에 설정하세요.
• allow 규칙은 trust를 기다립니다. allow 규칙과 extraKnownMarketplaces 항목은 상위 폴더가 아니라 각자가 이 폴더 자체를 신뢰한 뒤에 적용됩니다. deny·ask 규칙은 신뢰 여부와 관계없이 모든 세션에 적용됩니다.
• hook은 저장소의 스크립트입니다. 이 파일의 hook은 .claude/hooks/block-rm.sh를 실행합니다. 작성 방법은 How a hook resolves를 보세요.
• 규칙은 쓰인 그대로의 명령·경로에 매치됩니다. Bash(git push *)는 git -C . push에 매치되지 않습니다. Read(./.env)만으로는 파일 tool과 cat .env처럼 파일 이름을 명시한 명령은 막지만 디렉터리에 대해 실행한 grep -r은 막지 못합니다. 이 파일의 sandbox 블록이 그 틈을 막는데, sandbox가 Read deny 경로를 추가해 sandbox 안의 모든 명령이 읽지 못하게 하기 때문입니다.

Copyable settings file — 저장소 최상위의 .claude/settings.json으로 저장하고 커밋합니다. 주석 없는 유효한 JSON입니다.

{
  "permissions": {
    "allow": [
      "Bash(npm run *)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "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"
}

What each key does

{
  "permissions": {
    // Run npm scripts without asking
    "allow": [
      "Bash(npm run *)"
    ],
    // Confirm before git push commands
    "ask": [
      "Bash(git push *)"
    ],
    // Deny reads of env files and the secrets folder by the file tools and file-reading commands
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  // Before every Bash command, run a script in the repo that can block it
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  },
  // Register the team's plugin marketplace on every clone
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    }
  },
  // Enable one plugin from that marketplace; a plugin from an external source such as a GitHub repository still needs each person to install it once
  "enabledPlugins": {
    "code-formatter@acme-tools": true
  },
  // Sandbox commands: writable build dir; npm and example.com pre-allowed
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": [
        "/tmp/build"
      ]
    },
    "network": {
      "allowedDomains": [
        "registry.npmjs.org",
        "*.example.com"
      ]
    }
  },
  // Keep plan files inside the repo
  "plansDirectory": "./plans"
}

키	의미
permissions.allow	npm script를 묻지 않고 실행
permissions.ask	git push 명령 전에 확인
permissions.deny	파일 tool과 파일 읽기 명령의 env 파일·secrets 폴더 읽기 거부
hooks.PreToolUse	모든 Bash 명령 전에 차단할 수 있는 저장소 스크립트 실행
extraKnownMarketplaces	모든 clone에 팀 플러그인 마켓플레이스 등록
enabledPlugins	그 마켓플레이스의 플러그인 하나 활성화. GitHub 저장소 같은 외부 출처의 플러그인은 각자 한 번 설치해야 함
sandbox	명령을 sandbox에서 실행. 빌드 디렉터리 쓰기 허용, npm·example.com 사전 허용
plansDirectory	계획 파일을 저장소 안에 보관

조직 managed settings

managed 키의 모양을 키마다 그럴듯한 값 하나로 보여 주는 managed-settings.json입니다. 권장 정책이 아니므로 요구 사항에 맞는 키를 골라 값을 직접 정하세요. 설정하는 키는 다음과 같습니다.

• forceLoginMethod, forceLoginOrgUUID: 로그인 방식과 조직 고정
• availableModels, enforceAvailableModels: 세션이 쓸 수 있는 모델 제한
• permissions.deny: 파일 읽기 두 개와 Claude가 쓴 형태의 curl 명령 거부. disableBypassPermissionsMode: bypass 권한 모드 제거
• allowManagedPermissionRulesOnly, allowManagedMcpServersOnly: managed 권한·MCP allowlist만 적용
• allowedMcpServers: MCP 서버를 URL로 고정
• strictKnownMarketplaces: 플러그인 마켓플레이스 하나만 허용
• sandbox: 고정된 네트워크 allowlist로 명령을 sandbox에서 실행하고 sandbox 밖 재시도 없음. failIfUnavailable 키는 sandbox를 실행할 수 없는 곳에서 Claude Code 시작을 막음
• requiredMinimumVersion: 최소 Claude Code 버전
• cleanupPeriodDays: 세션 transcript와 기타 로컬 데이터 보관을 7일로 단축
• companyAnnouncements: 시작 시 메시지 표시

관리자는 이 파일을 managed-settings.json으로, 또는 같은 JSON을 MDM이나 server-managed settings로 배포합니다. 배포된 파일 하나는 그것이 닿는 모든 기기·계정에 적용됩니다. 그룹마다 다른 값을 주려면 그 그룹에 다른 파일이나 profile을 배포해야 합니다. server-managed settings는 아직 그룹별 정책을 지원하지 않습니다.

Copyable settings file — managed-settings.json으로, 또는 같은 JSON을 MDM이나 claude.ai 콘솔로 배포합니다. 주석 없는 유효한 JSON이며, 예시 조직 UUID·서버 URL·마켓플레이스를 자기 값으로 바꾸고 원하지 않는 키는 지우세요.

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

What each key does

{
  // Only claude.ai logins, and only in this organization
  "forceLoginMethod": "claudeai",
  "forceLoginOrgUUID": [
    "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  ],
  // Only Opus and Sonnet models; with enforceAvailableModels, the Default option obeys the list too
  "availableModels": [
    "opus",
    "sonnet"
  ],
  "enforceAvailableModels": true,
  "permissions": {
    // Deny curl commands and reads of the project's .env file and secrets folder on every machine
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./secrets/**)"
    ],
    // Remove the bypass-permissions mode from every session
    "disableBypassPermissionsMode": "disable"
  },
  // Ignore permission rules from user, project, and local settings
  "allowManagedPermissionRulesOnly": true,
  // Only the GitHub MCP server, matched by URL rather than by name, since a user can
  // name any server "github". User-added servers that don't match don't load, including
  // every stdio server when the list has only URL entries. The allowManagedMcpServersOnly
  // key below makes this managed list the only allowlist that applies
  "allowedMcpServers": [
    {
      "serverUrl": "https://api.githubcopilot.com/*"
    }
  ],
  "allowManagedMcpServersOnly": true,
  // Plugins can come only from this marketplace
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    }
  ],
  // Sandbox every command Claude runs, refuse to start if the sandbox can't be
  // set up, and never let a blocked command retry outside the sandbox; network
  // limited to npm and GitHub, and users can't add domains
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false,
    "network": {
      "allowedDomains": [
        "registry.npmjs.org",
        "github.com"
      ],
      "allowManagedDomainsOnly": true
    }
  },
  // Refuse to start on versions older than 2.1.150
  "requiredMinimumVersion": "2.1.150",
  // Delete session transcripts and other local session data after 7 days
  "cleanupPeriodDays": 7,
  // A message every user sees at startup
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.example.com"
  ]
}

주석의 핵심을 한국어로 옮기면 다음과 같습니다.

키	의미
forceLoginMethod, forceLoginOrgUUID	claude.ai 로그인만, 그리고 이 조직에서만
availableModels, enforceAvailableModels	Opus·Sonnet 모델만. enforceAvailableModels가 있으면 Default 옵션도 목록을 따름
permissions.deny	모든 기기에서 curl 명령과 프로젝트 .env·secrets 폴더 읽기 거부
permissions.disableBypassPermissionsMode	모든 세션에서 bypass-permissions 모드 제거
allowManagedPermissionRulesOnly	user·project·local settings의 권한 규칙 무시
allowedMcpServers	GitHub MCP 서버만, 이름이 아닌 URL로 매치(사용자가 아무 서버나 "github"로 이름 붙일 수 있으므로). 일치하지 않는 사용자 추가 서버는 로드되지 않으며, 목록에 URL 항목만 있으면 모든 stdio 서버도 로드되지 않음
allowManagedMcpServersOnly	이 managed 목록만 적용되는 allowlist로 만듦
strictKnownMarketplaces	이 마켓플레이스에서만 플러그인 허용
sandbox	Claude가 실행하는 모든 명령을 sandbox에서 실행, sandbox를 설정할 수 없으면 시작 거부, 차단된 명령의 sandbox 밖 재시도 금지. 네트워크는 npm·GitHub로 제한하고 사용자가 도메인 추가 불가
requiredMinimumVersion	2.1.150보다 오래된 버전에서 시작 거부
cleanupPeriodDays	7일 뒤 세션 transcript와 기타 로컬 세션 데이터 삭제
companyAnnouncements	모든 사용자가 시작 시 보는 메시지

체크리스트

• 주석이 없는 Copyable settings file 버전에서 복사했다(settings 파일은 주석을 받지 않음).
• 개인 설정은 ~/.claude/settings.json, 팀 설정은 저장소 최상위 .claude/settings.json에 두었다.
• 팀 설정의 allow 규칙·extraKnownMarketplaces는 각자 폴더를 신뢰한 뒤 적용된다는 점을 공유했다.
• OpenTelemetry exporter 변수는 저장소가 아닌 managed 또는 개인 설정에 두었다.
• Read deny만으로 grep -r을 막지 못하므로 sandbox 블록을 함께 검토했다.
• managed settings 예시의 조직 UUID·서버 URL·마켓플레이스를 자기 값으로 바꿨다.
• 그룹별로 다른 값이 필요하면 그룹마다 다른 파일·profile을 배포한다.

다음 단계

• Settings: settings 파일 위치와 우선순위
• Managed settings: 조직 정책 배포 방법
• Permissions: 권한 규칙 문법과 한계
• Sandboxing: sandbox 설정과 managed 강제
• settings reference: 모든 키의 타입·기본값·설정 위치

기준일

이 문서는 2026-10-23에 공식 Example settings files 페이지를 기준으로 작성했습니다. settings 예제 JSON은 원문 그대로 옮겼습니다.