클로드 코드 설정, 덮어쓰기가 아니라 합치기

설정 파일이 여러 군데 있으면 위에 있는 게 아래를 덮어쓴다고 생각하게 됩니다. 대체로 맞는데, 그렇지 않은 경우가 세 가지 있습니다. 목록형 키는 하나가 이기는 게 아니라 전부 합쳐지고, 조직이 내린 설정보다 강한 값이 따로 있고, 환경변수는 아예 이 계단 밖에 있습니다. 여기에 오타 하나가 기능을 끄는 게 아니라 잠그는 경우까지. 최근 공식 문서가 설정 항목을 넷으로 쪼개면서 이 규칙들을 훨씬 자세히 적어놨길래 정리했습니다.

📌 30초 요약

• 순서는 관리 설정 → 명령줄 → 프로젝트 로컬 → 공유 프로젝트 → 사용자 다섯 층입니다.
• 목록형 키는 합쳐집니다. 내 파일에서 지워도 다른 파일에 있으면 그대로 살아 있습니다.
• 그 합치기에도 예외 둘이 있습니다 — 순서가 의미를 갖는 키, 조직이 잠그는 키.
• 환경변수는 이 계단에 없습니다. 이름이 비슷한 변수 두 개가 정반대로 동작하기도 합니다.
• 보안 관련 키 여섯 개는 아래층의 더 엄격한 값이 조직 설정을 이깁니다.
• 값이 잘못되면 무시가 아니라 더 잠그는 쪽으로 강제됩니다. MCP 서버가 통째로 안 붙을 수 있습니다.

다섯 층의 순서

같은 키가 여러 곳에 있으면 가장 높은 층의 값을 씁니다. 위에서부터 이렇습니다.

층	어디에 있나	누가 정하나
1. 관리 설정	회사가 배포한 파일·정책·콘솔	조직 관리자
2. 명령줄 인자	실행할 때 붙이는 플래그	나 (한 세션만)
3. 프로젝트 로컬	.claude/settings.local.json	나 (이 프로젝트만)
4. 공유 프로젝트	.claude/settings.json	팀 (저장소에 커밋)
5. 사용자	~/.claude/settings.json	나 (모든 프로젝트)

여기서 눈여겨볼 게 내 개인 설정이 맨 아래라는 점입니다. 팀 파일이 값을 정해두면 내 전역 설정은 그 프로젝트에서 밀립니다. 되찾으려면 같은 프로젝트의 로컬 파일에 적으면 됩니다 — 3층이 4층 위니까요. 이건 커밋되지 않아서 동료 환경은 안 건드립니다.

목록은 합쳐집니다

가장 헷갈리는 대목입니다. permissions.allow처럼 목록으로 된 키는 위층 것을 골라 쓰는 게 아니라 전부 이어붙입니다. 파일마다 항목을 더할 수 있게 하려는 설계인데, 뒤집어 보면 누구도 남의 항목을 지울 수 없다는 뜻이기도 합니다.

🔍 "지웠는데 왜 아직 허용돼 있지"

내 파일에서 허용 규칙을 빼도 팀 파일에 같은 게 남아 있으면 계속 허용됩니다. 덮어쓰기 규칙만 생각하면 "위에서 지웠으니 없어졌겠지" 싶지만, 목록은 지우기가 아니라 더하기만 되는 구조입니다. 권한 모드를 어떻게 잡아뒀든 이 합쳐진 목록이 함께 작동하니, 허용 범위가 예상보다 넓다면 내 파일이 아니라 다른 파일부터 열어보는 게 빠릅니다.

다만 목록이라고 다 합쳐지지는 않습니다. 예외가 둘입니다.

키	왜 다른가	실제 동작
대체 모델 목록	순서 자체가 의미를 가짐 (먼저 쓸 것부터)	가장 높은 층의 목록을 통째로 씀
쓸 수 있는 모델 목록	조직이 범위를 잠그는 용도	관리 소스가 정하면 내가 더한 건 무시

두 번째와 관련해 흔한 오해가 하나 있습니다. 조직이 모델을 지정했다고 해서 모델을 못 바꾸는 게 아닙니다. 그건 세션이 시작할 때의 모델을 정할 뿐이고, 실제로 선택지를 잠그는 건 "쓸 수 있는 모델 목록" 쪽입니다. 둘을 헷갈리면 "회사가 막아놨다"고 오해하기 쉽습니다.

