클로드코드 07-permissions

1. Permissions

참고: Claude Code가 접근하고 수행할 수 있는 것을 세밀하게 제어하는 방법

1.1. Permission 시스템 개요

Claude Code는 도구 유형별로 승인 방식을 구분한다.

- 도구 유형: 예시: 승인 필요: "다시 묻지 않음" 동작
- 읽기 전용: 파일 읽기, Grep: 아니오: 해당 없음
- Bash 명령어: 셸 실행: 예: 프로젝트 디렉토리와 명령어별로 영구 저장
- 파일 수정: 편집/쓰기: 예: 세션 종료까지

1.2. Permission 모드

Shift+Tab으로 모드를 전환하거나 settings.json의 defaultMode로 설정한다.

- 모드: 설명
- default: 표준 동작: 각 도구 첫 사용 시 권한 요청
- acceptEdits: 파일 편집과 일반적인 파일시스템 명령어(mkdir, touch, mv, cp 등)를 자동 승인
- plan: 읽기 전용 도구만 사용해 탐색하고 계획 제안. 소스 파일은 편집하지 않음
- auto: 백그라운드 안전 검사로 도구 호출 자동 승인. 연구 프리뷰
- dontAsk: /permissions나 permissions.allow 규칙으로 사전 승인된 도구만 사용
- bypassPermissions: 모든 권한 프롬프트를 건너뜀. rm -rf /와 같은 루트/홈 디렉토리 삭제는 여전히 프롬프트

참고: bypassPermissions는 격리된 환경(컨테이너, VM)에서만 사용하라. 관리자는 permissions.disableBypassPermissionsMode로 이 모드를 차단할 수 있다.

1.3. Permission 규칙 문법

규칙 형식: Tool 또는 Tool(specifier)

1.3.1. 전체 도구 허용/거부

{
  "permissions": {
    "allow": ["Bash", "WebFetch"],
    "deny": ["Read"]
  }
}

1.3.2. 세부 제어

{
  "permissions": {
    "allow": [
      "Bash(npm run build)",
      "Bash(npm run *)",
      "Bash(git commit *)",
      "Read(./.env)",
      "WebFetch(domain:example.com)"
    ],
    "deny": [
      "Bash(git push *)"
    ]
  }
}

1.3.3. 와일드카드 패턴

- Bash(npm run *): npm run으로 시작하는 모든 명령어
- Bash(* --version): --version으로 끝나는 모든 명령어
- Bash(ls *): ls 다음에 공백이 오는 명령어만 (lsof는 제외)

참고: Bash(ls*)는 공백 제약이 없어 ls와 lsof 모두 매칭한다.

1.3.4. 복합 명령어

&&, ||, ;, |, & 등으로 연결된 명령어는 각 하위 명령어별로 개별 규칙이 적용된다.

git status && npm test

위 명령어를 "다시 묻지 않음"으로 승인하면 git status와 npm test에 대해 별도의 규칙이 저장된다.

1.3.5. 프로세스 래퍼

timeout, time, nice, nohup, stdbuf, xargs는 자동으로 제거되어 내부 명령어와 매칭된다.

timeout 30 npm test

Bash(npm test *) 규칙이 위 명령어도 매칭한다.

1.3.6. Read / Edit 규칙

gitignore 스타일 패턴을 사용한다.

- 패턴: 의미: 예시
- //path: 파일시스템 루트부터의 절대 경로: Read(//Users/alice/secrets/**)
- ~/path: 홈 디렉토리 기준: Read(~/Documents/*.pdf)
- /path: 프로젝트 루트 기준: Edit(/src/**/*.ts)
- path 또는 ./path: 현재 디렉토리 기준: Read(*.env)

참고: Windows에서는 경로가 POSIX 형식으로 정규화된다. C:\Users\alice는 /c/Users/alice가 된다.

1.4. Working directories

기본적으로 Claude는 실행한 디렉토리의 파일에 접근할 수 있다. 추가 디렉토리 접근 방법:

- 시작 시: --add-dir <path> CLI 인자
- 세션 중: /add-dir 명령어
- 영구 설정: settings.json의 additionalDirectories

1.5. Managed settings

조직 전체 설정을 중앙에서 제어할 수 있다. 사용자나 프로젝트 설정으로 재정의할 수 없다.

- 설정: 설명
- allowManagedPermissionRulesOnly: true면 사용자/프로젝트 설정의 allow/ask/deny 규칙을 무시하고 관리 설정의 규칙만 적용
- disableBypassPermissionsMode: bypassPermissions 모드 사용 금지
- disableAutoMode: auto 모드 사용 금지

1.6. 설정 우선순위

높은 우선순위 → 낮은 우선순위:

Managed settings
CLI 인자
Local project settings (.claude/settings.local.json)
Shared project settings (.claude/settings.json)
User settings (~/.claude/settings.json)

어떤 레벨에서든 deny 규칙이 있으면 다른 레벨의 allow 규칙으로 재정의할 수 없다.