권한 시스템 (Permission System)

Claude Code는 강력한 AI 코딩 에이전트이지만, 그 강력함에는 반드시 안전장치가 따라야 한다. 권한 시스템은 Claude Code가 사용자의 파일과 시스템에 접근할 때 어떤 행동을 자동으로 할 수 있고, 어떤 행동에는 사용자의 명시적 승인이 필요한지를 결정하는 핵심 메커니즘이다.

1. 도구와 권한의 관계

Claude Code는 단순히 텍스트를 생성하는 AI가 아니다. 실제 도구(Tool)를 실행하여 파일을 읽고, 명령어를 실행하고, 코드를 수정한다. 이 도구들은 각각 다른 수준의 위험도를 가지고 있으며, 위험도에 따라 사용자의 승인 여부가 결정된다.

비유: 회사에서의 권한

회사에서 일하는 상황을 떠올려보자.

행동	회사 비유	Claude Code 비유
안전한 행동	커피 마시기, 자기 자리에서 일하기	파일 읽기, 디렉토리 목록 보기
주의가 필요한 행동	공용 프린터 사용, 회의실 예약	셸 명령어 실행
승인이 필요한 행동	회사 자산 구매, 중요 문서 수정	파일 편집, 파일 생성/삭제

커피를 마실 때마다 상사에게 "커피 마셔도 될까요?"라고 물어볼 필요는 없다. 하지만 회사 카드로 장비를 구매할 때는 반드시 결재가 필요하다. Claude Code의 권한 시스템도 정확히 이 논리를 따른다.

Claude Code가 사용하는 주요 도구

도구	기능	위험도
`Read`	파일 내용 읽기	낮음 (읽기만 함)
`Glob`	파일 패턴 검색	낮음 (검색만 함)
`Grep`	파일 내용 검색	낮음 (검색만 함)
`Bash`	셸 명령어 실행	높음 (무엇이든 실행 가능)
`Edit`	파일 부분 수정	높음 (코드 변경)
`Write`	파일 전체 작성	높음 (파일 생성/덮어쓰기)

2. 3계층 권한 시스템

Claude Code의 도구들은 위험도에 따라 3개의 계층으로 분류된다. 아래에서 위로 올라갈수록 위험도가 높아지고, 더 엄격한 승인이 필요하다.

1층: 읽기 전용 도구 (자동 승인)

도구	설명	예시
`Read`	파일 내용을 읽어온다	`Read("/src/main.go")`
`Glob`	파일 이름 패턴으로 검색한다	`Glob("*/.ts")`
`Grep`	파일 내용에서 텍스트를 찾는다	`Grep("TODO", "*.py")`

이 도구들은 시스템에 아무런 변경을 가하지 않는다. 파일을 읽거나 검색하는 것뿐이므로, Claude Code는 사용자에게 물어보지 않고 즉시 실행한다. 코드를 이해하기 위해 파일을 읽는 행위는 위험하지 않기 때문이다.

2층: 셸 실행 도구 (승인 필요)

Bash 도구는 터미널에서 임의의 명령어를 실행할 수 있다. npm install, go build, git status 같은 유용한 명령어부터, rm -rf / 같은 위험한 명령어까지 모두 실행할 수 있으므로 승인이 필요하다.

# Claude가 실행하려는 명령어 예시
> npm install express

Allow? [Yes / Yes for session / No]

Bash 도구의 특징은 명령어 단위로 세밀하게 권한을 설정할 수 있다는 점이다. 예를 들어 git status는 항상 허용하되, rm 명령은 매번 물어보도록 설정할 수 있다. 이 부분은 뒤에서 /permission 명령어로 자세히 다룬다.

3층: 파일 수정 도구 (승인 필요)

도구	설명	위험성
`Edit`	파일의 특정 부분을 수정한다	기존 코드가 변경됨
`Write`	파일 전체를 새로 작성한다	파일이 통째로 덮어써지거나 새로 생성됨

