lacvet/AX-Copilot

Fork 0

Files

lacvet deffb33cf9 Initial commit to new repository

2026-04-03 18:23:52 +09:00

5.8 KiB

Raw Blame History

권한 시스템

Claude Code가 어떤 작업을 자동으로 수행하고 어떤 작업에 명시적 승인이 필요한지 제어하는 방법.

Claude Code는 로컬 머신에서 도구를 실행합니다 — 셸 커맨드 실행, 파일 편집, URL 가져오기. 권한 시스템은 Claude가 자동으로 수행하는 작업과 명시적 승인이 필요한 작업을 정밀하게 제어합니다.

권한이 제어하는 것

권한은 세 가지 작업 범주에 적용됩니다:

파일 작업 — Read, Edit, Write 도구를 통한 로컬 파일시스템 읽기, 편집, 쓰기
Bash 커맨드 — Bash 도구를 통한 셸 커맨드 실행(설치, 빌드, git 작업, 임의 스크립트 포함)
MCP 도구 호출 — 연결된 MCP 서버가 노출한 도구(데이터베이스 쿼리, API 호출, 브라우저 자동화 등)

권한 모드

권한 모드는 특정 허용/차단 규칙과 일치하는 도구 호출이 없을 때의 기본 동작을 결정합니다. 모드를 한 번 설정하면 세션 전체에 적용됩니다.

default — 잠재적으로 위험한 작업에 확인 요청 표준 모드. 셸 커맨드 실행, 파일 편집, 네트워크 요청 등 부작용이 있을 수 있는 작업에 확인을 요청합니다. 파일 읽기, 검색 등 읽기 전용 작업은 자동 승인됩니다. 일상적인 사용에 권장됩니다.

acceptEdits — 파일 편집 자동 승인 Edit, Write 도구가 프롬프트 없이 자동 승인됩니다. Bash 커맨드는 여전히 확인이 필요합니다. Claude가 파일을 자유롭게 편집하도록 하되 셸 커맨드는 검토하고 싶을 때 유용합니다.

plan — 읽기 전용 계획 모드 Claude가 파일을 읽고, 코드베이스를 검색하고, 변경 사항에 대해 논의할 수 있지만 쓰기 또는 bash 작업을 실행할 수 없습니다. 모든 변경 도구 호출이 차단됩니다. Claude가 문제를 분석하고 변경 사항을 승인하기 전에 계획을 만들도록 할 때 사용하세요.

bypassPermissions — 모든 권한 검사 건너뛰기 모든 권한 검사가 비활성화됩니다. 모든 도구 호출이 확인 프롬프트 없이 즉시 실행됩니다.

⚠️ 이 모드는 Claude가 수행할 작업을 미리 감사한 완전 스크립트화된 자동화 워크플로우 전용입니다. Claude가 예기치 않은 작업을 취할 수 있는 대화형 세션에서는 절대 사용하지 마세요.

권한 모드 설정 방법

CLI 플래그:

claude --permission-mode acceptEdits
claude --permission-mode bypassPermissions
claude --permission-mode plan

/permissions 커맨드 (세션 중):

/permissions

재시작 없이 모드를 변경합니다.

settings.json:

{
  "defaultMode": "acceptEdits"
}

유효한 값: "default", "acceptEdits", "bypassPermissions", "plan", "dontAsk"

권한 규칙 (허용/차단 목록)

전역 모드 외에도, 활성 모드에 관계없이 특정 도구 호출을 항상 허용하거나 항상 차단하는 세분화된 규칙을 만들 수 있습니다.

규칙은 세 가지 구성 요소를 가집니다:

필드	설명
`toolName`	규칙이 적용되는 도구 이름 (예: `"Bash"`, `"Edit"`, `"mcp__myserver"`)
`ruleContent`	도구 입력과 일치해야 하는 선택적 패턴
`behavior`	`"allow"`, `"deny"`, 또는 `"ask"`

규칙은 권한 모드보다 먼저 평가됩니다. 일치하는 규칙이 있으면 해당 동작이 즉시 적용됩니다.

예시: 특정 git 커맨드 항상 허용

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Read(*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  }
}

Bash 권한 작동 방식

패턴 매칭:

git status — 정확한 일치만
git * — 모든 git 서브커맨드와 일치
npm run * — 모든 npm run 스크립트와 일치
* — 모든 bash 커맨드와 일치 (극도의 주의 필요)

복합 커맨드: &&, ||, ;, 파이프(|)로 연결된 복합 커맨드는 각 서브커맨드가 독립적으로 검사됩니다. 하나의 서브커맨드라도 차단되면 전체 복합 커맨드가 차단됩니다.

항상 차단/에스컬레이션되는 작업:

프로젝트 디렉토리 외부 경로로의 출력 리다이렉션(>, >>)
워킹트리 외부로의 디렉토리 변경(cd)
sed -i 편집 인플레이스 커맨드(파일 수정 추적을 위해 특별 처리)
.claude/ 또는 .git/ 설정 디렉토리를 대상으로 하는 커맨드
셸 설정 파일 수정(.bashrc, .zshrc 등)

MCP 도구 권한

MCP 도구는 내장 도구와 동일한 규칙 시스템을 따릅니다:

{
  "permissions": {
    "deny": [
      "mcp__myserver"
    ],
    "allow": [
      "mcp__myserver__read_database"
    ]
  }
}

mcp__servername을 규칙으로 사용하면(특정 도구 이름 없이) 해당 서버의 모든 도구가 차단됩니다 — 모델이 보기 전에 도구 목록에서 필터링됩니다.

보안 권장 사항

default 모드로 모든 대화형 세션을 시작하세요
익숙하지 않은 코드베이스를 탐색하거나 큰 변경 사항을 설계할 때는 plan 모드를 사용하세요
Claude가 파일을 자유롭게 편집하도록 하되 셸 커맨드는 검토하려면 **acceptEdits**를 사용하세요
광범위한 모드 에스컬레이션 대신 세분화된 허용 규칙을 선호하세요. Bash(git *)를 허용하는 것이 bypassPermissions로 전환하는 것보다 안전합니다
친숙하지 않은 저장소를 클론할 때 .claude/settings.json을 검토하세요 — 권한 규칙이 미리 설정되어 있을 수 있습니다

5.8 KiB Raw Blame History