02-구조

02. 구조 — settings.json 스키마

Morph의 settings.json — Every Field Explained가 가장 정확한 레퍼런스다. 핵심만 추린다.

세 파일, 하나의 머지 체인

“Three files, one merge chain. ~/.claude/settings.json (global) is your baseline. .claude/settings.json (project) configures team-shared settings. .claude/settings.local.json (local) holds your personal overrides.”
의역: “세 파일, 하나의 머지 체인. 글로벌은 기준선, 프로젝트는 팀 공유, 로컬은 개인 오버라이드.”
— Morph, Claude Code settings.json: Every Field Explained

머지 규칙:

“Settings merge with a last-writer-wins strategy at the field level. Arrays are replaced, not appended. Objects are deep-merged.”
의역: “필드 단위 last-writer-wins. 배열은 교체, 객체는 깊은 머지.”

이 한 줄을 모르면 “왜 내가 추가한 allowedTools가 사라졌지?” 라는 질문이 무한히 나온다. 배열은 교체된다 — 더 좁은 스코프에서 부분만 추가하려고 하면 전체가 덮어써진다.

핵심 필드

필드	타입	용도
model	string	메인 대화 모델 ID
smallModel	string	백그라운드 작업용 모델(보통 Haiku)
allowedTools	string[]	권한 프롬프트 없이 통과할 도구 화이트리스트
permissions.defaultMode	enum	auto / approve / deny 기본 동작
mcpServers	object	MCP 서버 정의
env	object	도구 실행 시 주입 환경변수
hooks	object	이벤트별 hook 정의
apiBaseUrl	string	프록시/엔터프라이즈 게이트웨이 라우팅

매처 패턴

“The allowedTools array controls which tools Claude can use without asking for permission. Each entry is a tool name, optionally with a glob pattern for arguments.”

예시: Read, Edit, Bash(git *), Bash(npm test). 매처는 hook 시스템과 동일한 문법을 쓰므로 한 번만 익히면 된다(07장 참고).

시크릿 분리

“Put API keys and secrets in settings.local.json (not committed) or use environment variables from your shell. Never commit secrets in settings.json.”
의역: “API 키와 시크릿은 settings.local.json(커밋 금지) 또는 셸 환경변수로. settings.json에 절대 커밋하지 말 것.”