Claude Code 권한 bypass 설정 완벽 가이드 | dangerously-skip-permissions부터 settings.json까지

핵심 요약

Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 에이전트로, 파일 읽기/쓰기·명령어 실행 등 민감한 작업마다 사용자 확인을 요청하는 권한(Permission) 시스템을 갖추고 있습니다. 반복 확인이 불편한 자동화 환경에서는 --dangerously-skip-permissions 플래그나 설정 파일로 이를 우회할 수 있습니다. 이 글에서는 Claude Code의 권한 시스템 구조부터 bypass 설정 방법, 그리고 안전하게 사용하는 방법까지 IT 실무자 시각으로 정리합니다.

목차

• Claude Code란? 터미널 AI 에이전트 개요
• Claude Code 권한(Permission) 시스템 구조
• 권한 bypass 설정 방법
• settings.json으로 세밀한 권한 제어하기
• CI/CD·자동화 환경에서 안전하게 bypass 사용하기
• 자주 묻는 질문 (FAQ)

Claude Code란? 터미널 AI 에이전트 개요

Claude Code는 Anthropic이 개발한 터미널 기반 AI 코딩 에이전트입니다. 단순히 코드를 생성해 주는 챗봇과 달리, 실제로 파일을 읽고 수정하고, 쉘 명령어를 실행하고, Git 커밋까지 수행하는 자율 행동형(Agentic) AI입니다.

Claude Code는 npm을 통해 설치하며, 터미널에서 대화형으로 사용할 수 있습니다.

npm install -g @anthropic-ai/claude-code
claude

설치 후 claude 명령어로 실행하면 대화형 세션이 시작됩니다. 이 세션 안에서 "이 레포 전체를 리팩토링해줘", "테스트 실패 원인 찾아서 고쳐줘" 같은 자연어 명령을 내리면 Claude가 직접 파일을 분석하고 수정합니다.

이처럼 강력한 만큼, Claude Code는 기본적으로 민감한 작업(파일 쓰기, 명령어 실행, 네트워크 요청 등)을 수행하기 전에 사용자에게 허가를 요청합니다. 이것이 Claude Code의 권한(Permission) 시스템입니다.

Claude Code 공식 문서 바로가기 →

Claude Code 권한(Permission) 시스템 구조

Claude Code의 권한 시스템은 크게 세 가지 레벨로 나뉩니다. 각 레벨마다 요청 방식과 허가 범위가 다릅니다.

권한 레벨 분류

• 읽기 전용(Read-only): 파일 읽기, 디렉토리 탐색 — 별도 허가 없이 자유롭게 수행
• 쓰기 작업(Write): 파일 생성·수정·삭제 — 기본적으로 실행 전 사용자 확인 요청
• 명령어 실행(Execute): 쉘 명령어, npm run, git 등 — 가장 엄격하게 확인 요청

권한 요청 응답 옵션

Claude Code가 작업 허가를 요청할 때 사용자는 다음 중 하나를 선택할 수 있습니다.

• Yes: 이번 한 번만 허가
• Yes, don't ask again: 이 세션 동안 동일 작업 유형 자동 허가
• No: 거부

이 시스템의 목적은 AI가 사용자 의도를 벗어난 작업을 수행하지 못하도록 하는 안전장치입니다. 하지만 자동화 스크립트나 CI/CD 파이프라인에서는 이 대화형 확인이 걸림돌이 됩니다. 그래서 bypass 설정이 필요합니다.

권한 bypass 설정 방법

방법 1: --dangerously-skip-permissions 플래그

가장 직접적인 방법은 실행 시 --dangerously-skip-permissions 플래그를 추가하는 것입니다. 이 플래그를 사용하면 모든 권한 확인을 건너뛰고 자동으로 허가합니다.

# 권한 확인 완전 우회
claude --dangerously-skip-permissions

# 특정 작업을 바로 실행
claude --dangerously-skip-permissions "테스트 전체 실행하고 실패하는 케이스 고쳐줘"

