Claude Code 파일시스템 권한 관리 완전 가이드

저는 매일 Claude Code를 사용하면서 다양한 파일시스템 권한 문제를 겪었습니다. 이번 글에서는 Claude Code의 파일시스템 권한 관리를 심층적으로 다뤄드리겠습니다. HolySheep AI를 활용하면 단일 API 키로 Claude를 포함한 다양한 모델을 간편하게 연동할 수 있습니다.

Claude Code 파일시스템 권한이란?

Claude Code(Anthropic의 공식 CLI 도구)는 개발자의 파일시스템에 접근하여 코드를 작성, 수정, 삭제할 수 있습니다. 하지만 보안상 모든 작업이 자동으로 허용되지는 않습니다. 명시적인 권한 승인이 필요한 작업들이 있습니다.

자주 발생하는 파일시스템 권한 오류 해결

1. Write permissions required 오류

파일을 생성하거나 수정할 때 가장 흔히遭遇하는 오류입니다.

Error: Write permissions required for /path/to/project/src/index.ts
Claude Code cannot write to this location without explicit permission.

To grant permission, you can:
1. Run: claude --dangerously-skip-permissions
2. Use: /dangerously-skip-permissions in the session
3. Allow in settings: claude_settings.json

이 오류는 Claude Code가 아직 해당 경로에 대한 쓰기 권한을 부여받지 않았을 때 발생합니다.

2. Read permissions required 오류

Error: Read permissions required for /path/to/sensitive/config.json
Claude Code cannot read files outside the allowed project directories.

