권한 모드와 사람의 확인 단계

Claude Code에 일을 맡기면 곧바로 코드를 쓰기 시작하지 않습니다. 먼저 파일을 읽고, 관련된 로직을 따라가며 코드베이스의 그림을 그립니다. 이 단계가 탐색입니다.

충분히 파악해서 바꿀 내용을 제안할 수 있게 되면, 그다음에 계획을 만듭니다. 계획은 어떤 편집을 할지 구조를 잡아 적은 설명입니다. 사람이 그 계획을 검토하고 승인한 뒤에야 코드 단계로 넘어가, 실제로 변경을 쓰고 실행합니다.

이 순서가 중요한 데는 이유가 둘 있습니다. 하나는 결과의 질입니다. 무언가를 건드리기 전에 코드베이스를 먼저 이해하기 때문에, 넘겨짚는 부분이 줄고 뒤따르는 영향을 더 많이 잡아냅니다. 다른 하나는 권한 모드가 끼어드는 자리가 바로 여기라는 점입니다. plan 모드는 Claude Code를 탐색 단계에 붙들어 두고, 사람이 풀어 줄 때까지 파일 편집과 셸 명령을 모두 막습니다. 낯선 코드베이스나 위험이 큰 작업에서 기본값으로 삼기 좋은 이유입니다.

권한 모드는 Claude Code가 확인을 물으려고 멈추는 빈도를 조절합니다. 모드마다 속도와 점검 사이의 균형을 다르게 잡습니다. 어떤 모드가 맞는지는 코드베이스를 얼마나 잘 아는지, 그리고 변경을 얼마나 쉽게 되돌릴 수 있는지에 따라 달라집니다.

여섯 가지 모드가 각각 무엇을 자동으로 승인하고, 무엇은 여전히 확인을 요구하며, 어떤 한계가 있는지 정리하면 다음과 같습니다.

SIX MODES — 여섯 가지 권한 모드

권한 모드를 정했다면, 그 규칙을 어디에 적어 둘지가 다음 문제입니다. 설정은 여러 층위에 둘 수 있고, 층위마다 규칙이 미치는 범위가 달라집니다.

SETTINGS SCOPE — 설정을 두는 네 층위

허용 규칙과 차단 규칙은 선택한 모드 위에 겹쳐서 적용됩니다. 그리고 차단 규칙은 어떤 모드에서든 허용 규칙을 이깁니다. 가장 오래가는 통제는 엔터프라이즈 층위의 차단 규칙입니다. 개별 개발자가 지울 수 없고, bypass 모드가 걸려 있어도 그대로 적용되기 때문입니다.

권한 모드와 차단 규칙은 에이전트가 무엇을 묻지 않고 할 수 있는지를 정합니다. 하지만 어떤 동작이 반영되기 전에 사람이 어디를 직접 봐야 하는지까지 정해 주지는 않습니다. 그건 한 가지 질문으로 판단합니다. 안전한 모드와 위험한 모드를 가르는 것과 같은 질문입니다. 이 동작이 사람의 확인 없이 실행되면, 최악의 경우 무슨 일이 벌어질까?

잘못됐을 때 감수할 위험이 작을수록 더 많이 통과시켜도 됩니다. 위험이 크고 되돌리기 어려울수록, 실행 전에 사람이 확인하는 단계를 두는 편이 좋습니다.

같은 질문이 확인 단계를 어디에 둘지도 정합니다. 에이전트가 코드를 쓸 때든, 풀 리퀘스트에 코멘트를 달거나 막는 봇처럼 사람 없이 자동으로 실행될 때든 똑같습니다. 여기서 배치가 세 가지로 갈립니다.

• 위험이 작고 되돌릴 수 있는 동작은 확인 없이 통과시킵니다. 형식을 맞추는 수정이나 작업 디렉터리 안에 갇힌 편집은 잘못돼도 감수할 위험이 작습니다. 이런 것마다 사람의 승인을 요구하면, 필요 없는 점검만 늘고 일이 느려집니다. acceptEdits가 이런 경우를 위해 만들어진 모드입니다.
• 되돌리기 어렵거나 민감한 경로에 닿는 동작에는 확인 단계를 둡니다. 작업 디렉터리 밖 쓰기, 파괴적 셸 명령, 보안과 관련되거나 보호된 파일의 편집이 여기에 해당합니다. 잘못됐을 때 위험이 크므로, 에이전트가 실행 전에 멈추고 그 동작을 사람 앞에 내놓도록 두는 편이 안전합니다. 차단 규칙은 이를 예외 없이 강제하고, default나 plan 모드는 사람이 판단하는 동안 확인 창을 유지합니다.
• 팀이 민감하다고 표시한 코드에 대한 변경이라면, 에이전트 하나만 확인 장치로 두지 않습니다. 여기서 에이전트의 작업은 사람의 판단을 대신하는 것이 아니라 판단의 재료입니다. 에이전트나 그 자체 검토가 아무리 확신에 차 있어도, 병합 전에 사람이 변경을 직접 검토합니다.

