Claude Code 권한 시스템 완전정리: 안전하게 AI와 협업하기

Claude Code 권한 시스템 완전정리: 안전하게 AI와 협업하기

Claude Code는 파일을 편집하고, 터미널 명령을 실행하고, Git 커밋까지 할 수 있는 강력한 도구입니다. 하지만 잘못된 명령 하나가 프로젝트를 망칠 수 있기 때문에, 권한 시스템을 제대로 이해하고 설정하는 것이 중요합니다. 이 글에서는 권한 모드, 도구별 규칙, settings.json 설정, 샌드박스까지 완전 정리합니다.

Claude Code 권한 시스템 완전정리

---

1. 권한 시스템이란?

Claude Code의 권한 시스템은 Claude가 어떤 도구를 어떤 조건에서 사용할 수 있는지 제어하는 메커니즘입니다.

왜 필요한가?

Claude Code는 다음과 같은 실제 시스템 변경을 수행할 수 있습니다.

도구	기능	위험
Edit	파일 수정	코드가 깨질 수 있음
Write	파일 생성/덮어쓰기	기존 파일 삭제 위험
Bash	터미널 명령 실행	rm -rf, git push --force 등
NotebookEdit	Jupyter 노트북 수정	노트북 데이터 손실

3가지 제어 수단

수단	위치	역할
권한 모드	세션 단위	실시간 승인/자동 수준 설정
권한 규칙	settings.json	도구별 allow/deny/ask 규칙
샌드박스	시스템 설정	파일시스템/네트워크 격리

권한 시스템이란?

---

2. 권한 모드 3가지

Claude Code는 3가지 권한 모드로 작동하며, Shift+Tab으로 실시간 전환할 수 있습니다.

Normal 모드 (기본)

항목	내용
파일 편집	매번 승인 요청
Bash 명령	매번 승인 요청
MCP 도구	매번 승인 요청
파일 읽기	자동 허용
웹 검색	자동 허용
대상	처음 사용하는 사람

모든 변경 작업에 승인이 필요하므로 가장 안전한 모드입니다. Claude가 파일을 수정하거나 명령을 실행하기 전에 항상 diff를 보여주고 확인을 요청합니다.

Auto-Accept 모드

항목	내용
파일 편집	자동 승인
Bash 명령	허용 목록만 자동, 나머지 승인
MCP 도구	허용 목록만 자동
파일 읽기	자동 허용
대상	Claude Code에 익숙해진 사용자

파일 편집은 자동 승인되지만, Bash 명령은 허용 목록에 없으면 여전히 승인을 요청합니다. npm test, git status 같은 안전한 명령은 자동, rm, git push 같은 위험한 명령은 확인합니다.

Plan 모드

항목	내용
파일 편집	불가
Bash 명령	불가
MCP 도구	불가
파일 읽기	자동 허용
대상	분석/설계 단계

읽기만 가능한 모드입니다. 코드를 분석하고 계획을 세우는 단계에서 사용합니다. 실수로 코드를 변경하는 것을 원천적으로 방지합니다.

모드 전환

Shift+Tab → Normal → Auto-Accept → Plan → Normal (순환)

CLI에서는 플래그로 시작 모드를 지정할 수 있습니다.

claude --allowedTools "Edit,Write,Bash(npm test)"

권한 모드 3가지

---

3. 승인 프롬프트 이해하기

Normal 모드에서 Claude가 도구를 사용하려 할 때, 승인 프롬프트가 표시됩니다.

승인 옵션

키	의미	적용 범위
Y (Enter)	이번만 허용	이번 한 번
A	항상 허용	이 세션 내 동일 도구
N	거부	이번 한 번
E	수정 후 허용	내용 편집 후 승인

A (항상 허용)의 범위

A를 누르면 해당 도구의 정확한 패턴이 세션에 기억됩니다.

예: Bash(npm test)에서 A를 누르면
→ "npm test"만 자동 허용
→ "npm run build"는 여전히 승인 필요

승인 프롬프트 예시

Claude wants to execute:

  Edit: src/auth.ts (lines 15-23)

  - function login(email: string) {
  + function login(email: string, password: string) {
  +   validateInput(email, password);

  [Y]es  [A]lways  [N]o  [E]dit

팁: diff를 꼼꼼히 확인하세요. 특히 여러 파일을 동시에 수정하는 경우, 각 파일의 변경 내용을 모두 검토하는 것이 좋습니다.

 

승인 프롬프트 이해하기

---

4. settings.json 권한 규칙

영구적인 권한 규칙은 settings.json에서 설정합니다.

파일 위치

위치	경로	적용 범위
관리 정책	/etc/claude-code/settings.json	조직 전체 (최우선)
프로젝트	.claude/settings.json	프로젝트 전체
개인	~/.claude/settings.json	모든 프로젝트
로컬	.claude/settings.local.json	프로젝트 (개인)

규칙 3가지 타입

타입	의미	동작
allow	항상 허용	승인 없이 자동 실행
deny	항상 차단	Claude가 사용 불가
ask	매번 확인	승인 프롬프트 표시

우선순위

deny > ask > allow

deny가 있으면 allow와 충돌해도 deny 우선

기본 설정 예시

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Bash(curl * | bash)",
      "Read(.env*)",
      "Edit(.env*)"
    ]
  }
}