Allowed directories: /home/user/projects/*, /tmp/*

프로젝트 외부 파일에 접근하려 할 때 발생하는 보안 오류입니다.

3. Delete permissions required 오류

Warning: This will delete /path/to/file.js
Error: Delete permissions required
Claude Code requires explicit confirmation for destructive operations.

파일 삭제나 중요한 디렉토리 변경 시 항상 요청되는 권한 확인입니다.

권한 설정 방법

방법 1: 프로젝트별 권한 설정

# 프로젝트 루트에 claude_settings.json 생성
{
  "permissions": {
    "allow": [
      "/home/user/projects/my-app/src/**",
      "/home/user/projects/my-app/tests/**",
      "/home/user/projects/my-app/package.json"
    ],
    "deny": [
      "/home/user/projects/my-app/node_modules/**",
      "/home/user/projects/my-app/.env",
      "/home/user/projects/my-app/secrets/**"
    ]
  },
  "dangerouslySkipPermissions": false
}

방법 2: CLI 실행 시 권한 부여

# 특정 디렉토리에 대한 읽기/쓰기 권한 부여
claude --allowed-directory /home/user/projects/my-app

모든 작업에 대해 권한 확인 건너뛰기 (개발용으로만!)
claude --dangerously-skip-permissions

특정 파일 타입만 허용
claude --allow-write "*.{ts,js,json}"

방법 3: 대화 중 권한 요청

Claude Code 대화창에서 직접 권한을 요청할 수 있습니다.

# 대화창에서 입력
/dangerously-skip-permissions

또는 특정 경로만 허용
/allow /path/to/directory

HolySheep AI로 Claude API 연동하기

HolySheep AI를 사용하면 Claude Code뿐만 아니라 API를 통한 Claude 연동도 간편하게 할 수 있습니다. 지금 가입하면 무료 크레딧을 받을 수 있습니다.

# HolySheep AI를 통한 Claude API 연동 예제
import anthropic

client = anthropic.Anthropic(
    api_key="YOUR_HOLYSHEEP_API_KEY",
    base_url="https://api.holysheep.ai/v1"
)

파일시스템 권한 관련 작업 프롬프트 작성
message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": """다음 JavaScript 코드를 검토하고 파일시스템 접근 시 
            발생할 수 있는 보안 취약점을 분석해주세요.
            
            
            const fs = require('fs');
            const path = require('path');
            
            function readUserFile(filename) {
                return fs.readFileSync(filename, 'utf8');
            }
            
            
            분석 항목:
            1. 경로 순회(Path Traversal) 취약점 가능성
            2. 입력 검증 필요 여부
            3. 보안 개선建议"""
        }
    ]
)

print(message.content)

HolySheep AI의 Claude API 가격은 매우 경쟁력 있습니다:

• Claude Sonnet 4.5: $15/MTok
• Claude Opus 4: $75/MTok
• Claude Haiku: $1.25/MTok

프로덕션 환경에서의 권장 사항

# production-settings.json 권장 설정
{
  "permissions": {
    "allow": [
      "${PROJECT_ROOT}/src/**",
      "${PROJECT_ROOT}/dist/**",
      "${PROJECT_ROOT}/package.json"
    ],
    "deny": [
      "${PROJECT_ROOT}/.env",
      "${PROJECT_ROOT}/node_modules/**",
      "${PROJECT_ROOT}/secrets/**",
      "${HOME}/.ssh/**",
      "${HOME}/.aws/**"
    ],
    "requireExplicitConfirmation": [
      "delete",
      "rmdir",
      "exec"
    ]
  },
  "dangerouslySkipPermissions": false,
  "auditLog": true
}

실전 경험: 권한 설정 실수 사례

제가 처음 Claude Code를 사용할 때 가장 큰 실수였는 것이 바로 --dangerously-skip-permissions 옵션을 습관처럼 사용한 것이었습니다. 어느 날深夜, Claude Code가 실수로 node_modules 전체를 삭제하는 상황이 발생했죠.

# 잘못된 사용법 (절대 따라하지 마세요!)
claude --dangerously-skip-permissions
-> 모든 파일시스템 작업이 확인 없이 실행됨

올바른 사용법
claude --allowed-directory /path/to/project
-> 지정된 디렉토리 내에서만 권한 부여

그 후로 저는 반드시 필요한 디렉토리만 허용하는 방식을 채택했습니다. 또한 .gitignore에 민감한 파일을 등록하고, CI/CD 환경에서는 읽기 전용 모드를 사용하는 것을 권장합니다.

자주 발생하는 오류와 해결책

오류 1: "Permission denied: ENOTDIR - not a directory"

파일을 디렉토리처럼 접근하려 할 때 발생합니다.

# 잘못된 경로 설정 예시
{
  "permissions": {
    "allow": ["/path/to/file.txt/**"]  # 파일에 ** 패턴 사용 불가
  }
}

올바른 설정
{
  "permissions": {
    "allow": ["/path/to/directory/**"]  # 디렉토리만 허용
  }
}

오류 2: "Symbolic link detected - permission denied"

심볼릭 링크를 통한 파일 접근은 보안상 기본적으로 차단됩니다.

# 심볼릭 링크 우회 방법 (신중하게 사용)
claude --allow-symlinks /path/to/link/directory

또는 실제 경로 직접 지정
claude --allowed-directory /real/path/to/target

오류 3: "Maximum recursion depth exceeded"

** glob 패턴 사용 시 너무 많은 파일이 매칭되면 발생합니다.

# 문제가 되는 설정
{
  "permissions": {
    "allow": ["/home/**"]  # 너무 넓은 범위
  }
}

권장 설정
{
  "permissions": {
    "allow": [
      "/home/user/projects/*/src/**",
      "/home/user/projects/*/tests/**"
    ],
    "maxFilesPerOperation": 100
  }
}

결론

Claude Code의 파일시스템 권한 관리는 보안을 위해 반드시 이해해야 하는 핵심 기능입니다. 저의 경험상, 명시적인 권한 허용 방식이 가장 안전하며, --dangerously-skip-permissions는 절대로 습관처럼 사용하지 말아야 합니다.

HolySheep AI를 사용하면 Claude를 포함한 다양한 AI 모델을 단일 API로 간편하게 연동할 수 있으며, 로컬 결제 지원으로 해외 신용카드 없이도 즉시 시작할 수 있습니다.

👉 HolySheep AI 가입하고 무료 크레딧 받기