Reference 1, 디렉토리 구조 - Claude Code Deep Dive Workshop

한 장 지도

세 층입니다: 사용자 전역(~/.claude), 프로젝트(.claude와 루트 파일), 그리고 조직 강제(managed).

Directory Map

~/.claude/                              # 사용자 전역 (모든 프로젝트 공통)
├─ settings.json                        #   개인 기본 설정 (모델, 권한 기본값)
├─ CLAUDE.md                            #   전역 메모리, 모든 세션에 주입
├─ skills/<이름>/SKILL.md               #   개인 스킬 (커스텀 슬래시 커맨드의 표준)
├─ commands/*.md                        #   (legacy) 구식 개인 커맨드
├─ agents/*.md                          #   개인 서브에이전트 정의
├─ plugins/                             #   설치된 플러그인 본체
├─ projects/<프로젝트별>/               #   세션 대화 기록, /resume과 --resume의 저장소
└─ feedback-bundles/                    #   /bug 로컬 아카이브 (서드파티 연결 시)

<프로젝트 루트>/
├─ CLAUDE.md                            # 프로젝트 메모리 (커밋, 팀 공유)
├─ .mcp.json                            # 프로젝트 MCP 서버 (커밋, 팀 공유)
└─ .claude/
   ├─ settings.json                     #   프로젝트 설정 (커밋, 팀 공유)
   ├─ settings.local.json               #   개인 오버라이드 (gitignore 대상)
   ├─ skills/  agents/                  #   팀 공유 스킬과 서브에이전트
   ├─ commands/                         #   (legacy) 팀 커맨드
   └─ loop.md                           #   /loop 기본 프롬프트

# 조직 강제 (managed-settings, Chapter 3)
Linux, WSL   /etc/claude-code/managed-settings.json
macOS        /Library/Application Support/ClaudeCode/managed-settings.json
Windows      C:\Program Files\ClaudeCode\managed-settings.json

무엇을 어디에 두나

두고 싶은 것	위치	공유 범위	워크샵
모든 프로젝트에서 지킬 개인 취향	`~/.claude/CLAUDE.md`, `~/.claude/settings.json`	나만	Ch1
이 저장소의 규칙과 맥락	루트 `CLAUDE.md`	팀 (커밋)	Ch1
팀이 함께 쓰는 스킬, 에이전트	`.claude/skills/`, `.claude/agents/`	팀 (커밋)	Ch2, Ch4
팀 표준 권한과 훅	`.claude/settings.json`	팀 (커밋)	Ch4
나만의 로컬 예외	`.claude/settings.local.json`	나만 (gitignore)	Ch4
팀 공용 MCP 서버	`.mcp.json`	팀 (커밋)	Ch4
조직이 강제할 정책	managed-settings.json (OS별 경로)	조직 (배포 도구)	Ch3

우선순위, 충돌하면 누가 이기나

같은 키가 여러 곳에 있으면 위가 아래를 덮습니다.

순위	출처	메모
1	managed-settings (조직)	사용자가 뒤집을 수 없음, Chapter 3의 통제선
2	CLI 인자	--model, --allowed-tools 같은 실행 시 지정
3	`.claude/settings.local.json`	개인 로컬
4	`.claude/settings.json`	프로젝트 공유
5	`~/.claude/settings.json`	사용자 전역

CLAUDE.md는 계층 합산 설정과 달리 메모리(CLAUDE.md)는 덮어쓰기가 아니라 전역 + 프로젝트 + 하위 디렉토리가 함께 로드됩니다. 하위 디렉토리의 CLAUDE.md는 그 영역을 만질 때 불려 옵니다. 비대해진 메모리는 /doctor가 스킬과 중첩 파일로 다이어트를 제안합니다.

현장 팁 7

#	팁	내용
1	CLAUDE.md 다이어트 기준	코드베이스에서 유추 가능한 것(디렉토리 배치, 의존성 목록, 아키텍처 개요)은 빼고, 함정, 이유, 도구 기본값과 다른 관례만 남기세요. `/doctor`가 정확히 이 기준으로 다이어트를 제안하고, 늘 로드될 필요 없는 내용은 스킬과 중첩 CLAUDE.md로 옮겨 줍니다.
2	세션은 디렉토리에 산다	대화 기록은 `~/.claude/projects/`에 프로젝트 디렉토리별로 저장됩니다. `--resume`이 "그 폴더에서 실행할 때"만 이전 대화를 찾는 이유입니다. 디렉토리를 옮기며 이어가려면 `/cd`를 쓰세요, 세션 저장소까지 함께 이사합니다.
3	/add-dir는 접근권, /cd는 이사	`/add-dir`는 파일 접근만 열어 줄 뿐 그 디렉토리의 `.claude/` 설정 대부분을 읽지 않습니다. 다른 프로젝트의 스킬과 설정까지 원하면 `/cd`로 이동하세요.
4	훅은 파일이 아니라 블록	훅은 별도 디렉토리가 아니라 각 스코프 settings.json의 hooks 블록에 삽니다. 개인 실험은 local, 팀 표준은 프로젝트, 조직 강제는 managed에 두는 식으로 같은 훅도 스코프만 바꿔 승격합니다 (Chapter 3, 4에서 실습한 경로).
5	worktree는 새 루트	superpowers처럼 git worktree로 이동하면 그곳이 새 프로젝트 루트입니다. 프로젝트 스킬과 설정은 worktree 쪽 `.claude/`에 있어야 로드됩니다. 캡스톤에서 스킬을 항상 worktree 안에 만들게 한 이유입니다.
6	스킬 발동의 두 스위치	SKILL.md frontmatter의 `description`은 Claude가 알아서 불러 쓰는 자동 발동의 기준이고, `disable-model-invocation: true`를 켜면 사람이 슬래시로 부를 때만 동작합니다. 배포나 파괴적 절차가 담긴 스킬은 후자가 안전합니다 (워크샵 스킬 전부가 이 방식).
7	새 머신 이주 체크리스트	옮길 것은 셋뿐입니다: `~/.claude/settings.json`, `~/.claude/skills/`, `~/.claude/agents/`. 세션 기록(projects/)은 무겁고 플러그인은 재설치가 깔끔합니다. 프로젝트 쪽 자산은 이미 git에 있습니다.

자주 하는 실수와 처방

증상	원인	처방
동료 머신에서 내 설정이 적용됨	settings.local.json을 커밋	gitignore 확인, 개인 값은 local로만
다른 프로젝트에서 엉뚱한 규칙 적용	프로젝트 규칙을 전역 CLAUDE.md에 기록	루트 CLAUDE.md로 이동, 전역엔 개인 취향만
새 커맨드가 목록에 안 보임	commands/(legacy)에 생성 또는 세션 미갱신	skills/이름/SKILL.md로 작성 후 /reload-skills
플러그인 수정이 반영 안 됨	세션이 구버전을 로드 중	/reload-plugins, MCP 변경 시 --force
--resume이 대화를 못 찾음	다른 디렉토리에서 실행	원래 폴더에서 실행하거나 세션을 /cd로 옮겨 두기
관리자인데 정책이 안 먹음	managed 경로 오타 (하이픈, OS별 경로)	/status의 설정 출처 목록에서 managed 줄 확인 (Chapter 3)