Claude Code 설정이 안 먹힐 때 — 비슷한 파일이 두 개고, 하위 폴더는 읽을 때만 로드됩니다

분명히 적어뒀는데 Claude가 그 지시를 무시하거나, 설정한 기능이 아예 안 보이는 경험 있으실 겁니다. 공식 진단 문서를 열어보니 원인이 대체로 셋 중 하나였습니다 — 파일이 안 읽혔거나, 내가 생각한 곳과 다른 데서 읽혔거나, 다른 파일이 덮어썼거나. 그리고 이름이 딱 하나 다른 파일 두 개를 헷갈리는 것이 목록 맨 위에 있었습니다.

📌 30초 요약

• 설정 파일이 두 개고 역할이 다릅니다. 권한·훅·환경변수를 엉뚱한 쪽에 넣으면 통째로 무시됩니다.
• 하위 폴더의 CLAUDE.md는 시작할 때 안 읽습니다. 그 폴더 파일을 읽을 때 비로소 로드됩니다.
• 내장 탐색·계획 에이전트는 CLAUDE.md를 건너뜁니다. 시킬 때 다시 적어줘야 합니다.
• 훅 매처를 배열로 쓰면 그 설정 파일 전체가 거부됩니다. 대소문자도 구분합니다.
• 삭제 금지 규칙은 명령 문자열만 봅니다. 같은 일을 하는 다른 명령은 안 막힙니다.
• 모르겠으면 전부 끄고 시작하는 모드가 있습니다. 다만 회사 정책은 그래도 살아 있습니다.

먼저 뭐가 실제로 로드됐는지 봅니다

추측하기 전에 지금 무엇이 올라와 있는지부터 확인하라는 게 문서의 첫 조언입니다. 컨텍스트 현황 명령 하나로 시스템 프롬프트·도구·서브에이전트·메모리 파일·스킬이 어디서 왔는지까지 나옵니다. 거기 내 파일이 없으면 로드 문제고, 있으면 문장을 어떻게 썼느냐의 문제입니다.

확인할 것	무엇을 보여주나
컨텍스트 현황	지금 창을 차지한 전부. 항목별 출처까지
메모리	사용자·프로젝트 범위의 파일 위치, 자동 메모리 폴더
스킬 · 훅 · MCP	각각 사용 가능 목록, 등록된 설정, 연결 상태
권한	여러 층이 합쳐진 뒤 최종 적용되는 허용·거부 규칙
건강검진	잘못된 설정 파일, 중복 설치, 같은 폴더의 이름 겹친 에이전트
상태	활성 설정 출처. 회사 관리 설정이 걸려 있는지 여부

건강검진 쪽에 재미있는 항목이 하나 있습니다 — 코드베이스만 봐도 Claude가 알아낼 수 있는 내용이 CLAUDE.md에 적혀 있으면 그걸 짚어주고 줄여도 된다고 제안합니다. 제안은 내가 확인해야 적용되고요. CLAUDE.md 작성법을 정리했을 때도 "길면 묻힌다"고 썼는데, 이제 도구가 직접 다이어트를 권하는 셈입니다.

비슷하게 생긴 파일이 두 개입니다

증상표에서 제가 제일 흔하겠다 싶었던 항목입니다. 개인 폴더 아래 점 하나 붙은 설정 파일과 설정 폴더 안의 설정 파일이 따로 있는데, 이름이 거의 같습니다. 그런데 권한·훅·환경변수를 앞쪽에 적으면 전부 무시됩니다.

~/.claude.json            # 앱 상태와 화면 토글. 여기 넣으면 안 먹음
~/.claude/settings.json   # 권한·훅·환경변수는 이쪽

# 프로젝트 쪽 우선순위 (뒤가 이김)
~/.claude/settings.json  <  .claude/settings.json  <  .claude/settings.local.json

합쳐지는 순서도 알아둘 만합니다. 회사 관리 설정이 가장 먼저 적용되고, 나머지는 가까운 쪽이 이깁니다 — 로컬, 프로젝트, 사용자 순으로요. 여기에 명령줄 플래그와 환경변수가 또 한 겹 얹힙니다. 그래서 문서가 이렇게 정리합니다 — "설정이 적용되지 않는 것 같다면, 대개는 다른 범위나 환경변수가 그 값을 덮어쓰고 있는 것"이라고요. 참고로 설정 파일을 고치면 재시작은 필요 없습니다. 파일이 안정되면 돌고 있는 세션에 바로 반영됩니다.

하위 폴더 CLAUDE.md는 읽을 때만 로드됩니다

이건 저도 몰랐습니다. 프로젝트 하위 폴더에 CLAUDE.md를 두면 세션이 시작될 때 읽히는 게 아닙니다. Claude가 그 폴더 안의 파일을 읽기 도구로 열 때 비로소 로드됩니다. 문서가 조건을 더 좁혀두는데 — 그 폴더에 파일을 쓰거나 새로 만들 때는 로드되지 않습니다.

