클로드 코드 설정 가이드: settings.json 파헤치기

클로드 코드를 설치하고 기본 사용법을 익혔다면 이제 나에게 맞는 환경을 만들어볼 차례입니다. 클로드 코드는 settings.json이라는 설정 파일을 통해 권한 관리부터 모델 선택, 환경 변수, 샌드박스, 커밋 메시지 스타일까지 폭넓게 제어할 수 있는데요. 이 글에서는 설정 체계를 처음 접하는 분도 쉽게 따라올 수 있도록 하나씩 뜯어보겠습니다.

설정 파일의 계층 구조

클로드 코드의 설정은 한 군데 모여 있지 않고 여러 레벨로 나뉘어 있습니다. 각 레벨마다 역할이 다르기 때문에 상황에 맞는 위치에 설정을 놓아야 해요.

기본 규칙은 “높은 우선순위가 낮은 우선순위를 덮어쓴다”입니다. 사용자 설정에서 Bash(rm -rf *) 명령을 허용했더라도 프로젝트 설정에서 이를 차단하면 차단이 적용되죠.

어디에 무엇을 넣을까?

실무에서는 주로 세 가지 파일을 쓰게 됩니다.

~/.claude/settings.json (사용자 설정)은 모든 프로젝트에 공통으로 적용되는 개인 설정입니다. 선호하는 모델이나 응답 언어, 자주 쓰는 명령어 허용 규칙 같은 것을 넣어두면 돼요.

{
  "model": "claude-sonnet-4-5-20250929",
  "language": "korean",
  "permissions": {
    "allow": ["Bash(* --version)", "Bash(* --help *)"]
  }
}

.claude/settings.json (프로젝트 설정)은 팀원 모두가 공유하는 설정입니다. Git에 커밋하면 팀 전체에 동일한 규칙을 적용할 수 있어요. 프로젝트에서 사용하는 빌드 명령어나 테스트 명령어를 허용하고 민감한 파일 접근을 차단하는 용도로 활용합니다.

{
  "permissions": {
    "allow": [
      "Bash(npm run build)",
      "Bash(npm run test *)",
      "Bash(npm run lint)"
    ],
    "deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"]
  }
}

.claude/settings.local.json (로컬 프로젝트 설정)은 .gitignore에 포함되어 Git에 커밋되지 않는 개인용 프로젝트 설정입니다. 팀 설정을 기반으로 자신만의 추가 규칙을 덮어쓸 때 유용해요.

/config로 간편하게 설정하기

JSON 파일을 직접 편집하지 않아도 /config 슬래시 커맨드로 대화형 UI에서 설정을 바꿀 수 있습니다. 클로드 코드 세션에서 /config를 입력하면 세 개의 탭(Status, Config, Usage)이 나타나는데요. Config 탭에서 Space 키로 토글하고 Enter로 저장하면 끝이에요.

  ╭───────────────────────────────────────────────╮
  │ ⌕ Search settings...                          │
  ╰───────────────────────────────────────────────╯

    Auto-compact                          true
    Show tips                             true
    Thinking mode                         true
    Rewind code (checkpoints)             true
    Verbose output                        true
    Terminal progress bar                 true
    Show turn duration                    true
    Theme                                 Light mode
    Model                                 Default (recommended)
    ...

  Space to change · Enter to save · / to search

여기서 바꾼 값은 사용자 설정 파일(~/.claude/settings.json)에 저장됩니다. 결국 JSON을 직접 편집하는 것과 같은 결과인데 UI로 하면 오타 걱정이 없다는 장점이 있죠.

/config에서 조절할 수 있는 주요 설정을 정리하면 다음과 같습니다.

이 중 model, autoUpdatesChannel, showTurnDuration 같은 옵션은 아래에서 다루는 JSON 설정과 동일한 항목이에요. JSON 파일에 익숙하지 않다면 /config로 시작하고 세밀한 제어가 필요할 때 JSON을 직접 편집하는 방식을 추천합니다.

관리자 설정 (기업용)

