Claude Code 설정

Claude Code는 사용자의 요구에 맞게 동작을 구성할 수 있는 다양한 설정을 제공합니다. 터미널에서 claude config를 실행하거나 대화형 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/policies.json에, Linux 및 WSL을 통한 Windows의 경우 /etc/claude-code/policies.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"
  }
}

​

설정 우선순위

설정은 다음 우선순위 순서로 적용되며, 나중 소스가 이전 소스를 재정의합니다:

• 사용자 설정
• 공유 프로젝트 설정
• 로컬 프로젝트 설정
• 명령줄 인수
• 기업 정책

​

구성 옵션

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 config set <key> <value>로 프로젝트 구성을 관리하세요 (-g 플래그 없이):

예시:

# npm test를 승인 없이 실행하도록 허용
claude config add allowedTools "Bash(npm test)"

# npm test와 모든 하위 명령어를 승인 없이 실행하도록 허용
claude config add allowedTools "Bash(npm test:*)"

# Claude가 node_modules를 무시하도록 지시
claude config add ignorePatterns node_modules
claude config add ignorePatterns "node_modules/**"

​

권한

/allowed-tools를 사용하여 Claude Code의 도구 권한을 관리할 수 있습니다. 이 UI는 모든 권한 규칙과 이들이 소스로 하는 settings.json 파일을 나열합니다.

• Allow 규칙은 Claude Code가 추가 수동 승인 없이 지정된 도구를 사용할 수 있게 합니다.
• Deny 규칙은 Claude Code가 지정된 도구를 사용하지 못하게 합니다. Deny 규칙은 allow 규칙보다 우선합니다.

권한 규칙은 Tool(optional-specifier) 형식을 사용합니다.

예를 들어, allow 규칙 목록에 WebFetch를 추가하면 사용자 승인 없이 웹 fetch 도구를 사용할 수 있습니다. Claude에서 사용 가능한 도구 목록을 참조하세요 (제공된 경우 괄호 안의 이름을 사용하세요).

일부 도구는 더 세밀한 권한 제어를 위해 선택적 지정자를 사용합니다. 예를 들어, WebFetch(domain:example.com)이 있는 allow 규칙은 example.com에 대한 fetch는 허용하지만 다른 URL은 허용하지 않습니다.

Bash 규칙은 Bash(npm run build)와 같은 정확한 일치이거나, Bash(npm run test:*)와 같이 :*로 끝나는 접두사 일치일 수 있습니다.

Read() 및 Edit() 규칙은 gitignore 사양을 따릅니다. 패턴은 .claude/settings.json이 포함된 디렉토리를 기준으로 해석됩니다. 절대 경로를 참조하려면 //를 사용하세요. 홈 디렉토리를 기준으로 하는 경로는 ~/를 사용하세요. 예: Read(//tmp/build_cache) 또는 Edit(~/.zshrc). Claude는 또한 Grep, Glob, LS와 같은 다른 파일 관련 도구에도 Read 및 Edit 규칙을 최선을 다해 적용합니다.

MCP 도구 이름은 mcp__server_name__tool_name 형식을 따릅니다. 여기서:

• server_name은 Claude Code에 구성된 MCP 서버의 이름입니다
• tool_name은 해당 서버에서 제공하는 특정 도구입니다

더 많은 예시:

​

자동 업데이터 권한 옵션

Claude Code가 전역 npm 접두사 디렉토리에 쓰기 권한이 충분하지 않음을 감지하면(자동 업데이트에 필요), 이 문서 페이지를 가리키는 경고가 표시됩니다. 자동 업데이터 문제에 대한 자세한 해결 방법은 문제 해결 가이드를 참조하세요.

​

권장: 새로운 사용자 쓰기 가능 npm 접두사 생성

# 먼저, 나중에 마이그레이션할 기존 전역 패키지 목록을 저장
npm list -g --depth=0 > ~/npm-global-packages.txt

# 전역 패키지용 디렉토리 생성
mkdir -p ~/.npm-global

# 새 디렉토리 경로를 사용하도록 npm 구성
npm config set prefix ~/.npm-global

# 참고: ~/.bashrc를 사용자의 셸에 맞게 ~/.zshrc, ~/.profile 또는 다른 적절한 파일로 교체
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

