Field Log · Entry

Claude Code 권한 설정 가이드 — allow / ask / deny와 permission mode 매트릭스 (5/8)

ruah · 2026-04-23 수정 2026-09-08 · 9분 읽기

Claude Code 권한 규칙은 deny → ask → allow 순서로 판단합니다. plan은 코드를 수정하지 않고 탐색하는 모드이며, auto는 요청과의 정합성을 검사하며 자동 승인하는 모드입니다. 권한 규칙, 도구 범위, 실행 환경의 격리를 함께 설계해야 읽기 전용 조사와 실제 변경을 구별할 수 있습니다.

이 글의 설정 문법은 2026년 9월 8일 공식 문서를 대조했습니다. 제품 기능과 조직 관리 정책에 따라 사용할 수 있는 모드가 달라지므로 실제 환경에서는 claude --version, /permissions, /hooks로 적용된 설정을 확인합니다. 예시는 최소 구조를 설명하며 특정 운영 환경의 침해 방지를 입증한 설정은 아닙니다.

allow·ask·deny는 무엇을 결정하나

공식 권한 문서는 deny, ask, allow의 순서를 명시합니다. 좁은 allow가 넓은 deny를 뒤집지 않습니다.

규칙	의미	예
`deny`	일치하는 도구 호출을 거절	리뷰어의 `Write`, `Edit`, `Bash` 차단
`ask`	일치하는 호출에 승인 요구	파일 변경이나 `git push`를 검토
`allow`	일치하는 호출의 승인을 생략	검증한 읽기 도구·명령 허용

규칙에 맞지 않는 호출은 현재 permission mode와 도구의 기본 동작에 따라 처리됩니다. “목록에 없으면 모두 ask”라고 가정하면 읽기 명령이나 자동 승인 모드를 잘못 이해하게 됩니다. 보안 관리 설정과 sandbox 정책도 함께 적용됩니다.

Permission mode를 작업 목적에 맞춘다

탐색과 변경의 경계를 먼저 고릅니다. mode는 세 종류로 고정된 목록이 아니며, 각 mode에서 명시한 deny 규칙이 우선한다는 원칙을 유지합니다.

모드	핵심 동작	사용 예
`default`	도구의 기본 승인 흐름을 사용	변경을 확인하며 작업
`plan`	소스를 수정하지 않고 읽기·탐색	변경 계획과 영향 조사
`acceptEdits`	파일 편집 등을 자동 승인	범위가 합의된 로컬 수정
`auto`	요청과 맞는지 안전 판단 후 자동 승인	조직/계정에서 허용한 자동 작업
`dontAsk`	사전 허용되지 않은 도구를 자동 거절	승인창을 처리할 사람이 없는 제한된 작업

claude --permission-mode plan
claude --permission-mode default

auto는 무조건 실행이나 sandbox 해제를 뜻하지 않습니다. plan도 “수정할 때마다 물어보는 학습 모드”가 아닙니다. 탐색을 끝낸 뒤 사용자가 승인한 변경을 수행할 때 적절한 변경 모드로 전환합니다. 며칠 사용했는지보다 허용 경로·도구·검증·복구 범위가 정해졌는지를 기준으로 삼습니다.

파일 변경은 묻고, 배포는 따로 묻는 예시

다음은 프로젝트 .claude/settings.json에 둘 수 있는 제한적 예시입니다. 도구 이름만 쓰면 해당 도구 전체를 지정합니다. Bash(git status *)처럼 프로그램과 하위 명령을 적고 인자 부분에 wildcard를 둡니다.

{
  "permissions": {
    "defaultMode": "default",
    "allow": ["Read", "Grep", "Glob", "Bash(git status *)"],
    "ask": ["Write", "Edit", "Bash(git push *)"],
    "deny": ["Bash(sudo *)"]
  }
}

이 예시가 모든 위험한 명령을 나열한 것은 아닙니다. Bash(DROP *)를 추가해도 psql -c ..., Python DB client, MCP tool로 실행하는 SQL까지 차단하는 규칙은 되지 않습니다. 실제 데이터베이스에는 읽기 전용 계정을 주고, 운영 자격 증명을 작업 환경에 제공할지부터 결정해야 합니다.

프로젝트 설정을 커밋하는 것과 팀원의 설치에 즉시 권한이 부여되는 것도 다릅니다. 사용자 설정·관리 정책·workspace 신뢰 여부와 설정 우선순위를 확인합니다.

읽기 전용 리뷰어는 도구부터 줄인다

리뷰어가 셸 실행을 필요로 하지 않는다면 subagent의 도구 pool을 좁힙니다. 공식 subagent 문서의 tools와 disallowedTools를 사용합니다.