그러니까 "이 폴더에서는 이렇게 작성해라"를 하위 CLAUDE.md에 적어두고 새 파일을 만들게 시키면, 그 규칙은 안 읽힌 상태입니다. 기존 파일을 고치라고 시켰을 때만 걸리는 거죠. 규칙이 될 때도 있고 안 될 때도 있는 것처럼 보였다면 이게 원인일 수 있습니다.

비슷한 함정이 하나 더 있습니다. 내장 탐색 에이전트와 계획 에이전트는 CLAUDE.md를 아예 건너뜁니다. 직접 만든 서브에이전트는 본 대화와 똑같이 읽는데, 내장 둘만 예외입니다. 그래서 문서가 일을 시키는 프롬프트에 그 지시를 다시 적으라고 안내합니다. 커스텀 에이전트라면 에이전트 파일 본문에 넣으라고요 — 그게 그 에이전트의 시스템 프롬프트가 되니까요. 용어를 정리하면서 서브에이전트를 다뤘는데, "무엇을 물려받느냐"가 종류마다 다르다는 건 이번에 알았습니다.

훅이 안 걸리는 이유는 네 가지

훅이 목록에 아예 안 보이면 안 읽힌 것이고, 보이는데 안 터지면 거의 매처 문제입니다. 문서가 원인을 네 가지로 좁혀놨는데, 첫 줄이 특히 무섭습니다.

잘못 쓴 것	결과
매처를 배열로 씀	그 설정 파일 전체가 거부됨
도구 이름을 소문자로 씀	대소문자를 구분해서 하나도 안 맞음
여러 도구를 쉼표로 나열	특정 버전 이전에는 글자 그대로 취급돼 안 맞음
훅을 별도 파일에 둠	아예 안 읽힘. 설정 파일 안의 항목이어야 함

첫 줄을 풀어보면 이렇습니다 — 매처를 배열로 적으면 형식 오류로 처리돼서 그 파일에 있던 다른 훅까지 전부 사라집니다. 하나 잘못 쓰고 열 개를 잃는 거죠. 그런데 회사 관리 설정에서는 다르게 동작합니다 — 잘못된 항목만 빼고 나머지 훅은 그대로 살립니다. 같은 오류인데 파일의 성격에 따라 처리가 갈립니다. 관리자가 배포한 정책이 오타 하나로 통째로 날아가면 곤란하니 그렇게 설계했겠죠. 훅 기능을 정리했던 글에 이 실패 패턴들을 붙여둘 만합니다.

🚫 삭제 금지 규칙은 명령 문자열만 봅니다

증상표 마지막 줄이 보안적으로 제일 중요해 보였습니다. 삭제 명령을 막는 거부 규칙을 걸어둬도, 전체 경로로 부르거나 다른 도구로 같은 일을 하면 안 막힙니다. 이유는 명확합니다 — 접두 규칙은 명령 문자열을 글자 그대로 비교하지, 실제로 어떤 실행 파일이 도는지를 보지 않기 때문입니다. 문서가 제시하는 해법은 둘입니다. 변형마다 패턴을 다 적어두거나, 아니면 실행 전 훅이나 샌드박스로 막으라는 것 — 즉 확실한 보장이 필요하면 규칙 문자열이 아니라 다른 층으로 가라는 이야기입니다. 격리 방식 여섯 가지를 비교했을 때와 정확히 같은 결론이 여기서도 나옵니다.

그래도 모르겠으면 전부 끄고 시작합니다

원인이 안 잡힐 때 쓰는 순서가 둘로 나뉩니다. 먼저 안전 모드가 있습니다 — CLAUDE.md, 스킬, 플러그인, 훅, MCP 서버, 커스텀 커맨드와 에이전트를 전부 끄고 시작합니다. 로그인·모델 선택·기본 도구·권한은 정상 동작하고요. 안전 모드에서 문제가 사라지면 껐던 것들 중 하나가 범인입니다.

단, 단서가 하나 붙습니다 — 안전 모드에서도 회사가 배포한 훅과 정책은 그대로 적용됩니다. 그것들은 개인 설정 폴더 바깥의 시스템 경로에 있으니까요. 그래서 더 깊게 파려면 설정 폴더 자체를 빈 곳으로 돌려버리는 방법을 씁니다.

# 개인 설정을 통째로 우회 + 프로젝트 설정도 없는 곳에서 실행
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

제대로 걸렸는지 확인하는 법도 알려줍니다 — 처음 실행 화면(테마 선택부터)이 뜨면 청정 설정이 먹은 것입니다. 같은 폴더로 두 번째부터는 안 뜨고요.

운영체제	청정 세션에서 로그인은	이유
윈도우 · 리눅스	다시 해야 함	자격증명이 설정 폴더 아래 있어서
맥	그대로 넘어감	키체인에 있어서 설정 폴더와 무관

📐 CLAUDE.md는 안내고, 훅과 권한은 보장입니다

