Claude Code 자동 모드 설정하기

Claude Code 자동 모드에서 분류기(용어 사전)가 회사의 일상 작업(사내 저장소 push, 팀 버킷 쓰기, 사내 API 호출)을 계속 막을 때, 분류기에게 조직의 신뢰 인프라를 알려 주고 막을 것·풀 것을 조정하는 절차다. 자동 모드 자체(무엇을 기본으로 막는지, 켜고 끄는 법)는 권한 모드와 Claude Code 권한 모드 고르기, 조직 단위 통제는 Claude Code 관리자 권한 통제에 있다.

준비물(필요한 것)#

0. 먼저 알아 둘 것: 기본 신뢰 범위와 설정이 읽히는 곳#

• 분류기는 기본으로 작업 디렉터리와 현재 저장소에 설정된 remote만 신뢰한다. 회사 소스 관리 조직으로의 push, 팀 클라우드 버킷 쓰기 같은 동작은 autoMode.environment에 넣을 때까지 막힌다. Claude Code 자동 모드 설정
• 분류기는 Claude가 로드하는 것과 같은 메모리(CLAUDE.md) 내용을 읽는다. 프로젝트의 CLAUDE.md에 "never force push"라고 쓰면 Claude와 분류기를 동시에 이끈다. 프로젝트 관례와 행동 규칙은 여기서 시작하라고 원본은 권한다. Claude Code 자동 모드 설정
• 여러 프로젝트에 걸친 규칙(신뢰 인프라, 조직 전체 차단 규칙)은 autoMode 블록에 둔다. 읽는 곳은 셋뿐이다. Claude Code 자동 모드 설정

• 분류기는 프로젝트의 .claude/settings.json과 .claude/settings.local.json에서 autoMode를 읽지 않는다. 두 파일 모두 저장소 디렉터리에 있어 체크인된 저장소나 빌드 단계가 자기 allow 규칙을 주입할 수 있기 때문이다. .claude/settings.local.json에 autoMode 블록이 있으면 ~/.claude/settings.json으로 옮긴다. Claude Code 자동 모드 설정 settings reference(2026-10-21)도 autoMode의 Scope를 User or managed로 적고, 여러 파일이 같은 배열을 두면 항목을 이어 붙인다고 한다. Claude Code 설정 키 전체 레퍼런스 → Claude Code 설정 키 레퍼런스

1. 기본 규칙부터 본다#

claude auto-mode defaults

내장 environment, allow, soft_deny, hard_deny 규칙을 JSON으로 출력한다. 규칙 하나의 전체 문장만 보려면 --label에 규칙 이름의 앞부분을 준다(예: claude auto-mode defaults --label 'Git Destructive'). 대소문자를 가리지 않는 접두어 일치이고, 맞는 것이 없는 섹션은 빈 목록으로 나온다. Claude Code 자동 모드 설정

2. 신뢰 인프라를 autoMode.environment에 적는다#

원본은 대부분의 조직에 필요한 필드는 environment 하나라고 한다. 분류기는 이 목록으로 "외부"가 무엇인지 정하므로, 목록에 없는 목적지는 잠재적 유출 대상이 된다. Claude Code 자동 모드 설정

항목은 자연어 문장이다. 정규식이나 도구 패턴이 아니고, 새 엔지니어에게 인프라를 설명하듯 쓴다. 내장 항목 옆에 내 항목을 더하려면 배열에 문자열 "$defaults"를 그대로 넣는다. 그 자리에 기본 항목이 끼워지므로 내 항목을 앞이나 뒤에 둘 수 있다. Claude Code 자동 모드 설정

원본 예시(기본 항목을 유지하고 조직의 저장소·버킷·도메인·서비스를 더함):

{
  "autoMode": {
    "environment": [
      "$defaults",
      "Source control: github.example.com/acme-corp and all repos under it",
      "Trusted cloud buckets: s3://acme-build-artifacts, gs://acme-ml-datasets",
      "Trusted internal domains: *.corp.example.com, api.internal.example.com",
      "Key internal services: Jenkins at ci.example.com, Artifactory at artifacts.example.com"
    ]
  }
}

원본의 시작 템플릿(대괄호 칸을 채우고 해당 없는 줄은 지운다):

