클로드 코드 권한 설정 사용법: 파일 수정은 빠르게, 위험한 명령은 확인받는 법

TL;DR

Claude Code 권한 설정은 AI에게 모든 권한을 주거나 매번 멈추게 하는 선택이 아닙니다.

낯선 저장소에서는 plan 모드로 먼저 범위를 확인하고, 반복 편집은 acceptEdits 로 처리합니다. 삭제·배포·외부 연결처럼 되돌리기 어려운 작업은 ask 또는 deny 규칙으로 남겨 두는 방식이 안전합니다.

핵심 3줄 요약

• 핵심 1
  plan 모드는 파일을 고치지 않고 읽기와 읽기 전용 명령으로 작업 계획을 검토할 때 씁니다.
• 핵심 2
  acceptEdits 는 작업 디렉터리 안의 파일 편집과 일부 일반 파일 작업의 승인 부담을 줄입니다.
• 핵심 3
  권한 규칙은 deny , ask , allow 순서로 평가되므로 넓은 거부 규칙을 먼저 만들면 좁은 허용 규칙도 적용되지 않을 수 있습니다.

이 글에서 다룰 내용

코드 에이전트에게 파일 수정을 맡기면 속도는 빨라집니다. 문제는 속도가 아니라 경계입니다. 문서 오탈자를 고치는 일과 배포 명령을 실행하는 일은 같은 승인 규칙으로 다루기 어렵습니다.

Claude Code의 권한 기능은 이 경계를 나누는 도구입니다. 편집처럼 자주 반복하는 일은 흐름을 덜 끊고, 삭제·외부 전송·배포처럼 영향이 큰 작업은 사람이 확인하도록 설계할 수 있습니다.

Claude Code 권한은 어떻게 작동하나요?

한 문장 정의: Claude Code 권한은 읽기, 파일 수정, 명령 실행처럼 성격이 다른 도구 사용을 규칙과 모드로 나눠 승인 범위를 관리하는 기능입니다.

Anthropic 공식 문서에 따르면 Claude Code는 읽기 전용 작업, Bash 명령, 파일 수정에 서로 다른 승인 흐름을 둡니다. 읽기 전용 작업은 작업 디렉터리와 추가 디렉터리 안에서 기본적으로 승인 없이 수행할 수 있습니다. Bash 명령은 읽기 전용 명령 일부를 제외하면 승인을 요구합니다. 파일 수정 승인은 세션이 끝날 때까지 유지될 수 있습니다.

권한을 관리할 때는 /permissions 를 먼저 확인합니다. 이 화면에서는 어떤 규칙이 적용되는지와 각 규칙이 어느 설정 파일에서 왔는지 볼 수 있습니다.

규칙은 세 종류입니다.

• allow : 지정한 도구나 작업을 별도 승인 없이 허용합니다.
• ask : 작업을 실행할 때마다 확인을 요청합니다.
• deny : 지정한 도구나 작업을 막습니다.

중요한 점은 규칙의 우선순위입니다. 공식 문서는 deny , ask , allow 순서로 규칙을 평가한다고 안내합니다. 예를 들어 넓은 deny 규칙이 먼저 맞으면, 그 안에 더 구체적인 allow 규칙을 넣어도 예외로 풀리지 않을 수 있습니다.

처음 여는 저장소에서는 plan 모드부터 시작합니다

처음 보는 프로젝트는 바로 수정하지 않는 편이 좋습니다. plan 모드는 Claude Code가 파일을 읽고 읽기 전용 셸 명령으로 구조를 살피되, 소스 파일을 수정하지 않도록 하는 모드입니다.

다음 상황에서 특히 유용합니다.

• 수정 범위가 여러 폴더에 걸칠 때
• 인증, 결제, 권한, 데이터 처리 코드가 섞여 있을 때
• 기존 테스트와 배포 흐름을 아직 모를 때
• 요청이 짧지만 실제 영향 범위가 클 때

예를 들어 “로그인 방식을 바꿔 달라”는 요청은 화면 하나만 고치는 일이 아닐 수 있습니다. 인증 API, 세션, 환경 변수, 사용자 데이터, 개인정보 안내문까지 함께 확인해야 할 수 있습니다.

이때는 먼저 다음 내용을 계획으로 받습니다.

