06. 설정 파일 체계

학습 목표

• Claude Code의 JSON 설정 파일 체계를 이해한다.
• 3가지 스코프(프로젝트, 개인, 사용자)의 차이와 용도를 파악한다.
• 설정 우선순위 규칙을 정확히 이해하고 활용한다.
• 실전 시나리오에 맞는 설정 전략을 세울 수 있다.

---

1. 설정 파일 개요

Claude Code의 동작을 세밀하게 제어하는 방법은 크게 두 가지다.

구분	메모리 파일 (CLAUDE.md)	설정 파일 (settings.json)
형식	Markdown	JSON
대상	AI에게 주는 지침 (프롬프트)	Claude Code 시스템 자체의 동작 설정
역할	"이 프로젝트에서는 테스트를 꼭 작성해", "커밋 메시지는 한국어로" 등	권한 규칙, 사용 모델, 환경변수, 응답 언어 등
읽는 주체	Claude (AI 모델)	Claude Code (호스트 애플리케이션)

CLAUDE.md는 AI에게 "어떻게 행동할지" 알려주는 지침서이고, settings.json은 Claude Code 애플리케이션 자체가 "어떻게 작동할지" 결정하는 설정 파일이다. 둘은 상호 보완적이지만 완전히 별개의 시스템이다.

왜 별도의 설정 파일이 필요한가?

CLAUDE.md에 "bash 명령어는 자동 승인해줘"라고 적어도, Claude Code 시스템은 이를 보안 규칙으로 인식하지 않는다. AI가 읽는 텍스트일 뿐이다. 반면 settings.json의 permissions.allow에 "bash"를 추가하면, 시스템 레벨에서 확실하게 자동 승인이 적용된다.

CLAUDE.md  → AI가 읽고 행동을 조절하는 "지침서"
settings.json → 시스템이 읽고 기능을 제어하는 "설정 파일"

---

2. 3가지 설정 파일

Claude Code는 설정을 스코프(적용 범위) 에 따라 나누어 관리한다. 각 설정 파일은 서로 다른 위치에 존재하며, 적용 범위와 공유 대상이 다르다.

---

2-1. 프로젝트 설정 (settings.json)

항목	내용
위치	프로젝트루트/.claude/settings.json
적용 범위	이 프로젝트를 사용하는 모든 팀원
Git 공유	커밋하여 팀원과 공유
용도	팀 공통 규칙, 프로젝트 표준

프로젝트 설정은 팀 전체가 공유하는 규칙을 정의한다. Git에 커밋하므로 팀원이 클론만 받으면 동일한 설정이 적용된다.

// .claude/settings.json - 팀 공유 설정 예시
{
  "permissions": {
    "allow": [
      "bash(npm run *)",
      "bash(npx *)",
      "bash(git status)",
      "bash(git diff *)",
      "bash(git log *)",
      "edit",
      "mcp__context7"
    ],
    "deny": [
      "bash(rm -rf *)",
      "bash(git push --force *)",
      "bash(git reset --hard *)",
      "edit(~/.ssh/*)",
      "edit(.env*)"
    ]
  },
  "defaultMode": "plan",
  "model": "sonnet",
  "env": {
    "NODE_ENV": "development"
  },
  "language": "ko"
}

주요 활용 사례:

• 위험한 명령어(force push, hard reset 등) 팀 차원에서 차단
• 프로젝트 공용 빌드 스크립트 자동 승인
• 팀 공통 모델과 응답 언어 통일
• 개발 환경변수 기본값 설정

---

2-2. 개인 설정 (settings.local.json)

항목	내용
위치	프로젝트루트/.claude/settings.local.json
적용 범위	이 프로젝트에서 나만
Git 공유	절대 공유 안 함 (.gitignore 필수)
용도	개인 취향, 개인 API 키, 로컬 환경

개인 설정은 팀원에게 영향을 주지 않는 나만의 설정이다. 중요한 점은 이 파일은 절대로 Git에 커밋하면 안 된다는 것이다.

// .claude/settings.local.json - 개인 설정 예시
{
  "permissions": {
    "allow": [
      "bash(docker *)",
      "bash(kubectl *)",
      "mcp__playwright"
    ]
  },
  "model": "opus",
  "env": {
    "GEMINI_API_KEY": "my-personal-api-key",
    "DATABASE_URL": "postgresql://localhost:5432/mydb"
  },
  "additionalDirectories": [
    "/Users/me/workspace/reference-project"
  ]
}

주요 활용 사례:

• 개인 API 키나 로컬 DB 접속 정보 설정
• 팀은 Sonnet을 쓰지만 나만 Opus를 사용하고 싶을 때
• 개인적으로 사용하는 도구(Docker, kubectl 등) 자동 승인
• 다른 프로젝트를 참고 자료로 추가 (additionalDirectories)

---

2-3. 사용자 설정 (User Settings)

항목	내용
위치	~/.claude/settings.json
적용 범위	내 PC의 모든 프로젝트
Git 공유	홈 디렉토리라 공유 불가
용도	전역 기본값

사용자 설정은 내 컴퓨터에서 Claude Code를 실행할 때마다 항상 적용되는 전역 기본값이다. 어떤 프로젝트를 열든 이 설정이 기본으로 깔린다.

// ~/.claude/settings.json - 전역 사용자 설정 예시
{
  "permissions": {
    "allow": [
      "bash(git status)",
      "bash(git log *)",
      "bash(git diff *)"
    ],
    "deny": [
      "bash(rm -rf /)",
      "bash(sudo *)"
    ]
  },
  "defaultMode": "plan",
  "language": "ko"
}

주요 활용 사례:

• 모든 프로젝트에서 공통적으로 적용할 안전 규칙
• 기본 응답 언어 설정
• 전역 기본 권한 모드 (plan 권장)

---

2-4. Enterprise 관리 정책

항목	내용
위치 (macOS)	/Library/Application Support/claude-code/settings.json
위치 (Linux)	/etc/claude-code/settings.json
위치 (Windows)	%ProgramData%\claude-code\settings.json
적용 범위	해당 머신의 모든 사용자, 모든 프로젝트
관리 주체	IT 관리자 / 회사 보안팀
용도	회사 차원의 보안 정책 강제

Enterprise 관리 정책은 회사 IT 관리자가 머신 레벨에서 강제하는 보안 정책이다. 일반 개발자가 직접 설정할 일은 거의 없으며, MDM(모바일 디바이스 관리) 등을 통해 배포된다. 이 설정은 최우선 순위로 적용되어 개인이 덮어쓸 수 없다.

// /Library/Application Support/claude-code/settings.json (macOS 예시)
{
  "permissions": {
    "deny": [
      "bash(curl * | bash)",
      "bash(wget * | bash)",
      "edit(/etc/*)",
      "edit(~/.ssh/*)"
    ]
  }
}

---

3. 설정 우선순위

4가지 설정 파일이 동시에 존재할 때, Claude Code는 다음 우선순위로 설정을 적용한다.

우선순위 요약

Enterprise 관리 정책 > 개인 설정(local) > 프로젝트 설정 > 사용자 설정 > 기본값
       (최우선)                                                    (최하위)

핵심 포인트

• Enterprise 관리 정책은 절대적이다. deny에 포함된 항목은 어떤 설정으로도 허용할 수 없다.
• 개인 설정(local)이 프로젝트 설정보다 우선한다. 팀이 Sonnet을 쓰도록 정했어도, 개인 설정에서 Opus로 바꿀 수 있다.
• permissions는 병합(merge)된다. allow 목록과 deny 목록은 각 레벨에서 합산되며, deny가 allow보다 항상 우선한다.
• 단일 값 설정은 상위가 덮어쓴다. model, language, defaultMode 같은 단일 값은 더 높은 우선순위의 설정이 완전히 대체한다.

permissions 병합 예시

사용자 설정:    allow: ["bash(git *)"]              deny: ["bash(rm -rf /)"]
프로젝트 설정:  allow: ["bash(npm run *)"]           deny: ["bash(git push --force *)"]
개인 설정:      allow: ["bash(docker *)"]            deny: []

=== 최종 병합 결과 ===
allow: ["bash(git *)", "bash(npm run *)", "bash(docker *)"]
deny:  ["bash(rm -rf /)", "bash(git push --force *)"]

---

4. 주요 설정 옵션

4-1. 전체 설정 구조

{
  "permissions": {
    "allow": ["..."],
    "deny": ["..."]
  },
  "defaultMode": "plan",
  "model": "sonnet",
  "additionalDirectories": ["/path/to/reference-project"],
  "env": {
    "NODE_ENV": "development"
  },
  "language": "ko"
}

4-2. 각 옵션 상세

permissions.allow - 자동 승인 목록

도구 사용 시 승인 프롬프트 없이 자동으로 실행을 허용할 명령어 패턴 목록이다.

{
  "permissions": {
    "allow": [
      "bash(npm run *)",
      "bash(npx *)",
      "bash(git status)",
      "bash(git diff *)",
      "bash(git log *)",
      "bash(go test *)",
      "bash(make *)",
      "edit",
      "mcp__context7",
      "mcp__playwright"
    ]
  }
}