기업 환경에서는 IT 관리자가 시스템 레벨의 설정 파일로 조직 전체 정책을 강제할 수 있습니다. 이 설정은 사용자나 프로젝트 설정으로는 절대 덮어쓸 수 없어요.

관리자 설정에서만 쓸 수 있는 옵션이 몇 가지 있는데요. disableBypassPermissionsMode를 "disable"로 설정하면 위험한 권한 우회 모드를 완전히 막을 수 있고, companyAnnouncements로 모든 사용자에게 공지 메시지를 띄울 수도 있습니다.

권한(Permission) 설정

클로드 코드를 쓰다 보면 가장 자주 마주치는 것이 권한 요청 팝업입니다. permissions 설정을 잘 잡아두면 이런 번거로움을 줄일 수 있어요.

{
  "permissions": {
    "allow": ["자동 허용할 도구와 패턴"],
    "deny": ["차단할 도구와 패턴"],
    "defaultMode": "acceptEdits"
  }
}

권한 규칙은 도구(패턴) 형식으로 작성합니다. Bash(npm run *), Read(./.env), WebFetch(domain:example.com), mcp__github__create_issue처럼 도구마다 패턴 문법이 다르고, 평가 순서는 deny → allow라서 차단 규칙이 항상 우선합니다.

도구별 패턴 작성법, 권한 모드, 샌드박스 연동, 관리자 설정 같은 내용은 클로드 코드 권한 설정에서 자세히 다루고 있습니다.

주요 설정 옵션

권한 외에도 클로드 코드의 동작을 조절하는 설정 옵션이 여러 가지 있습니다.

model — 기본 모델 대신 다른 모델을 지정할 수 있습니다. 비용이나 속도를 고려해서 Sonnet을 기본으로 쓰다가 복잡한 작업에만 Opus를 사용하는 식으로 운영할 수 있죠. CLI에서 claude --model claude-opus-4-20250514처럼 일회성으로 모델을 바꿀 수도 있습니다.

{
  "model": "claude-sonnet-4-5-20250929"
}

세션 중에 모델을 바꾸고 싶다면 /model 슬래시 커맨드가 편합니다. 실행하면 사용 가능한 모델 목록이 나타나고 번호로 선택할 수 있어요. 같은 화면에서 좌우 방향키로 effort 수준도 조절할 수 있어서 모델과 effort를 한번에 세팅하기 좋습니다.

설정 파일에는 opus, sonnet, haiku 같은 alias를 쓸 수도 있고 claude-opus-4-6처럼 정확한 모델 ID를 지정할 수도 있는데요. 사용 가능한 모델 이름 전체 목록은 공식 모델 설정 문서에서 확인할 수 있습니다.

availableModels — 사용자가 선택할 수 있는 모델을 제한합니다. 팀에서 비용을 관리하거나 특정 모델만 허용하고 싶을 때 유용해요.

{
  "availableModels": ["sonnet", "haiku"]
}

language — 클로드 코드의 응답 언어를 지정합니다. "korean", "japanese", "english" 등을 설정할 수 있어서 한국어 프로젝트에서 한국어로 응답받고 싶을 때 유용해요.

{
  "language": "korean"
}

outputStyle — Claude의 응답 스타일을 조절합니다. "Explanatory"로 설정하면 코드만 달랑 주는 대신 구현 선택의 이유를 함께 설명해줘요.

{
  "outputStyle": "Explanatory"
}

env — 셸 설정 파일(.bashrc, .zshrc)을 수정하지 않고도 클로드 코드 세션에서만 적용되는 환경 변수를 설정할 수 있습니다. 타임아웃 값이나 토큰 제한을 조정할 때 쓰면 됩니다. 여러 세션이 같은 태스크 리스트를 공유하도록 CLAUDE_CODE_TASK_LIST_ID를 설정하는 것도 가능합니다.

{
  "env": {
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "16384",
    "BASH_DEFAULT_TIMEOUT_MS": "30000",
    "MCP_TIMEOUT": "10000"
  }
}

