auto 모드 구성하기

auto 모드 구성하기 (Configure auto mode)

auto 모드 분류기에게 조직이 신뢰하는 리포지토리·버킷·도메인을 알려주는 설정 페이지예요. 환경 컨텍스트를 정하고 기본 차단·허용 규칙을 재정의하며, auto-mode CLI 서브커맨드로 실제 적용되는 구성을 보고하세요. 기본적으로 분류기는 작업 디렉토리와 현재 리포지토리의 구성된 리모트만 신뢰하므로, 회사 소스 컨트롤 조직으로 푸시하거나 팀 클라우드 버킷에 쓰는 동작은 autoMode.environment에 추가하기 전까지 차단됩니다.

출처: 공식문서

본문

Auto 모드는 도구 호출을 분류기를 통해 라우팅해 Claude Code가 일상적인 권한 프롬프트 없이 실행되게 합니다. 분류기는 비가역적·파괴적·환경 밖을 겨냥한 것을 차단합니다. 거부 규칙과 명시적 ask 규칙은 분류기보다 먼저 평가되며 여전히 차단하거나 프롬프트합니다. autoMode 설정 블록으로 그 분류기에게 조직이 신뢰하는 리포지토리·버킷·도메인을 알려주면 일상적인 내부 작업을 더 이상 차단하지 않습니다.