환경변수는 계단 밖입니다

셸에 내보낸 환경변수는 이 다섯 층 어디에도 속하지 않습니다. 파일 설정과 환경변수 중 어느 쪽이 이기는지는 층이 아니라 짝마다 따로 정해져 있습니다. 문서가 든 예가 인상적인데, 이름이 거의 같은 변수 둘이 정반대로 동작합니다.

# 이름이 비슷한데 동작이 반대
ANTHROPIC_MODEL          → 파일의 model 설정을 덮어씀
ANTHROPIC_DEFAULT_MODEL  → 파일에 model이 없을 때만 적용

# 설정 파일 안의 env 블록은 다름
#   그건 그냥 평범한 키라서 위 다섯 층 규칙을 따름

# 지금 무엇이 로드됐는지 확인
$ /status          # 어떤 파일·어떤 관리 소스가 적용됐나
$ claude doctor    # 버려진 항목을 출처·필드까지 알려줌

그래서 "설정을 고쳤는데 안 먹는다"면 파일만 뒤지지 말고 셸에 뭐가 내보내져 있는지도 봐야 합니다. 파일 위치 때문에 안 먹는 경우는 따로 정리해둔 적이 있는데, 그쪽은 파일이 안 읽히는 문제이고 이 글은 읽힌 다음 값이 정해지는 규칙이라 원인이 다릅니다.

위가 항상 이기지는 않습니다

관리 설정이 맨 위라고 했는데, 보안에 민감한 키 여섯 개는 예외입니다. 이 키들에 대해서는 아래층에서 온 더 엄격한 값을 존중합니다. 조직이 "켜도 된다"고 해도 내가 "안 켠다"고 하면 안 켜지는 쪽이죠.

방향이 한쪽으로만 열려 있다는 게 요점입니다. 느슨하게 만드는 값은 아래층에서 못 올리고, 조이는 값만 올라갑니다. 어떤 키는 세 단계 사다리로 되어 있어서, 더 엄격한 쪽으로만 바뀌고 아니면 무시됩니다. 개인이 조직 정책을 뚫을 수는 없지만 자기 기기를 더 잠글 수는 있게 해둔 설계입니다.

🔒 오타 하나가 끄는 게 아니라 잠급니다

값이 형식에 안 맞으면 보통 무시되고 기본값으로 돌아간다고 생각하는데, 일부 키는 반대입니다. 허용할 MCP 서버 목록이 잘못 적혀 있으면 빈 목록으로 강제돼서 서버가 하나도 안 붙습니다. 관리 훅 관련 키도 잘못되면 가장 조이는 값으로 취급됩니다. 고쳐질 때까지요. 게다가 JSON 자체가 깨진 파일은 통째로 아무것도 기여하지 않습니다 — 항목 몇 개만 빠지는 게 아니라 그 파일 전부가 없는 셈이 됩니다. 정책을 계산해주는 도우미 프로그램은 더 엄해서, 어긋난 값이 하나라도 남으면 아예 시작을 거부합니다. "조용히 넘어가겠지"가 통하지 않는 자리입니다.

🔁 우선순위를 따지기 전에 봐야 할 것이 하나 더 있습니다

이 글은 여러 곳에 설정됐을 때 어느 값이 이기는지를 다뤘는데, 설정 키 전체 참조 문서를 보면 그 이전 단계가 하나 더 있습니다 — 키마다 놓을 수 있는 파일이 정해져 있습니다. 아무 데나 둬도 되는 키가 있고, 사용자 쪽에만·관리형에만·홈 폴더의 전역 파일에만 둘 수 있는 키가 따로 있습니다. 차이 보기 도구나 IDE 자동 연결처럼 프로젝트 설정에 적으면 아예 읽히지 않는 키가 그렇습니다. 다섯 층의 순서를 아무리 맞춰도 범위가 안 맞으면 층은 의미가 없습니다.

🔁 같은 규칙이 파일에 따라 다른 곳을 가리킵니다

합쳐지는 순서를 알았다면 한 걸음 더 — 같은 문장이 어느 파일에 적혔느냐에 따라 겨누는 자리가 달라집니다. 파일 권한 규칙에서 앞에 슬래시를 붙인 경로가 그렇습니다. 프로젝트·지역 설정에 적으면 작업 폴더 기준이지만 사용자 설정에 적으면 설정 폴더 기준이 됩니다. 그래서 사용자 설정에 비밀 폴더 잠금을 걸어 두면 프로젝트 안의 같은 이름 폴더가 아니라 엉뚱한 곳을 막습니다. 모든 프로젝트에 두루 걸려면 절대 경로나 홈 기준 표기로 바꿔 적으세요.

