Claude Code 권한 모드 선택하기

배너를 추가해 달라고 했는데 에이전트가 오래된 모듈까지 업데이트하겠다고 제안합니다. 수정하기 전에 이런 계획을 확인하고 불필요한 항목을 빼면 좋습니다. 그러려면 요청을 명확히 작성하고 작업 모드도 알맞게 선택해야 합니다.

권한 모드는 Claude Code가 작업을 허용받는 방식을 정합니다. 어떤 작업은 바로 실행할 수 있고, 어떤 작업은 확인을 요청하며, 어떤 작업은 차단됩니다. 개별 작업에는 설정과 이미 부여된 권한도 영향을 줍니다. 모드 자체가 결과의 품질을 검증하지는 않습니다.

터미널에서 실행하는 로컬 Claude Code 세션을 예로 들어 각 모드를 살펴보겠습니다.

요청과 권한

겉보기에는 비슷하지만 실제로는 다르게 작동하는 두 가지를 혼동하기 쉽습니다.

첫 번째는 작업 요청에 적는 내용입니다. 예외 항목, "먼저 계획을 보여 주고 아무것도 바꾸지 마세요"라는 문장, 수정하면 안 되는 파일 목록 같은 것이죠. 이것은 의미상의 경계입니다. 작업을 설명해 주고 에이전트가 무엇을 제안할지에도 큰 영향을 줍니다. 하지만 어디까지나 텍스트이므로 기술적인 권한을 바꾸지는 않습니다.

두 번째는 권한 모드, 즉 permission mode입니다. 세션 설정의 일부입니다. "아무것도 바꾸지 마세요"라고 요청하면서 변경 사항을 자동으로 적용하는 모드로 작업할 수도 있습니다. 에이전트는 요청을 따라야 하지만, 그 문장만으로 변경을 기술적으로 차단할 수는 없습니다.

부분적으로만 적용되는 예외가 하나 있습니다. auto 모드에서는 분류기가 대화 내용을 읽고 "push하지 마세요" 또는 "내 리뷰를 기다리세요"를 해당 작업을 차단하라는 신호로 받아들입니다. 하지만 이것은 설정 규칙이 아닙니다. 컨텍스트를 압축하면서 금지 문구가 빠지면 금지도 함께 사라집니다. 확실한 경계가 필요하다면 문장이 아니라 설정을 사용해야 합니다.

안전한 모드에서 위험한 모드까지

모드를 목록으로 외우기보다 단계가 있는 사다리로 생각하면 편합니다. 위쪽에서는 에이전트가 여러분 없이는 거의 아무것도 하지 않고, 아래쪽에서는 전혀 묻지 않습니다. 다섯 단계에 더해 이 순서에 들어맞지 않는 모드가 하나 있습니다.

여기서 볼 것은 여러분의 응답 없이 통과하는 작업이 얼마나 많은가입니다. 위에서 아래로 갈수록 그 수가 늘고, 실수의 대가도 커집니다. 위쪽에서는 확인에 시간을 쓰고, 아래쪽에서는 변경이 잘못된 뒤에야 알게 됩니다.

각 모드를 간단히 살펴보겠습니다.

• plan - 에이전트가 프로젝트를 조사하고 구현 전에 변경 사항을 제안합니다. 이때 소스 파일 수정은 차단됩니다. 예외가 하나 있습니다. 세션을 bypassPermissions 허용 상태로 시작했다면 터미널에서는 계획 모드가 수정을 막지 않고, 에이전트에게 변경하지 말라고 요청할 뿐입니다. 코드에 대한 답변만 원하고 코드 변경은 바라지 않을 때 적합합니다. auto 사용이 허용된 경우 조사 명령도 분류기가 검사하므로, default보다 확인 요청이 적을 수도 있습니다. 계획 모드는 소스 파일을 바꾸지 않기 때문에 단계의 위쪽에 있습니다. 계획이 완성되면 Claude Code가 다음 단계를 묻습니다. auto로 전환해 승인하거나, 수동 확인을 거쳐 변경하도록 승인하거나, 계획을 더 세울 수 있습니다.
• default, 화면에서는 보통 Manual로 표시됩니다. 수정, 명령 실행, 네트워크 접근 전에 확인을 요청합니다. 프로젝트 읽기와 이미 부여된 권한은 확인 없이 진행되므로 모든 작업을 매번 승인할 필요는 없습니다. 무해해 보이는 명령에도 확인이 뜰 때가 있습니다. 괜한 트집은 아닙니다. find에 -exec 플래그를 붙이면 임의의 명령을 실행할 수 있고, -delete는 찾은 항목을 삭제하므로 여러분의 확인 없이는 실행되지 않습니다.
• acceptEdits, 화면에서는 "accept edits"로 표시됩니다. 작업 폴더의 파일 변경 사항과 rm, mv를 포함한 일부 파일 명령을 직접 적용합니다. 어차피 나중에 다시 읽어 볼, 잘 아는 파일을 빠르게 수정할 때 쓰는 모드입니다.
• auto - 대부분의 작업을 직접 수행합니다. 작업 폴더의 읽기와 수정은 바로 진행하고, 명령과 네트워크 접근은 별도의 모델인 분류기가 검사합니다. 일부 작업은 차단되며, 자세한 내용은 뒤에서 다룹니다.
• bypassPermissions - --dangerously-skip-permissions 플래그로도 켤 수 있으며, 거의 아무것도 묻지 않습니다. 설정에 명시한 규칙(거부와 "항상 확인")과 몇 가지 시스템 안전장치만 남습니다. YOLO라고도 부르는데, 이름 그대로입니다.