Auto 모드는 Anthropic API, [Claude Platform on AWS](/docs/en/claude-platform-on-aws), Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, 로그인한 [Claude apps gateway](/docs/en/claude-apps-gateway) 세션을 포함한 모든 제공자의 모든 사용자에게 사용할 수 있습니다. Claude Code가 계정에 대해 auto 모드를 사용할 수 없다고 보고하면 지원 모델과 Team·Enterprise 플랜의 조직 수준 제어를 다루는 [전체 요구사항](/docs/en/permission-modes#eliminate-prompts-with-auto-mode)을 확인하세요. v2.1.158~v2.1.206에서는 Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, Claude apps gateway 세션에서 auto 모드에 `CLAUDE_CODE_ENABLE_AUTO_MODE=1` 설정이 필요했습니다. v2.1.207이 그 요구사항을 제거했습니다.

기본적으로 분류기는 작업 디렉토리와 현재 리포지토리의 구성된 리모트만 신뢰합니다. 회사의 소스 컨트롤 조직으로 푸시하거나 팀 클라우드 버킷에 쓰는 것 같은 동작은 autoMode.environment에 추가할 때까지 차단됩니다.

세션이 어떻게 auto 모드로 되는지, 분류기가 기본으로 무엇을 차단하는지는 Permission modes 페이지의 auto 모드를 참고하세요. 이 페이지는 설정 레퍼런스입니다.

이 페이지가 다루는 것:

permissions.ask로 푸시·풀 리퀘스트에 사람 체크포인트 추가
CLAUDE.md, 사용자 설정, 관리 설정에서 규칙을 어디에 둘지 고르기
autoMode.environment로 신뢰 인프라 정의
/auto-mode-setup으로 환경 항목 생성
기본값이 파이프라인에 안 맞을 때 차단·허용 규칙 재정의
설정 파일을 열지 않고 /permissions에서 규칙 편집
autoMode.classifyAllShell로 모든 셸 명령을 분류기로 라우팅
claude auto-mode 서브커맨드로 실제 구성을 검사
거부 검토로 무엇을 추가할지 파악

일반적인 경계 (Common boundaries)

auto 모드는 작업 중인 리포지토리의 어떤 브랜치(기본 브랜치 포함)로든 푸시와 풀 리퀘스트 생성을 기본으로 허용합니다. production, release, gh-pages처럼 이름이 배포·게시 대상을 표시하는 비기본 브랜치는 그 기본값에 포함되지 않습니다. 분류기가 거기 푸시를 프로덕션 배포를 포함해 자체 조건으로 판단합니다. 푸시 내용도 여전히 점검되므로, force push, 커밋에 들어가는 시크릿, CI·배포 파이프라인이 실행할 때 시크릿을 리포지토리 밖으로 보내는 변경은 차단된 채 유지됩니다.

v2.1.211 이전에는 분류기가 작업 브랜치, Claude가 만든 브랜치, 기본 브랜치로의 일상 푸시만 허용했습니다.

Claude의 푸시·풀 리퀘스트 명령 전에 사람 체크포인트를 원하면 권한 규칙을 추가하세요. 아래 레시피는 다른 모든 것에 auto 모드를 유지합니다.

사람 체크포인트 추가 (Add a human checkpoint)

가장 직접적인 메커니즘은 permissions.ask입니다. 아래 같은 내용 범위(콘텐츠 스코프) ask 규칙은 분류기보다 먼저 평가되고 auto 모드에서도 항상 권한 프롬프트를 강제합니다. 명시적 ask 규칙이 그 동작에 프롬프트받겠다는 우리의 명시된 의도이기 때문입니다. 설정에서 규칙을 추가하세요.

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

이 규칙들은 git push나 gh pr create로 시작하는 명령을 매칭합니다. Claude가 다른 방식으로 쓰는 푸시, 예를 들어 git -C <dir> push나 git -c <key>=<value> push는 규칙을 매칭하지 않아 체크포인트되지 않습니다. 전체 명령 텍스트를 검사하는 체크포인트가 필요하면 PreToolUse hook을 추가하세요.

경계가 얼마나 단단해야 하는지에 맞는 메커니즘을 고르세요.

경계	메커니즘	auto 모드에서의 동작
동작 전에 프롬프트	`permissions.ask`	위 레시피 같은 내용 범위 규칙을 매칭하는 명령에 항상 프롬프트. 분류기는 매칭 동작을 자동 승인할 수 없음
동작을 절대 실행 안 함	`permissions.deny`	분류기가 조회되기 전에 차단. 분류기나 사용자 의도 모두 재정의할 수 없음
이 세션만의 일회성 경계	대화에서 말하기. "don't push until I review"처럼	분류기가 매칭 동작을 차단하지만 컨텍스트 컴팩션이 그것을 말한 메시지를 제거하면 경계가 사라질 수 있음. 지속 보장에는 ask·deny 규칙 사용

분류기가 설정을 읽는 곳 (Where the classifier reads configuration)

분류기는 Claude 자신이 로드하는 같은 CLAUDE.md 내용을 읽으므로, 프로젝트 CLAUDE.md의 "never force push" 같은 지시가 Claude와 분류기를 동시에 안내합니다. 프로젝트 규칙·행동 규칙부터 거기서 시작하세요.

신뢰 인프라나 조직 전반 거부 규칙처럼 프로젝트를 넘어 적용되는 규칙은 autoMode 설정 블록을 쓰세요. 분류기는 다음 범위에서 autoMode를 읽습니다.

범위	파일	용도
한 개발자	`~/.claude/settings.json`	개인 신뢰 인프라
조직 전반	관리 설정	모든 개발자에게 배포된 신뢰 인프라
`--settings` 플래그 또는 Agent SDK	인라인 JSON	자동화용 호출별 재정의

분류기는 .claude/settings.json이나 .claude/settings.local.json의 프로젝트 설정에서 autoMode를 읽지 않습니다. 두 파일 모두 리포지토리 디렉토리에 있으므로, 체크인된 리포지토리나 빌드 단계가 자기 allow 규칙을 주입할 수 있습니다. v2.1.207 이전에는 분류기가 .claude/settings.local.json도 읽었습니다. 그 파일의 autoMode 블록은 ~/.claude/settings.json으로 옮기세요. .claude/settings.local.json을 제외하면 리포지토리가 파일을 커밋하거나 로컬 도구·빌드 단계가 쓰는 경우도 닫힙니다.

각 범위의 항목은 결합됩니다. 개발자는 environment, allow, soft_deny, hard_deny를 개인 항목으로 확장할 수 있지만 관리 설정이 제공하는 항목을 제거할 수는 없습니다. allow 규칙은 분류기 안에서 소프트 차단 규칙의 예외로 작동하므로, 개발자 추가 allow 항목이 조직 soft_deny 항목을 재정의할 수 있습니다. 결합은 가산적이지 단단한 정책 경계가 아닙니다.

분류기는 [권한 시스템](/docs/en/permissions) 뒤에 실행되는 두 번째 게이트입니다. 사용자 의도나 분류기 구성과 무관하게 절대 실행돼서는 안 되는 동작은 관리 설정의 `permissions.deny`를 쓰세요. 분류기가 조회되기 전에 차단하며 재정의할 수 없습니다.

신뢰 인프라 정의 (Define trusted infrastructure)

대부분 조직에서 autoMode.environment가 설정해야 할 유일한 필드입니다. 분류기에게 어떤 리포지토리·버킷·도메인이 신뢰되는지 알려주며, "external"이 무엇을 뜻하는지 결정하는 데 씁니다. 나열되지 않은 목적지가 잠재적 유출(exfiltration) 대상이 됩니다.

Claude Code v2.1.198부터 claude auto-mode defaults는 세 종류의 환경 항목을 출력합니다. v2.1.195 이전 버전은 처음 다섯 신뢰 슬롯만 출력합니다.

컨텍스트 슬롯: 조직, 스택, 보안 자세를 설명해 분류기가 컨텍스트의 다른 규칙을 읽게 합니다. 각각 None configured 또는 옆에 이름 붙은 보수적 가정으로 기본값이 정해집니다.
- Organization
- Claude Code의 주요 용도: 기본값 소프트웨어 개발
- Cloud provider(s)
- 리포지토리 가시성: 리모트 호스트와 이름이 달리 표시하지 않거나, 분류기가 읽는 대화 앞부분의 가시성 검사가 공개로 보여주지 않는 한 리포지토리는 비공개로 가정. 분류기는 메시지와 Claude가 실행하는 명령을 읽지 그 출력을 읽지 않으므로, 증거는 분류기가 읽을 수 있는 것(리포지토리를 공개로 이름을 정한 당신의 메시지 같은)이어야 합니다. gh repo view 출력 자체는 닿지 않습니다. 트랜스크립트 증거 검사는 Claude Code v2.1.200 이상 필요.
- 내부 공유 / 스니펫 호스팅: 공개 paste·gist 서비스는 하나를 이름 짓기 전까지 신뢰 경계 밖으로 취급
- 조직 특정 CLI
- 시크릿 관리
- CI/CD 배포 대상
- 네트워크 자세
- 호스트 격리(Host containment): 기본값은 열린 인터넷의 일반 개발자 머신·CI 러너. Claude Code가 이그레스 허용 목록이나 닿지 말아야 할 이웃이 있는 컨테이너·VM·팟에서 실행된다면, 허용 호스트, 클라우드 메타데이터 엔드포인트에 도달 가능해야 하는지, 작업이 쓰는 클라우드 프로젝트·클러스터·레지스트리와 어떤 아이덴티티로 쓰는지 이름을 정하세요. 이 항목이 그 아이덴티티를 이름 정할 때까지 분류기는 호스트 자신의 자격 증명 요청을 차단합니다. Claude Code v2.1.257 이상 필요.
- 보호된 배포 네임스페이스 / 환경: 이름을 정할 때까지 Sensitive remote targets 휴리스틱으로 폴백
- 데이터 보존 / 해제 분류
신뢰 슬롯: 분류기가 경계 안에 있다고 취급하는 것을 이름 짓습니다. 슬롯은 Trusted repo, Source control, Trusted internal domains, Trusted cloud buckets, Key internal services, Internal package registry입니다. 리포지토리·소스 컨트롤 항목은 작업 리포지토리와 구성 리모트로 기본값이 정해집니다. 다른 모든 신뢰 슬롯은 None configured로 기본값이 정해지므로, 추가하기 전까지 다른 것은 신뢰되지 않습니다. 리포지토리 가시성은 기밀 자료만 범위로 합니다. 비공개 리포지토리는 기밀 자료의 수용 가능한 목적지지만, 리포지토리를 비공개로 만드는 것은 시크릿·개인·신탁 데이터를 그 안으로 결코 해제하지 않으며, 분류기는 작업 리포지토리 밖에서 이식·재지정·처음 읽은 콘텐츠를 그 리포지토리 자체 작업이 아닌 것으로 취급합니다. 이 범위는 Claude Code v2.1.203 이상 필요.
민감도 슬롯: 보호 규칙이 고위험으로 취급하는 것을 이름 짓습니다. 슬롯은 Sensitive data locations & audiences, Sensitive remote targets, Protected IaC scopes입니다. 각각 prod·production이란 이름을 가진 어떤 호스트·네임스페이스든 민감한 리모트 대상으로 취급하는 것 같은 광범위한 휴리스틱으로 기본값이 정해집니다. 그래서 아무것도 구성하기 전에 보호 규칙이 활성화됩니다. 민감도 슬롯에 구체적 대상을 이름 지으면 그 규칙들이 휴리스틱 대신 이름 붙은 대상에 적용됩니다.

v2.1.211 이전에는 컨텍스트 슬롯에 Default / protected branches 항목도 있어 다른 것을 이름 짓기 전까지 main·master를 보호했습니다. v2.1.211이 제거했습니다. 작업 중인 리포지토리의 어떤 브랜치로든 푸시가 기본으로 허용되므로 구성할 보호 브랜치 기본값이 없습니다.

기본값과 함께 자기 항목을 추가하려면 배열에 리터럴 문자열 "$defaults"를 포함하세요. 기본 항목이 그 위치에 끼워지므로 커스텀 항목을 그 앞이나 뒤에 둘 수 있습니다.

다음 예시는 기본 항목을 유지하고 조직의 리포지토리·버킷·도메인·서비스를 추가합니다.

{
  "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"
    ]
  }
}

