설정 파일 settings.json — 네 곳의 의미

settings.json은 클로드 코드의 동작 규칙을 담아 두는 파일입니다. 어떤 명령을 허락 없이 실행해도 되는지는 물론, 기본으로 쓸 모델, 훅(정해진 순간이 오면 저절로 실행되는 자동 장치), 환경 변수까지 여기에 적습니다. 환경 변수는 프로그램이 켜질 때 참고하는 짧은 설정값입니다. 같은 역할을 하는 설정 파일이 네 곳에 나뉘어 있고, 겹치면 정해진 순서를 따릅니다.

settings.json이란

settings.json은 JSON이라는 형식으로 쓰는 설정 파일입니다. JSON은 항목 이름(키)과 내용(값)을 짝지어 적는 방식이라, “기본 모델은 무엇”, “이 명령어는 허용”처럼 규칙을 한 줄씩 담습니다.

한 번 적어 두면 클로드 코드를 켤 때마다 그 규칙이 자동으로 적용됩니다. 매번 같은 설정을 손으로 지정할 필요가 없습니다. 자주 쓰는 값을 미리 저장해 두는 자동차 좌석 메모리와 비슷합니다.

이 파일의 여러 항목 중 권한(permissions) 하나만 깊이 다루는 페이지는 「권한 — 허용·물어봄·막기」입니다. 이 페이지에서는 파일 자체, 즉 네 곳의 위치와 우선순위, 자주 쓰는 항목을 다룹니다.

설정 파일은 네 곳에 있습니다

설정은 한 파일에만 있지 않습니다. 개인 취향은 개인 파일에, 팀 전체가 지킬 규칙은 프로젝트 파일에 따로 두기 위해 네 곳으로 나뉩니다. 아래 표에서 ~는 홈 폴더(내 계정의 맨 위 폴더)를 뜻합니다.

로컬 파일은 깃(파일이 바뀐 기록을 남기는 도구)의 기록에서 빼 두는 파일이라 남에게 공유되지 않습니다. 클로드 코드가 이 파일을 처음 만들 때는 깃 제외 목록에 알아서 넣어 줍니다. 손으로 만든 파일이라면 그 목록(.gitignore)에 내가 직접 적어 둡니다. 그래서 남에게 보이면 안 되는 비밀 정보는 넷 중 로컬 파일에 둡니다.

관리자 파일에는 forceLoginMethod(로그인 방식 제한)·allowedMcpServers(쓸 수 있는 외부 연결 서버 통제) 같은 전용 항목도 있습니다. 회사 IT가 관리하는 몫이라 개인이 신경 쓸 일은 적습니다.

겹치면 무엇을 따를까요 — 우선순위 사다리

같은 항목이 여러 파일에 다르게 적혀 있으면 충돌이 생깁니다. 이때 어느 쪽을 따를지 정하는 순서가 우선순위입니다. 위에 있을수록 우선합니다.

우선순위는 관리자 > 명령줄 > 로컬 > 프로젝트 > 사용자입니다. 예를 들어 사용자 파일과 프로젝트 파일에 기본 모델이 다르게 적혀 있으면, 프로젝트 파일의 설정을 따릅니다.

설정 파일은 이렇게 생겼습니다

아래는 자주 쓰이는 항목 두 가지, 권한과 환경 변수를 담은 짧은 예시입니다.

# .claude/settings.json 예시
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  }
}

맨 위 $schema 줄은 이 설정 파일의 형식을 알려 주는 안내표입니다. 이 줄을 알아보는 편집기(파일을 열어 고치는 프로그램)에서는 자동완성과 오타 검사가 켜집니다. 넣어 두면 설정을 손으로 적을 때 실수를 줄일 수 있습니다. permissions는 어떤 도구·파일을 허용할지, 막을지 정합니다. env는 세션마다 자동으로 적용할 환경 변수를 정합니다. 우리 회사도 .env 같은 비밀 파일은 이렇게 막기(deny) 규칙으로 읽지 못하게 해 두고 시작합니다.

env에 적은 변수의 적용 범위는 파일 위치를 따릅니다. 사용자 파일에 적으면 모든 프로젝트에, 프로젝트 파일에 적으면 그 저장소를 쓰는 모두에게, 로컬 파일에 적으면 나 한 사람에게만 적용됩니다.

자주 쓰는 항목

넣을 수 있는 항목은 많지만, 비개발자 사장이 알아 두면 좋은 것만 골랐습니다. 나머지는 필요할 때 공식 문서에서 찾으면 됩니다.

확인하고 바꾸는 방법 — 말로, 또는 /config

가장 쉬운 길은 클로드에게 말로 시키는 것입니다. 어느 파일에 넣어야 할지까지 클로드가 판단해 줍니다.

# 클로드 코드 입력창에
커밋에 공동 작성자 표시가 안 붙게 설정해 줘.
어느 설정 파일을 고쳤는지도 알려 줘

직접 보고 싶으면 슬래시 명령어(입력창에 /로 시작해 입력하는 내장 명령)를 씁니다. 파일을 손으로 편집하지 않아도 됩니다.

# 설정을 대화창 안에서 보고 바꾸기
/config
# 한 항목만 빠르게 바꾸기 (key=value 한 줄)
/config key=value
# 지금 어떤 설정이 어디에서 적용되고 있는지 보기
/status
# 설정이 꼬여서 예상대로 동작하지 않을 때 진단
/doctor