여섯 번째 모드인 dontAsk가 그림에서 따로 떨어져 있는 이유를 살펴보겠습니다. 각 단계는 여러분의 응답 없이 통과하는 작업의 양이 다르며, 아래로 갈수록 에이전트가 더 많은 작업을 할 수 있습니다. dontAsk는 반대 방식입니다. 묻지 않는다는 점은 같지만, 승인하는 대신 거부합니다. 일반 모드에서도 질문이 필요 없는 작업(작업 폴더의 파일 읽기, 읽기 전용의 안전한 명령)과 미리 허용한 작업은 실행합니다. 질문이 필요했을 작업은 질문 없이 모두 거절합니다. 세션은 응답을 기다리지 않습니다. 자동화된 시나리오나 폐쇄된 환경처럼 답할 사람이 없는 곳에서 유용하지만, 키보드 앞에서 직접 작업할 때는 쓸 일이 없습니다.

모드는 채팅으로 요청하는 게 아니라 직접 전환합니다. 터미널에서는 Shift+Tab으로 모드를 차례로 바꾸거나 /plan 명령으로 계획 모드에 들어갈 수 있습니다. 시작할 때 모드를 지정하는 방법도 있습니다.

claude --permission-mode plan

명령은 프로젝트 폴더에서 터미널에 입력하고, /plan은 이미 열린 세션에서 실행합니다. 에디터에서는 전환 메뉴가 다르게 생겼고 입력란 아래에 있습니다. 어디서든 현재 모드 표시기를 기준으로 삼으세요.

이 단계들을 과대평가하지 않도록 두 가지를 기억하세요. 계획 모드는 백업이 아닙니다. 되돌아갈 지점을 만들거나 이미 한 일을 취소하지 않고, 계획이 변경 사항으로 이어지기 전에 먼저 보여 줄 뿐입니다. 또 어느 단계도 작업 범위를 바꾸지 않습니다. 범위는 여러분이 요청에 적은 그대로입니다.

auto가 도움보다 방해가 될 때

auto에 대해 미리 바로잡아 둘 기대가 하나 있습니다. 모드 이름이 "자동"이라 모든 작업이 다 통과할 것 같지만, 그렇지 않습니다. 분류기는 일부 작업을 중단하기 위해 존재합니다.

기본적으로 차단되는 작업에는 프로덕션 배포와 마이그레이션, 외부 주소로 데이터 전송, 강제 push, 클라우드 저장소의 대량 삭제, 권한 부여, 네트워크에서 코드를 다운로드하고 실행하는 작업, 세션 시작 전에 존재하던 파일의 복구 불가능한 삭제가 있습니다. 공통점은 직접 되돌릴 수 없는 작업이라는 것입니다.

그다음 동작은 차단이 몇 번 발생했는지에 따라 달라집니다. 한 번 차단된 작업은 최근 거부 목록(/permissions의 Recently denied 탭)에 표시되며, 여기서 수동 확인을 거쳐 다시 실행할 수 있습니다. 그동안 Claude는 거부 응답을 받고 다른 방법을 시도합니다. 분류기가 연속 세 번 또는 한 세션에서 스무 번 차단하면 모드가 일시 중지되고 Claude Code는 평소처럼 확인을 요청하는 방식으로 돌아갑니다. 여러분이 확인하면 auto를 다시 켭니다. 기준 횟수는 고정되어 있어 변경할 수 없습니다.

