Claude Code 의 구조 — 디렉토리 컨벤션과 검색 우선순위로 이해하기

Claude Code의 구조 — 디렉토리, 검색 우선순위, 구성요소

작성일: 2026-04-27

한 줄 정리

Claude Code는 "약속된 디렉토리에 마크다운/JSON을 두면 알아서 읽어서 동작하는 CLI 에이전트"다. 무거운 라이브러리가 아니라 컨벤션 기반이라, 어디에 무엇을 두면 어떤 일이 일어나는지가 곧 사용법이다.

디렉토리 두 곳

~/.claude/                          ← 사용자 전역 (모든 세션 공유)
  agents/        *.md               ← 서브에이전트 정의
  commands/      *.md               ← 슬래시 커맨드 (/foo)
  skills/        */SKILL.md         ← 자동 발동 능력
  settings.json                     ← 권한/모델/환경/훅 설정
  CLAUDE.md                         ← 모든 세션에 자동 로드되는 지침
  hooks/                            ← (드물게) 전역 훅 스크립트

<project>/.claude/                  ← 프로젝트별 (CWD 기준 상위 탐색)
  agents/   commands/   skills/
  settings.json                     ← 팀과 공유할 설정 (커밋 권장)
  settings.local.json               ← 본인 전용 설정 (gitignore 권장)
  hooks/
<project>/CLAUDE.md                 ← 프로젝트 자동 로드 지침

검색 우선순위 (가장 중요한 멘탈 모델)

세션이 시작되면 Claude Code는 CWD에서 위로 올라가며 .claude/와 CLAUDE.md를 찾고, 마지막에 ~/.claude/까지 본다. 충돌하면 가까운 쪽이 이긴다.

CWD: /home/jai/workspace/pypy/interpark_camping/
탐색 순서:
1. /home/jai/workspace/pypy/interpark_camping/.claude/   ← 가장 우선
2. /home/jai/workspace/pypy/.claude/
3. /home/jai/workspace/.claude/
4. /home/jai/.claude/                                    ← 전역 fallback

같은 이름의 에이전트가 1번과 4번에 모두 있으면 1번이 사용된다. 즉 "전역 기본값 + 프로젝트 덮어쓰기" 패턴이 가능하다.

구성 요소 한눈에 보기

파일/폴더	무엇	언제 발동	특징
CLAUDE.md	영구 지침/컨텍스트	세션 시작 시 자동 로드	코드베이스 룰, 프로젝트 목적 등 — 매 응답에 포함
agents/*.md	서브에이전트	메인이 Agent 도구로 호출	별도 컨텍스트에서 동작 → 메인 대화 절약
commands/*.md	슬래시 커맨드	사용자가 /이름 입력	사용자 발화 trigger, 정형화된 작업 자동화
skills/SKILL.md	자동 발동 능력	사용자 발화가 description과 매칭	"trigger when…" 패턴으로 모델이 알아서 호출
hooks	셸 스크립트	도구 호출 전후 등 이벤트	자동 검사/포매팅/알림. 실패 시 동작 차단 가능
settings.json	정적 설정	항상	권한 allowlist, 모델 선택, env, 훅 등록
MCP 서버	외부 도구 통합	도구 호출 시	Gmail/DB/API 같은 외부 자원을 도구로 노출
plugins	위 묶음 배포 단위	설치 시	한 패키지로 여러 에이전트/스킬/훅 배포

직관 한 줄 요약

• CLAUDE.md는 "항상 들고 다니는 헌장"
• agents는 "필요할 때 부르는 외주 직원"
• commands는 "사용자가 누르는 매크로 버튼"
• skills는 "Claude가 알아서 발동하는 반사신경"
• hooks는 "행동 전후의 자동 체크포인트"
• MCP는 "외부 시스템을 도구로 노출하는 표준 콘센트"

왜 이런 구조인가

• 파일 시스템이 곧 상태 저장소 — 별도 DB 없이 git만으로 버전 관리됨.
• CWD 기반 탐색 — 프로젝트마다 다른 컨텍스트를 자연스럽게 분리. cd만 잘 해도 다른 환경으로 전환됨.
• 마크다운 중심 — LLM이 가장 잘 이해하는 형식이자 사람도 읽기 쉬움. 별도 파서/DSL 없음.
• 계층적 fallback — 전역에 두면 모든 프로젝트가 쓰고, 프로젝트에 두면 좁게 적용. 덮어쓰기는 자연스럽게.

흔한 함정

• CLAUDE.md는 매 응답에 포함 → 너무 길면 비용 폭증. 200줄 안팎 권장.
• .claude/와 ~/.claude/는 별개. 헷갈리면 어떤 에이전트가 안 보이는 이유가 됨.
• CWD가 핵심. claude 명령을 어디서 실행했느냐가 모든 걸 결정.
• settings.json과 settings.local.json 둘 다 머지됨. 팀 공유는 전자, 개인은 후자.

연관 개념

• 디렉토리 컨벤션: .editorconfig, .vscode/처럼 도구가 약속된 위치를 읽는 패턴
• LSP (Language Server Protocol) ↔ MCP (Model Context Protocol)
• monorepo의 nested config (Nx, Turbo)