# 새 PATH 설정 적용
source ~/.bashrc

# 이제 새 위치에 Claude Code 재설치
npm install -g @anthropic-ai/claude-code

# 선택 사항: 이전 전역 패키지를 새 위치에 재설치
# ~/npm-global-packages.txt를 확인하고 유지하고 싶은 패키지 설치
# npm install -g package1 package2 package3...

이 옵션을 권장하는 이유:

• 시스템 디렉토리 권한 수정 방지
• 전역 npm 패키지를 위한 깔끔하고 전용 위치 생성
• 보안 모범 사례 준수

Claude Code가 활발히 개발 중이므로, 위의 권장 옵션을 사용하여 자동 업데이트를 설정하는 것을 권장합니다.

​

자동 업데이터 비활성화

권한을 수정하는 대신 자동 업데이터를 비활성화하려면 다음을 사용하세요:

claude config set -g autoUpdaterStatus disabled

​

터미널 설정 최적화

Claude Code는 터미널이 적절히 구성되었을 때 가장 잘 작동합니다. 최적의 경험을 위해 다음 지침을 따르세요.

지원되는 셸:

• Bash
• Zsh
• Fish

​

테마와 외관

Claude는 터미널의 테마를 제어할 수 없습니다. 이는 터미널 애플리케이션에서 처리됩니다. 온보딩 중이나 /config 명령어를 통해 언제든지 Claude Code의 테마를 터미널과 일치시킬 수 있습니다.

​

줄 바꿈

Claude Code에서 줄 바꿈을 입력하는 여러 옵션이 있습니다:

• 빠른 이스케이프: \ 입력 후 Enter를 눌러 새 줄 생성
• 키보드 단축키: 적절한 구성으로 Option+Enter (Meta+Enter) 사용

터미널에서 Option+Enter 설정하기:

Mac Terminal.app의 경우:

1. 설정 → 프로필 → 키보드 열기
2. “Option을 Meta 키로 사용” 체크

iTerm2 및 VSCode 터미널의 경우:

1. 설정 → 프로필 → 키 열기
2. 일반에서 왼쪽/오른쪽 Option 키를 “Esc+“로 설정

iTerm2 및 VSCode 사용자를 위한 팁: Claude Code 내에서 /terminal-setup을 실행하여 Shift+Enter를 더 직관적인 대안으로 자동 구성할 수 있습니다.

​

알림 설정

적절한 알림 구성으로 Claude가 작업을 완료할 때를 놓치지 마세요:

​

터미널 벨 알림

작업 완료 시 소리 알림 활성화:

claude config set --global preferredNotifChannel terminal_bell

macOS 사용자의 경우: 시스템 설정 → 알림 → [사용 중인 터미널 앱]에서 알림 권한을 활성화하는 것을 잊지 마세요.

​

iTerm 2 시스템 알림

작업 완료 시 iTerm 2 알림을 위해:

1. iTerm 2 환경설정 열기
2. 프로필 → 터미널로 이동
3. “벨 음소거” 및 “유휴 시 알림 보내기” 활성화
4. 원하는 알림 지연 시간 설정

이러한 알림은 iTerm 2에 특화되어 있으며 기본 macOS 터미널에서는 사용할 수 없습니다.

​

대용량 입력 처리

광범위한 코드나 긴 지시사항 작업 시:

• 직접 붙여넣기 피하기: Claude Code는 매우 긴 붙여넣기 내용을 처리하는 데 어려움을 겪을 수 있습니다
• 파일 기반 워크플로우 사용: 내용을 파일에 작성하고 Claude에게 읽도록 요청
• VS Code 제한사항 인지: VS Code 터미널은 특히 긴 붙여넣기를 잘라내는 경향이 있습니다

​

Vim 모드

Claude Code는 /vim 또는 /config를 통해 활성화할 수 있는 Vim 키바인딩의 일부를 지원합니다.

지원되는 기능은 다음과 같습니다:

• 모드 전환: Esc (NORMAL로), i/I, a/A, o/O (INSERT로)
• 탐색: h/j/k/l, w/e/b, 0/$/^, gg/G
• 편집: x, dw/de/db/dd/D, cw/ce/cb/cc/C, . (반복)

​

환경 변수

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