클로드 코드(Claude Code)를 쓰다가 “분명 설정을 바꿨는데 왜 그대로지?”라는 상황을 자주 만납니다. 이때 재설치부터 하기 쉬운데, 실제로는 설정 파일 우선순위 충돌이나 권한 규칙 충돌인 경우가 많습니다.
최근 npm 패키지 페이지 기준으로 @anthropic-ai/claude-code는 주간 다운로드가 420만 회를 넘는 수준으로 표시됩니다. 사용자층이 커진 만큼, 설치 이후의 세팅 충돌과 운영 이슈를 겪는 사례도 같이 늘고 있습니다. 그래서 이 글은 설치 자체보다 세팅이 적용되지 않을 때 바로 복구하는 실전 순서에 집중했습니다.
Table of Contents
왜 설정이 “안 먹는 것처럼” 보일까
공식 문서의 핵심은 간단합니다. 같은 키를 여러 곳에서 설정하면 더 구체적인 범위가 우선합니다. 즉 아래 순서로 우선순위를 생각하면 됩니다.
- Managed 정책
- CLI 인자(현재 세션)
.claude/settings.local.json.claude/settings.json~/.claude/settings.json
예를 들어 사용자 전역 파일에서 allow를 넣어도, 프로젝트의 local 파일에서 deny를 넣으면 local 규칙이 이깁니다. 이 패턴을 모르고 있으면 “왜 방금 바꾼 값이 무시되지?”가 계속 반복됩니다.
가장 먼저 해야 할 점검 5단계
/config에서 현재 활성 스코프 확인/permissions에서 allow/ask/deny 충돌 확인/add-dir로 작업 디렉터리 범위 확인claude doctor로 환경 점검- 세션 재시작 후 최소 재현 테스트
여기서 중요한 점은 한 번에 여러 파일을 바꾸지 않는 것입니다. 한 단계씩 바꾼 뒤 바로 같은 명령으로 재현해 보면 원인 분리가 쉬워집니다.
settings.local.json을 먼저 의심해야 하는 이유
공식 문서 기준으로 .claude/settings.local.json은 팀에 공유되지 않고 로컬에서만 적용됩니다. 그래서 팀 문서를 보고 따라했는데 내 환경에서만 다르게 동작한다면 local 오버라이드가 남아 있을 확률이 높습니다.
특히 이런 경우가 많습니다.
- 예전에 테스트하던 allow 규칙이 남아 있음
- deny 규칙이 넓게 잡혀 특정 명령이 전부 차단됨
- 프로젝트를 복사해 오면서 local 파일이 같이 따라옴
권한 충돌을 빠르게 보는 방법
/permissions에서 규칙이 길어지면 “왜 막히는지”가 잘 안 보입니다. 이때는 작업을 둘로 나눠 보면 빠릅니다.
- 읽기/분석 계열: 우선 allow 또는 ask로 부드럽게
- 실행/수정 계열: 위험도 높은 항목은 ask 유지
권한은 많이 여는 것이 목표가 아니라, 반복 작업은 덜 끊기고 위험 작업은 한 번 더 확인하도록 균형을 잡는 것이 핵심입니다.
“설정은 맞는데 파일을 못 본다”가 뜰 때
이 케이스는 권한보다 범위 문제인 경우가 많습니다. 현재 작업 디렉터리 바깥을 읽어야 하면 /add-dir를 써서 범위를 명시해야 합니다.
/add-dir ../shared-lib설정을 넓게 푸는 것보다 필요한 경로를 추가하는 쪽이 추적과 유지보수 모두 쉽습니다.
실전 복구 예시
# 1) 상태 확인
/config
/permissions
# 2) 범위 확인
/add-dir ../shared-lib
# 3) 환경 진단
claude doctor
# 4) 최소 재현 테스트
claude -p "현재 권한 규칙 요약해줘"이렇게 점검하면 대부분의 “설정이 안 먹는다” 이슈를 재설치 없이 정리할 수 있습니다.
함께 보면 좋은 글
정리
클로드 코드 세팅 문제는 설치 실패보다 적용 범위 충돌로 생기는 경우가 더 많습니다. 그래서 재설치보다 먼저 우선순위 확인 -> 권한 충돌 확인 -> 작업 범위 확인 순서로 보는 편이 빠릅니다.
한 번 이 흐름을 잡아두면 다음부터는 설정 이슈가 생겨도 바로 원인을 좁혀 복구할 수 있습니다.
참고한 자료
- Anthropic Claude Code Settings 문서(설정 파일/스코프 우선순위)
- Anthropic Claude Code Permissions 문서
- npm 패키지
@anthropic-ai/claude-code페이지(주간 다운로드 지표)