Claude Code 플랜 모드와 권한 설정으로 안전하게 작업하기 - 실수로 파일을 건드리지 않으려고 정리한 기록

Claude Code 플랜 모드와 권한 설정으로 안전하게 작업하기 - 실수로 파일을 건드리지 않으려고 정리한 기록

개발 도구 사용기

공식 문서와 실제 사용 경험을 기준으로 정리했습니다.

AI 도구에게 코드 작업을 맡길 때 가장 신경 쓰이는 건 "시키지도 않은 파일을 고치면 어쩌지" 하는 부분입니다. Claude Code에는 이런 걱정을 덜어 주는 두 가지 장치가 있습니다. 먼저 계획만 세우고 실제 수정은 하지 않는 플랜 모드(Plan Mode), 그리고 어떤 작업을 자동 허용·확인·차단할지 미리 정해 두는 권한 설정(Permissions)입니다. 이 글은 플랜 모드와 권한 설정을 어떻게 쓰면 실수로 파일을 건드리는 일을 줄일 수 있는지 공식 문서를 기준으로 정리한 기록입니다. 명령과 동작은 버전에 따라 달라질 수 있으니 본문에 적은 공식 문서를 함께 확인하시길 권합니다.

먼저 계획만 보고 싶을 때 — 플랜 모드

플랜 모드는 이름 그대로, Claude가 실제 수정 없이 조사하고 계획만 제시하게 하는 모드입니다. 공식 문서의 설명을 옮기면, 이 모드에서 Claude는 파일을 읽고 셸 명령으로 코드베이스를 탐색해 계획을 작성하지만 소스는 편집하지 않습니다.

덕분에 "이 작업을 어떻게 진행할 생각인지" 먼저 확인한 뒤에 실행 여부를 결정할 수 있습니다. 큰 변경이나 낯선 코드베이스를 다룰 때, 곧바로 파일을 고치기 전에 방향부터 점검하는 용도로 쓰기 좋았습니다.

플랜 모드로 들어가고 나오기

공식 문서 기준으로 플랜 모드를 켜는 방법은 몇 가지입니다.

• 대화 중 Shift+Tab으로 모드를 순환할 수 있습니다(기본 → 편집 자동 승인 → 플랜 모드 순).
• 실행할 때 플래그로 지정: claude --permission-mode plan
• 계획을 다 세운 뒤에는 Claude가 계획을 제시하고 어떻게 진행할지 물어봅니다. 여기서 승인하면 실제 작업 모드로 넘어가고, 더 다듬고 싶으면 계획을 계속 수정할 수 있습니다.

플랜 모드라고 해서 권한 확인이 사라지는 것은 아닙니다. 공식 문서는 이 모드에서도 권한 프롬프트가 평소처럼 적용된다고 설명합니다. 즉 "탐색은 하되 수정은 승인 뒤에"라는 안전장치가 이중으로 걸리는 셈입니다.

권한 모드 — 얼마나 자동으로 맡길지 정하기

권한 설정의 출발점은 "작업을 얼마나 자동으로 승인할지"를 정하는 권한 모드입니다. 공식 문서에 정리된 대표적인 모드는 다음과 같습니다.

모드	동작
default (기본)	각 작업을 그때그때 확인받고 진행
acceptEdits	파일 편집을 자동 승인(반복 확인 줄이기)
plan	읽기 전용으로 탐색·계획만, 수정은 안 함
bypassPermissions	모든 확인을 건너뜀(격리·신뢰된 환경에서만 권장)

bypassPermissions는 확인 절차를 통째로 건너뛰기 때문에, 문서도 격리된 안전한 환경에서만 쓰기를 권합니다. 평소에는 default로 확인을 받다가, 편집이 많은 구간에서 acceptEdits로 잠깐 바꾸는 정도가 무난했습니다.

허용·확인·차단 규칙 — allow / ask / deny

모드가 "전체 분위기"를 정한다면, 세밀한 규칙은 settings.json의 permissions에서 정합니다. 도구별로 allow(자동 허용), ask(실행 전 확인), deny(차단) 목록을 둘 수 있습니다.

// .claude/settings.json
{
  "permissions": {
    "allow": ["Bash(npm run test:*)", "Read(src/**)"],
    "ask":   ["Bash(git push:*)"],
    "deny":  ["Read(.env)", "Bash(rm:*)"]
  }
}

규칙은 도구 이름과 괄호 안 매처로 적습니다. 예를 들어 Bash(npm run test:*)는 그 명령으로 시작하는 실행을 허용하고, Read(.env)를 deny에 두면 민감한 환경 변수 파일을 아예 읽지 못하게 막을 수 있습니다. Read·Edit·Bash·WebFetch(domain:...) 같은 도구별로 각자의 매처를 쓸 수 있습니다.

규칙이 겹칠 때는 공식 문서 기준으로 deny → ask → allow 순으로 평가되어, 차단 규칙이 가장 우선합니다. 그래서 "이건 절대 안 됨"에 해당하는 것부터 deny로 못 박아 두는 편이 안전했습니다.