이 도구들은 실제로 코드를 변경하므로 가장 주의가 필요하다. 잘못된 편집은 빌드 실패, 버그 도입, 또는 데이터 손실로 이어질 수 있다.

# Claude가 파일을 수정하려 할 때
> Edit: src/server.ts
  - const port = 3000;
  + const port = process.env.PORT || 3000;

Allow? [Yes / Yes for session / No]

3. 4가지 권한 모드

Claude Code는 상황에 따라 사용할 수 있는 4가지 권한 모드를 제공한다. 각 모드는 도구 실행에 대한 승인 정책이 다르며, Shift+Tab (Mac) 또는 Alt+M (Windows)으로 전환할 수 있다.

3-1. Default 모드 (기본 모드)

가장 안전한 기본 모드이다. Claude Code가 처음 사용하는 도구에 대해 매번 승인을 요청한다.

동작 방식:

읽기 전용 도구 (Read, Glob, Grep): 자동 승인
Bash 명령어: 승인 필요
파일 편집 (Edit, Write): 승인 필요

적합한 상황:

Claude Code를 처음 사용할 때
민감한 프로젝트에서 작업할 때
Claude의 행동을 세밀하게 통제하고 싶을 때

3-2. AcceptEdit 모드 (편집 자동 승인)

파일 편집 작업은 자동으로 승인하되, Bash 명령어 실행은 여전히 물어보는 모드이다.

동작 방식:

읽기 전용 도구: 자동 승인
Bash 명령어: 승인 필요
파일 편집 (Edit, Write): 자동 승인

적합한 상황:

Claude에게 코드 리팩토링을 맡길 때
여러 파일을 동시에 수정해야 할 때
매번 "Yes"를 누르는 것이 번거로울 때

주의: Bash 명령어는 여전히 승인이 필요하다. npm install이나 docker build 같은 명령이 시스템에 영향을 줄 수 있기 때문이다.

3-3. Plan 모드 (계획 모드) -- 가장 중요!

Plan 모드는 Claude Code에서 가장 중요한 모드이다. 이 모드에서 Claude는 어떤 쓰기 작업도 수행하지 않는다. 오직 코드를 읽고 분석하여 계획을 세우는 것에만 집중한다.

동작 방식:

읽기 전용 도구: 자동 승인
Bash 명령어: 사용 불가 (읽기 전용 명령만 허용)
파일 편집 (Edit, Write): 사용 불가

적합한 상황:

복잡한 작업을 시작하기 전에 계획을 세울 때
Claude가 코드베이스를 분석하고 전략을 제안해주길 원할 때
실행 전에 Claude의 접근 방식을 검토하고 싶을 때

Plan 모드가 왜 그토록 중요한지는 다음 섹션에서 자세히 다룬다.

3-4. Bypass Permission 모드 (전체 자동 승인)

모든 도구 사용을 자동으로 승인하는 모드이다. Claude가 아무런 제약 없이 자유롭게 작업한다.

동작 방식:

읽기 전용 도구: 자동 승인
Bash 명령어: 자동 승인
파일 편집 (Edit, Write): 자동 승인

적합한 상황:

Docker 컨테이너 같은 격리된 환경에서 작업할 때
테스트용 throwaway 프로젝트에서 빠르게 실험할 때
CI/CD 파이프라인에서 Claude Code를 실행할 때

경고: 실제 프로덕션 코드에서는 이 모드를 사용하지 않는 것이 좋다. Claude가 의도하지 않은 명령어를 실행하거나 파일을 변경할 수 있다.

모드 전환 방법

환경	단축키
Mac 터미널	`Shift + Tab`
Windows 터미널	`Alt + M`
모든 환경	프롬프트 입력 영역 하단의 모드 표시 클릭

현재 모드는 Claude Code 인터페이스 하단에 항상 표시된다. 작업 중에도 자유롭게 모드를 전환할 수 있다.

4. Plan 모드 심화

AI 택시 비유

Claude Code를 AI 택시라고 생각해보자.