{
  "autoMode": {
    "environment": [
      "$defaults",
      "Organization: {COMPANY_NAME}. Primary use: {PRIMARY_USE_CASE, e.g. software development, infrastructure automation}",
      "Source control: {SOURCE_CONTROL, e.g. GitHub org github.example.com/acme-corp}",
      "Cloud provider(s): {CLOUD_PROVIDERS, e.g. AWS, GCP, Azure}",
      "Trusted cloud buckets: {TRUSTED_BUCKETS, e.g. s3://acme-builds, gs://acme-datasets}",
      "Trusted internal domains: {TRUSTED_DOMAINS, e.g. *.internal.example.com, api.example.com}",
      "Key internal services: {SERVICES, e.g. Jenkins at ci.example.com, Artifactory at artifacts.example.com}",
      "Additional context: {EXTRA, e.g. regulated industry, multi-tenant infrastructure, compliance requirements}"
    ]
  }
}

환경 항목의 세 종류 (claude auto-mode defaults가 보여 주는 것): Claude Code 자동 모드 설정

칸별로 조건이 붙은 것: Claude Code 자동 모드 설정

• Repository visibility: Claude Code가 직접 보내는 분류기 요청에서 분류기는 사용자 메시지와 Claude가 돌린 명령을 읽고 그 출력은 읽지 않는다. 그래서 gh repo view 출력만으로는 "공개 저장소"라는 증거가 분류기에 닿지 않고, 사용자가 메시지로 저장소를 공개라고 말하는 것처럼 분류기가 읽을 수 있는 증거여야 한다.
• Trusted repo와 공개 범위: 저장소의 공개 여부는 기밀 자료에만 범위를 정한다. 비공개 저장소는 기밀 자료를 둘 수 있는 곳이지만, 저장소를 비공개로 만든다고 비밀값이나 개인·위탁 데이터를 넣어도 되는 것은 아니다. 작업 저장소 밖에서 옮겨 오거나 처음 읽은 내용은 그 저장소 자신의 작업으로 보지 않는다.
• Host containment: Claude Code가 egress 허용 목록이 있거나 건드리면 안 되는 이웃이 있는 컨테이너·VM·pod에서 돌면, 허용 호스트, 클라우드 메타데이터 엔드포인트에 닿아도 되는지, 작업이 쓰는 클라우드 프로젝트·클러스터·레지스트리와 그 신원을 적는다. 이 항목이 그 신원을 적기 전까지 분류기는 호스트 자체 자격 증명 요청을 막는다. v2.1.257 이상.
• Internal package registry: 설치가 거쳐야 할 사내 npm·PyPI 등 레지스트리를 적으면, 그것을 건너뛰고 공개 레지스트리로 가는 설치가 막힌다.
• Sensitive remote targets: 운영으로 칠 네임스페이스·호스트·컨테이너를 적으면, 그곳으로의 원격 셸·포트 포워딩에 명시적 승인이 필요해진다. Protected IaC scopes는 apply·destroy 때 변경을 사용자가 직접 말하게 할 인프라 자원이다.

한 번에 다 채우지 않는다. 원본이 제시한 도입 순서: 기본값에서 시작해 소스 관리 조직과 핵심 내부 서비스를 더하면(자기 저장소로의 push 같은 가장 흔한 오탐이 풀린다), 다음에 신뢰 도메인과 클라우드 버킷, 나머지는 차단이 생길 때마다 채운다. Claude Code 자동 모드 설정

2-1. 초안을 /auto-mode-setup으로 만들기#

/auto-mode-setup을 실행하면 Claude Code가 프로젝트와 그 프로젝트의 최근 세션에서 environment 항목(때로 규칙 항목도) 초안을 만들고, 수락하면 ~/.claude/settings.json에 쓴다. Claude Code 자동 모드 설정