이런 상황에서 모드가 방해가 되기 시작합니다. 작업에 문제가 될 만한 명령이 하나뿐이라면 auto는 의도한 대로 작동합니다. 직접 허용하고 계속 진행하면 됩니다. 하지만 작업 대부분이 그런 명령이라면, 예를 들어 테스트 환경을 구축하거나 마이그레이션을 실행하거나 다른 사람의 인프라에서 작업할 때는 흐름이 어색해집니다. 결국 거의 모든 단계를 직접 확인해야 하는데, 불필요한 과정까지 늘어납니다. 에이전트는 차단에 부딪혀 다른 방법을 찾고, 모드는 일시 중지됐다가 다시 켜집니다.

이럴 때는 사다리에서 더 위쪽 모드로 직접 바꾸는 편이 간단합니다. 어느 모드를 쓸지는 무엇이 불편한지에 따라 달라집니다.

• default - 가장 단순한 선택입니다. 수정과 명령마다 확인을 요청하며, 거부되는 작업은 없습니다. 느리지만 모든 단계가 눈에 보입니다.
• acceptEdits - 파일 변경은 괜찮지만 배포나 마이그레이션 같은 명령이 걱정될 때 선택할 수 있습니다. 다만 작업 폴더에서 rm과 mv 명령은 확인 없이 통과합니다. auto에서는 분류기가 기존 파일 삭제를 차단했습니다.

이것은 차단을 우회하는 방법이 아니므로 혼동하지 마세요. 검사를 끄는 게 아니라 여러분이 직접 확인하는 것입니다. 디스크 루트나 홈 폴더 같은 시스템 경로를 삭제하는 작업은 bypassPermissions에서도 여러분의 확인 없이는 진행되지 않습니다. 이 모드와 auto에서는 Claude Code가 여러분에게 확인을 요청하며, 터미널에서는 답할 시간이 몇 분 주어집니다. 물어볼 방법이 없는 경우 auto는 해당 명령을 거부하고, dontAsk는 항상 거부합니다. 여기서 말하는 것은 어차피 직접 확인할 작업이라면 불필요한 단계를 줄이자는 뜻입니다.

더 위쪽 모드로 바꾸는 두 번째 이유는 차단과 관계가 없습니다. 분류기는 작업이 위험한지는 판단하지만, 작업이 올바른 방향으로 진행되는지는 판단하지 않습니다. 에이전트가 같은 부분을 세 번째로 수정해도 결과가 여전히 잘못됐다면 auto에서는 묻지 않고 네 번째 시도를 할 뿐입니다. Claude Code 개발자들은 이럴 때 계속 밀어붙이지 말고 plan으로 돌아가 계획을 다시 합의한 뒤에 진행하라고 권합니다. 시작할 때도 같은 원칙이 적용됩니다. 여러분이 전체를 이해하고 있는 작업은 더 자유로운 모드에 바로 맡길 수 있습니다. 원하는 결과가 무엇인지 아직 확신이 없다면 plan부터 시작하세요.

실제 작업에서 달라지는 점

일상적인 작업에서는 네 가지 습관으로 정리할 수 있습니다.

1. 작업을 시작할 때 표시기를 확인하세요. 현재 모드를 보여 줍니다. 개별 작업에는 이미 부여된 권한도 중요합니다.
2. 실행 전에 제안된 계획이 작업 범위에 맞는지 확인하세요. 불필요한 항목은 말로 수정할 수 있고, 이것이 가장 부담이 적은 수정입니다.
3. 계획을 승인할 때 선택하는 항목의 문구를 읽으세요. plan을 종료한 뒤 어떤 모드에서 세션이 계속될지 알려 줍니다.
4. 작업이 끝난 뒤 결과를 확인하세요. 어떤 모드도 작업이 올바르게 해결됐는지 보장하지 않습니다. 그 판단은 여러분의 확인에 달려 있습니다.

권한 모드는 "내가 없어도 무엇을 할 수 있는가"에 대한 답이지, "제대로 했는가"에 대한 답은 아닙니다. 어떤 모드를 선택하더라도 두 번째 질문의 답은 여전히 여러분의 몫입니다.