권한 규칙과 매칭

전역 권한 모드가 전체 동작을 결정한다면, 권한 규칙(Permission Rules) 은 특정 도구와 패턴에 대해 더 세밀한 제어를 제공합니다. “git 명령어는 항상 허용하되, rm 명령어는 항상 차단”과 같은 구체적인 정책을 표현할 수 있습니다.

규칙의 3요소

모든 권한 규칙은 세 가지 요소로 구성됩니다.

1. toolName (대상 도구)

어떤 도구에 규칙을 적용할지 지정합니다.

Bash          # Bash 도구 전체
Read          # Read 도구 전체
mcp__github   # GitHub MCP 서버 전체
mcp__github__create_issue  # 특정 MCP 도구

2. ruleContent (패턴 매칭)

도구 호출의 어떤 내용에 규칙을 적용할지 패턴으로 지정합니다. Bash의 경우 명령어 문자열, 파일 도구의 경우 경로 패턴입니다.

git *          # git으로 시작하는 모든 명령어
*.test.ts      # 테스트 파일 경로
/tmp/**        # /tmp 하위 모든 경로

3. behavior (동작)

규칙이 매칭될 때 어떻게 처리할지 결정합니다.

behavior	동작
`allow`	확인 없이 자동 승인
`deny`	실행 차단, 오류 반환
`ask`	사용자에게 확인 요청

규칙 출처와 범위

규칙은 다섯 가지 출처에서 올 수 있으며, 각 출처마다 적용 범위가 다릅니다.

출처	파일 위치	범위
userSettings	`~/.claude/settings.json`	모든 프로젝트에 적용
projectSettings	`.claude/settings.json`	해당 프로젝트의 모든 사용자
localSettings	`.claude/settings.local.json`	단일 사용자-프로젝트 조합
session	런타임 메모리	현재 세션에만 적용
CLI 인수	`--allow-tool`, `--disallow-tool`	단일 실행에만 적용

설정 파일 예시

// .claude/settings.json (프로젝트 전체)
{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm run *)",
      "Read(**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  }
}

// ~/.claude/settings.json (개인 전역)
{
  "permissions": {
    "allow": [
      "Bash(brew *)",
      "Bash(docker *)"
    ]
  }
}

우선순위: 세분화된 규칙이 전역 모드보다 우선

전역 권한 모드와 개별 규칙이 충돌할 때는 더 구체적인 규칙이 우선 합니다.

시나리오: 전역 모드 = Default (Bash는 확인 필요)
         규칙: allow Bash(git *)

→ git 명령어: 규칙에 의해 자동 승인 (전역 모드 무시)
→ npm install: 전역 모드에 따라 확인 요청

여러 규칙이 동일한 명령어에 매칭될 때는 가장 구체적인 규칙이 적용됩니다. deny Bash(rm -rf /) 규칙은 allow Bash(rm *) 규칙보다 더 구체적이므로 우선합니다.

MCP 도구 권한 규칙

MCP(Model Context Protocol) 서버와 도구에도 동일한 규칙 시스템을 적용할 수 있습니다.

서버 전체 차단

{
  "permissions": {
    "deny": [
      "mcp__filesystem"
    ]
  }
}

mcp__servername 형식으로 서버 전체를 차단합니다. 해당 서버의 모든 도구 호출이 거부됩니다.

개별 도구 제어

MCP 도구의 전체 식별자는 mcp__servername__toolname 형식입니다.

{
  "permissions": {
    "allow": [
      "mcp__github__list_repos",
      "mcp__github__get_file"
    ],
    "deny": [
      "mcp__github__delete_repo",
      "mcp__github__push_commits"
    ]
  }
}

패턴으로 그룹 제어

{
  "permissions": {
    "allow": [
      "mcp__github__list_*",
      "mcp__github__get_*"
    ],
    "deny": [
      "mcp__github__delete_*",
      "mcp__github__create_*"
    ]
  }
}

읽기 작업(list_*, get_*)은 허용하고 쓰기 작업은 차단하는 패턴입니다.

프로젝트 설정 파일 검토 권장

외부 저장소를 클론할 때 .claude/settings.json이 이미 존재할 수 있습니다. 이 파일에는 프로젝트 기여자가 사전에 설정한 권한 규칙이 있을 수 있습니다.

# 클론 직후 확인 권장
cat .claude/settings.json

확인해야 할 사항:

allow 목록에 과도하게 넓은 패턴이 없는지
deny 목록이 예상대로 구성되었는지
MCP 서버 접근 권한이 적절한지

규칙 작성 모범 사례

권한 규칙을 효과적으로 작성하려면 최소 권한 원칙을 따릅니다.

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(npm test)",
      "Bash(npm run lint)"
    ],
    "deny": [
      "Bash(git push --force *)",
      "Bash(git reset --hard *)",
      "Bash(rm -rf *)"
    ]
  }
}

명시적으로 필요한 것만 허용하고, 위험한 것은 명시적으로 차단합니다. 나머지는 전역 모드의 기본 동작(확인 요청)에 맡깁니다.