effortLevel — Claude가 응답에 얼마나 많은 토큰을 쓸지 조절합니다. 단순히 사고(thinking) 분량만 달라지는 게 아니라 도구 호출 횟수, 응답 길이, 설명의 상세함까지 전부 영향을 받아요.

{
  "effortLevel": "medium"
}

"low", "medium", "high", "max" 네 단계가 있고 Opus 4.6과 Sonnet 4.6에서 지원됩니다. "low"는 간단한 작업이나 속도가 중요한 경우에 적합하고 "high"나 "max"는 복잡한 추론이 필요한 작업에 유용합니다. Opus 4.6은 기본값이 "medium"이고 Sonnet 4.6은 "high"입니다. 세션 중에 /model 슬래시 커맨드에서 좌우 방향키로 조절할 수도 있고 환경 변수 CLAUDE_CODE_EFFORT_LEVEL로도 설정할 수 있어요.

alwaysThinkingEnabled — Claude가 항상 확장 사고(Extended Thinking) 모드를 사용하도록 합니다. 복잡한 문제를 풀 때 Claude가 내부적으로 더 깊이 생각하게 되어 답변 품질이 좋아질 수 있어요.

{
  "alwaysThinkingEnabled": true
}

autoUpdatesChannel — "stable" 또는 "latest" 중 선택할 수 있습니다. 안정성을 중시한다면 "stable"을, 최신 기능을 빠르게 써보고 싶다면 "latest"를 선택하면 돼요.

{
  "autoUpdatesChannel": "stable"
}

cleanupPeriodDays — 클로드 코드와 나눈 대화 기록의 보관 기간을 설정합니다. 기본값은 30일이고 0으로 설정하면 자동 삭제를 끌 수 있습니다.

{
  "cleanupPeriodDays": 30
}

커밋 메시지와 PR 서명

클로드 코드가 Git 커밋이나 PR을 생성할 때 자동으로 붙이는 서명을 커스터마이징할 수 있습니다.

{
  "attribution": {
    "commit": "Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>",
    "pr": "Generated with Claude Code"
  }
}

commit은 커밋 메시지 끝에 추가되는 텍스트이고 pr은 PR 본문에 추가되는 텍스트입니다. 팀 컨벤션에 맞게 수정하거나 빈 문자열("")로 설정하면 서명을 뺄 수도 있어요.

UI 커스터마이징

클로드 코드의 인터페이스도 입맛에 맞게 바꿀 수 있습니다.

showTurnDuration — 응답이 끝나면 “Cooked for 1m 6s” 같은 소요 시간을 표시합니다. 기본값은 true예요.

spinnerVerbs — Claude가 작업 중일 때 표시되는 동사를 커스터마이징합니다. 기본 동사에 추가하거나 완전히 교체할 수 있어요.

{
  "spinnerVerbs": {
    "mode": "append",
    "verbs": ["Pondering", "Brewing"]
  }
}

mode를 "append"로 설정하면 기본 동사에 추가되고, "replace"로 설정하면 완전히 교체됩니다.

prefersReducedMotion — true로 설정하면 터미널 애니메이션을 줄여줍니다. 접근성이 필요하거나 깔끔한 출력을 선호할 때 유용해요.

statusLine — 화면 하단에 커스텀 상태 바를 표시합니다. 셸 스크립트로 컨텍스트 사용량, 비용, Git 브랜치 같은 정보를 실시간으로 보여줄 수 있어요. 자세한 설정 방법과 예제는 클로드 코드 Statusline에서 다루고 있습니다.

MCP 서버 설정

프로젝트의 .mcp.json에 정의된 MCP 서버를 자동으로 승인하려면 다음 옵션을 쓸 수 있습니다.

{
  "enableAllProjectMcpServers": true
}

모든 서버를 한꺼번에 승인하는 대신 특정 서버만 골라서 승인하거나 차단할 수도 있어요.

{
  "enabledMcpjsonServers": ["memory", "github"],
  "disabledMcpjsonServers": ["filesystem"]
}