택시에 타자마자 "아무 데나 가주세요"라고 하면 어떻게 될까?
택시 기사가 열심히 운전했지만, 도착한 곳이 원하는 곳이 아니라면?
다시 돌아오는 데 시간과 비용이 두 배로 든다.

Plan 모드는 택시에 타기 전에 지도를 펼쳐놓고 경로를 먼저 확인하는 것과 같다.

목적지(원하는 결과)를 명확히 하고, 경로(구현 방법)를 미리 검토한 다음, 만족스러운 경로가 확정되면 그때 출발(실행)하는 것이다.

Plan 모드 워크플로우

4가지 실행 옵션 상세 설명

옵션 1: Clear Context & 실행

Plan 모드에서 계획을 수립하면, Claude는 코드를 분석하면서 많은 **컨텍스트(대화 맥락)**를 소비한다. 이 상태에서 바로 실행으로 넘어가면, 남은 컨텍스트 공간이 부족할 수 있다.

"Clear Context & 실행"을 선택하면:

현재까지의 대화 내용을 정리(clear)한다
계획서 내용은 파일로 저장되어 있으므로 사라지지 않는다
깨끗한 컨텍스트에서 저장된 계획을 참조하며 실행을 시작한다

이 옵션이 가장 권장되는 방식이다. 특히 복잡한 작업일수록 컨텍스트 공간이 충분해야 정확한 실행이 가능하기 때문이다.

옵션 2: AcceptEdit 모드로 실행

컨텍스트를 유지한 채 AcceptEdit 모드로 전환하여 실행한다. 파일 편집은 자동으로 진행되고, Bash 명령만 확인하면 된다.

옵션 3: Default 모드로 실행

컨텍스트를 유지한 채 Default 모드로 전환하여 실행한다. 모든 도구 사용을 하나하나 확인하므로 가장 안전하지만, 가장 느리다.

옵션 4: 계획 수정 요청

계획의 특정 부분이 마음에 들지 않으면 수정을 요청할 수 있다. "이 부분은 다른 라이브러리를 써줘", "테스트 코드도 추가해줘" 같은 피드백을 주면 Claude가 계획을 수정한다.

Plan 모드에서 계획이 저장되는 방식

Plan 모드의 핵심적인 장점 중 하나는 계획이 파일로 저장된다는 것이다.

Claude가 수립한 계획은 대화 컨텍스트에만 존재하는 것이 아니라, 실제 파일로 기록된다
따라서 "Clear Context"를 해도 계획이 사라지지 않는다
실행 단계에서 Claude는 저장된 계획 파일을 참조하여 작업을 수행한다
이 덕분에 계획 수립 단계와 실행 단계를 완전히 분리할 수 있다

5. /permission 명령어로 세밀한 권한 관리

Claude Code는 /permission 명령어를 통해 도구별, 명령어별로 세밀한 권한 규칙을 설정할 수 있다.

규칙 유형

유형	설명	사용 예시
Allow	해당 도구/명령을 항상 자동 승인한다	자주 사용하는 안전한 명령
Ask	해당 도구/명령 사용 시 매번 물어본다 (기본값)	대부분의 도구
Deny	해당 도구/명령 사용을 완전히 차단한다	위험한 명령 방지

도구 범위 지정 문법

Bash 명령어 권한

bash                    # 모든 bash 명령어
bash(git status)        # git status 명령만
bash(npm install)       # npm install 명령만
bash(rm)                # rm으로 시작하는 명령
bash(docker)            # docker로 시작하는 명령

실전 예시:

# 자주 쓰는 안전한 명령은 자동 허용
Allow  bash(git status)         Local
Allow  bash(git diff)           Local
Allow  bash(go test)            Local
Allow  bash(npm run build)      Local

# 위험한 명령은 항상 차단
Deny   bash(rm -rf)             Local
Deny   bash(git push --force)   Local

# 그 외 bash 명령은 매번 물어봄
Ask    bash                     Local

파일 편집 권한