• bash(패턴) : 특정 bash 명령어 패턴 허용. * 와일드카드 사용 가능.
• edit : 파일 편집 도구 전체 허용.
• mcp__서버이름 : 특정 MCP 서버의 도구 전체 허용.

permissions.deny - 사용 금지 목록

어떤 상황에서도 실행을 차단할 명령어 패턴 목록이다. allow에 포함되어 있어도 deny가 우선한다.

{
  "permissions": {
    "deny": [
      "bash(rm -rf *)",
      "bash(git push --force *)",
      "bash(git reset --hard *)",
      "bash(sudo *)",
      "bash(curl * | bash)",
      "edit(.env*)",
      "edit(~/.ssh/*)",
      "edit(**/credentials*)"
    ]
  }
}

• 보안에 민감한 파일(.env, SSH 키, 인증 정보)의 편집 차단에 특히 유용하다.
• 위험한 시스템 명령어를 팀 차원에서 원천 차단할 수 있다.

defaultMode - 기본 권한 모드

Claude Code를 시작할 때 적용되는 기본 권한 모드를 설정한다.

값	설명
"plan"	계획 모드. 실행 전 항상 계획을 먼저 세움. 초보자에게 권장
"auto"	자동 모드. allow 목록에 있으면 바로 실행
"bypassPermissions"	모든 권한 검사 건너뜀. 위험하므로 비권장

{
  "defaultMode": "plan"
}

model - 사용 모델 고정

사용할 AI 모델을 지정한다. 팀 전체의 비용 관리나 일관된 품질 유지에 유용하다.

값	특징
"opus"	최고 품질, 복잡한 작업에 적합, 비용 높음
"sonnet"	균형 잡힌 성능, 일상 개발에 최적, 기본값
"haiku"	빠른 응답, 간단한 작업에 적합, 비용 낮음

{
  "model": "sonnet"
}

additionalDirectories - 추가 참고 프로젝트

Claude Code가 현재 프로젝트 외에 추가로 참고할 디렉토리를 지정한다. 벤치마킹이나 모노레포 환경에서 특히 유용하다.

{
  "additionalDirectories": [
    "/Users/me/workspace/design-system",
    "/Users/me/workspace/api-reference",
    "/Users/me/workspace/competitor-app"
  ]
}

활용 예시:

• 디자인 시스템 프로젝트를 참고하면서 프론트엔드 개발
• 기존 API 서버 코드를 참고하면서 새 API 설계
• 경쟁사 오픈소스 프로젝트 구조를 참고하면서 아키텍처 설계

env - 환경변수

Claude Code 세션에서 사용할 환경변수를 설정한다.

{
  "env": {
    "NODE_ENV": "development",
    "DATABASE_URL": "postgresql://localhost:5432/devdb",
    "API_BASE_URL": "http://localhost:3000"
  }
}

주의: API 키나 비밀번호 같은 민감한 값은 settings.local.json에 넣고, 절대 settings.json에는 넣지 않는다.

language - 응답 언어

Claude Code의 응답 언어를 지정한다.

{
  "language": "ko"
}

값	언어
"ko"	한국어
"en"	영어
"ja"	일본어
"zh"	중국어

---

5. .gitignore 설정

settings.local.json은 반드시 .gitignore에 추가해야 한다. 개인 설정이 실수로 팀에 공유되면 다음과 같은 문제가 발생할 수 있다.

발생 가능한 사고

사고 유형	예시
API 키 유출	개인 GEMINI_API_KEY가 Git 히스토리에 남음
DB 접속 정보 유출	로컬 DATABASE_URL이 팀원에게 노출
설정 충돌	내가 Opus로 바꾼 설정이 팀원의 Sonnet 설정과 충돌
권한 혼란	개인적으로 허용한 위험 명령어가 팀 정책으로 오인

.gitignore 설정 방법

# .gitignore에 추가
.claude/settings.local.json

프로젝트 초기 세팅 시 다음 명령어로 한 번에 처리할 수 있다.

# .gitignore에 개인 설정 파일 제외 규칙 추가
echo ".claude/settings.local.json" >> .gitignore

이미 커밋된 경우에는 Git 추적을 해제해야 한다.

# 이미 커밋된 경우: 추적 해제 후 .gitignore에 추가
git rm --cached .claude/settings.local.json
echo ".claude/settings.local.json" >> .gitignore
git commit -m "개인 설정 파일 Git 추적 해제"

---

6. 실전 활용 시나리오

---

시나리오 1: 팀 프로젝트

팀에서 프론트엔드 프로젝트를 진행한다고 가정하자. 팀 리더가 공통 규칙을 정하고, 각 팀원이 개인 설정을 추가하는 구조다.