설정을 저장한 뒤 claude auto-mode config를 실행해 적용되는 규칙에 항목이 포함됐는지 확인하세요.

항목은 산문(prose)이며 정규식이나 도구 패턴이 아닙니다. 분류기가 자연어 규칙으로 읽습니다. 새 엔지니어에게 인프라를 설명하듯 쓰세요. 철저한 환경 섹션은 다음을 다룹니다.

Organization: 회사 이름과 Claude Code가 주로 쓰이는 용도(소프트웨어 개발, 인프라 자동화, 데이터 엔지니어링 등)
Source control: 개발자가 푸시하는 모든 GitHub·GitLab·Bitbucket 조직
Cloud providers and trusted buckets: Claude가 읽고 쓸 수 있어야 하는 버킷 이름·접두사
Trusted internal domains: 네트워크 안 API·대시보드·서비스의 호스트 이름(*.internal.example.com 등)
Key internal services: CI, 아티팩트 레지스트리, 내부 패키지 인덱스, 사고 도구
Internal package registry: 설치가 통과해야 하는 비공개 npm·PyPI·다른 레지스트리. 그래서 공용 레지스트리로 우회하는 설치는 차단됩니다.
Sensitive data locations & audiences: 개인 데이터, 기밀 비즈니스 데이터, 자격 증명, 규제 데이터, 비슷한 민감 자료를 담는 버킷·데이터베이스·경로와, 각 위치의 데이터가 공유될 수 있는 수신자. 분류기가 내용 추측 대신 이 위치들을 보호합니다. Claude Code v2.1.195~v2.1.197은 이 항목을 PII / regulated-data locations로 이름 짓고 수신자 차원 없이 개인·규제 데이터를 담는 위치만 다룹니다.
Sensitive remote targets: 프로덕션으로 간주되는 네임스페이스·호스트·컨테이너. 그래서 그쪽 원격 셸·포트 포워드에 명시적 승인이 필요합니다.
Protected IaC scopes: apply·destroy가 항상 변경을 이름 짓게 해야 하는 인프라 리소스
Additional context: 규제 산업 제약, 멀티 테넌트 인프라, 분류기가 위험으로 취급해야 하는 것에 영향을 주는 컴플라이언스 요구사항