팀 프로젝트에서 .mcp.json에 여러 MCP 서버를 정의해두고 .claude/settings.json에서 자동 승인을 켜두면 팀원마다 매번 승인할 필요가 없어집니다.

샌드박스 설정

샌드박스는 클로드 코드가 실행하는 명령어를 격리된 환경에서 돌려 시스템을 보호하는 기능입니다. macOS에서는 Seatbelt, Linux에서는 bubblewrap이라는 OS 레벨 격리 기술을 씁니다.

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker", "git"],
    "allowUnsandboxedCommands": true,
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"],
      "allowLocalBinding": true
    }
  }
}

autoAllowBashIfSandboxed를 true로 설정하면 샌드박스 내에서 실행되는 Bash 명령은 별도의 권한 확인 없이 자동 허용됩니다. 샌드박스가 시스템을 보호해주니 권한 확인 팝업 피로를 줄이면서도 안전하게 작업할 수 있는 방법이에요.

실전 예시: 개인 개발자를 위한 설정

지금까지 다룬 옵션을 한데 모으면 이런 설정이 됩니다.

{
  "model": "claude-sonnet-4-5-20250929",
  "language": "korean",
  "outputStyle": "Explanatory",
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(bun run *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git status)",
      "Bash(* --version)",
      "Bash(* --help *)"
    ],
    "deny": ["Bash(rm -rf *)", "Bash(sudo *)"],
    "defaultMode": "acceptEdits"
  },
  "attribution": {
    "commit": "Co-Authored-By: Claude <noreply@anthropic.com>"
  }
}

팀 프로젝트나 CI/CD 환경별 추천 설정은 클로드 코드 권한 설정에서 확인할 수 있습니다.

Hooks와 함께 활용하기

클로드 코드 Hooks는 settings.json과 같이 쓰면 더 유용해집니다. 코드 수정 후 자동으로 포맷터를 실행하는 Hook을 설정해 볼까요?

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATHS\""
          }
        ]
      }
    ]
  }
}

PostToolUse 이벤트에 Write|Edit 매처를 걸어두면 Claude가 파일을 수정할 때마다 Prettier가 자동으로 실행됩니다. Hooks에 대해 더 알고 싶다면 클로드 코드 Hooks 글을 참고해보세요.

JSON Schema로 자동 완성 활용하기

settings.json에 $schema를 추가하면 VS Code 같은 편집기에서 자동 완성과 유효성 검사를 받을 수 있습니다.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-5-20250929",
  "permissions": {
    "allow": []
  }
}

설정 키를 일일이 외울 필요 없이 편집기가 사용 가능한 옵션을 제안해줘요. 오타로 인한 설정 오류도 바로 잡을 수 있어서 편합니다.

마치며

이 글에서 살펴본 것처럼 클로드 코드 설정의 뼈대는 설정 파일을 어디에 둘지 정하는 계층 구조, 무엇을 허용하고 막을지 다루는 권한 시스템, 그 외 동작 방식을 조절하는 옵션으로 이루어져 있습니다.

처음에는 사용자 설정(~/.claude/settings.json)에 기본 모델과 언어, 자주 쓰는 명령어 허용 규칙만 넣어두는 것으로 충분합니다. 팀 프로젝트에서 일관된 규칙이 필요해지면 프로젝트 설정(.claude/settings.json)을 추가하고 보안이 중요한 환경에서는 샌드박스와 deny 규칙을 강화하면 돼요.

CLAUDE.md가 Claude에게 프로젝트의 맥락을 알려주는 역할이라면 settings.json은 Claude가 프로젝트 안에서 할 수 있는 행동의 범위를 정하는 역할입니다. 이 둘을 잘 조합해두면 안전하면서도 편리한 AI 코딩 환경을 만들 수 있어요. 설정 파일의 샌드박스 옵션을 더 깊이 알고 싶다면 클로드 코드 샌드박스에서 OS 레벨 격리의 원리와 활용법을 확인해보세요.