문서가 짧게 못 박은 구분인데 저는 이게 이 글의 결론이라고 봅니다. CLAUDE.md는 Claude가 좋은 판단을 하도록 프로젝트를 설명하는 것이고, 권한과 훅은 Claude가 무엇을 판단하든 상관없이 한계를 강제하는 것입니다. 그래서 "우리는 여기서 이렇게 합니다"는 CLAUDE.md, "절대 일어나면 안 됩니다"는 권한이나 훅이라고 안내합니다. 지시가 안 지켜진다고 CLAUDE.md에 대문자로 강조를 더 넣는 것보다, 보장이 필요한 건 애초에 다른 층에 두는 게 맞다는 이야기죠. 문서가 이유도 붙입니다 — 애매해서 여러 갈래로 읽히거나, 두 파일이 상충하거나, 파일이 길어져 개별 규칙에 주의가 덜 가면 준수율이 떨어진다고요.

🧾 정직하게 — 이 글의 한계

• 증상을 하나하나 재현해 보지는 않았습니다. 공식 진단 문서의 증상·원인·해결 표를 정리하고 우리말로 옮긴 것이라, 제 환경에서 확인한 건 아닙니다.
• 버전 경계가 여러 개 나옵니다. 쉼표 매처와 건강검진 항목이 특정 버전부터인데, 내 버전이 그 아래면 동작이 다릅니다. 정확한 버전 번호는 원문에 있습니다.
• 명령 이름은 우리말로 옮겼습니다. 실제로는 슬래시로 시작하는 짧은 영어 단어들이라, 그대로 쓰시려면 원문을 보시는 게 정확합니다.
• 여기 없는 원인도 당연히 있습니다. 설치·로그인·성능 문제는 아예 다른 문서로 안내합니다. 이 글은 "설정이 안 먹는" 경우만 다룹니다.

🗺️ AI 지출 전체 지도

설정이 안 먹으면 같은 일을 두 번 시키게 되고, 그게 곧 토큰입니다. 컨텍스트에 뭐가 올라가 있는지 보는 습관은 요금과도 직결되고요. 구독과 종량제 선택부터 캐시, 모델 조합, 상한 걸기까지 지금까지 확인한 것들을 일곱 단계 지도 한 장으로 묶어뒀습니다.

자주 묻는 것

Q. 스킬을 만들었는데 목록에 안 보입니다

파일 하나로 두면 안 됩니다. 스킬 폴더 아래에 이름을 딴 폴더를 만들고 그 안에 정해진 이름의 파일을 넣어야 인식됩니다. 목록에는 보이는데 Claude가 스스로 안 쓰는 경우는 다른 문제인데, 머리말에 "모델이 부르지 못하게" 옵션이 켜져 있거나 설명이 내가 말하는 방식과 안 맞아서입니다. 목록에서 "사용자 전용" 표시가 붙었는지 확인해 보라고 안내합니다.

Q. MCP 서버를 적었는데 안 붙습니다

원인이 네 갈래입니다. 파일 위치(프로젝트 설정은 저장소 맨 위, 설정 폴더 안이 아님), 설정 파일에 서버 항목을 적은 경우(그 키는 읽지 않습니다), 한 번뿐인 승인 창을 닫아버린 경우, 그리고 상대 경로입니다. 마지막이 은근히 잘 걸리는데 — 경로가 설정 파일 위치가 아니라 내가 실행한 폴더 기준으로 풀립니다. 그래서 어디서 켜느냐에 따라 됐다 안 됐다 합니다. 로컬 스크립트는 절대 경로로 적으라는 게 문서 권고입니다.

Q. 서버가 붙었다는데 도구가 하나도 없습니다

연결은 됐는데 도구 목록을 안 돌려주는 상태입니다. 먼저 재연결을 해보고, 그래도 0이면 디버그 모드로 켜서 그 서버가 뱉은 오류 출력을 보라고 안내합니다. 로그 위치까지 문서에 적혀 있습니다 — 개인 설정 폴더 아래 디버그 폴더에 세션 아이디로 된 파일이 생깁니다. "붙었다"와 "쓸 수 있다"가 다르다는 걸 구분해 준다는 점이 좋았습니다.

✨ 오늘 확인한 것 정리

설정이 안 먹는 이유는 대개 안 읽혔거나, 다른 데서 읽혔거나, 덮어써졌거나 셋 중 하나입니다. 실무에서 제일 잘 걸릴 둘은 이름이 하나 다른 설정 파일 두 개와 하위 폴더 CLAUDE.md가 "읽을 때만" 로드된다는 것이고요. 훅이라면 매처를 배열로 쓰는 순간 그 파일의 훅이 전부 날아간다는 걸 기억하세요. 그리고 보장이 필요한 건 CLAUDE.md가 아니라 권한·훅에 두는 게 맞습니다.

※ 확인 경로(2026년 8월 16일 기준): code.claude.com/docs/en/debug-your-config. 명령 이름과 설명은 제가 우리말로 옮긴 것입니다.

※ 일부 항목은 특정 버전 이상에서만 동작합니다. 정확한 버전과 명령 표기는 원문을 확인하세요.