Claude Code 설정 파일 지도 — 커밋할 것과 아닌 것이 갈리고, 목록에 없는 파일도 있습니다

쓰다 보면 설정 폴더에 파일이 열댓 개로 늘어납니다. 그런데 어느 걸 저장소에 올려 팀과 공유하고, 어느 걸 내 컴퓨터에만 둬야 하는지가 은근히 헷갈리죠. 공식 문서에 파일마다 커밋 여부를 표시한 지도가 있어서 정리했습니다. 그리고 그 표에 일부러 빠뜨린 파일이 셋 있는데, 문서가 따로 절을 만들어 설명합니다.

📌 30초 요약

• 거의 다 커밋하는 파일입니다. 예외는 개인 덮어쓰기 파일 하나와 전역 앱 상태뿐입니다.
• MCP 서버 설정은 커밋 대상입니다. 다만 개인용은 다른 파일에 들어갑니다.
• 파일 목록에 안 나오는 파일이 셋 있습니다. 그중 하나는 직접 만들어야 합니다.
• 규칙 파일은 경로로 걸 수 있습니다. 그 폴더를 건드릴 때만 적용되게요.
• 워크플로 파일은 저장하면 그대로 명령이 됩니다. 파일 이름이 곧 명령 이름입니다.
• 폴더의 절반은 내가 안 쓴 파일입니다. 대화 기록과 캐시가 자동으로 쌓입니다.

무엇을 하려면 어디를 고치나

문서가 "하고 싶은 일 → 고칠 파일" 순서로 표를 하나 줍니다. 파일부터 외우는 것보다 이쪽이 실용적이라 먼저 옮깁니다.

하고 싶은 일	고칠 곳	범위
프로젝트 맥락과 관례 알려주기	메모리 파일	프로젝트 또는 전역
특정 도구 호출을 허용·차단	설정 파일의 권한 또는 훅 항목	프로젝트 또는 전역
개인 취향을 git에서 빼두기	로컬 설정 파일	프로젝트 전용
이름 붙여 부르는 기능 만들기	스킬 폴더 안의 정의 파일	프로젝트 또는 전역
전용 도구를 가진 하위 에이전트 정의	에이전트 폴더	프로젝트 또는 전역
외부 도구를 붙이기	저장소 루트의 MCP 설정 파일	프로젝트 전용

범위 열이 중요합니다. "프로젝트 전용"이라고 적힌 둘은 전역으로 옮겨도 안 읽힙니다. 설정이 안 먹히는 원인을 정리했을 때도 MCP 서버를 설정 파일 안에 적어서 안 읽히는 경우가 목록에 있었는데, 애초에 파일이 정해져 있어서 그렇습니다.

커밋할 것과 아닌 것이 갈립니다

파일 지도 표에 커밋 열이 따로 있습니다. 세어 보니 대부분 체크고, 빠진 게 셋뿐이었습니다. 저는 이게 이 문서에서 제일 실용적인 정보라고 봤습니다 — "이거 올려도 되나?"를 매번 고민할 필요가 없어집니다.

# 저장소에 올리는 것 (팀과 공유)
CLAUDE.md                # 매 세션 로드되는 지시
.claude/rules/           # 주제별 지시. 경로로 걸 수 있음
.claude/settings.json    # 권한·훅·환경변수·모델 기본값
.claude/skills/          # 이름으로 부르는 기능
.claude/agents/          # 하위 에이전트 정의
.claude/workflows/       # 저장하면 그대로 명령이 됨
.mcp.json                # 저장소 루트. 팀 공용 MCP 서버

# 안 올리는 것 (내 것)
.claude/settings.local.json  # 개인 덮어쓰기
~/.claude.json               # 앱 상태·로그인·개인 MCP 서버

표에는 이 밖에도 출력 스타일 폴더(응답 형식), 커맨드 폴더(스킬과 같은 구조의 단일 파일), 하위 에이전트 영속 메모리 폴더가 커밋 대상으로 들어 있습니다. 전역 전용은 키보드 단축키와 테마, 그리고 자동 메모리입니다.

⚠️ 로컬 설정 파일은 이름이 헷갈립니다