name: code-reviewer
description: Review the requested code and report findings without edits.
tools: Read, Grep, Glob
disallowedTools: Write, Edit, Bash

이렇게 제한한 리뷰어는 셸을 통해 파일을 바꾸는 경로도 갖지 않습니다. 쓰기 가능한 다른 MCP 도구를 추가하면 경계를 다시 검토해야 합니다. tests/만 수정하라는 자연어 지시는 파일 접근 제어와 같지 않습니다.

실행 환경까지 신뢰 경계가 필요하면 OS 계정·sandbox·container/VM·네트워크·자격 증명 범위를 따로 제한합니다. worktree 격리는 파일 충돌을 줄이지만 OS 권한 격리를 대신하지 않습니다.

규칙 우선순위와 훅의 역할

deny 다음 ask 다음 allow를 평가하며 실행 전후 훅과 OS 격리의 책임을 구분하는 권한 흐름

규칙의 우선순위: deny → ask → allow
규칙에 일치하지 않음: 현재 mode와 도구 기본 동작 확인
실행 전: PreToolUse와 적용된 정책으로 거절·검사 가능
실행 후: PostToolUse로 결과 확인

이 그림은 규칙 우선순위를 설명하며 내부 구현의 모든 호출 순서를 나열하지 않습니다. 현재 공식 문서는 PreToolUse가 allow를 반환해도 명시한 deny/ask가 유지된다고 설명합니다. 실행 이후 훅은 이미 일어난 수정을 되돌리는 사전 방화벽이 아닙니다.

Hooks는 stdin JSON을 읽는 프로그램이다

공식 hooks 문서의 command hook은 JSON을 stdin으로 받습니다. matcher 아래에 hooks 배열을 두고 각 handler에 type을 지정합니다.

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/check_changed_file.py\""
      }]
    }]
  }
}

위 예시는 bash 계열 환경용입니다. 검증 script를 .claude/hooks/check_changed_file.py로 저장하고 프로젝트에 ESLint를 설치·설정해야 합니다. Script는 tool_input.file_path를 읽고 프로젝트 밖 경로를 거절한 뒤 npx --no-install eslint -- <path>를 shell 문자열 결합 없이 실행합니다. 변경을 자동 수정하지 않고 오류를 보고합니다.

eslint ... | tail은 기본 shell에서 마지막 명령의 성공 상태로 ESLint 실패를 가릴 수 있습니다. 예제는 lint 진단을 stderr로 보내고 오류 시 exit 2를 반환합니다. PostToolUse의 exit 2는 모델에 실패를 전달하며 이미 수행한 도구 실행을 취소하지 않습니다. 상세 검증 루프는 8편에서 이어집니다.

설정을 적용한 뒤 확인할 네 가지

/permissions와 /agents에서 실제 적용된 규칙·도구를 확인합니다.
허용된 읽기가 되고 금지한 쓰기/셸 도구가 거절되는지 무해한 임시 파일로 확인합니다.
/hooks와 debug log에서 Write와 Edit가 모두 검사되는지 봅니다.
실패하는 lint fixture를 넣어 실패가 성공으로 표시되지 않는지 확인합니다.

로컬 script 테스트가 통과해도 Claude Code의 전체 권한 체계를 테스트한 것은 아닙니다. 설치 버전의 실제 세션에서 이 네 가지를 확인한 뒤 운영에 적용합니다.

블로그 운영에서 중요했던 경계

이 블로그는 git push가 배포로 이어지므로 로컬 글 수정과 공개 상태 변경의 영향이 다릅니다. 제게 권한 설계의 핵심은 허용 목록을 길게 만드는 일이 아니라, 읽기·수정·배포 중 어느 경계를 넘는지를 분명히 하는 일이었습니다. 일정 기간 사용했다는 이유만으로 권한을 늘리지 않고 작업별 완료 검증과 복구 방법을 함께 둡니다.

자주 묻는 질문

allow와 deny에 동시에 맞으면 어떻게 되나요? deny가 우선합니다. ask와 allow가 동시에 맞으면 ask가 우선합니다.

plan에서 쓰기를 승인하면 바로 수정하나요? plan은 탐색 모드입니다. 실제 변경은 승인한 범위를 확인하고 적절한 변경 모드에서 수행합니다.

PostToolUse lint가 실패하면 변경이 취소되나요? 이미 수행된 변경은 남습니다. 실패 결과를 다음 판단에 반영하고 최종 build/CI gate로 배포 가능 여부를 확인합니다.

자동 승인에 읽기 전용 DB 계정도 필요한가요? 승인 정책과 DB 권한은 서로 다른 경계입니다. 도구 호출이 승인되더라도 DB 자체에서 허용한 범위만 실행할 수 있게 합니다.