03. 설정 스코프와 우선순위 — 합격하는 Claude Certified Architect 자격증

설정 스코프와 우선순위

Claude Code의 동작은 두 종류의 파일이 함께 결정한다. CLAUDE.md는 에이전트에게 주는 자연어 지시(메모리)이고, settings.json은 권한·환경변수·훅·도구 허용 같은 구성(configuration)이다. 시험은 이 둘을 혼동하게 만드는 함정을 자주 낸다. "도구 사용을 금지하라"는 자연어 규칙은 CLAUDE.md에 둘 수도 있지만, 실제로 강제하려면 settings.json의 권한 설정으로 막아야 한다. CLAUDE.md는 Claude가 따르도록 권유하는 지시이고, settings.json은 하네스가 실행 단계에서 강제하는 규칙이라는 차이를 이해하는 것이 이 절의 핵심이다.

settings.json 우선순위

여러 위치의 settings.json이 동시에 로드되면 다음 우선순위(높음에서 낮음)로 병합된다.

조직 정책(managed-settings.json, enterprise managed) — IT/DevOps 배포, 재정의 불가
명령줄 인자(CLI arguments) — 해당 세션 한정 임시 재정의
로컬 프로젝트 설정(.claude/settings.local.json) — 커밋하지 않는 개인 프로젝트 설정
공유 프로젝트 설정(.claude/settings.json) — 소스 관리에 포함되는 팀 공유 설정
사용자 설정(~/.claude/settings.json) — 모든 프로젝트에 적용되는 개인 전역 설정

이 순서가 시험의 단골 함정이다. 두 가지를 반드시 외워야 한다. 첫째, 맨 위는 조직 정책이다. 보안·컴플라이언스를 위해 무엇으로도 덮을 수 없다. 둘째, 명령줄 인자가 로컬·프로젝트·사용자 설정보다 위에 있지만 조직 정책보다는 아래다. "CLI 인자가 항상 최우선"이라고 적힌 보기는 틀리다. 또한 로컬 설정(settings.local.json)이 공유 설정(settings.json)보다 높다는 점도 자주 출제된다. 개인의 로컬 재정의가 팀 공유 설정을 이긴다.

위에서 아래로 우선순위가 낮아지며, 위 레이어의 값이 같은 키에서 아래를 덮는다.

%% settings.json 우선순위 (위가 높음) flowchart TB L1["1. 조직 정책 managed-settings.json\n재정의 불가, 최우선"] L2["2. CLI 인자\n세션 한정 임시 재정의"] L3["3. 로컬 프로젝트 settings.local.json\n커밋 안 함, 개인"] L4["4. 공유 프로젝트 settings.json\n팀 공유, 소스 관리"] L5["5. 사용자 설정 ~/.claude/settings.json\n개인 전역"] L1 -->|"덮어씀"| L2 -->|"덮어씀"| L3 -->|"덮어씀"| L4 -->|"덮어씀"| L5

활성화된 설정 소스는 세션 안에서 /status를 실행해 Status 탭의 "Setting sources"에서 확인할 수 있다. 어떤 레이어가 로드되었는지 점검할 때 유용하다.

병합 방식

설정은 단순히 한 파일이 다른 파일을 통째로 덮는 것이 아니라 레이어별로 병합된다. 우선순위가 높은 레이어의 값이 같은 키에서 이기고, 배열형 항목은 레이어 간에 합쳐지는 경우가 있다. 예를 들어 claudeMdExcludes는 사용자·프로젝트·로컬·관리 정책 어느 레이어에서나 설정할 수 있고 배열이 레이어를 가로질러 병합된다. 다만 관리 정책의 CLAUDE.md는 이 제외 목록으로도 배제되지 않아, 조직 지시는 개인 설정과 무관하게 항상 적용된다.

메모리 우선순위와의 구분

CLAUDE.md(메모리)의 적용도 스코프가 있지만, settings.json의 우선순위 규칙과 동일하지 않다는 점에 주의한다. 메모리 쪽에서는 조직 정책 CLAUDE.md가 가장 강하게 강제되고 개인이 제외할 수 없다는 원칙이 핵심이며, settings.json 쪽에서는 위의 5단계 병합 순서가 핵심이다. 시험은 메모리 계층과 설정 계층을 섞어서 혼동을 유도하므로, "지금 묻는 것이 자연어 지시(CLAUDE.md)인가 구성(settings.json)인가"를 먼저 가려낸 뒤 해당 우선순위를 적용해야 한다.

또 하나의 구분 기준: 프로그래밍 방식 옵션(예: SDK로 전달하는 agents, allowed_tools 같은 설정)은 파일시스템 설정보다 항상 우선한다. 코드로 명시적으로 넘긴 값이 파일에 적힌 값을 덮는다.

정리

settings.json 우선순위(높음에서 낮음): 조직 정책(managed-settings.json), CLI 인자, 로컬 프로젝트(settings.local.json), 공유 프로젝트(settings.json), 사용자 설정.
최상위는 조직 정책이며 무엇으로도 덮을 수 없다. CLI 인자는 그다음이지 최우선이 아니다.
로컬 설정(settings.local.json)이 공유 설정(settings.json)보다 높다. 개인 로컬 재정의가 팀 공유 설정을 이긴다.
CLAUDE.md는 따르도록 권유하는 자연어 지시(메모리), settings.json은 하네스가 강제하는 구성이다. 강제력이 필요하면 settings.json으로 막는다.
프로그래밍 방식 옵션은 파일시스템 설정을 항상 덮는다. 활성 소스는 /status로 확인한다.