settings.json 설정

앞 글의 CLAUDE.md는 Claude에게 "이렇게 해 달라"고 부탁하는 파일입니다. settings.json은 반대로 Claude가 무엇을 결정하든 Claude Code 클라이언트가 강제하는 파일입니다. 어떤 명령은 묻지 않고 실행하고, 어떤 파일은 절대 읽지 못하게 하고, 기본 모델과 환경 변수를 고정하는 일이 여기서 이루어집니다. 다음 글 「훅(Hooks)으로 동작 강제하기」는 이 파일의 hooks 키 하나를 깊게 파는 글입니다.

핵심 요약

• 설정 파일은 사용자, 프로젝트, 로컬, 관리 정책 네 층입니다.
• 우선순위는 관리 정책 > 명령줄 인수 > 로컬 > 프로젝트 > 사용자입니다. 단 deny 규칙은 어느 층에 있든 다른 층이 뒤집지 못합니다.
• 허용 목록은 손으로 짜지 말고 하루 써 본 뒤 로컬 파일에 쌓인 규칙에서 골라 올립니다.

파일 위치와 우선순위

겹치는 키는 높은 층이 이깁니다. 예외는 permissions.deny로, 사용자 설정에서 허용하고 프로젝트에서 거부하면 거부가 이기며 그 반대도 같습니다.

권한 허용 목록

{
  "permissions": {
    "allow": ["Bash(pnpm test *)", "Bash(git commit *)"],
    "deny": ["Read(./.env)", "Read(./.env.*)", "Bash(git push *)"],
    "ask": ["Bash(rm *)"]
  }
}

규칙은 도구(지정자) 형식이고 deny, ask, allow 순서로 첫 일치가 결과를 정합니다. 초급 4주차의 "키 3규칙"을 파일로 옮기면 .env 읽기 거부가 첫 줄이 됩니다. 문법과 함정은 「퍼미션 설정 최적화」에서 따로 다룹니다.

환경 변수

env 키의 값은 모든 세션에 주입됩니다. 셸 프로필을 건드리지 않고 프로젝트 단위로 고정할 수 있습니다.

{ "env": { "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "32000", "DISABLE_TELEMETRY": "1" } }

비밀값은 넣지 않습니다. 프로젝트 settings.json은 git에 올라갑니다.

자주 쓰는 옵션

허용 목록을 만드는 실전 순서

1. 첫날은 허용 목록 없이 씁니다. 권한 창에서 "예, 다시 묻지 않기"를 고르면 규칙이 .claude/settings.local.json에 쌓입니다.
2. 하루 뒤 그 파일에서 팀 전체가 써도 안전한 규칙만 골라 .claude/settings.json으로 옮깁니다.
3. 절대 안 되는 것(.env 읽기, git push)은 deny에 먼저 적습니다.
4. /permissions로 최종 목록과 출처 파일을 확인합니다.

팀에 배포할 때

.claude/settings.json을 커밋하면 클론한 사람 모두에게 적용됩니다. 단 프로젝트 설정의 allow 규칙은 워크스페이스 신뢰 대화를 수락한 뒤에야 효력이 생기고, deny와 ask는 즉시 적용됩니다. 개인 포트나 로컬 경로는 .claude/settings.local.json에 두고 .gitignore에 올립니다. 조직 차원의 강제(bypass 모드 금지 등)는 관리 정책 파일에 두고 MDM으로 배포합니다.

정리

• settings.json은 "부탁"이 아니라 "강제"입니다.
• 네 층의 우선순위와 deny의 예외를 알면 설정이 안 먹는 이유를 바로 찾습니다.
• 허용 목록은 로컬 파일에 쌓인 것을 골라 올립니다.

자주 묻는 질문