확인 단계를 어디에 둘지와 어떤 권한 모드를 고를지는, 사실 하나의 결정을 양쪽에서 본 것입니다. 모드는 세션 전체의 기본값을 정하고, 확인 단계는 그 기본값에 맡기기엔 위험이 너무 큰 한 동작에서 기본값을 덮어쓰는 자리입니다. 둘 다 "이게 확인 없이 실행되면 무엇이 깨질까"라는 하나의 질문에서 나옵니다.

COST · COMPLEXITY · RISK — 함께 따져 볼 세 가지

확인이 자꾸 뜨는 게 번거로워서 bypassPermissions로 바꿨다고 해 봅시다. 작업이 익숙하게 느껴졌기 때문입니다. 에이전트는 며칠째 얌전히 잘 움직였고, 정리 작업은 단순했고, 도구 호출마다 확인을 묻는 동작이 불필요한 마찰처럼 느껴졌습니다.

다음은 사흘 동안 별문제 없이 이어지던 코드베이스 정리 작업에서 오간 짝 프로그래밍 기록입니다.

TRANSCRIPT — 정리 작업 중 오간 대화

개발자: "이번 건 bypassPermissions로 바꿀게. 오래된 API 엔드포인트 이름만
        바꾸는 거야. 위험할 거 없어."
Claude Code: [ /v1/legacy/ 패턴에 맞는 파일 검색 중 … 47개 발견 ]
Claude Code: [ 엔드포인트 참조 갱신 중 … ]
Claude Code: [ 이름 변경 후 정리 스크립트 cleanup.sh 실행 중 … ]
Claude Code: [ /deploy/config/prod/ 안에서 /v1/legacy/ 패턴에 맞는 파일 3개 삭제됨 … ]
개발자: "잠깐. /deploy/config/prod/ 에 뭐가 있었지?"
Claude Code: [ 프로덕션 배포용 환경별 엔드포인트 설정 파일이었습니다. 삭제되었습니다. ]
개발자: "그 디렉터리는 작업 범위가 아니었어. 나는 /src/ 만 보고 있었는데."
Claude Code: [ /v1/legacy/ 패턴이 /src/ 와 /deploy/config/prod/ 양쪽 파일에
             걸렸습니다. bypassPermissions 모드에서는 삭제 전에 확인을
             요청하지 않았습니다. ]

이 실수를 잡아 줬을 확인 창은 bypassPermissions를 켜는 순간 함께 꺼졌습니다. default나 acceptEdits 모드였다면 정리 스크립트는 확인 없이 실행되지 않았을 것이고, 삭제가 프로덕션 설정 파일에 닿기 전에 멈출 수 있었을 것입니다. bypass 모드에서는 패턴이 의도보다 넓게 걸렸고, 스크립트와 그것이 지운 파일 사이에 아무 확인도 없었습니다.

게이트가 정확히 어디였는지 짚어 둘 필요가 있습니다. 확인을 띄웠을 지점은 rm 삭제 명령 자체가 아니라 스크립트 호출이었습니다. acceptEdits는 작업 디렉터리 안 경로에 대한 rm을 포함해 흔한 파일 명령을 자동으로 승인합니다. 만약 Claude가 삭제를 rm 명령으로 곧장 실행했다면 acceptEdits는 그대로 통과시켰을 것이고, 그런 명령에 확인을 묻는 것은 default 모드뿐입니다.

결제 모듈을 신뢰된 로컬 환경에서 리팩터링하도록 Claude Code를 설정하는 상황입니다. 조건은 셋입니다. 파일 편집은 자동으로 승인하되, 파괴적 셸 명령은 절대 실행되지 않아야 하고, .env.production 파일은 에이전트가 절대 읽을 수 없어야 합니다. 아래는 고를 수 있는 settings.json 조각들입니다.

settings.json · 조각 A–E

// Piece A
{ "permissions": { "defaultMode": "default" } }

// Piece B
{ "permissions": { "defaultMode": "bypassPermissions" } }

// Piece C
{ "permissions": { "allow": ["Bash(npm run:*)"],
                   "deny": ["Bash(rm:*)", "Bash(git push:*)"] } }

// Piece D
{ "permissions": { "deny": ["Read(.env.production)"] } }

// Piece E
{ "permissions": { "allow": ["Bash(*)", "Edit(*)"] } }

정답을 먼저 떠올려 본 뒤 골라 보세요. 맞히면 설명이 나옵니다. 조건에 맞는 조각은 모두 두 개입니다 — 앞의 두 문항이 그 둘을 하나씩 짚습니다.