빠른 설정

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  }
}

설정 구조

settings가 세 계층으로 나뉘어야 하는 이유

Claude Code 설정은 user, project, local 계층으로 나뉩니다. ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json이 서로 다른 범위와 우선순위를 가집니다. 이 구조 덕분에 개인 취향, 팀 공통 규칙, 로컬 실험 설정을 분리할 수 있습니다. 테마나 개인 알림은 user, 팀이 공유할 규칙은 project, 커밋하고 싶지 않은 실험은 local에 두는 식이 자연스럽습니다. 계층을 구분하지 않으면 개인 설정이 팀 설정을 덮어쓰거나 실험 설정이 저장소에 커밋되는 문제가 생깁니다.

현재 Anthropic 문서 기준으로 enterprise managed policy 설정도 별도 계층으로 지원됩니다. 따라서 개인, 프로젝트, 로컬만 있다고 보면 팀 보안 규칙이 실제로 어디에서 강제되는지 놓칠 수 있습니다.

permissions.deny가 프롬프트 지시보다 강력한 이유

permissions.deny는 특히 중요한 보안 설정입니다. .env, secrets, credential 파일처럼 민감한 내용을 Claude Code가 아예 읽지 못하게 구조적으로 막습니다. 프롬프트에 "이 파일은 읽지 마"라고 적는 것과 달리, permissions.deny는 요청 자체를 차단하므로 실수로 민감 파일을 노출할 가능성이 없습니다. 세션마다 지시를 반복할 필요도 없고, 팀원이 Claude Code를 처음 사용할 때도 자동으로 보호가 적용됩니다.

user
  -> 개인 기본값

project
  -> 팀 공통 규칙

local
  -> 내 컴퓨터에서만 쓰는 실험

/config와 CLI 명령으로 설정을 다루는 이유

설정은 interactive session의 /config와 CLI claude config ... 명령으로도 다룰 수 있습니다. 파일을 직접 열고 JSON을 수정하는 것보다 실수가 적고, 현재 활성화된 설정 상태를 바로 확인할 수 있습니다. 특히 프로젝트 설정이 복잡해졌을 때는 /config로 전체 적용 상태를 먼저 확인하는 것이 문제 진단에 빠릅니다.

권한 쪽은 /permissions 명령으로 따로 확인하거나 조정할 수 있다는 점도 중요합니다. /config가 설정 전반을 보는 창이라면, /permissions는 실제 도구 사용 허용과 확인 흐름을 더 직접 다루는 표면입니다.

settings가 편의성인 동시에 안전성 카드인 이유

Claude Code를 오래 쓸수록 output 품질보다 permissions와 scope 관리가 더 중요해집니다. 처음에는 빠른 시작을 위해 넓은 권한으로 시작하더라도, 실제 운영 환경에서는 project settings에 permissions.deny 항목을 명시적으로 관리하는 편이 안전합니다. 팀 전체가 같은 보호 규칙 아래에서 Claude Code를 쓰려면 project 계층의 settings 파일을 저장소에 커밋해 공유해야 합니다.

어디서 조정할까

주의할 점

❌ secrets 차단 규칙을 ~/.claude/settings.json 에만 추가

이렇게 하면 본인 환경만 안전하고, 다른 팀원 세션에는 같은 보호 규칙이 자동 적용되지 않습니다.