# 45개 중 손댈 건 2개입니다 — .claude 디렉터리 설정 파일 지도, settings.json 위치부터 skills 폴더까지

.claude 디렉터리 설정 파일 지도. settings.json 위치, skills 폴더, 겹칠 때 규칙, gitignore까지.

- source: https://polroute.com/posts/claude-directory-map/
- category: AI 워크플로우
- published: 2026-09-27

---

Claude Code를 쓰다 보면 `.claude` 폴더를 열어볼 일이 생깁니다. 규칙을 적으라는 `CLAUDE.md`도, 권한을 바꾸라는 `settings.json`도 전부 이 안에 있습니다. 그런데 막상 열어보면 처음 보는 이름이 줄줄이 나옵니다. 필자 맥의 `~/.claude/` 안에는 항목이 **45개** 있습니다.

결론부터 말씀드립니다. 두 가지만 기억하시면 됩니다.

1. `.claude` 폴더는 **두 군데**에 있습니다. 홈 폴더의 `~/.claude/`는 내 모든 프로젝트에, 프로젝트 폴더 안의 `.claude/`는 그 프로젝트에만 적용됩니다.
2. 그 안에서 여러분이 직접 고칠 파일은 **2개**입니다. 공식 문서에 이렇게 적혀 있습니다.

> "Most users only edit `CLAUDE.md` and `settings.json`."
> (대부분의 사용자는 `CLAUDE.md`와 `settings.json`만 편집합니다.)

나머지 43개는 Claude Code가 일하면서 스스로 남기는 기록이거나, 필요해졌을 때 만드는 선택 항목입니다. 이 글은 그 전체를 지도 한 장으로 정리합니다.

