나의 기본 세팅

문제

설정 옵션은 수십 개입니다. 무엇을 켜고 무엇을 꺼야 하는지, 그리고 그 선택이 실제로 무엇을 바꾸는지 알기 어렵습니다.

이유

컨텍스트를 손으로 관리할지 자동에 맡길지부터 정합니다. autoCompactEnabled를 끄면 무엇을 남기고 무엇을 버릴지 판단이 사람에게 남습니다. 대신 컨텍스트가 한계에 가까워졌을 때 직접 /clear하거나 핸드오프 문서를 쓰는 타이밍을 놓치지 않아야 합니다. 켜두면 그 판단을 자동 압축에 맡기는 대신, 압축이 무엇을 버릴지는 모델이 정하게 됩니다. 세션을 길게 끌고 가면서 중간 판단 근거를 계속 유지해야 하는 작업이면 끄는 쪽이 부담이 적습니다. 짧고 반복적인 작업이 많으면 켜두는 쪽이 부담이 적습니다.

퍼미션은 allowlist를 늘릴지 auto 모드에 맡길지를 고릅니다. permissions.defaultMode를 auto로 두면 개별 명령을 일일이 allow/deny로 등록하지 않고도 분류기가 위험도를 판단합니다. allow/deny 규칙을 프로젝트 공유 settings.json에 쌓기 시작하면 그 목록 자체가 유지 대상이 되고, 새 명령이 나올 때마다 갱신해야 합니다. 민감한 항목(예: Bash(curl:*)처럼 외부 네트워크를 여는 명령)을 allowlist에 넣어야 한다면 git에 커밋되는 공유 설정이 아니라 settings.local.json처럼 로컬에만 남는 파일에 두는 편이 낫습니다. 팀원마다 판단이 다를 수 있는 항목을 공유 설정에 강제하지 않기 위해서입니다.

모델명을 설정에 고정할지도 선택입니다. settings.json에 model 필드를 박아두면 새 모델이 나올 때마다 설정을 갱신해야 합니다. 반면 effortLevel 같은 값은 모델이 바뀌어도 의미가 유지되는 편입니다. 모델 자체는 /model로 세션마다 바꿔 쓰고, 영속시킬 값은 “어느 모델을 쓸까”가 아니라 “얼마나 공을 들일까” 쪽에 두는 편이 설정을 오래 유지하게 합니다.

스킬은 목록을 늘릴지 걸러낼지를 정합니다. 스킬이 많아지면 스킬 목록 자체가 컨텍스트를 차지합니다. skillOverrides로 특정 스킬을 off(완전 비활성)나 user-invocable-only(모델이 자동으로 부르지 못하고 사람이 명시적으로 호출해야만 동작)로 내려두면, 실제로 자주 쓰지 않는 스킬이 매 요청마다 후보 목록에 올라오는 비용을 줄일 수 있습니다. 스킬을 새로 설치할 때마다 기본값으로 전부 켜두기보다, 필요 없는 것부터 끄는 방향으로 접근하는 편이 목록을 관리 가능한 크기로 유지합니다. 플러그인도 마찬가지입니다. 등록된 플러그인 수와 실제로 쓰는 플러그인 수는 다를 수 있으므로, 쓰지 않는 플러그인은 비활성화합니다.

훅은 이벤트에 걸리므로, 어떤 이벤트를 고르느냐가 곧 그 훅이 얼마나 자주 도는지를 정합니다. 예를 들어 다음과 같은 조합이 흔합니다.

이벤트	용도
`PreToolUse`	특정 명령(예: 특정 디렉터리에서의 `git push`)을 조건부로 차단합니다(`exit 2`)
`Stop`	세션이 끝날 때 사람이 해야 할 일을 상기시킵니다
`PostToolUseFailure`	도구 호출이 실패했을 때만 추가 정보를 주입합니다

PreToolUse·PostToolUseFailure는 조건에 맞을 때만 발동하지만, 모든 프롬프트마다 도는 훅(UserPromptSubmit 등)은 세션 내내 반복해서 비용이 붙으므로 더 신중하게 고릅니다. 자세한 기준은 Rules에서 다룹니다.

