Claude Code 설정

Claude Code는 사용자의 요구에 맞게 동작을 구성할 수 있는 다양한 설정을 제공합니다. 대화형 REPL을 사용할 때 /config 명령을 실행하여 Claude Code를 구성할 수 있습니다.

​

설정 파일

settings.json 파일은 계층적 설정을 통해 Claude Code를 구성하는 공식 메커니즘입니다:

• 사용자 설정은 ~/.claude/settings.json에 정의되며 모든 프로젝트에 적용됩니다.
• 프로젝트 설정은 프로젝트 디렉토리에 저장됩니다:
  • .claude/settings.json은 소스 제어에 체크인되어 팀과 공유되는 설정용
  • .claude/settings.local.json은 체크인되지 않는 설정으로, 개인 선호도와 실험에 유용합니다. Claude Code는 .claude/settings.local.json이 생성될 때 git이 이를 무시하도록 구성합니다.
• Claude Code의 엔터프라이즈 배포의 경우, 엔터프라이즈 관리 정책 설정도 지원합니다. 이는 사용자 및 프로젝트 설정보다 우선합니다. 시스템 관리자는 다음 위치에 정책을 배포할 수 있습니다:
  • macOS: /Library/Application Support/ClaudeCode/managed-settings.json
  • Linux 및 WSL: /etc/claude-code/managed-settings.json
  • Windows: C:\ProgramData\ClaudeCode\managed-settings.json

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  }
}

​

사용 가능한 설정

settings.json은 여러 옵션을 지원합니다:

​

권한 설정

​

설정 우선순위

설정은 우선순위 순서대로 적용됩니다 (높음에서 낮음):

1. 엔터프라이즈 관리 정책 (managed-settings.json)

   • IT/DevOps에서 배포
   • 재정의할 수 없음

2. 명령줄 인수

   • 특정 세션에 대한 임시 재정의

3. 로컬 프로젝트 설정 (.claude/settings.local.json)

   • 개인 프로젝트별 설정

4. 공유 프로젝트 설정 (.claude/settings.json)

   • 소스 제어의 팀 공유 프로젝트 설정

5. 사용자 설정 (~/.claude/settings.json)

   • 개인 전역 설정

이 계층 구조는 엔터프라이즈 보안 정책이 항상 적용되도록 보장하면서도 팀과 개인이 경험을 사용자 정의할 수 있도록 합니다.

​

구성 시스템의 주요 사항

• 메모리 파일 (CLAUDE.md): Claude가 시작 시 로드하는 지침과 컨텍스트를 포함
• 설정 파일 (JSON): 권한, 환경 변수 및 도구 동작을 구성
• 슬래시 명령: /command-name으로 세션 중에 호출할 수 있는 사용자 정의 명령
• MCP 서버: 추가 도구와 통합으로 Claude Code를 확장
• 우선순위: 상위 수준 구성 (엔터프라이즈)이 하위 수준 구성 (사용자/프로젝트)을 재정의
• 상속: 설정이 병합되며, 더 구체적인 설정이 더 광범위한 설정에 추가되거나 재정의

​

서브에이전트 구성

Claude Code는 사용자 및 프로젝트 수준에서 구성할 수 있는 사용자 정의 AI 서브에이전트를 지원합니다. 이러한 서브에이전트는 YAML 프론트매터가 있는 Markdown 파일로 저장됩니다:

• 사용자 서브에이전트: ~/.claude/agents/ - 모든 프로젝트에서 사용 가능
• 프로젝트 서브에이전트: .claude/agents/ - 프로젝트별로 특정하며 팀과 공유 가능

서브에이전트 파일은 사용자 정의 프롬프트와 도구 권한을 가진 전문 AI 어시스턴트를 정의합니다. 서브에이전트 생성 및 사용에 대한 자세한 내용은 서브에이전트 문서를 참조하세요.

​

환경 변수

Claude Code는 동작을 제어하기 위해 다음 환경 변수를 지원합니다:

​

구성 옵션

구성을 관리하려면 다음 명령을 사용하세요:

• 설정 목록: claude config list
• 설정 보기: claude config get <key>
• 설정 변경: claude config set <key> <value>
• 설정에 추가 (목록용): claude config add <key> <value>
• 설정에서 제거 (목록용): claude config remove <key> <value>

기본적으로 config는 프로젝트 구성을 변경합니다. 전역 구성을 관리하려면 --global (또는 -g) 플래그를 사용하세요.

​

전역 구성

전역 구성을 설정하려면 claude config set -g <key> <value>를 사용하세요:

​

Claude가 사용할 수 있는 도구

Claude Code는 코드베이스를 이해하고 수정하는 데 도움이 되는 강력한 도구 세트에 액세스할 수 있습니다:

권한 규칙은 /allowed-tools를 사용하거나 권한 설정에서 구성할 수 있습니다.

​

훅으로 도구 확장

Claude Code 훅을 사용하여 도구 실행 전후에 사용자 정의 명령을 실행할 수 있습니다.

예를 들어, Claude가 Python 파일을 수정한 후 자동으로 Python 포매터를 실행하거나, 특정 경로에 대한 Write 작업을 차단하여 프로덕션 구성 파일의 수정을 방지할 수 있습니다.

​

참고 항목

• 신원 및 액세스 관리 - Claude Code의 권한 시스템에 대해 알아보기
• IAM 및 액세스 제어 - 엔터프라이즈 정책 관리
• 문제 해결 - 일반적인 구성 문제에 대한 해결책