edit                    # 모든 파일 편집
edit(src/**)            # src 디렉토리 하위만 허용
edit(*.test.ts)         # 테스트 파일만 허용
edit(package.json)      # 특정 파일만 허용

실전 예시:

# 소스 코드 편집은 자동 허용
Allow  edit(src/**)              Local

# 설정 파일 편집은 매번 확인
Ask    edit(*.json)              Local
Ask    edit(.env*)               Local

# 빌드 산출물 편집은 차단
Deny   edit(dist/**)             Local

적용 범위 (Scope)

범위	설명
Local	현재 프로젝트(디렉토리)에서만 적용된다. `.claude/settings.local.json`에 저장된다
User	모든 프로젝트에 전역으로 적용된다. `~/.claude/settings.json`에 저장된다

대부분의 경우 Local 범위를 사용하는 것이 좋다. 프로젝트마다 필요한 명령어와 편집 범위가 다르기 때문이다.

Workspace 설정

/permission 명령어에서는 Workspace 관련 설정도 할 수 있다. 이것은 Claude Code가 접근할 수 있는 추가 디렉토리를 지정하는 기능이다.

기본적으로 Claude Code는 현재 작업 디렉토리만 접근할 수 있다. 하지만 프로젝트가 여러 디렉토리에 걸쳐 있거나, 공유 라이브러리를 참조해야 하는 경우 추가 디렉토리를 허용할 수 있다.

# 예시: 공용 라이브러리 디렉토리를 참조 경로로 추가
Workspace: /Users/me/shared-libs (읽기 전용)

6. 승인 시 선택지 설명

Claude Code가 승인이 필요한 도구를 사용하려 할 때, 사용자에게 다음 3가지 선택지가 표시된다.

Claude wants to run: npm install express

  1) Yes                    - 이번 한 번만 승인
  2) Yes, for this session  - 이번 세션 동안 자동 승인
  3) No                     - 거부

1번: Yes (이번만 승인)

이번 실행에만 해당 도구 사용을 허용한다
같은 도구를 다시 사용하면 또 물어본다
가장 보수적이고 안전한 선택이다

적합한 상황:

처음 보는 명령어가 실행될 때
한 번만 실행하면 되는 명령일 때
신중하게 작업하고 싶을 때

2번: Yes, for this session (세션 동안 자동 승인)

현재 Claude Code 세션이 끝날 때까지 같은 종류의 도구 사용을 자동으로 승인한다
Claude Code를 종료하고 다시 시작하면 초기화된다
/permission으로 설정한 영구 규칙과는 다르다 (세션 한정)

적합한 상황:

반복적으로 같은 종류의 명령이 실행될 것으로 예상될 때
매번 "Yes"를 누르는 것이 번거로울 때
하지만 영구적으로 허용하고 싶지는 않을 때

3번: No (거부)

해당 도구 사용을 거부한다
Claude는 다른 방법을 찾거나, 사용자에게 대안을 제시한다

적합한 상황:

Claude가 잘못된 명령을 실행하려 할 때
의도하지 않은 파일이 수정되려 할 때
현재 상태에서 해당 작업이 불필요할 때

선택 팁

상황	권장 선택
`git status` 실행	2번 (세션 동안 자동)
`npm install <패키지>`	1번 (이번만, 패키지 확인 후)
`rm -rf node_modules`	1번 (이번만, 신중하게)
알 수 없는 명령어	3번 (거부 후 확인)
소스 코드 편집	내용 확인 후 1번 또는 2번

7. 실전 팁

팁 1: Plan 모드를 정말 많이 활용하라

이것은 Claude Code 사용에서 가장 중요한 습관이다.

복잡한 작업을 바로 실행하면 다음과 같은 문제가 발생한다:

Claude가 잘못된 방향으로 코드를 수정한다
되돌리기 위해 git reset을 해야 한다
컨텍스트가 낭비된다
시간이 두 배로 걸린다

Plan 모드를 활용하면:

Claude가 어떤 파일을 수정할지 미리 알 수 있다
접근 방식이 마음에 들지 않으면 실행 전에 수정할 수 있다
계획이 확정된 후 실행하므로 한 번에 올바르게 완료될 가능성이 높다

# 나쁜 예: 바로 실행
> "이 프로젝트에 인증 시스템 추가해줘"
# Claude가 바로 파일을 수정하기 시작... 결과가 마음에 안 들 수 있음

# 좋은 예: Plan 모드 먼저
> [Plan 모드로 전환]
> "이 프로젝트에 인증 시스템을 추가하려면 어떻게 해야 할까?"
# Claude가 분석하고 계획을 제시
> "JWT 대신 세션 기반으로 해줘, 그리고 테스트도 포함해줘"
# Claude가 계획을 수정
> [만족 -> Clear Context & 실행]

팁 2: 계획이 만족스러울 때까지 반복한 후 실행

계획에 대한 피드백을 주는 것을 아까워하지 마라. Plan 모드에서의 반복은 비용이 매우 저렴하다. 왜냐하면:

읽기 전용이므로 시스템에 아무런 부작용이 없다
잘못된 실행을 되돌리는 것보다 훨씬 빠르다
계획을 다듬을수록 최종 결과물의 품질이 높아진다

계획 검토 시 확인할 사항:

수정할 파일 목록이 정확한가?
새로 생성할 파일이 적절한가?
사용하려는 라이브러리/패턴이 프로젝트 컨벤션에 맞는가?
테스트 전략이 포함되어 있는가?
에지 케이스를 고려했는가?

팁 3: 복잡한 작업일수록 Plan 모드가 중요하다

작업의 복잡도에 따른 권장 모드:

작업 복잡도	예시	권장 워크플로우
간단	오타 수정, 변수 이름 변경	Default 모드로 바로 실행
보통	함수 추가, 버그 수정	Plan으로 간단히 확인 후 실행
복잡	새 기능 구현, 리팩토링	Plan으로 충분히 계획 후 Clear Context & 실행
매우 복잡	아키텍처 변경, 대규모 마이그레이션	Plan으로 단계별 계획 수립 후 단계별로 실행

팁 4: 권한 설정은 프로젝트별로 관리하라

/permission 명령어로 프로젝트에 맞는 권한 세트를 구성해두면 작업 효율이 크게 올라간다.

Go 프로젝트 예시:

Allow  bash(go test)            Local
Allow  bash(go vet)             Local
Allow  bash(go build)           Local
Allow  bash(go mod tidy)        Local
Allow  bash(git status)         Local
Allow  bash(git diff)           Local

Node.js 프로젝트 예시:

Allow  bash(npm run)            Local
Allow  bash(npm test)           Local
Allow  bash(npx)                Local
Allow  bash(git status)         Local
Allow  bash(git diff)           Local

팁 5: 승인 요청이 뜨면 반드시 내용을 확인하라

"Yes"를 기계적으로 누르는 습관은 위험하다. 특히:

파일 편집 시: 변경 내용(diff)을 반드시 읽어라
Bash 명령 시: 실행될 명령어를 확인하라
익숙하지 않은 명령: 잠시 멈추고 해당 명령이 무엇을 하는지 파악하라

권한 시스템의 존재 이유는 사용자가 최종 통제권을 가지기 위함이다. 이 통제권을 제대로 행사하려면 승인 요청을 주의 깊게 검토하는 습관이 필수적이다.

요약

핵심 개념	설명
3계층 구조	읽기(자동) / Bash(승인) / 편집(승인)
4가지 모드	Default / AcceptEdit / Plan / Bypass
Plan 모드	가장 중요한 모드. 읽기만 가능, 계획 수립에 집중
/permission	도구별, 명령어별 세밀한 규칙 설정
승인 선택지	Yes(1회) / Yes for session(세션) / No(거부)
핵심 습관	Plan 먼저, 계획 반복, 승인 내용 확인

Claude Code의 권한 시스템은 단순한 보안 기능이 아니다. AI와 개발자 간의 효과적인 협업 인터페이스이다. Plan 모드로 방향을 잡고, 적절한 권한으로 실행을 통제하며, 승인 요청을 주의 깊게 검토하는 습관을 들이면 Claude Code를 훨씬 더 효과적으로 활용할 수 있다.

권한 시스템 (Permission System) ​

1. 도구와 권한의 관계 ​

비유: 회사에서의 권한 ​

Claude Code가 사용하는 주요 도구 ​

2. 3계층 권한 시스템 ​

1층: 읽기 전용 도구 (자동 승인) ​

2층: 셸 실행 도구 (승인 필요) ​

3층: 파일 수정 도구 (승인 필요) ​

3. 4가지 권한 모드 ​

3-1. Default 모드 (기본 모드) ​

3-2. AcceptEdit 모드 (편집 자동 승인) ​

3-3. Plan 모드 (계획 모드) -- 가장 중요! ​

3-4. Bypass Permission 모드 (전체 자동 승인) ​

모드 전환 방법 ​

4. Plan 모드 심화 ​

AI 택시 비유 ​

Plan 모드 워크플로우 ​

4가지 실행 옵션 상세 설명 ​

옵션 1: Clear Context & 실행 ​

옵션 2: AcceptEdit 모드로 실행 ​

옵션 3: Default 모드로 실행 ​

옵션 4: 계획 수정 요청 ​

Plan 모드에서 계획이 저장되는 방식 ​

5. /permission 명령어로 세밀한 권한 관리 ​

규칙 유형 ​

도구 범위 지정 문법 ​

Bash 명령어 권한 ​

파일 편집 권한 ​

적용 범위 (Scope) ​

Workspace 설정 ​

6. 승인 시 선택지 설명 ​

1번: Yes (이번만 승인) ​

2번: Yes, for this session (세션 동안 자동 승인) ​

3번: No (거부) ​

선택 팁 ​

7. 실전 팁 ​

팁 1: Plan 모드를 정말 많이 활용하라 ​

팁 2: 계획이 만족스러울 때까지 반복한 후 실행 ​

팁 3: 복잡한 작업일수록 Plan 모드가 중요하다 ​

팁 4: 권한 설정은 프로젝트별로 관리하라 ​

팁 5: 승인 요청이 뜨면 반드시 내용을 확인하라 ​

요약 ​

권한 시스템 (Permission System)

1. 도구와 권한의 관계

비유: 회사에서의 권한

Claude Code가 사용하는 주요 도구

2. 3계층 권한 시스템

1층: 읽기 전용 도구 (자동 승인)

2층: 셸 실행 도구 (승인 필요)

3층: 파일 수정 도구 (승인 필요)

3. 4가지 권한 모드

3-1. Default 모드 (기본 모드)

3-2. AcceptEdit 모드 (편집 자동 승인)

3-3. Plan 모드 (계획 모드) -- 가장 중요!

3-4. Bypass Permission 모드 (전체 자동 승인)

모드 전환 방법

4. Plan 모드 심화

AI 택시 비유

Plan 모드 워크플로우

4가지 실행 옵션 상세 설명

옵션 1: Clear Context & 실행

옵션 2: AcceptEdit 모드로 실행

옵션 3: Default 모드로 실행

옵션 4: 계획 수정 요청

Plan 모드에서 계획이 저장되는 방식

5. /permission 명령어로 세밀한 권한 관리

규칙 유형

도구 범위 지정 문법

Bash 명령어 권한

파일 편집 권한

적용 범위 (Scope)

Workspace 설정

6. 승인 시 선택지 설명

1번: Yes (이번만 승인)

2번: Yes, for this session (세션 동안 자동 승인)

3번: No (거부)

선택 팁

7. 실전 팁

팁 1: Plan 모드를 정말 많이 활용하라

팁 2: 계획이 만족스러울 때까지 반복한 후 실행

팁 3: 복잡한 작업일수록 Plan 모드가 중요하다

팁 4: 권한 설정은 프로젝트별로 관리하라

팁 5: 승인 요청이 뜨면 반드시 내용을 확인하라

요약