Internal package registry, Sensitive data locations & audiences, Sensitive remote targets, Protected IaC scopes 항목은 Claude Code v2.1.195 이상이 필요합니다. 이전 버전은 그것들을 평문 컨텍스트로 읽지만 대상으로 하는 내장 규칙이 없습니다.

유용한 시작 템플릿: 대괄호 필드를 채우고 해당하지 않는 줄을 제거하세요.

{
  "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}"
    ]
  }
}

구체적인 컨텍스트를 줄수록 분류기가 일상 내부 작업과 유출 시도를 더 잘 구분할 수 있습니다.

한 번에 다 채울 필요는 없습니다. 합리적인 롤아웃: 기본값으로 시작해 소스 컨트롤 조직과 주요 내부 서비스를 추가하세요. 자기 리포지토리로의 푸시 같은 가장 흔한 오탐을 해결합니다. 다음에 신뢰 도메인과 클라우드 버킷을 추가하세요. 나머지는 차단이 나오면 채웁니다.

`/auto-mode-setup`으로 환경 항목 생성 (Generate environment entries)

/auto-mode-setup을 실행해 Claude Code가 프로젝트와 최근 세션에서 autoMode.environment 항목을, 때로는 규칙 항목도 초안으로 만들게 하세요. 초안을 수락하면 Claude Code가 ~/.claude/settings.json에 씁니다.

