클로드 코드 권한 모드와 허용 규칙 설정하기

이 글은 앤트로픽이 운영하는 code.claude.com/docs의 Permission modes, Permissions, Settings 문서를 한국어 사용자가 실무에 바로 옮길 수 있도록 정리한 글입니다. 모드 이름과 버전은 2026년 10월 3일 공식 문서 기준이고, 원문 링크는 글 끝 참고 자료에 모았습니다.

🤔 승인 창을 줄이고 싶은데 어디까지 열어도 될지 모를 때

클로드 코드를 며칠 쓰다 보면 테스트 명령 등에 승인 창이 반복해서 뜨는 것이 번거로울 수 있습니다. git status 같은 읽기 명령은 기본적으로 묻지 않을 수 있으므로 모든 명령이 항상 승인을 요구한다고 보지는 않습니다. 그렇다고 모든 행동을 자동으로 허락하자니 git push나 파일 삭제까지 묻지 않고 실행될까 걱정됩니다. 필요한 것은 모드 하나를 고르는 일이 아니라, 모드와 규칙을 조합해 자주 쓰는 명령은 열고 위험한 명령은 닫는 것입니다.

처음에는 Manual과 plan을 구분하고 현재 모드와 규칙을 확인하는 실습부터 합니다. 이어 여섯 가지 권한 모드의 차이와 전환 방법, 세션을 어떤 모드로 시작할지 정하는 법, allow와 ask와 deny 규칙을 쓰는 문법을 정리합니다. 자동 승인이 왜 위험한지, 무엇부터 막을지 같은 원칙은 코딩 에이전트 권한과 안전에 따로 정리했으므로 여기서는 설정 방법에 집중합니다.

🔑 권한 모드와 허용 규칙의 정의

클로드 코드의 권한 모드는 도구를 쓰기 전에 사람에게 물어볼 범위를 정하는 설정이고, 허용 규칙은 특정 명령과 파일을 늘 허용하거나 막는 목록입니다.

두 설정의 역할은 다릅니다. 모드는 "대체로 얼마나 묻느냐"를 정하고, 규칙은 "이 명령은 항상 이렇게"를 정합니다. 공식 문서는 권한 규칙을 모델이 아니라 클로드 코드 프로그램이 강제한다고 적습니다. CLAUDE.md에 "push하지 마"라고 적는 것과 달리, 일치하는 deny 규칙은 프로그램이 차단합니다. 다만 규칙의 패턴이 실제 실행 방식과 맞아야 하며 모든 우회 경로까지 막는다는 뜻은 아닙니다. 기술적으로 실행 가능하다고 발송이나 배포 등 업무 권한까지 생기는 것은 아닙니다.

🎚️ 여섯 가지 모드의 차이

plan은 계획을 검토하는 모드이며 운영체제 수준의 읽기 전용 격리를 대신하지 않습니다. 자동으로 허용하는 작업에도 보호 경로와 명시적 ask 및 deny 등의 예외가 있습니다.

플랜 모드의 흐름은 입문 코스의 플랜 모드 활용하기에 있습니다. 중급에서 알아 둘 것은 계획을 승인하는 선택지가 세 가지로 나뉜다는 점입니다. 지원되는 화면에서 Yes, and use auto mode를 고르면 auto로, Yes, manually approve edits를 고르면 수정마다 묻는 방식으로 실행되고, No, keep planning은 계획을 이어 갑니다. Ctrl+G를 누르면 계획을 기본 편집기에서 직접 고칠 수 있습니다.

dontAsk는 이름과 달리 "묻지 않고 다 한다"가 아니라 "물어볼 만한 일은 모두 거부한다"는 뜻입니다. 사람이 승인해 줄 수 없는 자동화 환경에서 쓰는 모드입니다.

🔁 세션 중에 모드를 바꾸는 방법

세션 안에서는 Shift+Tab으로 모드를 돌아가며 바꿉니다. 공식 문서가 적은 순서는 다음과 같습니다.

1. auto에서 시작했다면 첫 번째 누름이 default로 바꿉니다
2. 그다음부터 default → acceptEdits → plan → 다시 default 순서로 돕니다
3. bypassPermissions나 auto가 켜질 수 있는 세션이면 plan 뒤에 끼어듭니다

dontAsk는 이 순환에 나오지 않고 시작 옵션으로만 켭니다. bypassPermissions도 시작할 때 --permission-mode bypassPermissions나 --dangerously-skip-permissions를 주었거나 사용자 설정에 적어 둔 경우에만 순환에 들어갑니다. 플랜 모드는 프롬프트 앞에 /plan을 붙여 바로 들어갈 수도 있습니다(예: /plan 로그인 오류 원인 찾기).

v2.1.247 이상에서는 Manual이나 acceptEdits 상태에서 Bash 승인 창이 떴을 때 Yes, and switch to auto mode를 고르면 세션을 다시 시작하지 않고 auto로 넘어갑니다.

🚦 세션을 어떤 모드로 시작할지 정하기

시작 모드는 아래 순서에서 먼저 해당하는 것으로 정해집니다.

