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

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

설정 파일의 계층 구조

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

우선순위범위파일 위치용도
1 (최고)관리자OS별 시스템 경로기업 전체 정책 (IT 관리자용)
2CLI 인자명령줄 실행 시일회성 세션 설정
3로컬 프로젝트.claude/settings.local.json개인 프로젝트 설정 (gitignore 대상)
4프로젝트.claude/settings.json팀 공유 설정 (Git 커밋 대상)
5 (최저)사용자~/.claude/settings.json개인 글로벌 설정

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

어디에 무엇을 넣을까?

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

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

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

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

.claude/settings.json
{
  "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에 커밋되지 않는 개인용 프로젝트 설정입니다. 팀 설정을 기반으로 자신만의 추가 규칙을 덮어쓸 때 유용해요.

관리자 설정 (기업용)

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

OS경로
macOS/Library/Application Support/ClaudeCode/managed-settings.json
Linux/WSL/etc/claude-code/managed-settings.json
WindowsC:\Program Files\ClaudeCode\managed-settings.json

관리자 설정에서만 쓸 수 있는 옵션이 몇 가지 있는데요. 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"
}

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

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 <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로 설정하면 터미널 애니메이션을 줄여줍니다. 접근성이 필요하거나 깔끔한 출력을 선호할 때 유용해요.

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
    }
  }
}
옵션설명
enabled샌드박스 활성화 여부
autoAllowBashIfSandboxed샌드박스 안에서 실행되는 Bash 명령은 자동 허용
excludedCommands샌드박스를 거치지 않는 명령어 (예: docker, git)
allowUnsandboxedCommands샌드박스를 벗어나는 명령어 실행 허용 여부
network.allowedDomainsBash 명령이 접근할 수 있는 도메인
network.allowLocalBinding로컬 포트 바인딩 허용 여부

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

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

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

~/.claude/settings.json
{
  "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 레벨 격리의 원리와 활용법을 확인해보세요.

This work is licensed under CC BY 4.0 CC BY

관련 포스트

클로드 코드 자동 메모리: AI가 스스로 배우고 기억하는 법

클로드 코드에는 두 가지 메모리 시스템이 있습니다. 개발자가 직접 작성하는 CLAUDE.md와 Claude가 스스로 학습하는 자동 메모리(auto memory)입니다. CLAUDE.md가 "이렇게 해"라는 명시적인 지시라면, 자동 메모리는 Claude가 작업하면서 "아, 이 프로젝트에서는 이렇게 하는구나"하고 스스로 메모하는 노트에 가깝습니다. | | CLAUDE.md | 자동 메모리 | | --- | --- | --- | | 작성 주체 | 개발자 | Claude | | 담는 내용 | 지시와 규칙 | 학습과 패턴 | | 적용 범위

클로드 코드 Tasks: 세션을 넘나드는 작업 관리

클로드 코드로 규모 있는 프로젝트를 진행하다 보면 한 세션에서 끝나지 않는 작업이 생기기 마련입니다. 인증 시스템을 추가하려면 DB 스키마부터 설계하고, API 엔드포인트를 만들고, 프론트엔드를 고치고, 테스트까지 작성해야 하죠. 문제는 이 과정에서 어디까지 했고 뭐가 남았는지 추적하기가 쉽지 않다는 겁니다. 🤔 예전에는 Claude Code가 내부적으로 Todo라는 간단한 체크리스트를 사용했는데요. 세션 메모리에만 존재해서 터미널을 닫거나 /clear를 하면 사라져 버렸습니다. 서브 에이전트도 메인 세션의 Todo를 볼 수 없었

Agent Skill 만들기: SKILL.md 작성 가이드

이전 글에서 Agent Skills가 무엇인지, 왜 필요한지 살펴보았습니다. 컨텍스트 파일이 "프로젝트 소개서"라면, Skills는 "업무 매뉴얼"이라고 했죠. 이번 글에서는 한 걸음 더 나아가 직접 Skill을 설계하고 SKILL.md로 작성하는 방법을 알아보겠습니다. 🛠️ 좋은 Skill의 조건 Skill을 만들기 전에 어떤 Skill이 잘 동작하는지 생각해 볼 필요가 있습니다. 가장 중요한 건 범위가 명확해야 한다는 점입니다. "웹 개발하기" 같은 광범위한 Skill보다는 "Next.js API 라우트 작성하기"처럼 구체적인

Agent Skills: AI를 위한 업무 매뉴얼

AI 코딩 에이전트를 사용하다 보면 같은 종류의 작업을 반복적으로 요청하게 될 때가 있습니다. 예를 들어, "이 프로젝트에서는 Jest 대신 Vitest를 사용해", "API 테스트를 작성할 때는 이런 패턴을 따라줘", "마이그레이션 스크립트를 작성할 때는 항상 롤백 코드도 함께 작성해" 같은 지시를 매번 반복하게 되죠. 🤔 AGENTS.md나 CLAUDE.md 같은 컨텍스트 파일로 프로젝트 전반에 대한 정보를 제공할 수 있지만, 특정 작업에 대한 세부 지침까지 모두 담기에는 한계가 있습니다. 컨텍스트 파일이 너무 길어지면 AI가