# print 모드 (비대화형)와 함께 사용
claude -p --dangerously-skip-permissions "README.md 업데이트해줘"

플래그 이름에 dangerously가 붙은 이유는 분명합니다. 이 모드에서는 Claude가 사용자 확인 없이 파일을 삭제하거나 시스템 명령어를 실행할 수 있습니다. 신뢰할 수 있는 환경에서만 사용해야 합니다.

방법 2: -p (print/non-interactive) 모드

-p 또는 --print 플래그는 대화형 세션 없이 단일 명령을 실행하고 결과를 출력합니다. 스크립트 파이프라인에서 Claude를 도구처럼 활용할 때 유용합니다.

# 코드 리뷰 결과를 파일로 저장
claude -p "이 PR의 보안 취약점을 분석해줘" > review.txt

# 파이프로 입력 전달
cat error.log | claude -p "이 에러 로그 분석해서 원인 알려줘"

# --dangerously-skip-permissions와 조합하여 완전 자동화
claude -p --dangerously-skip-permissions "빌드 실패 원인 찾아서 수정해줘"

방법 3: 환경 변수 활용

CI 환경에서는 환경 변수를 통해 비대화형 모드를 강제할 수 있습니다.

# 비대화형 환경 강제 (터미널 감지 우회)
export CLAUDE_NON_INTERACTIVE=1

# GitHub Actions 예시
- name: Claude Code 자동 수정
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    claude -p --dangerously-skip-permissions \
      "실패한 테스트를 분석하고 수정해줘"

Claude Code GitHub 레포지토리 바로가기 →

settings.json으로 세밀한 권한 제어하기

완전한 bypass 대신 특정 작업만 자동 허가하고 싶다면 settings.json을 활용하세요. 전체 권한을 열어두는 것보다 훨씬 안전합니다.

설정 파일 위치

• 글로벌 설정: ~/.claude/settings.json — 모든 프로젝트에 적용
• 프로젝트 설정: .claude/settings.json (프로젝트 루트) — 해당 프로젝트에만 적용
• 로컬 오버라이드: .claude/settings.local.json — Git에 커밋하지 않는 개인 설정

settings.json 구조와 allowedTools

allowedTools 배열에 자동 허가할 도구를 명시하면 해당 도구 사용 시 확인을 건너뜁니다.

{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm run test)",
      "Bash(npm run lint)",
      "Read(**)",
      "Write(src/**)",
      "Edit(src/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "WebFetch(https://external-api.com/*)"
    ]
  }
}

glob 패턴으로 세밀한 허용 범위 지정

툴 이름 뒤에 괄호로 glob 패턴을 지정하면 매우 세밀하게 제어할 수 있습니다.

{
  "permissions": {
    "allow": [
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git push origin main)",
      "Write(tests/**/*.test.ts)",
      "Bash(docker-compose up *)",
      "Bash(docker-compose down)"
    ],
    "deny": [
      "Bash(git push --force *)",
      "Write(.env*)",
      "Bash(curl * | bash)"
    ]
  }
}

deny 규칙이 allow보다 우선합니다. 위 예시에서 git push --force는 deny에 명시되어 있으므로 git push *를 allow해도 force push는 차단됩니다. 이 방식으로 위험한 작업만 골라서 막는 것이 가장 이상적인 설정입니다.

CI/CD·자동화 환경에서 안전하게 bypass 사용하기

--dangerously-skip-permissions는 이름처럼 위험할 수 있지만, 올바른 환경 격리를 전제로 하면 안전하게 사용할 수 있습니다. 핵심은 Claude가 실행되는 환경 자체를 통제하는 것입니다.

Docker 컨테이너로 격리

가장 안전한 방법은 Claude Code를 Docker 컨테이너 안에서 실행하는 것입니다. 컨테이너 바깥 파일 시스템과 네트워크를 제한하면, Claude가 아무리 넓은 권한을 가져도 실제 피해 범위를 컨테이너 안으로 한정할 수 있습니다.

