Oh! Heepie Day! 🐢

Claude Code Permission 글로벌 설정

5 min read

  • Claude Code Permission 글로벌 설정은 프로젝트별 permission 반복 요청과 settings.local.json git 노출 문제를 동시에 해결하는 방법
  • ~/.claude/settings.json에 허용 규칙을 등록하여 모든 프로젝트에 일괄 적용하는 설정
  • settings.local.json 생성 자체를 줄여 git status 오염을 근본적으로 방지하는 전략

해당 개념이 필요한 이유

  • Claude Code에서 tool/명령어 사용 시 매번 permission을 물어봄 → “Always allow” 선택 시 .claude/settings.local.json에 저장됨
  • settings.local.json이 git status에 뜨지만, .gitignore 수정은 팀 프로젝트에 영향을 줌
  • 프로젝트마다 동일한 허용 작업을 반복해야 하는 비효율

AS-IS

sequenceDiagram
    autonumber
    participant User as 사용자
    participant CC as Claude Code
    participant Local as .claude/settings.local.json
    participant Git as git status

    User->>CC: tool 사용 요청
    CC->>User: Permission 물어봄
    User->>CC: "Always allow" 선택
    CC->>Local: 허용 규칙 저장
    Local->>Git: Untracked/Modified로 노출
    Note over Git: .gitignore 수정 불가<br/>(팀 프로젝트 영향)
    Note over User: 다른 프로젝트에서<br/>동일 작업 반복

TO-BE

sequenceDiagram
    autonumber
    participant User as 사용자
    participant Global as ~/.claude/settings.json
    participant CC as Claude Code
    participant Git as git status

    Note over User,Global: 한 번만 설정
    User->>Global: 허용 규칙 등록
    User->>CC: tool 사용 요청
    CC->>Global: 글로벌 설정 확인
    Note over CC: 이미 허용됨 → 물어보지 않음
    CC->>User: 바로 실행
    Note over Git: settings.local.json<br/>생성되지 않음 → 깨끗

Settings 계층 구조

우선순위Scope위치적용 범위git 공유
1 (최고)Managed조직 배포전체 사용자Yes
2Command lineCLI 인자현재 세션N/A
3Local.claude/settings.local.json나, 이 프로젝트만No
4Project.claude/settings.json팀 전체Yes
5 (최저)User~/.claude/settings.json나, 모든 프로젝트No

핵심: **Local(3순위)**이 **User(5순위)**보다 우선하므로, 글로벌 설정 후에도 프로젝트별 오버라이드 가능

해결 방법

Step 1: 기존 settings.local.json에서 허용 규칙 수집

각 프로젝트의 .claude/settings.local.json을 확인하여 allow 목록 수집:

cat 프로젝트/.claude/settings.local.json

Step 2: ~/.claude/settings.json에 병합

{
  "permissions": {
    "allow": [
      "Bash(git commit *)",
      "Bash(git add *)",
      "Bash(git stash *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "WebSearch",
      "WebFetch"
    ],
    "deny": [
      "Bash(git push --force *)",
      "Bash(git reset --hard *)",
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

Step 3: (보험) 글로벌 gitignore 설정

settings.local.json이 생기더라도 git status에 안 뜨게:

# 글로벌 gitignore 경로 설정
git config --global core.excludesFile ~/.gitignore_global
 
# 패턴 추가
echo ".claude/settings.local.json" >> ~/.gitignore_global

Permission 규칙 문법

패턴의미
Bash모든 Bash 명령 허용
Bash(git *)git으로 시작하는 명령만 허용
Bash(npm run *)npm run으로 시작하는 명령만 허용
Read(./.env)특정 파일 읽기 허용/차단
WebFetch(domain:github.com)특정 도메인만 허용
WebSearch웹 검색 전체 허용
WebFetch웹 페이지 패치 전체 허용

특정 프로젝트에서 글로벌 deny 오버라이드

글로벌에서 .env 읽기를 deny했더라도, 특정 프로젝트에서 허용이 필요한 경우:

Local (.claude/settings.local.json)  ← 3순위, 우선
  ↑ 오버라이드
User (~/.claude/settings.json)       ← 5순위

글로벌 ~/.claude/settings.json:

{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./.env.*)"]
  }
}

특정 프로젝트 .claude/settings.local.json:

{
  "permissions": {
    "allow": ["Read(./.env)"]
  }
}

Local(3순위)이 User(5순위)보다 우선하므로, 해당 프로젝트에서만 .env 읽기가 허용된다.

deny가 차단할 경우 Claude Code가 사용자에게 알려주므로, 필요할 때 프로젝트 Local 설정으로 오버라이드하면 된다.

설정 확인

Claude Code 내에서 /status 명령으로 활성 설정 확인 가능:

Enterprise managed settings (remote)
Project settings (.claude/settings.json)
User settings (~/.claude/settings.json)

참고 문서

Graph View