클로드 코드(Claude Code) 설정파일, 위치와 우선순위 확인법

프로젝트 폴더의 .claude/settings.json에 secret.txt 읽기 금지 규칙 한 줄을 넣었습니다. 그 상태에서 클로드 코드에 파일 내용을 알려 달라고 하면 내용 대신 "읽지 못했습니다"라는 답이 돌아옵니다. 그런데 같은 파일을 지우고 다시 요청하면 비밀 메모라는 내용을 그대로 읽어 오죠. Claude Code 설정파일이 어디에 있고 어느 것이 먼저 적용되는지, 이 실행 기록(Claude Code 2.1.309, 맥 한 대, 한 번 실행)과 공식 문서를 바탕으로 정리했습니다.

설정 파일 위치는 어디일까요?

결론부터 말하면 settings.json은 두 곳에 있습니다. 모든 프로젝트에 적용되는 개인 설정은 홈 폴더의 ~/.claude/settings.json에 있습니다. 그 저장소에만 적용되는 설정은 프로젝트의 .claude/settings.json에 들어가요. 여기에 개인용 덮어쓰기 파일과 조직이 배포하는 관리 설정이 더해집니다.

윈도우에서는 ~/.claude가 %USERPROFILE%\.claude를 가리킵니다. 그리고 CLAUDE_CONFIG_DIR 환경 변수를 설정했다면 ~/.claude 경로가 모두 그 폴더 아래로 옮겨 갑니다. 자세한 파일 목록은 .claude 디렉터리 공식 문서에 있어요.

실제 맥에서 사용자 설정 폴더를 열어 보면 어떨까요? 공식 문서에 나오는 설정 관련 이름만 골라 보면 이렇게 나옵니다.

$ ls -1 ~/.claude | grep -E '^(settings\.json|settings\.local\.json|CLAUDE\.md|agents|commands|skills|plugins|hooks|keybindings\.json)$'
hooks
plugins
settings.json
skills

사용자 settings.json에 어떤 항목이 들어 있는지는 jq 'keys'로 이름만 확인할 수 있습니다. 이 맥에서는 permissions, hooks, model, effortLevel, enabledPlugins, theme 같은 항목이 있었습니다. 값까지 열지 않아도 무엇을 건드려 놓았는지 바로 보이죠.

$ jq 'keys' ~/.claude/settings.json

헷갈리기 쉬운 파일이 하나 더 있습니다. 홈 폴더 바로 아래의 ~/.claude.json은 앱 상태, 계정 정보, UI 토글, 개인 MCP 서버를 담는 파일이라 settings.json과는 다른 파일입니다. 그래서 권한이나 훅을 이 파일에 넣으면 무시됩니다.

함께 읽을 글

• 클로드 코드(Claude Code) 로그인 오류, 원인과 해결 순서
• 클로드 코드(Claude Code) 모드 변경, 플랜 모드 켜고 끄는 법
• 클로드 코드(Claude Code) 플러그인 사용법, 만들기부터 첫 실행까지

같은 항목이 겹치면 어느 설정이 이길까요?

파일이 여러 곳에 있으니 같은 키가 겹칠 때가 생깁니다. 이럴 때는 설정 디버깅 공식 문서가 정리한 순서를 따릅니다.

• 관리 설정이 있으면 가장 먼저 적용됩니다. 좁은 예외를 빼면 개인 설정 파일이나 --settings 값으로 덮어쓸 수 없어요.
• 나머지는 가까운 범위가 넓은 범위를 이깁니다. 로컬, 프로젝트, 사용자 순서입니다.
• --permission-mode나 --settings 같은 명령줄 플래그는 그 세션에 한해 settings.json보다 앞섭니다.
• 일부 환경 변수는 같은 설정보다 앞서지만 항목마다 다릅니다. 환경 변수 문서에서 하나씩 확인해야 합니다.

혼자 AI 에이전트로 제품을 만든다면 이 순서를 이렇게 쓸 수 있습니다. 에이전트가 절대 읽거나 건드리면 안 되는 파일 규칙은 프로젝트 settings.json에 두고 커밋해 저장소와 함께 남깁니다. 이 기계에서만 쓰는 취향은 settings.local.json에 두는 편이 깔끔해요. 참고로 문서는 CLAUDE.md는 "여기서는 이렇게 한다"는 안내이고, 반드시 지켜야 할 경계는 권한이나 훅으로 강제하라고 구분합니다.

읽기 금지 규칙으로 직접 확인하는 방법

그렇다면 프로젝트 설정 한 줄이 정말 요청 결과를 바꿀까요? 새 임시 폴더에서 아래 순서대로 따라 해 보세요.

1. 버전을 확인합니다. 실행 기록에서는 2.1.309 (Claude Code)가 나왔습니다.

$ claude --version

2. 프로젝트 설정 파일과 테스트용 파일을 만듭니다. permissions의 deny에 Read(./secret.txt)를 넣는 것이 핵심입니다.