같은 폴더에 설정 파일과 로컬 설정 파일이 나란히 있는데, 뒤엣것만 개인용입니다. 문서 설명이 정확한데 — Claude Code가 여기에 설정을 저장할 때는 자동으로 git 무시 목록에 넣어줍니다. 문제는 내가 직접 만들었을 때죠. 그러면 무시 목록에 안 들어가 있을 수 있고, 내 개인 허용 규칙이 팀 저장소로 올라갑니다. 앞서 워크트리를 정리하면서 확인한 것도 같은 파일이었습니다 — "다시 묻지 않기"로 허용한 규칙이 전부 여기 쌓입니다. 한 번쯤 열어보시길 권합니다.

목록에 안 나오는 파일이 셋 있습니다

문서가 대화형 탐색기를 제공하면서 "탐색기는 당신이 작성하고 편집하는 파일만 다룬다"고 밝히고, 빠진 셋을 따로 표로 정리해 둡니다. 이 구분이 친절했습니다.

빠진 파일	왜 목록에 없나
회사 강제 설정	시스템 경로에 있고 운영체제마다 다름. 내가 못 덮어씀
개인 메모리 파일	기본으로 안 생김. 직접 만들고 무시 목록에 넣어야 함
설치된 플러그인	전용 명령이 관리. 내가 손댈 파일이 아님

가운데가 제일 쓸모 있습니다. 프로젝트 메모리 옆에 이름 끝에 로컬이 붙은 개인 메모리 파일을 만들어두면, 팀 공용 지시와 나란히 함께 로드됩니다. 팀 저장소의 지시는 건드리지 않으면서 "나는 이렇게 불러줘" 같은 개인 취향만 따로 둘 수 있는 자리인 셈이죠. 다만 기본으로 안 생기니 직접 만들고 무시 목록에 넣어야 합니다. 도구마다 다른 지시 파일 표준을 정리했을 때 아쉬웠던 "개인용 자리"가 여기 있었습니다.

🧩 표를 보다 새로 알게 된 넷

• 규칙 파일은 경로로 걸 수 있습니다. 주제별로 쪼갠 지시를 특정 폴더를 건드릴 때만 적용되게 하는 것요.
• 워크플로 파일은 저장하는 순간 명령이 됩니다. Claude가 써주고 내가 저장하면 파일 이름이 그대로 호출 이름이 됩니다.
• 하위 에이전트도 자기 메모리를 가질 수 있습니다. 이름별 폴더가 따로 있고 커밋 대상입니다.
• 커맨드 폴더와 스킬 폴더는 같은 구조를 씁니다. 문서 표현으로 "단일 파일 프롬프트, 스킬과 같은 메커니즘"입니다.

🗃️ 폴더의 절반은 내가 안 쓴 파일입니다

지금까지가 내가 작성하는 설정이고, 같은 폴더에 Claude Code가 쓰는 데이터가 훨씬 많이 쌓입니다 — 대화 기록, 도구 출력, 붙여넣은 내용, 편집 전 스냅숏, 계획 파일까지요. 문서가 "도구를 거친 것은 전부 디스크의 기록에 남는다"고 못 박습니다. 여기에 보관 기간이 붙는데 기본은 30일이고, 예외로 절대 안 지워지는 것들이 따로 있습니다. 그 얘기는 대화는 30일 뒤 지워지는데 내가 친 프롬프트는 안 지워진다에 따로 정리해 뒀습니다. 설정을 정리할 때 이 데이터도 같이 보시길 — 용량도 그렇고, 무엇이 남는지도 그렇습니다.

🧾 정직하게 — 이 글의 한계

• 파일 이름을 대부분 우리말로 풀었습니다. 표에 그대로 옮기면 읽기 어려워서인데, 실제로 만들 때는 원문 표기가 정확합니다.
• 전부 만들어보고 쓴 글이 아닙니다. 워크플로 파일과 에이전트 메모리는 제가 써본 적 없어 문서 설명을 옮긴 것입니다.
• 커밋 여부는 문서의 권고입니다. 팀 정책이 다르면 그쪽이 우선이고, 특히 훅이 담긴 설정 파일을 공유하는 건 보안 판단이 필요합니다.
• 목록은 계속 늘어납니다. 옛 버전에서 쓰던 폴더가 표에 "더 이상 쓰지 않음"으로 남아 있는 걸 보면요.

🗺️ AI 지출 전체 지도

설정 파일은 매 세션 컨텍스트에 올라가는 비용이기도 합니다. 길수록 토큰이고, 안 읽히면 그냥 낭비고요. 구독과 종량제 선택부터 캐시, 모델 조합, 상한 걸기까지 지금까지 확인한 것들을 일곱 단계 지도 한 장으로 묶어뒀습니다.

📦 반드시 커밋해야 하는 파일이 하나 늘었습니다