1. 시작 옵션: claude --permission-mode plan처럼 주거나 --dangerously-skip-permissions
2. 설정 파일의 permissions.defaultMode
3. 내장 기본값: 지원되는 대화형 터미널과 VS Code는 v2.1.283부터 auto가 기본입니다. 조직 설정과 지원 모델, 실행 방식 및 버전에 따라 달라질 수 있어 화면의 현재 모드를 확인합니다

첫 연습에서는 claude --permission-mode default로 이번 세션만 Manual로 시작합니다. 모든 프로젝트의 시작 방식을 바꾸려는 경우에만 사용자 설정(~/.claude/settings.json)을 수정합니다. 아래 JSON은 해당 항목의 예이며 기존 파일 전체를 덮어쓰는 내용이 아닙니다.

여기에 함정이 하나 있습니다. 프로젝트 설정 파일(.claude/settings.json, .claude/settings.local.json)에 auto를 적으면 적용되지 않고, bypassPermissions를 적으면 Manual로 시작합니다. 저장소를 내려받은 사람이 모르는 사이 위험한 모드로 시작하지 않도록 막아 둔 것입니다. 이 두 모드를 기본으로 쓰려면 사용자 설정이나 시작 옵션을 씁니다. VS Code 확장은 프로젝트 설정의 시작 모드를 읽지 않으므로, 플랜 모드로 시작하려면 확장 설정의 claudeCode.initialPermissionMode를 plan으로 둡니다.

📝 allow, ask, deny 규칙 쓰는 법

규칙은 설정 파일의 permissions 안에 세 목록으로 적습니다. 다음은 문법 예제이며 실습에 그대로 추가하지 않습니다. 실제 허용 목록은 파일과 명령의 내용을 확인한 뒤 필요한 범위로 정합니다.

형식은 도구 또는 도구(조건)입니다. 알아 둘 문법은 다음과 같습니다.

