[Claude Code] 클로드 코드 settings.json 설정 파일 사용법 총정리

클로드 코드 설정 파일이란 클로드 코드에서 설정 파일은 클로드 코드의 동작 방식을 결정하는 일종의 프로필입니다. 클로드가 어떤 파일에 접근할 수 있는지, 어떤 명령어를 실행할 수 있는지, 어떤 AI 모델을 사용할지 등 다양한 옵션을 이 설정 파일을 통해 지정할 수 있습니다. 개발 팀이나 프로젝트 상황에 맞게 설정을 최적화하면 훨씬 원활하게 개발을 진행할 수 있는데요. 이번 글에서는 클로드 코드의 설정 파일이 어떻게 구성되어 있는지, 그리고 어떤 옵션들을 활용할 수 있는지 정리해보겠습니다.

 

 설정 파일의 세 가지 레벨 

1. 사용자 설정

사용자 설정은 사용자 홈 디렉터리의 .claude 디렉터리 안에 있는 settings.json 파일에 저장됩니다. 이 설정은 사용자가 진행하는 모든 프로젝트에 공통으로 적용됩니다. 예를 들어 A, B, C 세 개의 프로젝트를 동시에 진행하고 있다면, 사용자 설정은 이 세 프로젝트 모두에 동일하게 적용되는 방식입니다. 실제로 사용자 홈 디렉터리를 확인해보면 .claude 디렉터리가 존재하며, 그 안에 settings.json 파일이 있고 기본으로 사용할 모델이나 스테이터스 라인 옵션 등이 저장되어 있는 것을 확인할 수 있습니다.

 

2. 프로젝트 설정

프로젝트 설정은 프로젝트 디렉터리 내부에 저장되는 설정으로, 해당 프로젝트에만 적용됩니다. 프로젝트 설정에는 용도에 따라 두 가지 파일이 존재합니다.

• settings.json: 팀원들과 함께 공유하는 설정 파일입니다. 이 파일은 깃으로 관리되며 커밋과 푸시를 통해 팀원들과 공유할 수 있습니다.
• settings.local.json: 개인적인 선호도에 따라 설정하는 파일로, 깃에 포함되지 않아야 합니다.

주의할 점은 settings.local.json 파일이 실수로 깃에 커밋되어 팀원들에게 공유되는 경우가 발생할 수 있다는 것입니다. 이런 상황을 방지하려면 .gitignore 파일에 settings.local.json을 추가하여 깃 추적 대상에서 제외해야 합니다. .gitignore 파일은 깃으로 관리하지 않고 무시할 파일이나 디렉터리를 지정하는 파일입니다.

 

3. 엔터프라이즈 관리 정책 설정

세 번째 설정은 큰 기업에서 엔터프라이즈 관리 정책을 설정할 때 사용하는 파일입니다. 사용 중인 OS에 맞게 설정 파일을 구성하면 됩니다.

 

---

설정 우선순위

설정이 중복될 경우 적용되는 우선순위는 다음과 같습니다.

1. 엔터프라이즈 관리 정책 설정 (가장 높은 우선순위)
2. 개인 설정 (settings.local.json)
3. 프로젝트 설정 (settings.json)
4. 사용자 설정

 

유용한 설정 옵션

설정 파일에는 권한이나 환경 변수 외에도 다양한 옵션을 지정할 수 있습니다. 그 중 자주 활용되는 몇 가지 옵션을 소개합니다.

• 기본 권한 모드 설정: 자주 사용하는 권한 모드가 있다면 이를 디폴트 모드로 설정해두면 편리합니다. 예를 들어 플랜 모드를 자주 사용한다면 디폴트 모드를 플랜으로 지정해둘 수 있습니다.
• Additional Directories 옵션: 현재 작업 디렉터리 외에 다른 프로젝트를 클로드 코드가 참고하도록 하고 싶을 때 사용하는 옵션입니다. 예를 들어 벤치마킹하고 싶은 오픈소스 프로젝트를 클론받은 후, 이 옵션에 해당 폴더 경로를 작은따옴표로 감싸서 추가하면 됩니다.
• deny 옵션: API 키나 환경 파일 등 민감한 정보를 클로드 코드가 읽지 못하도록 차단하는 옵션입니다. 보안이 중요한 파일에 클로드 코드가 접근하지 못하게 하고 싶을 때 유용하게 사용할 수 있습니다.

 

settings.json 예시

클로드 코드에서 /config 명령어로 설정 화면을 열 수 있습니다. 또는 아래 링크에 직접 파일을 만들어주시면 됩니다.

• 프로젝트 설정 파일: .claude/settings.json
• 사용자 설정 파일: ~/.claude/settings.json

