# 권한 시스템

> Claude Code가 어떤 작업을 자동으로 수행하고 어떤 작업에 명시적 승인이 필요한지 제어하는 방법.

Claude Code는 로컬 머신에서 도구를 실행합니다 — 셸 커맨드 실행, 파일 편집, URL 가져오기. 권한 시스템은 Claude가 자동으로 수행하는 작업과 명시적 승인이 필요한 작업을 정밀하게 제어합니다.

## 권한이 제어하는 것

권한은 세 가지 작업 범주에 적용됩니다:

- **파일 작업** — `Read`, `Edit`, `Write` 도구를 통한 로컬 파일시스템 읽기, 편집, 쓰기
- **Bash 커맨드** — `Bash` 도구를 통한 셸 커맨드 실행(설치, 빌드, git 작업, 임의 스크립트 포함)
- **MCP 도구 호출** — 연결된 MCP 서버가 노출한 도구(데이터베이스 쿼리, API 호출, 브라우저 자동화 등)

## 권한 모드

권한 모드는 특정 허용/차단 규칙과 일치하는 도구 호출이 없을 때의 기본 동작을 결정합니다. 모드를 한 번 설정하면 세션 전체에 적용됩니다.

**`default` — 잠재적으로 위험한 작업에 확인 요청**
표준 모드. 셸 커맨드 실행, 파일 편집, 네트워크 요청 등 부작용이 있을 수 있는 작업에 확인을 요청합니다. 파일 읽기, 검색 등 읽기 전용 작업은 자동 승인됩니다. 일상적인 사용에 권장됩니다.

**`acceptEdits` — 파일 편집 자동 승인**
`Edit`, `Write` 도구가 프롬프트 없이 자동 승인됩니다. Bash 커맨드는 여전히 확인이 필요합니다. Claude가 파일을 자유롭게 편집하도록 하되 셸 커맨드는 검토하고 싶을 때 유용합니다.

**`plan` — 읽기 전용 계획 모드**
Claude가 파일을 읽고, 코드베이스를 검색하고, 변경 사항에 대해 논의할 수 있지만 쓰기 또는 bash 작업을 실행할 수 없습니다. 모든 변경 도구 호출이 차단됩니다. Claude가 문제를 분석하고 변경 사항을 승인하기 전에 계획을 만들도록 할 때 사용하세요.

**`bypassPermissions` — 모든 권한 검사 건너뛰기**
모든 권한 검사가 비활성화됩니다. 모든 도구 호출이 확인 프롬프트 없이 즉시 실행됩니다.
> ⚠️ 이 모드는 Claude가 수행할 작업을 미리 감사한 완전 스크립트화된 자동화 워크플로우 전용입니다. Claude가 예기치 않은 작업을 취할 수 있는 대화형 세션에서는 절대 사용하지 마세요.

## 권한 모드 설정 방법

**CLI 플래그:**
```bash
claude --permission-mode acceptEdits
claude --permission-mode bypassPermissions
claude --permission-mode plan
```

**`/permissions` 커맨드 (세션 중):**
```
/permissions
```
재시작 없이 모드를 변경합니다.

**settings.json:**
```json
{
  "defaultMode": "acceptEdits"
}
```
유효한 값: `"default"`, `"acceptEdits"`, `"bypassPermissions"`, `"plan"`, `"dontAsk"`

## 권한 규칙 (허용/차단 목록)

전역 모드 외에도, 활성 모드에 관계없이 특정 도구 호출을 항상 허용하거나 항상 차단하는 세분화된 규칙을 만들 수 있습니다.

규칙은 세 가지 구성 요소를 가집니다:

| 필드 | 설명 |
|------|------|
| `toolName` | 규칙이 적용되는 도구 이름 (예: `"Bash"`, `"Edit"`, `"mcp__myserver"`) |
| `ruleContent` | 도구 입력과 일치해야 하는 선택적 패턴 |
| `behavior` | `"allow"`, `"deny"`, 또는 `"ask"` |

규칙은 권한 모드보다 **먼저** 평가됩니다. 일치하는 규칙이 있으면 해당 동작이 즉시 적용됩니다.

### 예시: 특정 git 커맨드 항상 허용

```json
{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Read(*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  }
}
```

## Bash 권한 작동 방식

**패턴 매칭:**
- `git status` — 정확한 일치만
- `git *` — 모든 `git` 서브커맨드와 일치
- `npm run *` — 모든 `npm run` 스크립트와 일치
- `*` — 모든 bash 커맨드와 일치 (극도의 주의 필요)

**복합 커맨드:**
`&&`, `||`, `;`, 파이프(`|`)로 연결된 복합 커맨드는 각 서브커맨드가 독립적으로 검사됩니다. 하나의 서브커맨드라도 차단되면 전체 복합 커맨드가 차단됩니다.

**항상 차단/에스컬레이션되는 작업:**
- 프로젝트 디렉토리 외부 경로로의 출력 리다이렉션(`>`, `>>`)
- 워킹트리 외부로의 디렉토리 변경(`cd`)
- `sed -i` 편집 인플레이스 커맨드(파일 수정 추적을 위해 특별 처리)
- `.claude/` 또는 `.git/` 설정 디렉토리를 대상으로 하는 커맨드
- 셸 설정 파일 수정(`.bashrc`, `.zshrc` 등)

## MCP 도구 권한

MCP 도구는 내장 도구와 동일한 규칙 시스템을 따릅니다:

```json
{
  "permissions": {
    "deny": [
      "mcp__myserver"
    ],
    "allow": [
      "mcp__myserver__read_database"
    ]
  }
}
```

`mcp__servername`을 규칙으로 사용하면(특정 도구 이름 없이) 해당 서버의 모든 도구가 차단됩니다 — 모델이 보기 전에 도구 목록에서 필터링됩니다.

## 보안 권장 사항

- **`default` 모드**로 모든 대화형 세션을 시작하세요
- 익숙하지 않은 코드베이스를 탐색하거나 큰 변경 사항을 설계할 때는 **`plan` 모드**를 사용하세요
- Claude가 파일을 자유롭게 편집하도록 하되 셸 커맨드는 검토하려면 **`acceptEdits`**를 사용하세요
- 광범위한 모드 에스컬레이션 대신 **세분화된 허용 규칙**을 선호하세요. `Bash(git *)`를 허용하는 것이 `bypassPermissions`로 전환하는 것보다 안전합니다
- 친숙하지 않은 저장소를 클론할 때 `.claude/settings.json`을 검토하세요 — 권한 규칙이 미리 설정되어 있을 수 있습니다