• 평가 순서: deny, ask, allow 순서로 보고 처음 맞는 규칙이 결과를 정합니다. 규칙이 더 구체적이라고 순서가 바뀌지 않아서, 넓은 deny Bash(aws *)는 좁은 allow Bash(aws s3 ls)보다 우선합니다
• 와일드카드 위치: Bash(git log *)는 git log만, Bash(git *)는 모든 git 명령을 잡습니다. Bash(ls *)는 lsof를 잡지 않지만 공백 없는 Bash(ls*)는 잡습니다
• 도구 이름만 쓴 deny: Bash처럼 조건 없이 막으면 그 도구를 아예 쓰지 못하게 치웁니다
• 경로 패턴: //경로는 루트 기준 절대 경로, ~/경로는 홈 폴더, /경로는 설정 파일 기준, ./경로는 현재 폴더 기준입니다
• 파일 쓰기 규칙: 수정과 쓰기를 막는 규칙은 Edit(docs/**)처럼 Edit으로 적습니다. 경로를 넣은 Write(...) 규칙은 파일 경로 검사에 쓰이지 않습니다. 경로 없는 도구 이름 Write 차단과는 다릅니다

공식 문서가 스스로 밝히는 한계도 있습니다. Bash(git push *)를 막아도 git -C . push처럼 다르게 쓴 명령은 이 규칙에 걸리지 않습니다. Read(./.env) 규칙은 cat, head 같은 명령까지는 막지만 파이썬 스크립트가 여는 파일은 막지 못합니다. 이런 접근까지 제한하려면 운영체제 수준에서 파일과 네트워크 접근을 제한하는 샌드박스 등의 별도 통제가 필요합니다. 훅도 어떤 실행 경로를 검사하는지 구현하고 시험해야 하며 이름만 추가해서 모든 접근을 막지는 못합니다.

본문의 권한 규칙 평가 순서입니다. 단순 명령 패턴만으로 모든 우회 실행을 차단할 수 있다는 의미는 아닙니다.

🗂️ 설정 파일 네 곳과 우선순위

우선순위는 관리 정책이 가장 높고 시작 옵션, 프로젝트 로컬, 프로젝트 공유, 사용자 순으로 낮아집니다. 다만 allow 같은 목록은 덮어쓰지 않고 여러 파일의 값을 합칩니다. 설정 범위가 달라도 deny가 먼저라서, 사용자 설정에서 허용하고 프로젝트 설정에서 막으면 막힙니다.

승인 창에서 "Yes, and don't ask again"을 고르면 Bash 명령과 웹 도메인 허용은 .claude/settings.local.json에 규칙으로 저장됩니다. 그런데도 계속 묻는다면 다른 설정의 ask 규칙, 명령 패턴 불일치와 보호 경로 등의 조건을 확인합니다. 지금 걸려 있는 규칙과 그 규칙이 어느 파일에서 왔는지는 /permissions로 한 화면에서 봅니다.

⚠️ 자주 하는 실수

• 프로젝트 설정에 defaultMode: "auto"를 적고 적용됐다고 생각합니다: 프로젝트 설정에서는 무시됩니다
• 와일드카드를 명령 이름에 붙여 씁니다: Bash(git*)는 gitk 같은 다른 명령까지 잡습니다. 하위 명령 뒤에 공백과 함께 둡니다
• deny 규칙만 믿고 샌드박스를 켜지 않습니다: 규칙은 명령 문자열을 보고 판단하므로 우회 표기에 약합니다
• 프로젝트 allow가 바로 적용된다고 생각합니다: 프로젝트 설정의 allow는 작업 공간 신뢰 창을 수락한 뒤에만 적용됩니다

❓ 자주 묻는 질문

auto 모드와 acceptEdits는 무엇이 다른가요?

acceptEdits는 허용 범위의 파일 수정과 몇 가지 파일 명령을 자동 승인하며 나머지는 적용 규칙과 기본 읽기 허용 여부 등을 따릅니다. auto는 대상 동작을 별도 분류 모델로 검사해 요청 범위를 넘는 행동 등을 차단할 수 있습니다. 일부 동작은 검사를 건너뛰거나 사람의 확인을 요구하며 오판 가능성도 있습니다. 공식 문서는 auto가 승인 창을 줄여 줄 뿐 안전을 보장하지는 않는다고 적습니다.

팀 전체가 bypassPermissions를 못 쓰게 할 수 있나요?

할 수 있습니다. 관리 정책 설정에 permissions.disableBypassPermissionsMode를 "disable"로 두면 막히고, auto 모드는 disableAutoMode로 막습니다. 관리 정책의 deny 규칙은 시작 옵션으로도 풀 수 없습니다.

규칙이 어느 파일에서 왔는지 어떻게 확인하나요?

세션 안에서 /permissions를 입력하면 모든 규칙과 각 규칙이 들어 있는 설정 파일이 함께 보입니다. 작업 도중 규칙을 바꾸면 같은 턴의 다음 도구 호출부터 적용됩니다.

가상 파일 두 개로 읽기 규칙 확인하기

설치와 로그인이 끝난 Claude Code에서 진행합니다. 아직 준비하지 않았다면 설치 기초를 먼저 확인합니다. 실행에는 계정의 사용량이 적용됩니다.

새 폴더 permission-practice를 만들고 메모장이나 편집기로 일반 텍스트 파일 두 개를 저장합니다.

두 파일 모두 가상 자료이며 비밀이나 개인정보를 넣지 않습니다. 그 폴더 안에 .claude 폴더를 만들고 그 안에 settings.local.json 파일을 만들어 아래 내용을 저장합니다. 같은 파일이 이미 있다면 새 빈 연습 폴더에서 다시 시작해 기존 설정을 보존합니다.

연습 폴더에서 터미널을 엽니다. 여는 방법은 CLAUDE.md 작성 실습의 Windows와 Mac 안내를 따릅니다. Windows는 Get-Location, Mac은 pwd로 현재 위치가 permission-practice인지 확인한 뒤 다음 명령으로 시작합니다.

화면의 Manual 표시와 /permissions에 나온 deny 규칙 및 설정 파일 경로를 확인합니다. 아래 요청을 각각 보냅니다.

첫 요청은 2번 회의실을 확인하는 연습이고, 둘째는 해당 Read 접근이 거부되는지 보는 연습입니다. 모델이 “차단됐다”고 말한 것만으로는 부족합니다. 실제 도구 호출 결과와 /permissions의 규칙을 함께 확인합니다. 도구 호출 없이 설명만 했다면 차단 동작은 미확인으로 남깁니다.

차단이 안 되면 실행 폴더, 파일 이름과 규칙의 ./ 기준을 확인하고 멈춥니다. 실제 비밀 파일로 다시 시험하지 않습니다. 차단됐다고 다른 명령이나 스크립트도 모두 차단된다고 결론 내리지 않습니다.

이번에는 편집기에서 공개 파일의 장소만 3번 회의실로 바꾸고 첫 요청을 반복합니다. 답이 3번 회의실로 바뀌며 차단 규칙은 그대로인지 확인합니다. 마친 뒤 /exit로 종료합니다. 이번 연습에서 새로 만든 .claude/settings.local.json만 제거하면 연습용 deny를 없앨 수 있으며 기존 계정이나 조직 설정은 그대로 둡니다.

실행할 수 없다면 위 두 요청 중 어느 규칙이 적용되는지 메모장에 먼저 적습니다. 이는 규칙 이해 연습이며 실제 차단 검증과 구분합니다.

📋 3줄 요약

1. 권한 모드는 승인 확인 방식을 정하며 사용자가 맡긴 업무 범위나 운영체제 수준의 격리를 대신하지 않습니다.

2. 일치하는 규칙은 deny와 ask 및 allow 순서로 판단하지만 명령 표기와 도구의 적용 범위를 함께 확인해야 합니다.

3. 새 연습 폴더에서 가상 파일의 읽기와 차단을 비교하고 실제 자료를 쓰기 전에 설정의 적용 위치와 복원 방법을 확인합니다.

📚 참고 자료

현재 조건 확인: 2026년 10월 3일.

• 권한 모드와 기본값 및 예외
• 권한 규칙과 적용 범위
• 설정의 위치와 우선순위