🔁 합쳐지기는커녕 아예 안 가는 자리도 있습니다

설정이 덮어쓰기가 아니라 합치기라고 적었는데, 합침의 대상이 되지도 못하는 경우가 있습니다. 클라우드 세션에서 도는 준비 절차를 보면 사용자 수준 설정 파일에 넣어 둔 세션 시작 훅은 클라우드에서 아예 돌지 않습니다. 그 설정은 내 기계에 남기 때문입니다. 클라우드에서 실제로 도는 건 저장소에 커밋한 설정의 훅과 조직이 서버에서 내려 주는 설정의 훅뿐입니다. 「우선순위가 어떻게 되지」를 따지기 전에 「그 파일이 거기까지 가기는 하는지」를 먼저 보세요.

자주 묻는 질문

Q. 버려진 항목은 어디서 보나요?

세 군데입니다. 대화형으로 켜면 시작할 때 대화상자로 목록이 뜨고, 출력 모드로 돌리면 오류 출력 쪽에 요약이 나오고, claude doctor는 항목마다 어느 파일 어느 필드인지까지 알려줍니다. 자동화 스크립트에서 돌리는 경우 화면을 안 보게 되니, 정기적으로 진단 명령을 한 번씩 돌려보는 편이 낫습니다.

Q. 훅이 안 도는데 이것 때문일 수도 있나요?

가능성이 있습니다. 훅 자체를 제대로 써놨더라도, 조직 쪽에서 관리 훅만 허용하는 키가 켜져 있으면 내 훅은 안 돕니다. 게다가 그 키가 잘못된 값으로 적혀 있어도 켜진 것으로 취급되니, 관리자가 의도치 않게 켠 상태일 수도 있습니다. 먼저 무엇이 적용됐는지 확인하고 훅 코드를 의심하는 순서가 맞습니다.

Q. 회사 정책을 개인이 바꿀 수 있나요?

느슨하게 만드는 방향은 안 됩니다. 명령줄로 값을 넘겨도 관리 설정을 못 이깁니다. 더 조이는 방향은 앞서 말한 여섯 개 키에 한해 됩니다. 정책 자체가 문제라고 생각되면 어느 소스가 적용 중인지 확인해서 관리자에게 그 근거와 함께 이야기하는 것이 현실적인 경로입니다. 서버에서 정책을 내리는 방식은 따로 정리해뒀습니다.

🧾 정직하게 밝혀둡니다

• 공식 문서를 읽고 정리한 내용이고, 조직 배포 환경은 직접 구성해보지 못했습니다. 개인 설정 부분은 확인 가능했지만 관리 설정 쪽은 문서 기준입니다.
• 키 이름을 일부러 한글 설명으로 풀었습니다. 정확한 철자는 버전마다 달라질 수 있어, 실제로 적을 때는 공식 설정 레퍼런스에서 확인하세요.
• ★예외 목록은 여섯 개로 적었지만 늘거나 줄 수 있습니다. 최근에 문서가 한 항목에서 네 항목으로 쪼개진 걸 보면 이 영역은 아직 정리 중입니다.
• 같은 업데이트에서 권한 모드 문서가 색인에서 빠졌습니다. 통합된 것으로 보이지만 어디로 갔는지는 확인하지 못했습니다.
• 버전·플랫폼에 따라 파일 경로와 메뉴 이름이 다를 수 있습니다.

✨ 정리하면

덮어쓰기라고 생각하면 세 군데에서 어긋납니다 — 목록은 합쳐지고, 환경변수는 계단 밖이고, 보안 키는 아래가 이깁니다. 설정이 이상할 땐 내 파일을 고치기 전에 무엇이 로드됐는지부터 보세요. AI 도구 설정과 비용을 한자리에서 보려면 AI 지출 정리 허브도 같이 보세요.

출처: Claude Code 공식 문서 Settings · Deploy managed settings (2026-08-24 확인). 설정 키와 동작은 버전에 따라 변경될 수 있습니다. 이 글은 정보 제공용입니다.