{
  "model": "claude-sonnet-4-6",
  "statusLine": {
    "type": "command",
    "command": "npx ccstatusline@latest"
  },
  "permissions": {
    "defaultMode": "plan",
    "allow": [
      "Bash(npm run *)",
      "Bash(git add *)",
      "Bash(git commit *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  },
  "additionalDirectories": [
    "../reference-project"
  ],
  "$schema": "https://json.schemastore.org/claude-code-settings.json"
}

위 예시에서 permissions.defaultMode는 기본 권한 모드를 지정하는 항목이며, allow와 deny 배열에는 각각 허용할 명령어와 차단할 명령어를 등록합니다. allow 항목에서 npm run *처럼 콜론이 아닌 공백 뒤에 와일드카드를 붙이는 방식이 최신 문법이라는 점을 다시 한번 확인할 수 있습니다. additionalDirectories에는 참고하고 싶은 다른 프로젝트 경로를 추가하면 되고, $schema 항목을 추가하면 코드 편집기에서 자동완성과 오타 감지 기능을 활용할 수 있습니다.

 

실전 예시: language 옵션으로 한국어 응답 고정하기

앞선 예시에 이어서, 실제로 많이 쓰이는 한국어 응답 고정 예시도 살펴보겠습니다.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "language": "korean",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(npm run build)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

이 설정의 의미는 다음과 같습니다.

• language: 클로드가 항상 한국어로 응답하도록 지정하는 옵션입니다. v2.1.0에서 추가된 공식 옵션입니다.
• allow: lint, test, build 명령어는 매번 실행 승인을 받지 않고 바로 실행되도록 허용합니다.
• deny: .env 파일이나 secrets 디렉터리는 클로드 코드가 절대 읽지 못하도록 차단합니다.

참고로 CLAUDE.md 파일에 "한국어로 답해줘"라고 지침을 적어두는 방법을 사용하는 경우가 많은데, language 옵션을 사용하는 편이 훨씬 정확하고 안정적으로 동작합니다. 이런식으로 팀원들과 공유할 항목은 settings.json에 작성하고, 개인적으로만 사용할 항목은 위와 동일한 구조로 settings.local.json 파일에 별도로 작성한 뒤 .gitignore에 등록해서 관리하면 됩니다.

 

---

 

 알아두면 좋은 변경 사항 및 팁 

Bash 권한 설정의 와일드카드 문법 변경

Bash는 터미널에서 컴퓨터에게 명령을 내리는 언어입니다. 예를 들어 폴더 안의 목록을 확인할 때는 ls 명령어를, 폴더를 이동할 때는 cd 명령어를 사용합니다. 클로드 코드 역시 이 Bash 명령어를 이용해 파일을 이동하거나 폴더를 탐색하는 등의 작업을 수행하며, 이러한 명령어에 대한 권한을 설정 파일의 permissions 속성 안에서 지정할 수 있습니다.

 

여기서 중요한 변경 사항은 와일드카드(*) 표현 방식입니다. 와일드카드는 "무엇이든 다"라는 의미로, 예를 들어 npm 뒤에 와일드카드를 붙이면 npm으로 시작하는 모든 명령어를 허용한다는 뜻이 됩니다. 예전에는 npm run:*처럼 콜론(:) 뒤에 와일드카드를 붙이는 방식이었지만, 이제는 콜론 대신 공백을 사용해서 npm run *과 같이 작성해야 합니다.

 

설정 파일의 JSON 스키마 지정

설정 파일에는 JSON 스키마도 지정할 수 있습니다. JSON 스키마는 코드 편집기에게 해당 파일이 클로드 코드 설정 파일이며, 어떤 키와 값을 사용할 수 있는지 미리 알려주는 일종의 명세 문서 역할을 합니다. 설정 방법은 간단합니다. 공식 문서의 설정 메뉴에서 스키마 한 줄을 복사해 설정 파일에 붙여넣기만 하면 됩니다. 이렇게 스키마를 적용하면 코드 편집기가 파일의 스펙을 미리 감지해 자동완성이나 오타를 잡아주는 기능을 제공합니다. 새로운 설정을 적용했을 때 빨간색 오류 표시가 뜬다면, 스키마를 적용해보는 것이 도움이 될 수 있습니다.

 

마무리

이번 글에서는 클로드 코드의 설정 파일 구조와 세 가지 레벨의 설정, 그리고 우선순위에 대해 정리해보았습니다. 또한 최근 변경된 와일드카드 문법과 JSON 스키마 지정 방법도 함께 살펴보았습니다. 공식 문서는 처음 볼 때 다소 어렵게 느껴질 수 있지만, 이는 자주 접하지 않아서인 경우가 많습니다. 가끔씩이라도 변경된 스펙을 확인하는 습관을 들인다면 바이브 코딩으로 개발할 때도 큰 도움이 될 것입니다.