Configuration — Claude Code 설정 파일 구조

Claude Code의 기본 동작을 바꾸고 싶습니다. 특정 모델을 고정하거나, 권한 설정을 자동화하거나, Hook을 추가하는 방법은 설정 파일에 있습니다.

설정 파일 위치

~/.claude/settings.json           # 전역: 모든 프로젝트에 적용
.claude/settings.json             # 프로젝트: 팀과 공유 (Git에 포함)
.claude/settings.local.json       # 로컬: 개인 설정 (Git 제외)

우선순위: 로컬 > 프로젝트 > 전역 순으로 병합됩니다.

설정 병합(Configuration Merge): 세 파일의 설정이 우선순위 순으로 합쳐집니다. 같은 키는 높은 우선순위 파일이 덮어씁니다. 겹치지 않는 항목은 모두 유지됩니다.

/config 명령

claude> /config

설정 파일을 인터랙티브하게 열고 편집할 수 있습니다.

주요 설정 항목

모델 설정

{
  "model": "claude-opus-4-5",
  "smallModel": "claude-haiku-4-5"
}

기본 모델과 빠른 작업에 쓸 소형 모델을 지정합니다.

권한 설정

{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Write",
      "Bash(npm *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Bash(git push --force *)",
      "Bash(rm -rf *)"
    ]
  }
}

Hook 설정

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npm run lint --fix" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "echo '완료' | terminal-notifier" }
        ]
      }
    ]
  }
}

MCP 서버 설정

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

환경변수를 ${VAR_NAME} 형식으로 참조할 수 있습니다. 토큰을 파일에 직접 쓰지 않아도 됩니다.

컨텍스트 설정

{
  "autoCompact": true,
  "autoCompactThreshold": 0.8
}

컨텍스트 사용량이 80%를 넘으면 자동으로 압축합니다.

UI 설정

{
  "theme": "dark",
  "statusLine": true,
  "notifications": true
}

전체 설정 예시

{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": [
      "Read", "Edit", "Write", "Glob", "Grep",
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git add *)",
      "Bash(git commit *)"
    ],
    "deny": [
      "Bash(git push --force *)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "npm run lint" }]
      }
    ]
  },
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  },
  "autoCompact": true
}

Local Settings vs Project Settings

// .claude/settings.json (프로젝트 공유)
{
  "permissions": {
    "allow": ["Read", "Glob", "Grep"],
    "deny": ["Bash(git push *)"]
  },
  "hooks": {
    "PostToolUse": [...]
  }
}

// .claude/settings.local.json (개인, Git 제외)
{
  "model": "claude-opus-4-8",
  "permissions": {
    "allow": [
      "Read", "Edit", "Write",
      "Bash(npm *)", "Bash(git *)"
    ]
  }
}

프로젝트 설정에는 팀 공통 규칙을, 로컬 설정에는 개인 편의 설정을 분리합니다.

/status 명령

claude> /status

현재 적용된 설정, 연결된 MCP 서버, 활성 Hook, 사용 중인 모델 등 Claude Code의 전체 상태를 확인합니다.

Managed Settings

조직에서 Claude Code를 팀 단위로 관리할 때 관리자가 강제 적용하는 설정입니다. 개인 설정보다 높은 우선순위를 가지며, 사용자가 임의로 변경할 수 없습니다. 보안 정책, 모델 제한, 필수 Hook 등을 강제할 수 있습니다.