설정 파일 4종은 역할이 서로 다릅니다.

파일	성격
`~/.claude/settings.json`	사람이 쓰는 선언적 설정
`~/.claude/settings.local.json`	git에 올리지 않는 퍼미션 allowlist
`.claude/settings.json`	프로젝트에서 공유하는 설정
`~/.claude.json`	앱이 실행 중 write back하는 UI 상태이며, 앱 실행 중 손편집하지 않습니다

이 구분을 놓치면 진단이 뒤집힐 수 있습니다. 업데이트 채널처럼 사람이 관리하는 값과 앱이 런타임에 갱신하는 값이 서로 다른 파일에 있으므로, 한쪽 파일만 보고 설정 상태를 판단하면 잘못된 결론에 이르기 쉽습니다. 교차 검증은 claude update 출력의 Checking for updates to <channel> version... 한 줄이면 됩니다.

병렬로 여러 세션을 굴리는 경우라면 백그라운드 세션을 그룹으로 보여주는 뷰의 설정도 살펴볼 만합니다. 그룹 기준이나 정렬 기준이 설정으로 바뀌지 않는 값(예: 생성 시각 기준 정렬)으로 고정돼 있을 수 있으므로, 특정 순서를 유지하고 싶다면 핀 고정 같은 별도 기능을 쓰는 편이 안전합니다. 한 레포만 보고 싶다면 CLI에 경로를 지정하는 옵션이 있는지 확인합니다.

예시

새 레포에서는 세팅보다 .gitignore에 worktree 디렉터리를 추가하는 일이 먼저입니다. worktree가 저장소 안에 생기는 구성을 쓰는 경우, 이 한 줄이 없으면 세 가지 문제가 생길 수 있습니다. worktree가 열려 있는 동안 main이 항상 dirty로 보여 병합 작업이 번거로워집니다. 모노레포 빌드 도구가 워크트리 디렉터리까지 중복 프로젝트로 스캔합니다. git에는 무시돼도 테스트 러너의 파일 수집에는 무시되지 않아, 다른 세션의 워크트리에 있는 옛 테스트 사본이 함께 실행돼 테스트 개수가 실제보다 많게 나옵니다.

# .gitignore — 커밋되는 쪽에 넣어야 다른 머신에서 재발하지 않는다
.claude/worktrees/

// vitest.config.mts
test: { exclude: ["**/node_modules/**", "**/.claude/worktrees/**"] }

모노레포 빌드 도구의 무시 설정에도 같은 줄을 추가합니다. .claude/ 전체를 무시하면 안 됩니다. .claude/settings.json은 커밋 대상입니다. 검증은 두 줄이면 됩니다.

git check-ignore -v .claude/worktrees/     # 무시돼야 한다
git check-ignore -v .claude/settings.json  # 무시되면 안 된다

급하면 로컬 전용 무시 설정으로 풀 수 있지만, 커밋되지 않으므로 다른 머신에서 같은 문제가 재발합니다.

하지 말 것

모델명을 settings.json에 박아두기. 모델이 바뀔 때마다 설정을 계속 고쳐야 합니다. 영속시킬 값은 effortLevel처럼 모델이 바뀌어도 의미가 유지되는 값이지, 모델명 자체가 아닙니다.

.claude/ 디렉터리 전체를 gitignore하기. worktree만 무시하려던 것이 settings.json까지 같이 지워 프로젝트 공유 설정이 사라집니다.

~/.claude.json과 ~/.claude/settings.json을 같은 파일로 취급하기. 하나는 앱이 UI 상태를 write back하는 파일이고 하나는 사람이 쓰는 선언적 설정입니다. 섞어서 읽으면 있어야 할 값이 다른 파일에 있어서 멀쩡한 설치를 잘못 진단하게 됩니다.

나의 기본 세팅

문제

추천

이유

예시

하지 말 것