> 2026년 9월 기준, Claude Code v2.1.283에서 확인했습니다. 경로와 동작은 공식 문서 [.claude 디렉터리](https://code.claude.com/docs/en/claude-directory)·[설정](https://code.claude.com/docs/en/settings)·[메모리](https://code.claude.com/docs/en/memory)를 근거로 삼았습니다. 파인더에서 `.claude` 폴더가 안 보이는 건 숨김 폴더라서입니다. 여는 법은 [폴더편](/posts/claude-code-folder-basics/)에 있습니다.

## 홈의 .claude와 프로젝트의 .claude는 적용 범위가 다릅니다

두 폴더는 이름만 같습니다. 누구에게, 어디까지 적용되느냐가 다릅니다.

| | 홈 `~/.claude/` | 프로젝트 `.claude/` |
|---|---|---|
| 위치 | 맥 `/Users/내이름/.claude`, 윈도우 `C:\Users\내이름\.claude` | 작업 폴더 안 (예: `바탕화면/my-app/.claude`) |
| 적용 범위 | 이 컴퓨터의 모든 프로젝트 | 그 프로젝트 하나 |
| 누구 것 | 나 혼자 | 팀 전체 (git으로 공유) |
| 생기는 때 | Claude Code를 쓰기 시작하면 저절로 | 내가 만들거나, Claude Code가 설정을 저장하면서 |

git은 파일의 변경 이력을 저장하고 팀과 나눠 갖게 해 주는 도구입니다. 혼자 쓰신다면 "git으로 공유"를 "다른 컴퓨터에서도 그대로 쓸 수 있다"로 읽으시면 됩니다.

`.claude` 폴더 **밖**에 놓이는 파일도 있어서 이름 때문에 자주 헷갈립니다.

- **`~/.claude.json`**: 폴더가 아니라 홈 폴더에 바로 놓인 **파일**입니다. 로그인 정보, 개인 MCP 서버(Claude를 외부 서비스와 연결하는 장치), 프로젝트별 신뢰 승인 기록이 들어 있습니다. 공식 문서는 이 파일을 직접 고칠 필요가 없다고 말합니다.
- **`CLAUDE.md`**: 프로젝트 지침은 프로젝트 폴더 바로 아래에 둬도 되고 `.claude/` 안에 둬도 됩니다. 어느 쪽이든 읽힙니다.
- **`.mcp.json`, `CLAUDE.local.md`**: 공식 문서가 정한 자리는 `.claude/` 안이 아니라 **프로젝트 폴더 바로 아래**입니다.

## Claude Code 설정 파일 지도 한 장

먼저 전체 모양입니다. 복사해서 메모장에 붙여 두셔도 됩니다.

```text
~/.claude/                     ← 홈: 나 혼자, 모든 프로젝트
├── CLAUDE.md                  ← 직접 고침
├── settings.json              ← 직접 고침
├── rules/                     ← 선택
├── skills/<이름>/SKILL.md      ← 선택
├── agents/                    ← 선택
└── projects/ 등                ← Claude Code가 씀. 건드리지 않음

my-app/                        ← 프로젝트 폴더
├── CLAUDE.md                  ← 팀 공유
├── CLAUDE.local.md            ← 나만 (git 제외)
├── .mcp.json                  ← 팀 공유
└── .claude/
    ├── settings.json          ← 팀 공유
    ├── settings.local.json    ← 나만 (git 제외)
    ├── rules/
    ├── skills/<이름>/SKILL.md
    └── agents/
```

공식 문서에도 같은 지도가 인터랙티브 탐색기로 들어 있습니다. 파일을 누르면 누가 쓰는 파일인지, 언제 읽히는지가 나옵니다. 아래는 오토 메모리의 `MEMORY.md`를 고른 화면입니다. "CLAUDE WRITES", 즉 Claude가 직접 쓰는 파일이라는 표시가 붙어 있습니다.

![Claude Code 공식 문서의 .claude 디렉터리 탐색기. Global(~/) 탭에서 MEMORY.md를 고르면 CLAUDE WRITES 배지와 세션 시작 시 앞 200줄(최대 25KB)만 읽힌다는 설명이 나온다](/images/claude-directory-map-1.webp)

각 파일이 무엇이고 언제 읽히는지 아래 표에 정리했습니다. "언제 읽히나"는 위 공식 탐색기의 설명을 옮긴 것입니다.

**홈 `~/.claude/` — 나 혼자, 모든 프로젝트**

| 경로 | 무엇인가 | 언제 읽히나 |
|---|---|---|
| `CLAUDE.md` | 사용자 지침. 모든 프로젝트에 공통으로 주는 규칙 | 매 세션 시작 |
| `settings.json` | 개인 설정. 권한, 기본 모델, 훅(Hook, 정해진 순간에 자동으로 도는 스크립트) | 매 세션 시작 |
| `rules/*.md` | 공통 규칙을 주제별 파일로 나눈 것 | 매 세션 시작 |
| `skills/<이름>/SKILL.md` | 개인 스킬(Skill). `/이름`으로 부르는 작업 설명서 | 설명은 시작 시, 본문은 쓸 때 |
| `agents/*.md` | 개인 서브에이전트. 따로 일하고 요약만 돌려주는 조수 | 부를 때 |
| `projects/<프로젝트>/memory/` | 오토 메모리. Claude가 스스로 적는 메모 | 시작 시 `MEMORY.md` 앞 200줄 또는 25KB까지 |

**프로젝트 폴더 — 팀 공유와 나만 쓰는 것**

| 경로 | 무엇인가 | 언제 읽히나 | git |
|---|---|---|---|
| `CLAUDE.md` 또는 `.claude/CLAUDE.md` | 프로젝트 지침. 팀이 같이 보는 규칙 | 매 세션 시작 | 올림 |
| `CLAUDE.local.md` | 이 프로젝트에서 나만 쓰는 지침 | 매 세션 시작 | 안 올림 |
| `.claude/settings.json` | 프로젝트 설정. 팀 공통 권한·훅 | 매 세션 시작 | 올림 |
| `.claude/settings.local.json` | 이 프로젝트에서 나만 쓰는 설정 | 매 세션 시작 | 안 올림 |
| `.claude/rules/*.md` | 주제별 규칙. 특정 파일을 다룰 때만 읽히게 할 수도 있음 | 시작 시, 또는 해당 파일을 열 때 | 올림 |
| `.claude/skills/<이름>/SKILL.md` | 프로젝트 스킬 | 설명은 시작 시, 본문은 쓸 때 | 올림 |
| `.claude/agents/*.md` | 프로젝트 서브에이전트 | 부를 때 | 올림 |
| `.mcp.json` | 팀이 같이 쓰는 MCP 서버 목록 | 매 세션 시작 | 올림 |

오래된 글에서 `.claude/commands/` 폴더를 보셨다면, 지금은 스킬과 같은 기능으로 합쳐졌습니다. 공식 문서도 새로 만들 때는 `skills/`를 쓰라고 합니다("Commands and skills are now the same mechanism. For new workflows, use skills/ instead"). 기존 파일은 그대로 동작합니다.

표의 칸 하나하나는 이 시리즈에서 한 편씩 따로 다룹니다. 지금은 어디에 무엇이 있는지만 잡아 두시면 됩니다.

## 직접 만드는 것과 저절로 생기는 것

필자 맥의 45개 중 상당수는 Claude Code가 일하면서 남긴 기록입니다. 대화 기록과 오토 메모리가 쌓이는 `projects/`, 파일을 고치기 직전 상태를 떠 둔 `file-history/`(되돌리기에 쓰입니다), 계획 모드의 `plans/`, 입력 기록인 `history.jsonl` 같은 것들입니다. 이 중 `projects/` 하나가 500MB였습니다.

크기에 놀라서 지우실 필요는 없습니다. 대화 기록 같은 항목은 30일(`cleanupPeriodDays` 기본값)이 지나면 Claude Code가 알아서 정리합니다.

반대로 **내가 만드는 것**은 몇 개 안 됩니다. 그마저 폴더를 손으로 만들 필요가 없습니다.

- **`/memory`**: CLAUDE.md 계열 파일 목록을 보여 줍니다. 아직 없는 파일을 고르면 새로 만들어서 열어 줍니다.
- **`/init`**: 프로젝트를 훑어보고 `CLAUDE.md` 초안을 써 줍니다.
- **권한 확인 창의 "다시 묻지 않기"**: 고르는 순간 Claude Code가 그 규칙을 `.claude/settings.local.json`에 저장합니다. 만든 적 없는 `.claude/` 폴더가 프로젝트에 생겼다면 대개 이것 때문입니다.

스킬과 규칙은 직접 만들어야 합니다. 스킬은 폴더(`skills/<이름>/`)와 `SKILL.md`를, 규칙은 `rules/` 폴더 안에 `.md` 파일을 만듭니다. 둘 다 뒤 편에서 실습으로 다룹니다.

## 프로젝트 설정이 개인 설정을 덮어쓰나요? 파일마다 다릅니다

가장 많이 받는 질문입니다. "좁은 쪽이 넓은 쪽을 덮어쓴다"는 설명이 흔한데, 공식 문서를 보면 파일 종류마다 규칙이 다릅니다.

| 겹치는 것 | 어떻게 되나 |
|---|---|
| `CLAUDE.md` | 덮어쓰지 않습니다. 전부 이어붙여 함께 읽힙니다 |
| `settings.json`의 값 하나 (예: 기본 모델) | 가까운 쪽이 이깁니다. 나만(local) > 프로젝트 > 개인 |
| `settings.json`의 목록 (예: 허용 권한 목록) | 합쳐집니다. 모든 파일의 항목이 다 적용됩니다 |
| 이름이 같은 스킬 | **개인 스킬이 이깁니다.** 프로젝트 스킬이 가려집니다 |
| 이름이 같은 MCP 서버 | 가까운 쪽이 이깁니다. 나만(local) > 프로젝트 > 개인 |

CLAUDE.md에 관한 공식 문서 원문은 이렇습니다.

> "All discovered files are concatenated into context rather than overriding each other."
> (찾은 파일은 서로 덮어쓰지 않고 전부 이어붙여 컨텍스트에 들어갑니다.)

그래서 사용자 지침과 프로젝트 지침이 서로 반대 말을 하면 어느 한쪽이 이기지 않습니다. 공식 문서는 이 경우 Claude가 "may pick one arbitrarily", 즉 둘 중 하나를 임의로 고를 수 있다고 적었습니다. 충돌하는 규칙은 애초에 만들지 않는 게 답입니다.

스킬은 방향이 반대라서 특히 조심해야 합니다. 공식 문서의 예시를 그대로 옮기면, `deploy`라는 스킬이 `~/.claude/skills/`와 프로젝트의 `.claude/skills/`에 모두 있을 때 `/deploy`는 **개인 것**을 실행합니다. 팀이 만든 스킬과 같은 이름으로 개인 스킬을 만들면, 나만 팀과 다른 스킬을 쓰게 됩니다.

CLAUDE.md가 정확히 어떤 순서로 이어붙는지는 로드 순서 편에서 설명합니다.

## 여기서 막힙니다: .claude 폴더를 통째로 .gitignore에 넣는 실수

`.gitignore`는 git에 올리지 않을 파일 목록을 적는 파일입니다. 개인 설정이 올라갈까 봐 걱정되는 마음에 여기에 `.claude/`를 통째로 적는 분이 있습니다. 그러면 팀이 같이 써야 할 프로젝트 설정, 스킬, 서브에이전트까지 전부 저장소에서 빠집니다. 동료가 프로젝트를 내려받으면 `/deploy` 같은 스킬이 없습니다.

빼야 하는 건 **나만 쓰는 파일 두 개**뿐입니다. 프로젝트의 `.gitignore`에 아래 두 줄을 붙여 넣으세요.

```gitignore
# Claude Code: 나만 쓰는 파일 두 개만 제외
CLAUDE.local.md
**/.claude/settings.local.json
```

"`settings.local.json`은 자동으로 제외된다던데요?"라는 질문도 받습니다. 절반만 맞습니다. 필자 맥에서 이 파일이 왜 제외되는지 물어보면 이렇게 나옵니다. `git check-ignore -v`는 어떤 파일이 어느 규칙 때문에 제외되는지 알려 주는 명령어입니다(사용자 이름은 `me`로 바꿨습니다).

```bash
$ git check-ignore -v .claude/settings.local.json
/Users/me/.config/git/ignore:1:**/.claude/settings.local.json	.claude/settings.local.json
```

막고 있는 건 저장소의 `.gitignore`가 아닙니다. **내 맥의 전역 제외 목록**(`~/.config/git/ignore`) 첫 줄입니다. Claude Code가 이 파일에 설정을 처음 저장할 때 그 한 줄을 추가해 둔 것입니다. 그래서 두 가지 빈틈이 생깁니다.

- 파일을 손으로 만들었고 Claude Code가 이 컴퓨터에서 이 파일에 한 번도 저장한 적이 없다면 이 한 줄이 없을 수 있습니다.
- 동료 컴퓨터에는 이 줄이 없을 수 있습니다. 공식 문서도 팀과 공유하려면 프로젝트 `.gitignore`에도 적으라고 합니다("To share the ignore rule with your team, also add it to the project `.gitignore`").

`CLAUDE.local.md`는 기본적으로 자동 제외가 아예 없습니다. 공식 문서 표현은 "Create it manually and add it to `.gitignore`", 직접 만들고 직접 `.gitignore`에 넣으라는 것입니다. 위 두 줄을 넣은 뒤 `git status`(올라갈 파일 목록을 보여 주는 명령어)를 쳤을 때 두 파일이 목록에 없으면 제대로 된 것입니다.

## 이 지도가 맞지 않는 경우

이 지도가 그대로 통하지 않는 경우가 두 가지 있습니다.

첫째, 회사가 Claude Code를 관리하고 있다면 이 지도 위에 한 층이 더 있습니다. 조직이 배포한 관리 설정(managed settings)입니다. 여기 적힌 값은 내가 어느 파일에 무엇을 쓰든 이기고 개인이 바꿀 수 없습니다. 표대로 설정했는데 적용이 안 된다면 가장 먼저 의심할 곳입니다.

둘째, 경로는 바뀝니다. Claude Code는 거의 매주 업데이트되고 공식 지도에는 이 글에서 뺀 `workflows/`, `output-styles/` 같은 폴더도 있습니다. 버전 차이가 크다면 [공식 문서의 인터랙티브 지도](https://code.claude.com/docs/en/claude-directory)를 직접 눌러 보세요.

이 지도를 외울 필요는 없습니다. 첫 달은 `CLAUDE.md` 하나로 충분합니다. 처음 보는 경로를 만났을 때 펼쳐 보시면 됩니다.

## 이어서 읽을 글

- `CLAUDE.md`에 무엇을 적을지: [복붙용 템플릿 3종](/posts/coding-system-prompt-templates/)
- 이 파일들을 하나의 작업 체계로 굴리는 방법: [하네스 엔지니어링](/posts/harness-engineering/)
- `/memory`, `/init`, `/config` 등 명령어 전체 목록: [슬래시 명령어 정리](/posts/claude-code-slash-commands/)
- 아직 첫 세션을 안 열어 보셨다면: [첫 세션 10분](/posts/claude-code-first-session/)