`/auto-mode-setup`은 Pro, Max, Team 플랜과 Claude Code v2.1.228 이상이 필요합니다. 네이티브 Windows에서는 v2.1.233 이상이 필요합니다. [웹의 Claude Code](/docs/en/claude-code-on-the-web)에서는 실행할 수 없습니다. [기능 플래그 가져오기](/docs/en/env-vars#features-that-need-feature-flag-fetching)도 필요하므로, 플래그 가져오기를 끈 세션에서는 실행할 수 없습니다.

`/auto-mode-setup`이 읽는 것

~/.claude/settings.json에 이미 autoMode 항목이 있으면 Claude Code는 환경 목록에 추가할지 교체할지 먼저 물어보고, 어느 쪽이든 당신이 쓴 규칙은 유지합니다. 그다음 Claude Code가 이 프로젝트를 어떻게 쓰는지 묻고, 아무것도 스캔하기 전에 두 선택적 스캔을 제안합니다. 스캔에서 Claude Code는 항상 이 소스를 읽습니다.

이 프로젝트의 CLAUDE.md, README.md, 구성 파일, git 리모트
당신의 autoMode와 permissions.allow 설정
Claude가 이 프로젝트의 최근 세션에서 실행한 명령들의 호스트·버킷·명령 이름. 절대 메시지는 읽지 않습니다.

두 선택적 스캔은 각각 하나의 소스를 추가합니다.

셸 기록의 각 명령 첫 단어
홈 디렉토리 아래 리포지토리의 원격 호스트와 이름

초안 검토·저장

Claude Code는 백그라운드에서 스캔한 뒤 초안을 보여줍니다. 전체로서 수락하거나 버리므로, 단일 항목을 조정하려면 나중에 ~/.claude/settings.json을 편집하세요. 수락하면 Claude Code가 초안을 쓰고 이미 가진 설정과 조정합니다.

Claude Code는 초안이 그대로 둔 내장 항목을 전부 써내려가므로 environment 목록을 "$defaults" 없이 씁니다.
Claude Code는 초안이 항목을 추가하는 각 allow, soft_deny, hard_deny 목록에 "$defaults"를 포함합니다. 직접 "$defaults" 없는 allow 목록을 썼다면 제외합니다. 그래서 대체하지 않은 내장 규칙이 계속 유지됩니다.
저장 후 Claude Code는 ~/.claude/settings.json에서 auto 모드가 무시하는(Bash(*) 같은) 것 또는 파괴적 명령을 자동 승인하는 permissions.allow 규칙을 제거하겠다고 제안합니다.

그런 다음 claude auto-mode config를 실행해 적용 결과를 보세요.

`/auto-mode-setup` 끄기

auto 모드가 여러 동작을 차단했는데 아직 autoMode.environment 항목이 없으면 CLAUDE Code가 턴 끝에 "Teach auto mode about your environment?" 제목의 대화상을 보여주고 /auto-mode-setup을 실행하겠다고 제안합니다. 제안을 끄고 명령만 유지하려면 그 대화상자에서 Don't show again을 선택하세요.

명령과 제안을 모두 끄려면 ~/.claude/settings.json에 이 skillOverrides 항목을 추가하세요.

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

/auto-mode-setup은 번들 스킬이 아니라 내장 명령이므로 이 skillOverrides 항목이 여전히 적용되지만, disableBundledSkills는 끄지 않습니다.

차단·허용 규칙 재정의 (Override the block and allow rules)

추가 필드 세 개로 분류기의 내장 규칙 목록을 대체할 수 있습니다.

autoMode.hard_deny: 무조건적인 보안 경계
autoMode.soft_deny: 사용자 의도가 해제할 수 있는 파괴적 동작
autoMode.allow: 소프트 차단 규칙의 예외

각각 산문 설명 배열이며 자연어 규칙으로 읽힙니다. 분류기보다 먼저 실행되는 도구 패턴 기반 하드 블록은 permissions.deny를 쓰세요.

분류기 안에서 우선순위는 네 계층으로 동작합니다.

hard_deny 규칙이 무조건 차단합니다. 사용자 의도와 allow 예외가 적용되지 않습니다.
soft_deny 규칙이 다음으로 차단합니다. 사용자 의도와 allow 예외가 이것을 재정의할 수 있습니다.
allow 규칙이 그다음 매칭 soft_deny 규칙을 예외로 재정의합니다.
명시적 사용자 의도가 남은 소프트 차단을 재정의합니다. 사용자 메시지가 Claude가 막 취하려는 정확한 동작을 직접·구체적으로 설명하면, soft_deny 규칙이 매칭돼도 분류기가 허용합니다.

일반적인 요청은 명시적 의도로 간주되지 않습니다. Claude에게 "clean up the repo"라고 하는 것은 force push를 승인하지 않지만, "force-push this branch"라고 하면 승인합니다.

완화하려면 분류기가 기본 예외가 다루지 않는 일상 패턴을 반복 플래그할 때 allow에 추가하세요. 강화하려면 기본값이 놓치는 환경 특정 파괴적 위험은 soft_deny에, 절대 넘어서는 안 되는 보안 경계는 hard_deny에 추가하세요.

내장 규칙을 유지하며 자기 것을 추가하려면 배열에 리터럴 문자열 "$defaults"를 포함하세요. 기본 규칙이 그 위치에 끼워지므로 커스텀 규칙을 그 앞이나 뒤에 둘 수 있고, 내장 목록이 릴리스를 거치며 바뀌어도 업데이트를 계속 물려받습니다.

다음 예시는 네 목록 모두 기본값을 유지하고 각각 조직별 규칙을 추가합니다.

{
  "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"
    ]
  }
}