1. 바뀌는 파일을 확인합니다

어떤 파일을 읽었는지와 수정 후보가 무엇인지 먼저 봅니다. 프로젝트 밖의 경로나 비밀값 파일까지 접근하려는 계획이 있으면 이유를 확인합니다.

2. 실행 전에 위험 작업을 표시하게 합니다

삭제, 배포, 외부 네트워크 호출, 데이터베이스 변경, 패키지 게시가 필요한지 계획 단계에서 분리합니다.

3. 테스트와 되돌리는 방법을 묻습니다

수정 뒤 어떤 테스트를 돌릴지, 문제가 생기면 어떤 변경을 되돌릴지 확인합니다.

4. 계획을 승인한 뒤 편집 모드로 전환합니다

계획이 납득될 때만 실제 편집을 맡깁니다. 계획 검토는 작업을 늦추는 절차가 아니라 불필요한 수정 범위를 줄이는 단계입니다.

acceptEdits는 어디까지 맡겨도 될까요?

acceptEdits 는 작업 디렉터리와 추가 디렉터리 안의 파일 편집, mkdir , touch , mv , cp 같은 일반 파일 작업을 자동 승인하는 모드입니다. 반복 편집 중 매번 승인 창을 처리하는 부담을 줄이는 데 맞습니다.

다음처럼 변경 범위가 분명하고 되돌리기 쉬운 작업에 잘 맞습니다.

• README, 변경 이력, 주석, 문서의 갱신
• 이미 정한 범위 안의 테스트 코드 추가
• 린트 오류와 오탈자 수정
• 특정 폴더 안의 파일명 또는 컴포넌트명 정리
• 계획에서 승인한 범위의 반복 리팩터링

반대로 acceptEdits 를 켰다고 모든 작업을 승인 없이 맡기는 것은 아닙니다. 이 모드는 위험한 Bash 명령까지 자동 허용하는 설정이 아닙니다.

다음 작업은 별도 확인을 남기는 편이 낫습니다.

• 배포, 패키지 게시, 외부 서비스 설정 변경
• 데이터베이스 마이그레이션과 초기화
• 대량 삭제나 Git 히스토리 변경
• 비밀값, 인증서, 운영 환경 설정을 다루는 작업
• 외부로 파일이나 데이터를 보내는 명령

편집이 끝나면 git diff 와 테스트 결과를 확인합니다. 승인 횟수를 줄이는 일과 변경 검토를 생략하는 일은 다릅니다.

권한 규칙은 넓게 허용하지 않습니다

권한 규칙은 가능한 한 작업과 경로를 좁혀 적는 편이 좋습니다. “Bash 전체 허용”처럼 넓은 규칙은 처음에는 편해 보여도, 나중에 어떤 명령이 자동 실행되는지 파악하기 어렵습니다.

안전한 시작점은 다음과 같습니다.

• 읽기와 탐색은 기본 흐름을 활용합니다.
• 파일 편집은 작업 디렉터리 안에서만 acceptEdits 로 처리합니다.
• 배포, 삭제, 외부 연결은 ask 규칙으로 남깁니다.
• 비밀값이나 운영 설정을 다루는 경로는 필요하면 deny 규칙으로 막습니다.

특히 bypassPermissions 모드는 격리된 컨테이너나 VM처럼 손상 범위를 제한할 수 있는 환경에서만 고려해야 합니다. Anthropic 공식 문서도 이 모드는 격리 환경에서만 사용하라고 안내합니다.

바로 복사해 쓰는 요청문

낯선 저장소를 처음 점검할 때

프롬프트: 이 저장소에서 [작업 목표]를 처리할 계획을 먼저 작성해 줘. 파일은 수정하지 말고 읽기와 읽기 전용 명령만 사용해. 수정할 파일, 새로 만들 파일, 실행이 필요한 명령, 외부 네트워크 호출 여부, 비밀값 접근 가능성, 테스트 방법, 되돌리는 방법을 목록으로 보여 줘. 삭제·배포·데이터베이스 변경·외부 전송이 필요하면 실행하지 말고 승인 항목으로 분리해.

반복 편집을 맡길 때