• 쓸 수 있는 곳 (2026-10-21 기준): Pro·Max·Team·Enterprise 플랜과 Claude Console API 키. Pro·Max·Team은 v2.1.228 이상(네이티브 Windows v2.1.233 이상), Enterprise와 Console API 키는 v2.1.283 이상. 클라우드 세션에서는 /auto-mode-setup isn't available in this environment.가 나오므로 터미널 대화형 세션에서 돌린다.
• 읽는 것: 항상 읽는 것은 이 프로젝트의 CLAUDE.md·README.md·설정 파일·git remote, 내 autoMode와 permissions.allow 설정, 이 프로젝트 최근 세션에서 Claude가 돌린 명령의 호스트·버킷·명령 이름(사용자 메시지는 읽지 않음)이다. 스캔 전에 묻는 선택 스캔 두 가지는 셸 기록의 각 명령 첫 단어, 홈 디렉터리 아래 저장소들의 원격 호스트와 이름이다. ~/.claude/settings.json에 이미 autoMode 항목이 있으면 먼저 environment 목록에 더할지 바꿀지를 묻고, 어느 쪽이든 내가 쓴 규칙은 유지한다.
• 저장 방식: 초안은 통째로 수락하거나 버린다(항목 하나씩 고치려면 저장 뒤 파일을 고친다). 저장할 때 environment 목록은 "$defaults" 없이 쓴다(초안이 바꾸지 않은 내장 항목을 직접 적기 때문). 초안이 항목을 더하는 allow·soft_deny·hard_deny 목록에는 "$defaults"를 넣는다(이미 "$defaults" 없는 allow 목록을 써 둔 경우 제외). 저장 뒤 자동 모드가 무시하는 permissions.allow 규칙(예: Bash(*))이나 파괴적 명령을 자동 승인하는 규칙을 ~/.claude/settings.json에서 지우자고 제안한다.
• "Unknown command"가 나오면: 설치·업그레이드 뒤 첫 세션이면 새 세션을 연다. claude --version이 플랜별 최소 버전보다 낮으면 업데이트한다. 텔레메트리를 끈 세션, 서드파티 제공자, Claude apps gateway에서는 v2.1.304 전까지 이 명령이 없다.
• 끄기: 자동 모드가 여러 번 막았는데 autoMode.environment 항목이 없으면 턴 끝에 "Teach auto mode about your environment?" 대화상자가 뜬다. 제안만 끄려면 그 대화상자에서 Don't show again, 명령과 제안을 모두 끄려면 ~/.claude/settings.json에 아래 항목을 둔다. 이 명령은 번들 스킬이 아닌 내장 명령이라 이 skillOverrides 항목은 적용되지만 disableBundledSkills로는 꺼지지 않는다. → 스킬

{
  "skillOverrides": {
    "auto-mode-setup": "off"
  }
}

3. 필요할 때만 규칙 목록을 바꾼다#

세 필드가 분류기의 내장 규칙 목록을 대체한다. 각각 자연어 문장 배열이다. Claude Code 자동 모드 설정

• autoMode.hard_deny: 무조건 지킬 보안 경계
• autoMode.soft_deny: 사용자 의도가 풀 수 있는 파괴적 동작
• autoMode.allow: soft block 규칙의 예외

분류기 안의 우선순위: hard_deny는 무조건 막는다(사용자 의도·allow 예외가 닿지 않음) → soft_deny가 다음으로 막는다 → allow가 맞는 soft_deny의 예외가 된다 → 끝으로 사용자의 명시적 의도가 남은 soft block을 넘는다. 명시적 의도는 사용자 메시지가 Claude가 하려는 바로 그 동작을 직접·구체적으로 말할 때만이다. "저장소 정리해 줘"는 force push를 허락하지 않고, "이 브랜치 force-push해 줘"는 허락한다. Claude Code 자동 모드 설정 → 권한 모드

언제 무엇을: 풀려면 기본 예외가 다루지 않는 일상 패턴을 분류기가 반복해 막을 때 allow에 더한다. 조이려면 기본값이 놓친 우리 환경의 파괴적 위험은 soft_deny, 절대 넘으면 안 될 보안 경계는 hard_deny에 더한다. 분류기보다 먼저 도는 도구 패턴 기반 차단은 Claude Code 권한 규칙 문법의 permissions.deny다. Claude Code 자동 모드 설정

원본 예시(네 목록 모두 기본값을 유지하고 조직 규칙을 더함):

{
  "autoMode": {
    "environment": [
      "$defaults",
      "Source control: github.example.com/acme-corp and all repos under it"
    ],
    "allow": [
      "$defaults",
      "Deploying to the staging namespace is allowed: staging is isolated from production and resets nightly",
      "Writing to s3://acme-scratch/ is allowed: ephemeral bucket with a 7-day lifecycle policy"
    ],
    "soft_deny": [
      "$defaults",
      "Never run database migrations outside the migrations CLI, even against dev databases",
      "Never modify files under infra/terraform/prod/: production infrastructure changes go through the review workflow"
    ],
    "hard_deny": [
      "$defaults",
      "Never send repository contents to third-party code-review APIs"
    ]
  }
}

설정 파일을 열지 않고 고치기: /permissions를 열고 Auto mode 탭을 고르면 분류기 규칙과 environment 항목을 보고 고칠 수 있다(v2.1.246 이상, 세션에서 자동 모드를 쓸 수 있을 때만 보임). managed settings나 --settings 플래그에서 온 항목은 읽기 전용으로 보이고, 이 탭에서 바꾼 것은 모두 ~/.claude/settings.json에 저장된다. Claude Code 자동 모드 설정