에이전트를 파일로 선언해 관리하면 새 파일이 하나 생깁니다. 어느 파일이 어느 자원인지 이어 주는 잠금 기록인데, 이게 없으면 다음 실행 때 전부 새로 만듭니다. 중간에 실패했더라도 커밋하세요 — 절반만 적용됐어도 이미 만들어진 것이 거기 기록돼 있습니다.

자주 묻는 것

Q. 프로젝트 것과 전역 것 중 뭘 먼저 쓰나요?

대부분의 파일이 프로젝트와 전역 양쪽에 둘 수 있습니다. 판단 기준은 간단합니다 — 이 저장소에서만 통하는 규칙이면 프로젝트, 내가 어디서 일하든 똑같이 원하는 취향이면 전역입니다. 스킬·에이전트·출력 스타일이 다 그렇고요. 반대로 프로젝트에만 둘 수 있는 것은 로컬 설정 파일, MCP 설정 파일, 워크트리 복사 목록 셋입니다. 전역에만 둘 수 있는 것은 단축키, 테마, 앱 상태, 자동 메모리고요.

Q. 팀에 공유하면 위험한 게 있나요?

문서가 위험하다고 말하지는 않지만, 표를 보면 판단이 섭니다. 권한과 훅이 같은 설정 파일에 들어간다는 점이 핵심입니다 — 훅은 내 컴퓨터에서 스크립트를 실행하니, 남이 올린 설정 파일을 받아 쓰는 건 남의 스크립트를 받아 도는 것과 같습니다. 반대로 환경변수 항목에 실제 비밀값을 적어 커밋하는 것도 흔한 사고고요. 값 자체는 개인용 파일이나 별도 비밀 관리로 빼는 게 맞습니다.

Q. 설정을 고쳤는데 반영이 안 되면요?

이 문서는 "안 먹을 때"는 다루지 않고 다른 문서로 넘깁니다. 위치와 역할을 확인했는데도 안 되면 대개 덮어쓰기거나 로드 시점 문제입니다. 증상별로 갈라 정리한 글에 이름이 하나 다른 두 파일을 헷갈리는 경우와 하위 폴더 메모리가 나중에야 로드되는 경우를 포함해 담아뒀습니다. 용어가 헷갈린다면 이름이 바뀐 용어 정리도 같이 보시고요.

📦 이 지도가 실전 문제가 되는 자리가 있습니다 (8월 17일 추가)

이 글에서 설정 폴더 안에 있는 것과 그 폴더 바깥의 별도 파일에 있는 것을 갈라 적었습니다. 평소에는 "그렇구나" 하고 넘길 구분인데, 컨테이너에서 개발하면 이 구분이 바로 증상으로 나타납니다. 재빌드할 때마다 홈이 지워지니 흔히 설정 폴더에 볼륨을 걸어 로그인을 유지하려 하는데, 그것만으로는 계속 로그인이 풀립니다. 계정 정보와 개인용 MCP 목록, 프로젝트별 신뢰 여부가 바로 그 바깥 파일에 들어 있어서죠. 해결은 설정 폴더 위치를 가리키는 환경 변수를 볼륨과 같은 경로로 지정해 그 파일까지 안으로 끌어오는 것입니다. 다만 그렇게 하면 자격증명이 재빌드에도 살아남는 볼륨에 영구히 얹힙니다 — 편의와 위험이 같은 파일을 가리키는 구조라, 신뢰하는 저장소에서만 쓰라는 문서 권고가 여기에 붙습니다. 자세한 설정은 컨테이너 쪽을 정리한 글에 적었습니다.

✨ 오늘 확인한 것 정리

설정 파일은 거의 다 커밋하는 게 기본이고, 빼는 건 개인 덮어쓰기 파일과 앱 상태 정도입니다. 목록에 안 나오는 파일 셋도 알아두시고요 — 특히 직접 만들어야 하는 개인 메모리 파일은 팀 지시를 건드리지 않고 내 취향만 얹는 자리로 쓸 만합니다. 그리고 같은 폴더에 내가 안 쓴 데이터가 훨씬 많이 쌓인다는 것도요.

※ 확인 경로(2026년 8월 17일 기준): code.claude.com/docs/en/claude-directory. 파일 이름과 설명은 제가 우리말로 옮긴 것이라, 실제 생성 시에는 원문 표기를 확인하세요.

※ 커밋 여부는 공식 문서의 권고이며, 팀 정책과 보안 요구가 우선합니다.