Quick Reference

Claude Code 설정은 단순한 사용자 환경설정이 아니라 파일 접근·명령 실행·hook·MCP를 결정하는 정책 표면입니다. 같은 값이 여러 곳에 있으면 기본 우선순위는 managed > 명령행 인수 > local > project > user입니다. 다만 권한 배열은 범위별로 합쳐지고, 어느 한 범위의 deny라도 일치하면 allow로 되돌릴 수 없습니다.

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

범위와 파일 위치

managed 설정은 조직이 배포하는 가장 높은 정책이며 사용자·프로젝트·명령행 설정으로 풀 수 없습니다. user 설정은 모든 프로젝트에 적용하는 개인 기본값, project 설정은 Git에 커밋해 공유하는 규칙, local 설정은 내 컴퓨터에서만 쓰는 프로젝트별 재정의에 맞습니다.

Git 저장소 안에서 .claude/settings.local.json은 저장소 루트에 두며, worktree와 하위 디렉터리에서 시작한 세션도 이 파일을 공유합니다. Claude Code가 이 파일을 만들면 전역 Git 제외 목록에 추가하려고 하지만, 사람이 파일을 만들었다면 Git ignore 여부를 직접 확인해야 합니다. 기계별 경로나 개인 허용 규칙을 실수로 커밋하면 팀 전체의 실행 표면이 달라집니다.

MCP 서버의 저장 위치는 settings.json과 다릅니다. user 범위 MCP는 ~/.claude.json, project 범위 MCP는 .mcp.json, local 범위 MCP는 ~/.claude.json의 프로젝트 항목에 보관됩니다. .mcp.json은 팀에 공유할 외부 연결 목록이므로 일반 설정 파일과 같은 방식으로 검토해서는 안 됩니다.

권한 규칙을 읽는 법

permissions.allow는 자동 승인, ask는 반드시 묻기, deny는 차단을 뜻합니다. 파일 비밀값을 막을 때는 Read(경로)처럼 실제 도구와 경로를 적습니다. 위처럼 deny한 파일은 검색·파일 발견 결과에서도 빠지고 직접 읽기 호출도 거부됩니다. 예전 ignorePatterns는 이 용도에서 사용하지 않습니다.

규칙은 도구 전체를 막는지, 특정 호출만 막는지에 따라 다르게 동작합니다. "Bash"나 "mcp__*" 같은 이름만 있는 deny는 해당 도구를 Claude의 선택지에서 제거합니다. 반면 "Bash(rm *)"처럼 범위를 붙인 deny는 Bash를 남겨 두되 일치하는 명령만 거부합니다. 와일드카드 하나는 공백을 포함한 여러 인자를 가로지를 수 있으므로, Bash(git *)처럼 넓은 규칙을 안전한 Git 명령 전용으로 오해하지 않습니다.

{
  "permissions": {
    "allow": ["Bash(npm test)", "Read"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env*)", "Bash(rm -rf *)", "mcp__unapproved__*"]
  }
}

프로젝트의 allow와 additionalDirectories는 새 권한을 주므로 workspace trust를 수락하기 전에는 적용되지 않습니다. 반대로 deny와 ask는 제한 규칙이므로 trust를 기다리지 않고 적용됩니다. PreToolUse hook은 권한 대화상자보다 먼저 실행될 수 있지만, hook이 허용해도 일치하는 deny와 ask 규칙을 넘을 수 없습니다.

적용 상태를 확인하는 법

대화형 세션에서 /config는 theme·상세 출력 같은 일부 토글을 바꾸는 인터페이스입니다. 모든 JSON 설정의 최종 병합 결과를 보여 주는 도구로 쓰면 안 됩니다. 어떤 범위가 실제로 읽혔는지는 /status의 Setting sources에서 확인하고, 설정 파일 오류는 /status 또는 claude doctor로 확인합니다. Setting sources는 파일별 키의 최종 승자를 보여 주지는 않으므로, 충돌한 키는 각 범위를 직접 대조합니다.

자주 틀리는 부분

잘못된 설정
- ~/.claude/settings.json의 allow 하나로 팀 보안 기준이 해결된다고 생각한다.
- local 파일이 자동으로 항상 Git에서 제외된다고 가정한다.
- Bash(git *)를 읽기 전용 Git 규칙으로 사용한다.
- hook이 allow를 반환하면 deny를 넘을 수 있다고 생각한다.

권장 절차
1. 팀 공통 제한은 project 또는 managed deny로 둔다.
2. 개인 예외는 local에 좁게 두고 ignore 상태를 확인한다.
3. /status로 읽힌 범위를 확인하고 claude doctor로 오류를 고친다.
4. trust 후 적용되는 allow와 즉시 적용되는 deny·ask를 구분해 검토한다.