`environment`, `allow`, `soft_deny`, `hard_deny` 중 하나를 `"$defaults"` 없이 설정하면 그 섹션의 전체 기본 목록을 대체합니다. `"$defaults"` 없는 배열을 설정하면 그 섹션의 내장 규칙을 버리는 것입니다.

soft_deny: force push, curl | bash, 프로덕션 배포, auto-mode 우회를 포함한 모든 내장 소프트 차단 규칙

hard_deny: 내장 데이터 유출(Data exfiltration) 규칙

각 섹션은 독립적으로 평가되므로 environment만 설정하면 기본 allow·soft_deny·hard_deny 목록은 그대로 유지됩니다.

목록의 소유권을 완전히 가질 의도일 때만 "$defaults"를 생략하세요. 안전하게 하려면 claude auto-mode defaults를 실행해 내장 규칙을 출력하고 설정 파일에 복사한 뒤, 각 규칙을 파이프라인과 위험 허용에 맞게 검토하세요.

`/permissions`에서 규칙 편집 (Edit rules from /permissions)

설정 파일을 열지 않고 분류기 규칙을 보고 편집하려면 /permissions을 실행하고 Auto mode 탭을 선택하세요. 탭은 Claude Code v2.1.246 이상이 필요하며, auto 모드가 세션에 가능할 때만 나타납니다.

탭은 분류기가 읽는 각 범위의 allow, soft_deny, hard_deny, environment 항목을 나열하고, 각 섹션에 내장 규칙이 유효한지 보여줍니다. Claude Code는 관리 설정이나 --settings 플래그의 항목을 읽기 전용으로 보여주고, 탭에서 만든 모든 변경을 ~/.claude/settings.json에 저장합니다. 탭에서 할 수 있는 것:

allow, soft_deny, hard_deny 섹션에서 규칙 추가·편집·삭제. 섹션에 첫 규칙을 추가하면 Claude Code가 "$defaults"도 삽입해 내장 규칙이 유지됩니다.
allow, soft_deny, hard_deny의 내장 규칙을 끄거나 다시 켜기. Claude Code는 그 섹션의 목록에 "$defaults"를 추가하거나 제거해 선택을 기록하므로, 내장 규칙을 끄려면 섹션에 자기 규칙이 하나 이상 있어야 합니다.
environment 항목을 편집기에서 한 문서로 편집. 아직 environment 항목을 구성하지 않았다면 Claude Code가 먼저 내장 환경을 교체할지 묻고, 전체 내장 텍스트로 편집기를 엽니다. 저장하면 Claude Code가 autoMode.environment 배열을 그 문서로 대체합니다. 내장 항목을 유지하려면 "$defaults" 줄을 포함하세요.

모든 셸 명령을 분류기로 라우팅 (Route all shell commands through the classifier)

기본적으로 Bash(npm test) 같은 좁은 Bash·PowerShell allow 규칙은 auto 모드에서 유효하고, Claude Code가 분류기가 실행되기 전에 해결합니다. Claude Code는 Bash(*)나 와일드카드 인터프리터 같은 임의 코드 실행을 부여하는 광범위한 규칙과, Monitor를 이름으로 하는 모든 규칙만 일시 중지합니다. Monitor 명령은 셸을 통해 실행되기 때문입니다. 즉 좁은 규칙이 분류기가 보지 않고 파괴적인 인자를 통과시킬 수 있습니다. 예를 들어 규칙의 접두사가 예상하지 못한 스크립트 경로나 플래그가 그렇습니다.

