읽는 시간: 10분 | 난이도: 중급자

Claude Code는 세밀한 권한 시스템을 지원하여 에이전트가 할 수 있는 것과 없는 것을 정확하게 지정할 수 있습니다. 권한 설정은 버전 관리에 체크인하여 조직의 모든 개발자에게 배포하거나, 개별 개발자가 커스터마이징할 수 있습니다.

권한 시스템 개요

Claude Code는 강력함과 안전성을 균형 있게 유지하기 위해 계층적 권한 시스템을 사용합니다.

권한 관리 UI

/permissions 명령으로 Claude Code의 도구 권한을 보고 관리할 수 있습니다. 이 UI는 모든 권한 규칙과 해당 규칙이 어느 settings.json 파일에서 왔는지 목록으로 보여줍니다.

• Allow 규칙: 수동 승인 없이 지정된 도구를 사용할 수 있습니다.
• Ask 규칙: Claude Code가 해당 도구를 사용하려 할 때마다 확인을 요청합니다.
• Deny 규칙: Claude Code가 해당 도구를 사용하는 것을 방지합니다.

규칙 평가 순서는 deny -> ask -> allow 입니다. 첫 번째로 매칭되는 규칙이 적용되므로, deny 규칙은 항상 우선합니다.

권한 모드

Claude Code는 도구 승인 방식을 제어하는 여러 권한 모드를 지원합니다. 설정 파일에서 defaultMode로 설정합니다.

경고: bypassPermissions 모드는 모든 권한 검사를 비활성화합니다. 컨테이너나 VM처럼 Claude Code가 피해를 줄 수 없는 격리된 환경에서만 사용하세요. 관리자는 관리형 설정에서 disableBypassPermissionsMode를 "disable"로 설정하여 이 모드를 방지할 수 있습니다.

권한 규칙 문법

권한 규칙은 도구 또는 도구(지정자) 형식을 따릅니다.

도구의 모든 사용 매칭

괄호 없이 도구 이름만 사용하면 해당 도구의 모든 사용을 매칭합니다.

Bash(*)는 Bash와 동일하며 모든 Bash 명령과 매칭됩니다.

세밀한 제어를 위한 지정자

괄호 안에 지정자를 추가하면 특정 도구 사용만 매칭할 수 있습니다.

와일드카드 패턴

Bash 규칙은 *를 사용한 글로브 패턴을 지원합니다. 와일드카드는 명령의 어느 위치에도 사용할 수 있습니다. 다음 설정은 npm과 git commit 명령은 허용하면서 git push를 차단합니다.

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)",
      "Bash(git * main)",
      "Bash(* --version)",
      "Bash(* --help *)"
    ],
    "deny": [
      "Bash(git push *)"
    ]
  }
}

중요: * 앞의 공백이 중요합니다. Bash(ls *)는 ls -la와 매칭되지만 lsof와는 매칭되지 않습니다. 반면 Bash(ls*)는 둘 다 매칭됩니다.

도구별 권한 규칙

Bash 규칙

Bash 권한 규칙은 *를 사용한 와일드카드 매칭을 지원합니다. 와일드카드는 명령의 시작, 중간, 끝 어디에도 사용할 수 있습니다.

• Bash(npm run build): 정확히 npm run build 명령 매칭
• Bash(npm run test *): npm run test로 시작하는 명령 매칭
• Bash(npm *): npm 으로 시작하는 명령 매칭
• Bash(* install): install로 끝나는 명령 매칭
• Bash(git * main): git checkout main, git merge main 같은 명령 매칭

팁: Claude Code는 && 같은 셸 연산자를 인식합니다. Bash(safe-cmd *)와 같은 접두사 매칭 규칙은 safe-cmd && other-cmd 실행 권한을 주지 않습니다.