패턴 문법

패턴	의미	예시
도구명	해당 도구 전체	Read - 모든 파일 읽기
도구명(패턴)	특정 인수만	Bash(npm test)
도구명(패턴*)	와일드카드	Bash(git diff *)
도구명(경로)	특정 경로	Edit(src/*)

실전 설정 모음

안전한 기본 설정:

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm test *)",
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(ls *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Bash(git reset --hard *)",
      "Bash(curl * | bash)",
      "Bash(wget *)",
      "Read(.env*)",
      "Edit(.env*)",
      "Write(.env*)"
    ]
  }
}

팀 프로젝트 설정 (.claude/settings.json):

{
  "permissions": {
    "deny": [
      "Edit(*.lock)",
      "Edit(package-lock.json)",
      "Bash(npm install *)",
      "Read(.env*)",
      "Edit(.env*)",
      "Bash(docker * --privileged *)"
    ]
  }
}

 

settings.json 권한 규칙

---

5. /permissions 커맨드

현재 적용된 모든 권한 규칙을 확인하고 관리합니다.

사용법

> /permissions

현재 권한 규칙:
─────────────────
Allow:
  ✅ Read (모든 파일)
  ✅ Glob
  ✅ Grep
  ✅ Bash(npm test)

Deny:
  🚫 Bash(rm -rf *)
  🚫 Read(.env*)

Session Allow (A로 추가됨):
  ✅ Bash(git status)
  ✅ Edit(src/auth.ts)

규칙 추가/제거

/permissions 커맨드에서 대화형으로 규칙을 추가하거나 제거할 수 있습니다.

> /permissions

→ [A]dd rule  [R]emove rule  [V]iew all
→ A
→ Type: allow
→ Rule: Bash(npm run build)
→ Scope: project  (프로젝트 settings.json에 저장)

✅ 규칙 추가 완료

/permissions 커맨드

---

6. 도구별 권한 상세

파일 도구

도구	기능	기본 권한	위험도
Read	파일 읽기	자동 허용	낮음
Glob	파일 패턴 검색	자동 허용	낮음
Grep	내용 검색	자동 허용	낮음
Edit	파일 수정	승인 필요	중간
Write	파일 생성/덮어쓰기	승인 필요	중간
NotebookEdit	Jupyter 수정	승인 필요	중간

Bash 도구

Bash는 가장 강력하면서도 가장 위험한 도구입니다.

명령 카테고리	예시	권장 권한
읽기 전용	ls, cat, git status, git log	allow
빌드/테스트	npm test, npm run build, cargo test	allow
Git 안전	git diff, git branch, git stash	allow
패키지 설치	npm install, pip install	ask
Git 변경	git commit, git push	ask
위험 명령	rm -rf, git push --force, git reset --hard	deny
네트워크	curl | bash, wget	deny

MCP 도구

MCP(Model Context Protocol) 서버가 제공하는 도구도 동일한 권한 시스템을 따릅니다.

{
  "permissions": {
    "allow": [
      "mcp__github__get_file_contents",
      "mcp__github__search_code"
    ],
    "deny": [
      "mcp__github__delete_repository"
    ]
  }
}

도구별 권한 상세

---

7. 샌드박스 (Sandbox)

샌드박스는 Claude Code의 파일시스템과 네트워크 접근을 물리적으로 격리합니다.

플랫폼별 샌드박스

플랫폼	기술	특징
macOS	Apple Seatbelt (sandbox-exec)	커널 수준 격리
Linux	Docker 컨테이너	파일시스템 + 네트워크 격리
Windows	제한적 (계획 중)	Bash 명령 제한

샌드박스 활성화

> /sandbox on

샌드박스 활성화됨
- 파일 접근: 프로젝트 폴더만
- 네트워크: localhost만
- 시스템 명령: 제한됨

샌드박스에서 허용/차단

허용됨	차단됨
프로젝트 폴더 읽기/쓰기	시스템 폴더 접근
localhost 네트워크	외부 네트워크 요청
npm test, cargo build 등	시스템 설정 변경
Git 명령 (로컬)	패키지 설치 (네트워크 필요)

네트워크 허용 추가

특정 호스트를 샌드박스에서 허용할 수 있습니다.

{
  "sandbox": {
    "enabled": true,
    "permissions": {
      "network": {
        "allowedHosts": [
          "registry.npmjs.org",
          "api.github.com"
        ]
      }
    }
  }
}

권장: CI/CD 환경이나 보안이 중요한 프로젝트에서는 샌드박스를 기본으로 활성화하세요.

샌드박스 (Sandbox)

---

8. 관리 정책 (Enterprise)

조직 관리자는 관리 정책 설정으로 모든 사용자에게 권한 규칙을 강제합니다.

관리 정책 위치

OS	경로
Linux	/etc/claude-code/settings.json
macOS	/Library/Application Support/ClaudeCode/settings.json
Windows	C:\ProgramData\ClaudeCode\settings.json

특징

• 개인이 덮어쓸 수 없음 (최우선 적용)
• MDM, Ansible, Group Policy로 배포
• 조직 보안 정책 통합 관리

관리 정책 예시

{
  "permissions": {
    "deny": [
      "Bash(curl * | bash)",
      "Bash(wget *)",
      "Bash(rm -rf /*)",
      "Bash(git push --force *)",
      "Read(/etc/passwd)",
      "Read(/etc/shadow)",
      "Edit(/etc/*)"
    ]
  },
  "sandbox": {
    "enabled": true
  }
}

관리 정책 (Enterprise)

---

9. 실전 시나리오별 권한 설정

시나리오 1: 혼자 개인 프로젝트

{
  "permissions": {
    "allow": [
      "Read", "Glob", "Grep", "Edit", "Write",
      "Bash(npm *)", "Bash(git *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl * | bash)"
    ]
  }
}

→ 대부분 자동 허용, 위험한 것만 차단

시나리오 2: 팀 프로젝트

{
  "permissions": {
    "allow": [
      "Read", "Glob", "Grep",
      "Bash(npm test *)", "Bash(npm run lint)"
    ],
    "deny": [
      "Edit(.env*)", "Read(.env*)",
      "Edit(*.lock)",
      "Bash(npm install *)",
      "Bash(git push --force *)"
    ]
  }
}

→ 읽기 + 테스트 자동, 설치/잠금파일/비밀파일 차단

시나리오 3: 보안 민감 프로젝트

{
  "permissions": {
    "allow": [
      "Read", "Glob", "Grep"
    ],
    "deny": [
      "Bash(*)", "Write(*)",
      "Read(.env*)", "Read(*secret*)",
      "Read(*credential*)"
    ]
  }
}

→ 읽기만 허용, Bash와 파일 생성 전면 차단

시나리오 4: CI/CD 자동화

{
  "permissions": {
    "allow": [
      "Read", "Glob", "Grep", "Edit", "Write",
      "Bash(npm test *)", "Bash(npm run build *)",
      "Bash(git commit *)", "Bash(git push *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)"
    ]
  },
  "sandbox": { "enabled": true }
}

→ 빌드/테스트/커밋/푸시 자동화, 샌드박스로 격리

실전 시나리오별 권한 설정

---

10. 트러블슈팅

Claude가 승인 없이 실행해요

1. 현재 모드 확인: Shift+Tab 상태 바 확인
2. Auto-Accept 모드인지 확인
3. /permissions로 allow 규칙 검토
4. 세션 중 A로 추가된 규칙 확인

필요한 명령이 차단돼요

1. /permissions로 deny 규칙 확인
2. 관리 정책이 설정되어 있는지 확인
3. deny 규칙 > allow 규칙 (우선순위)
4. 관리 정책은 개인이 변경 불가

권한 설정 디버깅

# 모든 설정 파일 경로 확인
claude --print-settings

# 적용된 권한 규칙 전체 보기
> /permissions

---

마무리

Claude Code 권한 시스템의 핵심을 정리하면:

1. 3가지 모드: Normal(안전), Auto-Accept(효율), Plan(읽기 전용)
2. 3가지 규칙: allow(허용), deny(차단), ask(확인) / deny가 최우선
3. 승인 옵션: Y(이번만), A(항상), N(거부), E(수정 후)
4. settings.json: 영구 규칙 저장 (프로젝트/개인/관리)
5. 샌드박스: 파일시스템/네트워크 물리적 격리

권장 시작 설정: Normal 모드로 시작하고, 자주 승인하는 명령은 settings.json의 allow에 추가하세요. .env 등 민감한 파일은 반드시 deny로 차단하세요.

다음 편에서는 모델 선택과 컨텍스트 최적화를 다룹니다. Opus, Sonnet, Haiku 모델의 차이와 비용 대비 성능 최적화 방법을 살펴봅니다.

---

이전 글: [6편] 메모리 시스템 심화: Auto Memory와 프로젝트 메모리
다음 글: [8편] 모델 선택과 컨텍스트 최적화: 비용 대비 최고 성능

---

면책 조항: 본 글은 교육 목적의 정보 제공용이며, Claude Code의 기능 및 요금제는 Anthropic의 정책에 따라 변경될 수 있습니다. 최신 정보는 공식 문서(docs.anthropic.com)를 참고하세요.