4. 사람 확인 지점은 권한 규칙으로 둔다#

자동 모드는 작업 중인 저장소의 모든 브랜치(기본 브랜치 포함)로의 push와 PR 생성을 기본으로 허용한다. 이름이 배포·공개 대상을 가리키는 기본 브랜치 아닌 브랜치(production, release, gh-pages 등)는 이 기본에서 빠져 분류기가 따로(운영 배포로서도) 판단한다. push 내용도 계속 검사해 force push, 비밀값이 커밋에 들어가는 것, CI나 배포 파이프라인이 돌릴 때 비밀값을 저장소 밖으로 보낼 변경은 막는다. Claude Code 자동 모드 설정

Claude의 push·PR 명령 앞에 사람 확인을 두려면 설정에 permissions.ask 규칙을 더한다. 이런 내용 지정 ask 규칙은 분류기보다 먼저 평가되고 자동 모드에서도 확인 창을 띄운다(분류기는 맞는 동작을 자동 승인할 수 없다). 원본 레시피: Claude Code 자동 모드 설정

{
  "permissions": {
    "ask": [
      "Bash(git push *)",
      "Bash(gh pr create *)"
    ]
  }
}

한계: 이 규칙은 git push나 gh pr create로 시작하는 명령만 맞춘다. Claude가 git -C <dir> push나 git -c <key>=<value> push처럼 다르게 쓴 push는 규칙에 맞지 않아 확인 지점을 거치지 않는다. 명령 전체 텍스트를 검사하는 확인 지점이 필요하면 PreToolUse 훅을 더하라고 원본은 말한다. Claude Code 자동 모드 설정 → Claude Code 권한 규칙 문법, Claude Code 차단 훅 단단하게 만들기

경계를 얼마나 단단히 둘지로 장치를 고른다(원본 표):

근거: Claude Code 자동 모드 설정 → 장기 작업 컨텍스트 관리

5. 모든 셸 명령을 분류기에 보내려면 classifyAllShell#

기본으로 Bash(npm test) 같은 좁은 Bash·PowerShell allow 규칙은 자동 모드에서도 유효하다. Claude Code가 분류기보다 먼저 그 규칙으로 판정하기 때문이다(명령에 명령별 허용 도메인이 붙은 경우는 예외). 자동 모드가 정지시키는 것은 Bash(*)나 와일드카드 인터프리터처럼 임의 코드 실행을 주는 넓은 규칙과, Monitor를 이름으로 대는 모든 규칙(Monitor 명령은 셸로 돌기 때문)뿐이다. 그래서 좁은 규칙도 규칙 접두어가 예상하지 못한 스크립트 경로나 플래그 같은 파괴적 인자를 분류기가 보지 못한 채 통과시킬 수 있다. Claude Code 자동 모드 설정

autoMode.classifyAllShell을 true로 두면 자동 모드가 켜진 동안 모든 Bash·PowerShell allow 규칙이 정지되고, 허용 목록과 상관없이 분류기가 모든 셸 명령을 평가한다. 단 치명 경로 삭제(critical-path removals)는 예외다. Claude Code 자동 모드 설정

{
  "autoMode": {
    "classifyAllShell": true
  }
}

• 맞바꿈: 허용 규칙이 즉시 승인했을 명령도 분류기 판정을 기다리고, 셸 명령마다 분류기 호출 1회로 잡힌다. Claude Code 자동 모드 설정
• 자동 모드가 켜져 있을 때만 적용되고, 다른 권한 모드에서는 allow 규칙이 평소대로 동작한다. Claude Code 자동 모드 설정
• 키의 Scope·기본값·최소 버전(v2.1.193)과 managed가 false여도 user나 --settings의 true를 따르는 규칙은 Claude Code 설정 키 레퍼런스, Claude Code 설정 파일. Claude Code 설정 키 전체 레퍼런스

6. 됐는지 확인하는 법#

claude auto-mode config

내 설정이 있는 곳은 내 설정, 없는 곳은 기본값을 적용해 분류기가 실제로 쓰는 규칙을 JSON으로 출력한다. defaults와 config 모두 네 목록을 하나의 JSON 객체로, 규칙마다 문장 하나로 출력한다. 설정을 저장한 뒤 이 명령으로 내 항목이 들어갔는지 확인하라고 원본은 말한다. Claude Code 자동 모드 설정

claude auto-mode critique

직접 쓴 allow·soft_deny·hard_deny·environment 항목을 AI가 검토해 모호하거나 중복되거나 오탐을 낼 만한 항목을 짚는다. Claude Code 자동 모드 설정