프롬프트: 작업 디렉터리 안에서 [대상 파일 또는 폴더]만 수정해 [결과물]을 만들어 줘. .env , 인증서, 배포 설정, 데이터베이스 관련 파일은 건드리지 마. 수정 전에 변경 파일 목록을 보여 주고, 수정 뒤에는 git diff 요약과 실행한 테스트 결과를 알려 줘. 삭제, 외부 전송, 패키지 게시, 배포 명령은 실행 전에 반드시 확인을 요청해.

권한을 정한 뒤에는 이렇게 점검합니다

첫 설정을 곧바로 실서비스 작업에 적용하지 않습니다. 작은 샘플 작업으로 규칙이 의도대로 작동하는지 확인합니다.

1. 안전한 파일 편집을 시험합니다

임시 Markdown 파일이나 테스트 파일 하나를 고치게 합니다. acceptEdits 가 예상한 범위에서만 작동하는지 봅니다.

2. 읽기 전용 명령을 확인합니다

저장소 상태 확인과 diff 확인처럼 영향이 작은 명령이 정상적으로 실행되는지 점검합니다.

3. 위험 작업은 승인 흐름을 확인합니다

삭제, 외부 연결, 배포를 실제로 실행하지 않아도 됩니다. Claude Code가 승인 대상으로 분리하는지 먼저 확인합니다.

4. 변경 뒤에는 사람이 검수합니다

변경 파일 목록, diff, 테스트 결과를 확인합니다. 권한 규칙은 AI가 할 수 있는 일을 늘리는 장치가 아니라, 사람이 어떤 시점에 판단할지를 정하는 장치입니다.

사용할 때 주의할 점

첫째, 권한 규칙은 프롬프트나 CLAUDE.md 지시와 다릅니다. 지시문은 Claude가 무엇을 시도할지에 영향을 주지만, 실제 허용과 차단은 권한 규칙, 권한 모드, PreToolUse hook이 결정합니다.

둘째, “Yes, don’t ask again”으로 저장한 일부 명령 권한은 이후 세션에도 적용될 수 있습니다. 승인한 범위가 생각보다 넓지 않은지 /permissions 에서 주기적으로 확인합니다.

셋째, 기능과 표기 방식은 Claude Code 버전에 따라 달라질 수 있습니다. 특히 manual 표기와 별칭은 공식 문서에서 Claude Code v2.1.200 이상을 기준으로 설명합니다. 실제 화면과 설치 버전을 함께 확인합니다.

주의: 승인 창이 줄었다고 보안 검토가 끝난 것은 아닙니다. 비밀값, 배포, 삭제, 외부 전송은 자동화 편의성보다 영향 범위를 먼저 따져야 합니다.

자주 묻는 질문

acceptEdits를 켜면 모든 명령이 자동 실행되나요?

아닙니다. acceptEdits 는 파일 편집과 일부 일반 파일 작업의 승인 부담을 줄이는 모드입니다. 위험한 Bash 명령까지 전부 자동 허용하는 설정이 아닙니다.

plan 모드에서는 무엇을 할 수 있나요?

공식 문서 기준으로 plan 모드는 파일을 읽고 읽기 전용 셸 명령으로 저장소를 탐색할 수 있습니다. 소스 파일은 수정하지 않습니다.

권한을 완전히 끄는 bypassPermissions 모드는 언제 쓰나요?

손상 범위를 격리할 수 있는 컨테이너나 VM에서만 고려합니다. 공식 문서도 이 모드는 격리 환경에서만 사용하라고 안내합니다.

deny 규칙 안에 allow 예외를 둘 수 있나요?

주의가 필요합니다. 공식 문서는 deny , ask , allow 순서로 규칙을 평가한다고 설명합니다. 넓은 deny 규칙이 맞으면 좁은 allow 규칙으로 예외를 만들 수 없으므로, 규칙 범위를 먼저 다시 나누는 편이 낫습니다.

마무리

Claude Code를 안전하게 쓰는 방법은 승인 창을 많이 띄우는 데 있지 않습니다. 반복 편집은 빠르게 넘기고, 되돌리기 어려운 작업만 사람이 확인하도록 경계를 나누는 데 있습니다.

처음에는 plan 모드로 저장소를 살펴보고, 작은 범위의 편집에서만 acceptEdits 를 시험해 보세요. 이후에도 diff와 테스트를 확인하면 작업 속도와 통제력을 함께 유지할 수 있습니다.