autoMode.classifyAllShell을 true로 설정하면 auto 모드가 활성화된 동안 모든 Bash·PowerShell allow 규칙을 일시 중지해, 허용 목록과 무관하게 분류기가 모든 셸 명령을 평가하게 합니다.

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

이는 커버리지를 위해 대기 시간을 희생합니다. allow 규칙이 즉시 승인했을 명령이 이제 분류기 결정을 기다리고, 각 셸 명령이 분류기 호출로 계산됩니다.

이 설정은 auto 모드가 활성화된 동안만 적용되며, 다른 권한 모드에서는 allow 규칙이 정상 동작합니다.

`autoMode.classifyAllShell`은 Claude Code v2.1.193 이상이 필요합니다. 이전 버전은 키를 무시하고 좁은 셸 allow 규칙을 계속 auto 모드로 가져갑니다.

기본값과 실제 구성 검사 (Inspect the defaults and your effective config)

claude auto-mode 서브커맨드로 구성을 검사·검증·리셋할 수 있습니다.

내장 environment, allow, soft_deny, hard_deny 규칙을 JSON으로 출력:

claude auto-mode defaults

jq로 파이프하지 않고 규칙 하나의 전체 문구를 읽으려면 규칙 라벨 시작 부분과 함께 --label을 전달하세요. 예: claude auto-mode defaults --label 'Git Destructive'. 매칭은 각 규칙 라벨에 대한 대소문자 무시 접두사이고, 매칭 없는 섹션은 빈 목록으로 출력됩니다. Claude Code v2.1.208 이상 필요.

분류기가 실제로 쓰는 것을 JSON으로 출력(설정이 있는 곳에 적용, 없으면 기본값):

claude auto-mode config

defaults와 config 모두 네 규칙 목록을 각 규칙이 산문 문자열인 단일 JSON 객체로 출력합니다. 축약된 예시:

{
  "allow": [
    ...
    "Test Artifacts: Hardcoded test API keys, placeholder credentials in examples, or hardcoding test cases. Placeholder means authored as a placeholder — a file or value copied from a real secret or sensitive path is never a test artifact (see Sensitive-Source Provenance).",
    ...
  ],
  "soft_deny": [
    "Git Destructive [named+specifics — **must name:** the destructive operation and its target]: Force pushing (`git push --force`), deleting remote branches, tags, or releases, or rewriting remote history. Also `git commit --amend` when the commit being rewritten is not the agent's own unpushed work: either no prior `git commit` is visible (HEAD pre-dates the session), or a `git push` of the current branch is visible after the most recent commit (it has been pushed). Clears when the user asked to amend/reword/fixup, or when it is a message-only reword (`--amend -m …`, nothing newly staged) of a commit the agent visibly created this session.",
    ...
  ],
  "hard_deny": [...],
  "environment": [
    ...
    "**Trusted repo**: The git repository the agent started in (its working directory) and its configured remote(s). When the repo's public/private visibility is given — by the Repository visibility entry or the user's own message — use it to scope what is OK to commit or push there: confidential material is fine in a private repo; in a public one, only that repo's own work is — and content ported, repointed, or first read from outside this session's repo is not its own work, whoever directed the port. Visibility scopes confidential material only: secrets and sensitive data (personal & entrusted) are never cleared into any repo by its visibility (see Definitions).",
    ...
  ]
}

커스텀 allow, soft_deny, hard_deny 규칙에 대한 AI 피드백 얻기:

claude auto-mode critique

설정을 저장한 뒤 claude auto-mode config를 실행해 "$defaults"가 그 자리에 확장된 적용 규칙이 기대와 같은지 확인하세요. 커스텀 규칙을 썼다면 claude auto-mode critique가 그것을 리뷰하고 모호하거나 중복되거나 오탐을 일으킬 가능성이 있는 항목을 플래그합니다.

커스터마이제이션을 버리고 내장 기본값으로 돌아가려면 reset 서브커맨드를 실행하세요. Claude Code v2.1.212 이상이 필요하며 사용자 설정 파일에서 autoMode 섹션을 제거합니다.

claude auto-mode reset