설정을 어디에 두느냐 — 파일 계층

권한과 설정은 적용 범위에 따라 여러 위치에 둘 수 있고, 위치마다 우선순위가 다릅니다. 공식 문서 기준으로 정리하면 다음과 같습니다.

위치	범위 · 우선순위
엔터프라이즈(관리형)	조직 전체 · 가장 높음(개인이 못 덮음)
로컬 .claude/settings.local.json	내 프로젝트 개인용(버전 관리 제외)
프로젝트 .claude/settings.json	팀과 공유하는 프로젝트 규칙
사용자 전역 ~/.claude/settings.json	내 모든 프로젝트 공통 · 가장 낮음

권한 규칙은 여러 위치의 것이 합쳐지는데, 공식 문서에 따르면 어느 위치든 deny가 있으면 다른 곳의 allow보다 차단이 우선합니다. 조직이 막아 둔 명령은 개인 설정으로 열 수 없다는 뜻입니다. 팀 공용 규칙은 프로젝트 파일에, 나만의 설정은 로컬 개인용 파일에 나눠 두면 서로 충돌 없이 겹쳐 쓸 수 있었습니다.

대화 중에 확인·편집하기 — /permissions

설정 파일을 직접 열지 않아도, 대화 중 /permissions 명령으로 현재 적용된 권한 규칙과 그 출처를 볼 수 있습니다. 여기서 규칙을 추가·수정·삭제할 수 있어, 매번 같은 확인을 받는 도구가 있으면 그 자리에서 allow로 옮겨 두는 식으로 정리했습니다.

작업 디렉터리 밖의 폴더에 접근해야 할 때는 --add-dir 플래그나 대화 중 /add-dir 명령으로 추가 디렉터리를 허용할 수 있고, 영구적으로 두려면 permissions.additionalDirectories에 경로를 적어 둘 수 있습니다.

써보며 걸렸던 점

• 처음부터 자동 승인은 부담 — 익숙해지기 전에는 default로 하나씩 확인받는 편이 마음이 편했습니다. 흐름이 익으면 편집 구간만 acceptEdits로 바꿨습니다.
• deny를 먼저 정함 — "절대 건드리면 안 되는 것"(예: 비밀 키 파일 읽기, 삭제 명령)을 deny로 못 박아 두니 나머지를 느슨하게 열어도 덜 불안했습니다.
• 개인 규칙은 로컬 파일에 — 나만 쓰는 허용 규칙을 팀 공유 파일에 적었다가 혼선을 준 적이 있어, 로컬 개인용 파일로 옮겼습니다.
• 큰 작업은 플랜 모드로 먼저 — 곧바로 시키기보다 플랜 모드로 방향을 본 뒤 승인하니, 엉뚱한 파일을 고치는 일이 줄었습니다.

자주 묻는 질문

Q. 플랜 모드에서도 파일이 수정될 수 있나요?

공식 문서 기준으로 플랜 모드는 조사·계획만 하고 소스를 편집하지 않습니다. 실제 수정은 계획을 승인해 작업 모드로 넘어간 뒤에 이뤄집니다.

Q. allow와 deny가 겹치면 어떻게 되나요?

deny가 우선합니다. 문서에 따르면 규칙은 deny → ask → allow 순으로 평가되어, 차단 규칙이 있으면 다른 곳의 허용보다 앞섭니다.

Q. 팀 공용 설정과 개인 설정을 나눌 수 있나요?

네. 팀과 공유할 규칙은 프로젝트의 .claude/settings.json에, 나만의 설정은 버전 관리에서 제외되는 .claude/settings.local.json에 나눠 둘 수 있습니다.

마무리

정리하면, 곧바로 시키기 전에 계획부터 보고 싶으면 플랜 모드로 방향을 확인하고, 어떤 작업을 자동으로 맡길지는 권한 모드와 allow/ask/deny 규칙으로 정해 두면 됩니다. 여기에 deny를 먼저 못 박고, 팀 공용과 개인 규칙을 파일로 나눠 두는 것만으로도 "실수로 파일을 건드리는" 상황을 꽤 줄일 수 있었습니다. 처음에는 default 모드로 하나씩 확인받다가, 익숙해지면 반복되는 것만 allow로 옮겨 가는 방식을 권합니다.

이 글의 기능 설명은 Claude Code 공식 문서를 기준으로 정리했습니다. 세부 구성과 명령은 버전에 따라 달라질 수 있으니, 최신 내용은 공식 문서에서 직접 확인하시길 권합니다.

• 권한 모드 문서: code.claude.com/docs/en/permission-modes
• 권한 설정 문서: code.claude.com/docs/en/permissions

※ 본 글은 공개된 공식 문서와 개인적인 사용 경험을 바탕으로 정리한 정보성 콘텐츠입니다. 도구의 기능·화면·명령은 버전에 따라 달라질 수 있으며, 특정 결과를 보장하지 않습니다.