Claude Code 설정을 한번 잡아두면, 매번 같은 허락을 반복하거나 원치 않는 동작을 막느라 시간 쓰는 일이 줄어듭니다. 결론부터 말하면, settings.json 파일 하나를 이해하면 권한 관리부터 도구 허용까지 대부분 해결돼요.
이 글은 개발자가 아닌 분들, 그러니까 Claude Code를 매일 업무에 쓰지만 프로그래밍 자체가 본업은 아닌 분들을 위해 썼습니다. 코드 예시는 꼭 필요한 만큼만 넣었어요.
Claude Code 설정, 왜 건드려야 하나요
Claude Code를 처음 설치하면 기본 설정 상태로 동작합니다. 이 상태에서도 쓸 수는 있지만, 매번 “이 파일 수정해도 돼요?” 같은 확인 창이 뜨거나, 특정 명령어를 실행할 때마다 승인을 요구해요.
자주 쓰는 도구는 미리 허용해두고, 위험한 동작은 차단해두면 훨씬 편해집니다. 그게 바로 Claude Code 설정의 핵심이에요.
settings.json이 뭔가요
settings.json은 Claude Code의 동작 방식을 정해두는 파일입니다. “이 도구는 허락 없이 써도 돼”, “이 명령어는 항상 물어봐” 같은 규칙을 적어두는 곳이에요.
CLAUDE.md가 “무엇을 해줘”라는 지시서라면, settings.json은 “어떻게 동작해”라는 규칙서에 가깝습니다. 둘 다 중요하지만 역할이 달라요.
3가지 범위: 프로젝트, 사용자, 글로벌
Claude Code 설정에는 적용 범위가 3단계로 나뉩니다. 이 구조를 이해하면 “왜 이 설정이 안 먹히지?” 하는 상황을 피할 수 있어요.
1. 프로젝트 설정 (해당 프로젝트에만 적용)
프로젝트 폴더 안의 .claude/settings.json에 저장됩니다. 이 프로젝트에서만 적용되는 설정이에요. 팀원과 공유할 수 있다는 장점이 있습니다.
또 하나, .claude/settings.local.json이라는 파일도 있어요. 이건 같은 프로젝트 범위지만 나만 쓰는 개인 설정입니다. Git에 올라가지 않아서 팀원에게 영향을 주지 않아요.
2. 사용자 설정 (내 컴퓨터 전체에 적용)
홈 디렉토리의 ~/.claude/settings.json에 저장됩니다. 어떤 프로젝트를 열든 이 설정이 기본으로 깔려요. “나는 항상 이 도구를 허용할 거야” 같은 규칙을 여기에 넣으면 됩니다.
3. 글로벌 설정 (조직 전체 적용)
조직 관리자가 관리하는 설정이에요. 개인이 바꿀 수 없고, 회사에서 일괄 적용하는 보안 정책 같은 것이 들어갑니다. 개인 사용자라면 신경 쓸 일이 거의 없어요.
적용 우선순위: 글로벌 > 사용자 > 프로젝트 순으로 적용됩니다. 글로벌에서 막아놓은 건 프로젝트에서 풀 수 없어요.
권한 모드 3가지
Claude Code는 파일을 읽고, 수정하고, 명령어를 실행할 수 있는 도구이다 보니 권한 관리가 중요합니다. 권한 모드는 3가지가 있어요.
- allowedTools — 허락 없이 자동으로 쓸 수 있는 도구 목록입니다. 여기에 넣어두면 매번 승인 창이 뜨지 않아요
- deniedTools — 아예 사용을 차단하는 도구 목록입니다. 위험하다고 판단되는 도구를 여기에 넣으면 실행 자체가 안 돼요
- 기본(미지정) — allowedTools에도 deniedTools에도 없으면, 실행할 때마다 사용자에게 물어봅니다
실전에서 가장 많이 쓰는 건 allowedTools입니다. 예를 들어 파일 읽기(Read), 파일 검색(Glob, Grep) 같은 안전한 도구는 허용해두면 작업 흐름이 빨라져요.
allowedTools 설정 예시
settings.json에 이렇게 적으면 됩니다.
{
"permissions": {
"allowedTools": [
"Read",
"Glob",
"Grep",
"Write",
"Edit"
]
}
}위 설정은 파일 읽기, 검색, 쓰기, 수정을 자동 허용한다는 의미예요. Bash 명령어(터미널 실행)는 일부러 빼두는 게 안전합니다. 특정 Bash 명령만 허용하고 싶으면 "Bash(npm run build)"처럼 괄호 안에 명령어를 지정할 수도 있어요.
이 설정을 직접 파일을 열어서 편집할 수도 있지만, Claude Code 안에서 /permissions를 입력하면 대화형으로 권한을 관리할 수 있습니다. 비개발자분들에게는 이 방법이 더 편해요.
자주 쓰는 설정 항목 정리
| 항목 | 위치 | 용도 |
|---|---|---|
| allowedTools | permissions 안 | 자동 허용할 도구 목록 |
| deniedTools | permissions 안 | 차단할 도구 목록 |
| model | 최상위 | 사용할 AI 모델 지정 (예: claude-sonnet-4-20250514) |
| customApiKeyResponses | 최상위 | API 키 사용 시 동작 설정 |
이 외에도 환경 변수, 훅(hook) 같은 고급 설정이 있지만, 매일 쓰는 수준에서는 permissions 설정만 알아도 충분합니다.
주의할 점 3가지
1. allowedTools에 Bash를 무조건 넣지 마세요
"Bash"를 통째로 허용하면 Claude Code가 어떤 터미널 명령이든 확인 없이 실행할 수 있게 됩니다. 파일 삭제 명령이 실행될 수도 있어요. 꼭 필요한 명령어만 "Bash(git status)" 형식으로 지정하는 게 안전합니다.
2. settings.json과 CLAUDE.md를 혼동하지 마세요
settings.json은 도구 권한과 동작 규칙을 관리하고, CLAUDE.md는 작업 지시와 프로젝트 맥락을 전달합니다. “보고서는 HTML로 만들어줘”는 CLAUDE.md에, “Write 도구는 항상 허용”은 settings.json에 넣는 거예요.
3. 프로젝트 설정과 사용자 설정을 구분하세요
모든 프로젝트에 적용할 설정은 사용자 설정(~/.claude/settings.json)에, 특정 프로젝트에서만 쓸 설정은 프로젝트 설정(.claude/settings.json)에 넣으세요. 섞어서 넣으면 나중에 “이 설정이 왜 안 먹히지?” 하는 상황이 생깁니다.
정리하면
Claude Code 설정은 한번 잡아두면 매일 쓰는 과정이 훨씬 편해집니다. 핵심만 요약하면 이렇습니다.
- settings.json이 권한과 동작 규칙을 관리하는 파일
- 적용 범위는 프로젝트 < 사용자 < 글로벌 3단계
- allowedTools에 자주 쓰는 안전한 도구를 넣어두면 승인 반복이 사라짐
- Bash는 통째로 허용하지 말고, 필요한 명령어만 지정
처음에는 /permissions 명령으로 대화형으로 관리하다가, 익숙해지면 settings.json을 직접 편집하는 순서를 추천합니다.
※ 이 글은 2026년 6월 기준으로 작성됐습니다. Claude Code 설정 관련 최신 정보는 공식 문서에서 확인하실 수 있어요.
관련 글 추천