/config로 연 설정 목록에서 정해진 값 가운데 하나를 고르는 항목은 ←·→를 눌러 앞뒤 값으로 바꿉니다. 목록이 길면 PgUp·PgDn으로 한 화면씩 넘깁니다.

대부분의 설정은 프로그램을 다시 켜지 않아도 바로 반영됩니다. 다만 모델(model)은 예외입니다. 파일에서 바꾼 값은 지금 켜 둔 세션에 반영되지 않으니, 클로드 코드를 껐다가 다시 켜거나 세션 안에서 /model로 바꾸십시오.

주의 — 설정 파일은 상위 폴더에서 물려받지 않습니다

클로드 코드는 프로젝트 설정(.claude/settings.json)을 폴더마다 층층이 합치지 않습니다. CLAUDE.md는 작업 폴더와 그 위쪽 폴더의 것을 차례로 불러오지만, 설정 파일은 켠 폴더의 것을 읽을 뿐 위쪽 폴더 것까지 쌓지 않습니다. 그래서 회사 폴더 안에 사업부 폴더를 두고 사업부 폴더에서 클로드를 켜면, 회사 폴더에 적어 둔 훅·권한 규칙은 따라오지 않습니다. 개인용 .claude/settings.local.json만 예외입니다. 2.1.211 버전부터는 이 파일을 저장소(회사) 맨 위 한 곳에만 두면, 어느 하위 폴더에서 켜도 같은 것을 읽습니다. 켠 폴더가 무엇을 정하는지는 「작업 폴더」 페이지에 있습니다.

또 하나, 프로젝트 설정의 허용(allow) 규칙은 워크스페이스 신뢰 창에서 한 번 수락해야 실제로 켜집니다. 그 폴더를 믿어도 되는지 묻는 창입니다. 자세한 내용은 「권한」 페이지에서 다룹니다.

폴더 이름을 바꾸거나 옮길 때

처음에 급하게 지은 회사 폴더 이름이 마음에 안 든다면, 지금 바꿔도 됩니다. 다만 “폴더를 옮기면 안에 든 것이 다 따라온다”는 말은 대체로 맞고 일부는 틀립니다. 어디까지 따라오고 무엇이 남는지만 알면 됩니다.

대부분은 그대로 따라옵니다

운영 헌법(CLAUDE.md)도, 직원과 설정이 든 .claude/ 폴더도 회사 폴더 안에 함께 들어 있습니다. 서류가 든 캐비닛을 통째로 옮기는 것과 같아서, 폴더째 움직이면 안의 서류도 함께 갑니다. 이름만 바꾸는 경우도 마찬가지입니다. 파일을 다시 만들 필요는 없습니다.

따라오지 않는 것 — 설정 안에 적어 둔 전체 주소

문제는 절대 경로입니다. 절대 경로란 /Users/이름/회사폴더/…처럼 컴퓨터 안의 전체 주소를 처음부터 끝까지 적은 값입니다. 설정 어딘가에 이런 주소가 적혀 있으면, 폴더를 옮겨도 그 주소는 옛 자리를 그대로 가리킵니다. 이사 간 뒤에도 명함에 옛 주소가 남아 있는 것과 같습니다.

특히 두 곳을 봅니다.

• 훅 — 실행할 스크립트(명령을 미리 적은 짧은 파일)의 위치를 설정에 적어 두는 구조라, 그 위치가 옛 자리면 훅이 제 일을 못 합니다.
• 외부 연결(MCP) 서버 — 내 컴퓨터에 있는 스크립트를 연결할 때는 전체 주소로 적으라고 공식 안내가 권합니다. 지금 폴더를 기준으로 적는 짧은 주소(상대 경로)는 쓰지 않습니다. 그래서 이사 뒤에 어긋나기 쉬운 곳입니다.

프로젝트 설정은 클로드를 시작한 폴더에서만 읽으므로, 옮기면서 세션을 시작하는 위치가 달라지면 읽히는 설정 자체가 달라질 수 있습니다.

옮긴 뒤 점검 세 단계

새 위치에서 클로드를 켜고 차례로 확인합니다. 몇 분이면 끝납니다.

여기에 말로 시키는 점검 하나를 더 붙이면 좋습니다. 어디에 옛 주소가 남았는지 사람이 찾는 것보다 빠릅니다.

# 클로드 코드 입력창에
이 폴더를 다른 위치로 옮겼어.
설정 파일과 훅에 옛 경로가 남아 있는지 훑어보고,
고쳐야 할 곳을 목록으로 알려 줘

이름을 바꾸는 것도, 자리를 옮기는 것도 해도 되는 일입니다. 이름이 마음에 걸린 채로 몇 달을 끌고 가는 편이 오히려 손해입니다. 대신 옮긴 직후 위 세 단계를 한 바퀴 도는 것이 습관이 되어야 합니다. 옮긴 날에 확인하면 5분이고, 한 달 뒤에 알아채면 그동안 훅이 안 돌았다는 사실부터 되짚어야 합니다.

이 페이지는 Claude Code v2.1.216을 기준으로 썼습니다. 최신 사항은 공식 안내에서 확인하십시오.