# 현재 디렉토리만 마운트해서 격리 실행
docker run --rm \
  -v $(pwd):/workspace \
  -w /workspace \
  --network none \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  node:20-slim \
  npx @anthropic-ai/claude-code \
    -p --dangerously-skip-permissions \
    "코드 리뷰하고 개선점 반영해줘"

GitHub Actions에서 안전하게 사용하기

name: Claude Code Auto Fix

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  auto-fix:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Run Claude Code
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          npx @anthropic-ai/claude-code \
            -p --dangerously-skip-permissions \
            "린트 에러를 모두 수정하고 변경사항을 git commit해줘"

      - name: Push changes
        run: |
          git config user.name "Claude Code Bot"
          git config user.email "bot@example.com"
          git push

CLAUDE.md로 행동 범위 제한

프로젝트 루트에 CLAUDE.md 파일을 두면 Claude Code가 세션 시작 시 자동으로 읽습니다. 여기에 행동 범위와 금지 사항을 명시하면, 권한 시스템과 별개로 AI 레벨에서 추가 안전장치가 됩니다.

# CLAUDE.md — 이 프로젝트에서 지켜야 할 규칙

## 허용 작업
- src/ 하위 파일 수정
- tests/ 하위 파일 수정
- npm run test, npm run lint 실행
- git add, git commit (main 브랜치 직접 push 금지)

## 금지 사항
- .env 파일 읽기/수정
- 외부 서버로 데이터 전송
- node_modules 직접 수정
- 프로덕션 데이터베이스 접근

## 우선 확인 사항
- 파괴적 변경(Breaking Change) 발생 시 반드시 코멘트로 알릴 것

Claude Code 설정 공식 문서 보기 →

자주 묻는 질문 (FAQ)

Q. --dangerously-skip-permissions 사용 시 어떤 위험이 있나요?

Claude가 잘못된 명령을 실행해도 중간에 멈추지 않습니다. 예를 들어 Claude가 의도치 않게 중요한 파일을 삭제하거나, 의도하지 않은 외부 서비스에 API 요청을 보낼 수 있습니다. 반드시 버전 관리(Git)가 된 디렉토리에서 사용하고, 실수해도 복구할 수 있는 환경을 갖추세요.

Q. settings.json의 deny와 allow 중 어느 쪽이 우선순위가 높나요?

deny가 항상 우선합니다. allow에 광범위한 패턴을 설정해도 deny에 명시된 항목은 차단됩니다. 보안 원칙상 "기본 차단, 필요한 것만 허용(Allowlist)" 방식보다 "기본 허용, 위험한 것만 차단(Denylist)" 방식이 설정이 편하지만, 더 안전한 것은 Allowlist입니다.

Q. 로컬 개발 환경에서도 bypass를 상시 켜두는 게 좋은가요?

권장하지 않습니다. 로컬에서는 권한 확인 프롬프트가 나올 때 한 번 더 Claude의 행동을 검토할 수 있습니다. 자동화 환경(CI/CD)에서만 bypass를 사용하고, 로컬에서는 settings.json으로 자주 쓰는 명령만 allowlist에 추가하는 것이 훨씬 안전합니다.

Q. 프로젝트별로 다른 권한 설정을 적용할 수 있나요?

네, 가능합니다. 프로젝트 루트의 .claude/settings.json이 글로벌 설정인 ~/.claude/settings.json보다 우선 적용됩니다. 프로덕션 관련 프로젝트는 엄격하게, 실험용 프로젝트는 느슨하게 설정하는 식으로 분리 관리할 수 있습니다.

Q. CLAUDE.md와 settings.json 중 어느 것을 우선해야 하나요?

역할이 다릅니다. settings.json은 시스템 레벨의 하드 제어(실제로 명령을 차단)이고, CLAUDE.md는 AI 레벨의 소프트 가이드(Claude가 읽고 따르는 지시)입니다. 두 가지를 함께 사용하면 시스템 차단과 AI 지침이 이중으로 작동해 가장 안전합니다.