← 목록으로AI WORKFLOW

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

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

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 디렉터리·설정·메모리를 근거로 삼았습니다. 파인더에서 .claude 폴더가 안 보이는 건 숨김 폴더라서입니다. 여는 법은 폴더편에 있습니다.

홈의 .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 설정 파일 지도 한 장

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

~/.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)만 읽힌다는 설명이 나온다

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

홈 ~/.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에 아래 두 줄을 붙여 넣으세요.

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

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

$ 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/ 같은 폴더도 있습니다. 버전 차이가 크다면 공식 문서의 인터랙티브 지도를 직접 눌러 보세요.

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

이어서 읽을 글