1단계: 팀 공통 규칙 (settings.json)

// .claude/settings.json - Git에 커밋
{
  "permissions": {
    "allow": [
      "bash(npm run *)",
      "bash(npx *)",
      "bash(git status)",
      "bash(git diff *)",
      "bash(git log *)",
      "edit"
    ],
    "deny": [
      "bash(rm -rf *)",
      "bash(git push --force *)",
      "bash(git reset --hard *)",
      "edit(.env*)"
    ]
  },
  "defaultMode": "plan",
  "model": "sonnet",
  "env": {
    "NODE_ENV": "development"
  },
  "language": "ko"
}

2단계: 개인 취향 (settings.local.json)

// .claude/settings.local.json - .gitignore에 추가
{
  "permissions": {
    "allow": [
      "bash(docker *)",
      "mcp__playwright"
    ]
  },
  "model": "opus",
  "env": {
    "GEMINI_API_KEY": "my-personal-key"
  }
}

3단계: .gitignore 설정

# .gitignore
.claude/settings.local.json

이렇게 하면 새 팀원이 레포를 클론받으면 팀 공통 규칙이 자동 적용되고, 각자의 개인 취향은 독립적으로 관리된다.

---

시나리오 2: 1인 프로젝트

혼자 진행하는 프로젝트에서는 settings.json 하나면 충분하다.

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "bash(go test *)",
      "bash(go vet *)",
      "bash(make *)",
      "bash(git *)",
      "edit"
    ],
    "deny": [
      "bash(rm -rf /)"
    ]
  },
  "defaultMode": "auto",
  "model": "sonnet",
  "language": "ko"
}

1인 프로젝트에서는 defaultMode를 "auto"로 설정해도 괜찮다. 혼자 작업하므로 실행 속도를 높이는 것이 더 효율적이다.

---

시나리오 3: 벤치마킹 / 참고 프로젝트 활용

새 프로젝트를 시작하면서 기존 프로젝트의 구조를 참고하고 싶을 때, additionalDirectories를 활용한다.

// .claude/settings.local.json
{
  "additionalDirectories": [
    "/Users/me/workspace/existing-api-server",
    "/Users/me/workspace/design-system"
  ]
}

이렇게 설정하면 Claude Code에게 "이 프로젝트의 코드를 참고해서 작업해줘"라고 말할 수 있다.

사용자: "existing-api-server 프로젝트의 인증 모듈 구조를 참고해서
        이 프로젝트에도 비슷한 인증 시스템을 만들어줘."

Claude: (두 프로젝트를 모두 참조하여 작업 수행)

---

7. 설정 파일 빠른 참조표

설정 파일	위치	적용 범위	Git 공유	주요 용도
Enterprise 정책	OS별 시스템 경로	머신 전체	N/A	회사 보안 정책
사용자 설정	~/.claude/settings.json	내 PC 전체	불가	전역 기본값
프로젝트 설정	.claude/settings.json	프로젝트 전체	커밋하여 공유	팀 공통 규칙
개인 설정	.claude/settings.local.json	프로젝트 + 나만	.gitignore 필수	개인 취향

설정 옵션	설명	권장 위치
permissions.allow	자동 승인할 도구/명령어	프로젝트 설정
permissions.deny	사용 금지할 도구/명령어	프로젝트 설정
defaultMode	기본 권한 모드	프로젝트 설정
model	사용할 모델	프로젝트 또는 개인 설정
additionalDirectories	참고 프로젝트 경로	개인 설정
env (공개 값)	환경변수 (공개 가능)	프로젝트 설정
env (비밀 값)	환경변수 (API 키 등)	개인 설정
language	응답 언어	프로젝트 또는 사용자 설정

---

8. 핵심 요약

1. settings.json은 시스템 설정, CLAUDE.md는 AI 지침 -- 이 둘은 역할이 완전히 다르다.
2. 4가지 스코프: Enterprise > 개인(local) > 프로젝트 > 사용자 순으로 우선순위가 적용된다.
3. permissions는 병합, 단일 값은 덮어쓰기 -- deny는 항상 allow보다 우선한다.
4. settings.local.json은 반드시 .gitignore에 추가 -- 개인 키와 설정 유출을 방지한다.
5. 팀 프로젝트는 settings.json + settings.local.json 조합이 최적이다.
6. 1인 프로젝트는 settings.json 하나면 충분하다.
7. additionalDirectories로 벤치마킹 프로젝트를 참고할 수 있다.

---

다음 단계

• 이전: 05. 메모리 관리
• 다음: 07. MCP
• 목차로 돌아가기