Claude Code 가이드 #17 Claude Code를 프로덕션 워크플로우나 CI/CD 파이프라인에 연결하려다 "어디까지 허용해야 하나"에서 막힌 경험이 있나요. 이 편에서는 Claude Code의 권한 시스템 전체 구조, 안전한 설정 방법, 그리고 실무에서 쓰는 보안 Best Practice를 정리합니다. Claude Code는 실행 중에 파일 읽기/쓰기, 셸 명령 실행, 외부 API 호출 등 다양한 작업을 수행합니다.
Claude Code 가이드 #17 — Claude Code를 프로덕션 워크플로우나 CI/CD 파이프라인에 연결하려다 "어디까지 허용해야 하나"에서 막힌 경험이 있나요? 이 편에서는 Claude Code의 권한 시스템 전체 구조, 안전한 설정 방법, 그리고 실무에서 쓰는 보안 Best Practice를 정리합니다.
† 이 글은 2026년 3월 기준, Claude Code 공식 Permissions 문서 기반으로 작성됐습니다.
Claude Code는 실행 중에 파일 읽기/쓰기, 셸 명령 실행, 외부 API 호출 등 다양한 작업을 수행합니다. 이 모든 작업은 권한 시스템(Permission System)을 통해 제어됩니다.
권한 체계는 크게 세 레이어로 구성됩니다:
| 레이어 | 위치 | 적용 범위 |
|---|---|---|
| 글로벌 설정 | ~/.claude/settings.json | 모든 프로젝트에 기본 적용 |
| 프로젝트 설정 | .claude/settings.json | 해당 프로젝트에서만 적용 (글로벌 덮어쓰기) |
| 실행 플래그 | --dangerously-skip-permissions | 해당 세션 전체의 권한 확인 우회 |
권한 설정의 우선순위는 실행 플래그 > 프로젝트 설정 > 글로벌 설정 순입니다. 프로젝트 설정이 있으면 글로벌 설정보다 우선 적용됩니다.
.claude/settings.json은 레포지토리에 커밋할 수 있습니다. 팀 전체에 공통 권한 규칙을 적용할 때 유용하지만, 신뢰할 수 없는 레포를 클론한 뒤 Claude Code를 실행하면 레포의 settings.json이 자동으로 로드됩니다. 외부 레포 작업 시 반드시 이 파일을 먼저 확인하세요.Claude Code에는 실행 시 적용되는 4가지 권한 모드가 있습니다. 상황에 따라 맞는 모드를 선택해야 합니다.
| 모드 | 파일 수정 | 셸 실행 | 사용 시나리오 |
|---|---|---|---|
| Ask permissions (기본) | 승인 요청 | 승인 요청 | 일반 개발, 처음 사용 시 |
| Auto accept edits | 자동 승인 | 승인 요청 | 파일 작업이 많은 반복 작업 |
| Plan mode | 불가 | 불가 | 계획 수립, 코드 리뷰 전용 |
| dontAsk (skip-permissions) | 자동 승인 | 자동 승인 | 신뢰된 로컬 환경 자동화 |
실무에서는 대부분 Ask permissions(기본) 또는 allowedTools를 이용한 선택적 허용 조합으로 운영하는 것이 가장 균형 잡힌 선택입니다.
settings.json의 permissions 블록으로 도구별 허용/거부 규칙을 정밀하게 제어할 수 있습니다.
~/.claude/settings.json 또는 .claude/settings.json 기본 구조{ "permissions": { "allow": [ "Read", "Edit", "Write", "Bash(git status)", "Bash(git diff *)", "Bash(node --check *)" ], "deny": [ "Bash(rm *)", "Bash(curl *)", "Bash(wget *)" ] } }
allow와 deny 규칙은 다음 우선순위로 적용됩니다:
deny 목록에 있으면 무조건 차단allow 목록에 있으면 자동 승인도구 이름 패턴:
Read, Edit, Write — 파일 관련 도구Bash(명령어 패턴) — 셸 명령. *는 와일드카드WebFetch, WebSearch — 외부 네트워크 접근mcp__서버명__도구명 — MCP 서버 도구실전 예시 — 콘텐츠 생성 프로젝트용 설정// .claude/settings.json (프로젝트 레벨) { "permissions": { "allow": [ "Read", "Edit", "Write", "Bash(node --check *)", "Bash(git status)", "Bash(git diff *)", "Bash(git log *)" ], "deny": [ "Bash(rm *)", "Bash(git push *)", "Bash(git reset *)", "WebFetch", "WebSearch" ] } }
deny 목록에 Bash(rm *)를 추가해도 Bash(rm -rf /)까지 모두 막을 수 있는 것은 아닙니다. Bash(*) 전체 거부 후 필요한 명령만 allow에 추가하는 화이트리스트 방식이 보안상 더 안전합니다.🎓 유데미 강의 추천
Claude Code 실전 강의 — AI 코딩을 지금 시작하세요
설치부터 자동화·에이전트 활용까지, 실무에서 바로 쓰는 Claude Code 활용법을 단계별로 배울 수 있습니다.
--dangerously-skip-permissions는 Claude Code의 모든 권한 확인을 비활성화하는 플래그입니다. 이름에 "dangerously"가 붙은 이유는 실제로 위험하기 때문입니다.
rm, curl, git push 포함)이 플래그를 사용하면 Claude Code가 사용자 개입 없이 모든 작업을 자동으로 진행합니다.
| ✅ 사용해도 되는 상황 | ❌ 절대 사용 금지 |
|---|---|
| 로컬 개발 머신 개인 작업 | 프로덕션 서버 |
| 신뢰된 프로젝트 반복 유지보수 | CI/CD 자동화 파이프라인 |
| 광고 축소, H2 재작성 등 단순 수정 | 외부에서 받은 레포 |
| 검증 스크립트 일괄 실행 | 여러 사람이 접근하는 공유 환경 |
skip-permissions 실행 방법# 기본 사용 claude --dangerously-skip-permissions # Agent Teams와 함께 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude --dangerously-skip-permissions # settings.json에서 팀 전체에 적용 (권장하지 않음) # 대신 allowedTools 방식 사용 권장
--dangerously-skip-permissions로 열면, 레포에 포함된 .claude/settings.json이나 .mcp.json의 악의적 설정이 자동 실행될 수 있습니다. 신뢰할 수 없는 레포에서는 이 플래그를 절대 사용하지 마세요. Claude Code를 열기 전에 .claude/ 디렉토리와 .mcp.json을 먼저 확인하세요.Claude Code 자체에는 OS 수준의 샌드박스가 없습니다. 즉, Claude Code가 실행하는 셸 명령은 현재 사용자의 권한으로 그대로 실행됩니다. 이를 보완하는 방법이 몇 가지 있습니다.
Claude Code를 Docker 컨테이너 내부에서 실행하면, 호스트 시스템과 격리됩니다.
Docker 컨테이너에서 Claude Code 실행# 프로젝트 디렉토리를 컨테이너에 마운트하고 실행 docker run -it --rm \ -v $(pwd):/workspace \ -w /workspace \ node:20 \ bash -c "npm install -g @anthropic-ai/claude-code && claude" # API 키는 환경변수로 전달 docker run -it --rm \ -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \ -v $(pwd):/workspace \ -w /workspace \ node:20 \ bash -c "npm install -g @anthropic-ai/claude-code && claude --dangerously-skip-permissions"
Docker 격리 실행의 장점:
Docker 없이도 settings.json의 allowedTools로 실행 가능한 명령을 최소화할 수 있습니다.
--dangerously-skip-permissions로 실행할 때는 반드시 Docker 컨테이너 안에서 실행하거나, allowedTools를 엄격하게 제한해야 합니다. PR 이벤트를 트리거로 쓰면 외부 기여자의 PR에 포함된 악의적 코드가 실행될 수 있습니다.Claude Code를 팀 환경이나 자동화 파이프라인에서 안전하게 운영하기 위한 실전 체크리스트입니다.
ANTHROPIC_API_KEY는 절대 코드에 하드코딩하지 마세요~/.zshrc 또는 ~/.bashrc에 export로 설정.env 파일에 넣더라도 반드시 .gitignore에 추가.claude/settings.json을 팀 레포에 커밋할 때는 반드시 팀 리뷰 거치기.claude/settings.json 내용 확인 필수deny 블록에 파괴적 명령어 명시적으로 추가allow에 추가 (최소 권한 원칙)프로덕션/리뷰 전용 settings.json — Plan mode 강제// .claude/settings.json (프로덕션 브랜치용) { "permissions": { "allow": [ "Read" ], "deny": [ "Edit", "Write", "Bash(*)", "WebFetch", "WebSearch" ] } } // Read만 허용 → 코드 읽기/분석만 가능, 어떤 변경도 불가
MCP(Model Context Protocol) 서버를 연결하면 Claude Code의 권한 범위가 MCP 서버가 제공하는 도구까지 확장됩니다. MCP 서버 관련 보안 주의사항입니다.
.mcp.json은 레포 루트에 위치하며, .claude/settings.json과 마찬가지로 외부 레포 클론 시 자동 로드됩니다.permissions.deny에 mcp__서버명__* 패턴으로 특정 MCP 서버 전체를 차단할 수 있습니다.MCP 도구 차단 예시 — settings.json{ "permissions": { "deny": [ "mcp__filesystem__write_file", "mcp__filesystem__delete_file", "mcp__github__create_or_update_file" ] } }
settings.json의 allow 블록에 필요한 도구만 명시적으로 추가하는 화이트리스트 방식을 권장합니다. 기본적으로 모든 MCP 도구를 deny하고, 필요한 것만 추가하는 패턴이 가장 안전합니다.권한 설정 중 자주 발생하는 문제와 해결법입니다.
allow에 추가했는데도 계속 승인을 요청함 — 도구 이름 오타가 원인인 경우가 많습니다. Bash(node --check *)처럼 공백과 와일드카드를 정확히 맞춰야 합니다. Claude Code를 시작할 때 --debug 플래그를 추가하면 어떤 도구 이름으로 요청되는지 확인할 수 있습니다.deny에 추가했는데도 실행이 됨 — 글로벌 설정(~/.claude/settings.json)의 allow가 프로젝트 settings.json의 deny보다 우선되는 경우가 있습니다. 프로젝트 설정이 글로벌 설정을 완전히 덮어쓰는지 확인하거나, 실행 플래그를 사용하세요.정리하면:
settings.json의 allow/deny로 도구별 허용/차단을 세밀하게 제어--dangerously-skip-permissions는 신뢰된 로컬 환경에서만 사용Bash(*) deny 후 필요한 것만 allow)이 가장 안전한 설정관련 가이드:
권한 설정에서 가장 위험한 착각은 deny에 Bash(rm *)를 넣으면 파괴적 명령이 다 막힌다고 믿는 것입니다. 이 패턴은 rm -rf / 같은 변형까지 전부 잡지 못합니다. 블랙리스트로는 빈틈이 생기니, Bash(*)를 통째로 deny한 뒤 필요한 명령만 allow에 추가하는 화이트리스트 방식이 정석입니다. 또 흔히 헷갈리는 것이 적용 시점과 우선순위입니다. settings.json은 세션 시작 시에만 읽히므로 실행 중 수정은 재시작해야 반영되고, 글로벌 ~/.claude/settings.json의 allow가 프로젝트 settings.json의 deny보다 우선되는 경우가 있어 deny가 무력화되기도 합니다. 차단을 확실히 하려면 프로젝트 설정으로 덮어쓰거나 실행 플래그를 쓰세요.
권한 모드는 신뢰 수준으로 갈라집니다. 처음 쓰거나 낯선 코드를 만질 때는 기본 Ask permissions가 맞습니다. 작업마다 묻는 게 번거롭지만 안전하니까요. 파일을 대량으로 고치는 반복 작업이면 Auto accept edits로 파일 수정만 자동 승인하되 셸 실행은 여전히 확인받는 절충이 좋습니다. 코드 리뷰나 계획만 세울 때는 변경이 전혀 안 되는 Plan mode가 안전합니다. --dangerously-skip-permissions는 신뢰된 개인 로컬 머신의 단순 유지보수에만 쓰고, 프로덕션 서버, CI/CD, 외부에서 받은 레포, 공유 환경에서는 절대 쓰면 안 됩니다. 자동화가 꼭 필요하면 그 자리에는 Bash(*) 전체 deny 후 필요한 명령만 allow하는 화이트리스트나 Docker 격리가 더 맞습니다.
가장 먼저 볼 곳은 공식 Permissions 문서(code.claude.com/docs/en/permissions)와 Settings 문서입니다. allow/deny 규칙의 정확한 패턴 문법과 settings.json 전체 스키마가 여기 있습니다. 그다음 보안 관점을 잡으려면 공식 Security 가이드를 함께 보세요. 키워드로는 최소 권한 원칙(least privilege), 화이트리스트 vs 블랙리스트, 그리고 .mcp.json 자동 로드로 인한 공급망 위험을 검색해 보면 이 글의 설계 근거가 보입니다. 실전 격리는 Docker 컨테이너 마운트 실행과 GitHub Actions에서의 allowedTools 제한 문서를 보면 CI/CD까지 확장됩니다.
Claude Code의 권한은 글로벌, 프로젝트, 실행 플래그 3레이어로 동작하며, settings.json의 allow/deny로 도구별 허용·차단을 정밀하게 제어합니다. 안전의 핵심은 단 하나로, Bash(*)를 통째로 deny한 뒤 필요한 명령만 allow에 추가하는 화이트리스트 방식입니다. --dangerously-skip-permissions는 신뢰된 로컬에서만 쓰고, CI/CD나 외부 레포에서는 Docker 격리 또는 엄격한 allowedTools 제한을 반드시 거쳐야 합니다.
먼저 알아둘 전제는 Claude Code 자체에 OS 수준 샌드박스가 없다는 점입니다. 셸 명령은 현재 사용자 권한 그대로 실행되므로, 격리는 별도로 마련해야 합니다. 그래서 처음 도입할 때 정해야 할 것은 권한 모델입니다. 신뢰된 로컬 개인 작업이면 allowedTools 화이트리스트로 충분하지만, CI/CD나 외부 기여자 PR을 다룬다면 Docker 컨테이너 안에서 실행하거나 allowedTools를 엄격히 제한해야 합니다. 그리고 외부 레포를 클론했다면 claude를 켜기 전에 그 레포의 .claude/settings.json과 .mcp.json을 먼저 열어 악의적 설정이 없는지 확인하는 것이 첫 점검 항목입니다.
🎓 관련 강의
Claude Code 완전 정복 — 유데미 강의
이 글에서 다룬 내용을 더 체계적으로 배우고 싶다면 강의를 확인해보세요. 실전 예제 중심으로 구성되어 있습니다.