7. 거부를 보고 고친다#

1. 어디서 보나: /permissions의 Recently denied 탭에 분류기가 거부한 동작이 기록된다. 거부된 동작에서 r을 누르면 재시도로 표시되고, 대화상자를 나가면 Claude Code가 모델에게 그 도구 호출을 다시 해도 된다고 알리고 대화를 이어 간다. Claude Code 자동 모드 설정
2. 무엇이 막혔나: 대화에서 그 도구 호출을 찾는다. Ran 3 shell commands처럼 접혀 있으면 Ctrl+O로 트랜스크립트 보기를 연다. 입력창 근처 알림(예: bash denied by auto mode · [Data Exfiltration] · /permissions)은 도구와 이유만, Recently denied 탭은 셸 명령을 Claude가 쓴 설명으로만 보여 주고 명령·URL은 빼므로, 정확한 입력을 기록하려면 PermissionDenied 훅을 더한다(입력을 tool_input으로 받는다). Claude Code 자동 모드 설정 → 훅 이벤트 레퍼런스
3. 고칠 것이 있나: 호출 아래 흐린 Not run · auto mode's check had no usable answer 줄이나 Auto mode could not evaluate this action처럼 분류기 자체의 문제를 알리는 문구는 분류기 판정 없이 막혔다는 뜻이다. 이런 거부는 Recently denied에 기록되지 않고, 원인과 대처는 원본이 오류 문서로 넘긴다. Denied by auto mode classifier와 [Production Deploy]·Blocked by classifier 같은 이유가 보이면 분류기가 위험하다고 판정한 것이다. 대괄호 안은 분류기가 맞춘 규칙 이름이고, 전체 문장은 1단계의 --label로 읽는다. Claude Code 자동 모드 설정
4. 무엇으로 고치나: Claude Code 자동 모드 설정

environment 항목과 allow 규칙은 /permissions의 Auto mode 탭에서도 더할 수 있다. 같은 목적지가 반복해 막히면 대개 분류기에 맥락이 없다는 뜻이니 autoMode.environment에 더하거나 /auto-mode-setup으로 초안을 만들고, claude auto-mode config로 반영됐는지 확인한다. Claude Code 자동 모드 설정

8. 처음으로 되돌리기#

claude auto-mode reset

user 설정 파일에서 autoMode 절을 지워 내장 기본값으로 돌아간다. 지울 내용을 요약한 뒤 Reset auto mode configuration to defaults?라고 묻고, --yes면 묻지 않는다. 바뀌는 것은 ~/.claude/settings.json뿐이고 managed settings나 --settings 플래그의 autoMode 규칙은 계속 적용된다. Claude Code 자동 모드 설정

언제 쓰고 언제 쓰지 않는가#

• 쓴다: 자동 모드를 켠 개발 조직에서 사내 저장소 push·사내 API·팀 버킷 같은 일상 작업이 반복해 막힐 때, 도입 컨설팅에서 "자동 모드를 켜되 회사 인프라 맥락을 어떻게 알려 주나"를 설계할 때, 민감 데이터 위치·운영 네임스페이스·보호할 IaC 범위를 분류기에 명시해 기본 추정 규칙 대신 지정한 대상에 보호 규칙을 걸고 싶을 때. Claude Code 자동 모드 설정
• 쓰지 않는다: 절대 실행되면 안 되는 동작을 autoMode.hard_deny나 soft_deny에만 맡기지 않는다. 원본은 분류기를 권한 시스템 뒤에 도는 두 번째 관문으로 설명하고, 사용자 의도나 분류기 설정과 상관없이 막아야 할 동작은 managed settings의 permissions.deny로 막으라고 한다. 조직의 soft_deny도 개발자가 더한 allow가 넘을 수 있다(원본: "the combination is additive, not a hard policy boundary"). Claude Code 자동 모드 설정 → Claude Code 관리자 권한 통제
• 쓰지 않는다: 저장소에 체크인하는 .claude/settings.json으로 팀에 자동 모드 규칙을 나눠 주려는 경우. 분류기는 프로젝트 파일의 autoMode를 읽지 않는다. 팀 공통이면 managed settings로 배포한다(Claude Code managed settings 배포·점검). 프로젝트 관례는 CLAUDE.md에 둔다. Claude Code 자동 모드 설정
• 함께 볼 것: 자동 모드 자체의 한계와 원본 경고는 권한 모드의 "자동 모드와 분류기" 절에 있다.