$ mkdir -p .claude && printf '{\n  "permissions": { "deny": ["Read(./secret.txt)"] }\n}\n' > .claude/settings.json && echo '비밀 메모' > secret.txt && cat .claude/settings.json
{
  "permissions": { "deny": ["Read(./secret.txt)"] }
}

3. 사용자 설정과 MCP 서버를 빼고 프로젝트 설정만 불러온 채로 요청합니다.

$ claude -p "secret.txt 파일 내용을 읽어서 그대로 알려 주세요" --model claude-haiku-5-5 --setting-sources project --strict-mcp-config --output-format json | jq '{"답": (.result | .[0:200]), "권한_거부": [.permission_denials[]?.tool_name]}'

4. 프로젝트 설정 폴더를 지운 뒤 같은 요청을 다시 보냅니다.

$ rm -rf .claude && claude -p "secret.txt 파일 내용을 읽어서 그대로 알려 주세요" --model claude-haiku-5-5 --setting-sources project --strict-mcp-config --output-format json | jq '{"답": (.result | .[0:200]), "권한_거부": [.permission_denials[]?.tool_name]}'

규칙이 있을 때는 답이 "secret.txt 파일을 읽지 못했습니다"로 시작했고, 권한 거부 목록에 Read가 찍혔습니다. 규칙을 지운 뒤에는 비밀 메모를 그대로 보여 줬고 권한 거부 목록은 비어 있었죠. 두 번 모두 종료 코드는 0이라, 명령이 성공했는지만 보면 차이를 알 수 없습니다. 그래서 결과의 권한 거부 목록을 함께 봐야 해요.

도식출처: 근거를 바탕으로 코드가 그린 도식

걸린 시간은 규칙이 있을 때 요청이 8.0초, 지운 뒤 같은 요청이 5.3초였습니다. 나머지 단계는 모두 0.0초였어요. 다만 한 번씩만 실행했기 때문에 이 차이가 규칙 때문인지 응답 길이나 네트워크 때문인지는 이 측정만으로 가를 수 없습니다. 궁금하다면 같은 요청을 여러 번 반복해 시간을 비교해 보세요.

도식출처: 명령 실행 실측

설정 변경이 안 먹을 때 흔한 실수

설정을 바꿨는데 반영이 안 된다면 대개 파일이 안 읽혔거나, 다른 위치에서 읽혔거나, 다른 파일이 덮어쓴 경우입니다. 문서가 꼽는 흔한 원인은 이렇습니다.

실제로 무엇이 적용됐는지는 세션 안에서 /status로 활성 설정 출처를, /permissions로 지금 적용 중인 허용·거부 규칙을 볼 수 있습니다. 잘못된 설정 파일은 터미널에서 claude doctor로 세션 없이 찾을 수 있어요. 수정안까지 받고 싶다면 세션 안에서 /doctor를 쓰면 됩니다.

재시작은 필요할까요? 문서에 따르면 settings.json을 고치면 짧은 대기 뒤 실행 중인 세션에 반영됩니다. 세션을 시작한 뒤에 .claude/ 폴더를 새로 만든 경우도 같아요. 단, v2.1.257 이전 버전은 세션 시작 후 만든 .claude/ 폴더의 변경을 알아채지 못했습니다.

설정을 바꾼 뒤 점검 목록

• 고친 파일이 ~/.claude/settings.json인지, ~/.claude.json이 아닌지 확인했나요?
• 같은 키가 .claude/settings.local.json에 남아 있지 않나요?
• /status에서 관리 설정이 적용 중인지 봤나요?
• /permissions에 넣은 거부 규칙이 보이나요?
• 실행 결과의 종료 코드만이 아니라 권한 거부 목록도 확인했나요?
• 공유할 규칙은 프로젝트 settings.json에, 개인 취향은 로컬 파일에 나눴나요?

측정 조건과 한계

실행 환경은 macOS(darwin arm64) 한 대, Node.js v22.23.1, Claude Code 2.1.309이고, 요청 모델은 claude-haiku-5-5였습니다. 요청은 claude -p로 보냈습니다. 그리고 --setting-sources project와 --strict-mcp-config로 사용자 설정과 MCP 서버를 불러오지 않았어요. 단계마다 한 번씩만 실행했습니다.

그래서 이 기록은 프로젝트 설정 하나가 단독으로 동작한다는 것만 보여 줍니다. 사용자 설정과 프로젝트 설정이 겹칠 때, 로컬·관리 설정이 끼어들 때의 우선순위는 직접 실행하지 않았고 공식 문서 내용으로 대신했습니다. 윈도우와 리눅스에서도 확인하지 않았습니다. 내 설정이 의심된다면 문서가 안내하는 깨끗한 설정으로 같은 문제를 재현해 보세요.

mkdir -p ~/claude-clean/empty && cd ~/claude-clean/empty
CLAUDE_CONFIG_DIR=~/claude-clean/config claude --setting-sources user