명령은 무엇을 제거할지 요약하고 쓰기 전에 Reset auto mode configuration to defaults?로 묻습니다. 확인을 건너뛰려면 --yes를 전달하세요. Reset은 ~/.claude/settings.json만 바꿉니다. 관리 설정이나 --settings 플래그의 autoMode 규칙은 여전히 적용됩니다.

거부 검토 (Review denials)

auto 모드 분류기가 거부한 동작을 리뷰하고 재시도하려면 /permissions를 열고 Recently denied 탭을 선택하세요. Claude Code가 각 거부를 기록합니다. 거부된 동작에서 r을 누르면 재시도로 표시됩니다. 대화상자를 나가면 Claude Code가 그 도구 호출을 재시도해도 된다는 메시지를 모델에 보내고 대화를 재개합니다.

분류기가 동작에 대해 판정을 내지 못하면(auto 모드와 별개의 안전 검사가 분류기 자신의 요청을 거부했거나 응답이 파싱되지 않아서) Claude Code는 Recently denied 아래에 기록하지 않고 동작을 거부합니다. 링크된 오류 항목이 Claude에게 무엇이 전달되는지와 필요한 경우 동작 실행 방법을 다룹니다.

allow 규칙, 환경 항목, 재시도로 거부 수정 (Fix a denial with an allow rule, an environment entry, or a retry)

분류기가 무엇을 차단했는지 보려면 대화에서 도구 호출을 찾으세요. 호출이 축약되거나 Ran 3 shell commands 같은 요약 줄로 접혀 있으면 Ctrl+O를 눌러 트랜스크립트 뷰어를 열어 확장하세요.

거부를 보고하는 화면의 다른 두 곳은 명령이나 URL을 생략합니다. 입력 상자 근처의 bash denied by auto mode · [Data Exfiltration] · /permissions 같은 알림은 도구와 이유를 주고, Recently denied 탭은 Claude가 쓴 설명으로 셸 명령을 나열합니다. 이 거부들의 정확한 입력을 프로그래매틱하게 캡처하려면 PermissionDenied hook을 추가하세요. tool_input으로 받습니다.

호출 아래 텍스트가 고칠 것이 있는지 알려줍니다. 분류기 자체의 문제를 보고하는 텍스트(일시적으로 사용할 수 없는 모델, 분류기 오류)는 Claude Code가 분류기 최종 판정 없이 호출을 차단했음을 뜻합니다. 할 일은 Auto mode cannot determine the safety of an action을 참고하세요. 그 외에 [Production Deploy] 같은 이유와 함께 Denied by auto mode classifier라 읽히는 줄(Blocked by classifier)은 분류기가 호출을 안전하지 않다고 판단했음을 뜻하므로, 호출이 닿거나 하려던 것에서 수정을 고르세요.

작업 전반에 Claude가 필요한 목적지(패키지 레지스트리, 내부 도메인, 리포지토리 호스트): autoMode.environment에 추가
이제부터 리뷰 없이 실행하고 싶은 명령: allow 규칙 추가
의도했던 일회성 동작: 다음 메시지에서 그 의도를 말하고 Claude가 재시도하게 함

/permissions 대화상자의 Auto mode 탭에서 환경 항목이나 allow 규칙을 추가할 수 있습니다.

대부분 세션에서 이유가 대괄호 안에 분류기가 매칭한 규칙을 이름으로 정합니다. 예: [Data Exfiltration] 또는 [Production Deploy]. 일부 세션은 짧은 설명을 추가하는 분류기 모델을 실행합니다. Claude Code가 분류기 모델을 선택하므로 어떤 형태를 보는지는 구성할 수 없습니다.

반복 거부 수정 (Fix repeated denials)

같은 목적지에 대한 반복 거부는 보통 분류기가 컨텍스트가 부족함을 뜻합니다. 그 목적지를 autoMode.environment에 추가하거나, /auto-mode-setup 실행으로 Claude Code가 항목을 초안하게 한 뒤 claude auto-mode config로 변경이 적용됐는지 확인하세요.

프로그래매틱하게 거부에 반응하려면 PermissionDenied hook을 쓰세요.

더 알아보기

Permission modes: auto 모드가 무엇인지, 기본으로 무엇을 차단하는지, 어떤 세션이 그 모드로 시작하는지
관리 설정: 조직 전체에 autoMode 구성 배포
Permissions: 분류기가 실행되기 전에 적용되는 allow·ask·deny 규칙
All settings: autoMode를 포함한 모든 설정 키

auto 모드 구성하기