경고: 명령 인수를 제한하려는 Bash 권한 패턴은 취약할 수 있습니다. 예를 들어 Bash(curl http://github.com/ *)는 GitHub URL로 curl을 제한하려 하지만, 다음 변형은 매칭하지 못합니다:

• URL 앞에 옵션: curl -X GET http://github.com/...
• 다른 프로토콜: curl https://github.com/...
• 리다이렉트: curl -L http://bit.ly/xyz (github로 리다이렉트)
• 변수: URL=http://github.com && curl $URL

더 신뢰할 수 있는 URL 필터링을 위해서는 WebFetch 권한 규칙과 PreToolUse 훅을 함께 사용하는 것을 권장합니다.

Read와 Edit 규칙

Edit 규칙은 파일을 편집하는 모든 빌트인 도구에 적용됩니다. Claude는 Grep, Glob 같은 파일을 읽는 모든 빌트인 도구에 Read 규칙을 최선을 다해 적용합니다.

Read와 Edit 규칙은 모두 gitignore 명세를 따르며 네 가지 패턴 유형이 있습니다.

주의: /Users/alice/file 같은 패턴은 절대 경로가 아닙니다. 설정 파일 기준 상대 경로입니다. 절대 경로에는 //Users/alice/file을 사용하세요.

예시:

• Edit(/docs/**): <project>/docs/의 편집 (NOT /docs/)
• Read(~/.zshrc): 홈 디렉토리의 .zshrc 읽기
• Edit(//tmp/scratch.txt): 절대 경로 /tmp/scratch.txt 편집
• Read(src/**): <현재 디렉토리>/src/에서 읽기

참고: gitignore 패턴에서 *는 단일 디렉토리의 파일과 매칭되고, **는 디렉토리를 재귀적으로 매칭합니다. 모든 파일 접근을 허용하려면 괄호 없이 도구 이름만 사용하세요: Read, Edit, Write.

WebFetch 규칙

• WebFetch(domain:example.com): example.com으로의 가져오기 요청 매칭

MCP 규칙

• mcp__puppeteer: puppeteer 서버가 제공하는 모든 도구 매칭
• mcp__puppeteer__*: puppeteer 서버의 모든 도구와 매칭하는 와일드카드 문법
• mcp__puppeteer__puppeteer_navigate: puppeteer 서버의 puppeteer_navigate 도구 매칭

Task (서브에이전트) 규칙

Task(에이전트이름) 규칙으로 Claude가 사용할 수 있는 서브에이전트를 제어할 수 있습니다.

• Task(Explore): Explore 서브에이전트 매칭
• Task(Plan): Plan 서브에이전트 매칭
• Task(my-custom-agent): my-custom-agent라는 커스텀 서브에이전트 매칭

설정의 deny 배열이나 --disallowedTools CLI 플래그로 특정 에이전트를 비활성화할 수 있습니다. Explore 에이전트를 비활성화하는 예시입니다.

{
  "permissions": {
    "deny": ["Task(Explore)"]
  }
}

훅을 통한 권한 확장

Claude Code 훅은 런타임에 권한 평가를 수행하기 위한 커스텀 셸 명령을 등록하는 방법을 제공합니다. Claude Code가 도구 호출을 할 때, PreToolUse 훅이 권한 시스템보다 먼저 실행되며 훅 출력이 도구 호출을 승인하거나 거부할 수 있습니다.

작업 디렉토리

기본적으로 Claude는 실행된 디렉토리의 파일에 접근할 수 있습니다. 다음 방법으로 이 접근 범위를 확장할 수 있습니다.

• 시작 시: --add-dir <경로> CLI 인수 사용
• 세션 중: /add-dir 명령 사용
• 영구 설정: 설정 파일의 additionalDirectories에 추가

추가 디렉토리의 파일은 원래 작업 디렉토리와 동일한 권한 규칙을 따릅니다. 프롬프트 없이 읽을 수 있게 되고, 파일 편집 권한은 현재 권한 모드를 따릅니다.

권한과 샌드박싱의 상호작용

권한과 샌드박싱은 상호 보완적인 보안 레이어입니다.

• 권한: Claude Code가 사용할 수 있는 도구와 접근 가능한 파일이나 도메인을 제어합니다. Bash, Read, Edit, WebFetch, MCP 등 모든 도구에 적용됩니다.
• 샌드박싱: Bash 도구의 파일시스템 및 네트워크 접근을 제한하는 OS 수준의 강제 메커니즘입니다. Bash 명령과 그 자식 프로세스에만 적용됩니다.

심층 방어를 위해 두 가지를 함께 사용하세요.

• 권한 deny 규칙으로 Claude가 제한된 리소스에 접근 시도 자체를 차단
• 샌드박스 제한으로 프롬프트 인젝션이 Claude의 의사 결정을 우회하더라도 정의된 경계 외부의 리소스에 접근 방지

관리형 설정

중앙 집중식 제어가 필요한 조직의 경우, 관리자가 시스템 디렉토리에 managed-settings.json 파일을 배포할 수 있습니다. 이 정책 파일은 일반 설정 파일과 동일한 형식을 따르며 사용자 또는 프로젝트 설정으로 재정의할 수 없습니다.

관리형 설정 파일 위치:

• macOS: /Library/Application Support/ClaudeCode/managed-settings.json
• Linux 및 WSL: /etc/claude-code/managed-settings.json
• Windows: C:\Program Files\ClaudeCode\managed-settings.json

참고: 이 경로들은 시스템 전체 경로(~/Library/... 같은 사용자 홈 디렉토리가 아닙니다)로 관리자 권한이 필요합니다. IT 관리자가 배포하도록 설계되었습니다.

관리형 전용 설정

일부 설정은 관리형 설정에서만 효과가 있습니다.

설정 우선순위

권한 규칙은 다른 Claude Code 설정과 동일한 설정 우선순위를 따릅니다. 관리형 설정이 가장 높은 우선순위를 가지며, 그 다음은 명령줄 인수, 로컬 프로젝트, 공유 프로젝트, 사용자 설정 순입니다.

사용자 설정에서 허용된 권한이 프로젝트 설정에서 거부된 경우, 프로젝트 설정이 우선하여 권한이 차단됩니다.

설정 예시

개발 환경용 기본 설정

{
  "permissions": {
    "allow": [
      "Bash(npm *)",
      "Bash(yarn *)",
      "Bash(git status *)",
      "Bash(git log *)",
      "Bash(git diff *)",
      "Read(src/**)",
      "Edit(src/**)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Read(~/.ssh/*)",
      "Read(.env*)"
    ]
  }
}

CI/CD 환경용 설정

{
  "defaultMode": "bypassPermissions",
  "permissions": {
    "allow": [
      "Bash(npm run test *)",
      "Bash(npm run build *)",
      "Bash(git *)",
      "Read(**)",
      "Edit(**)"
    ],
    "deny": [
      "Bash(curl *)",
      "Bash(wget *)",
      "WebFetch"
    ]
  }
}

읽기 전용 코드 리뷰 모드

{
  "defaultMode": "plan",
  "permissions": {
    "allow": [
      "Read(**)",
      "Bash(grep *)",
      "Bash(find *)"
    ],
    "deny": [
      "Edit",
      "Write",
      "Bash"
    ]
  }
}

다음 단계

• 설정(Settings) 가이드 - 권한 설정 테이블을 포함한 전체 설정 레퍼런스
• 훅(Hooks) 가이드 - 워크플로우 자동화 및 권한 평가 확장
• 헤드리스 모드 - 프로그래밍 방식으로 실행 시 권한 설정
• 보안 가이드 - 보안 안전장치 및 모범 사례