02. Claude Code 디렉터리 구조

개요

---

.claude 디렉터리는 Claude Code 하네스의 설정 층위(코드 없는 층위) 표면이다. 01. LLM Agent Harness Engineering 에서 harness engineering 을 설정 층위와 구현 층위로 나눴는데, .claude 는 그중 설정 층위를 파일 구조로 노출한 것이다. 파일을 놓는 위치와 이름이 곧 하네스 동작(주입되는 지침, 권한, 도구, 서브에이전트)을 결정한다.

• Claude Code 를 쓰면서 추가할 수 있는 설정은 대부분 이 디렉터리 안의 파일로 표현된다.
• .claude 는 두 곳에 있다. 프로젝트 루트(your-project/.claude/, 팀 공유, git commit)와 홈(~/.claude/, 개인, 전역).

프로젝트 디렉터리

---

your-project/
├── CLAUDE.md
├── CLAUDE.local.md
├── .mcp.json
├── .worktreeinclude
└── .claude/
    ├── rules/
    │   ├── testing.md
    │   └── api-design.md
    ├── skills/
    │   └── security-review/
    │       ├── SKILL.md
    │       └── checklist.md
    ├── commands/
    │   └── fix-issue.md
    ├── agents/
    │   └── code-reviewer.md
    ├── output-styles/
    │   └── teaching.md
    ├── workflows/
    │   └── <name>.js
    ├── agent-memory/
    │   └── <agent>/MEMORY.md
    ├── settings.json
    └── settings.local.json

• CLAUDE.md: 매 세션 시작 시 context 에 로드되는 프로젝트 지침. 규칙, 명령어, 아키텍처 맥락을 둔다.
• CLAUDE.local.md: 개인용 프로젝트 지침. gitignore 해서 팀에 공유하지 않는다. deprecated 이며 @import 로 대체 권장된다(로드 자체는 아직 됨).
• .mcp.json: 프로젝트 스코프 MCP 서버 정의. 외부 도구(DB, API)를 붙이고 팀과 공유한다.
• .worktreeinclude: 새 git worktree 를 만들 때 복사할 gitignore 된 파일 목록.
• .claude/: 프로젝트 레벨 설정, 규칙, 확장을 모은 폴더.
  • rules/: 토픽별 지침 파일. frontmatter paths 로 특정 파일을 다룰 때만 로드된다(v2.0.64+). 큰 CLAUDE.md 를 쪼개는 용도.
  • skills/: 이름으로 불러 쓰는 재사용 프롬프트. 스킬 하나가 폴더 하나이고 SKILL.md 가 엔트리포인트, 나머지는 번들 파일.
  • commands/: 슬래시 명령. 파일명이 /명령어 가 된다. 이제 skills 와 같은 메커니즘이라 신규 작업은 파일 번들이 가능한 skills/ 를 권장한다.
  • agents/: 별도 context window 를 갖는 서브에이전트. 특정 작업만 위임한다.
  • output-styles/: 답변 형식과 말투를 바꾸는 출력 스타일.
  • workflows/: 서브에이전트 다수를 오케스트레이션하는 동적 워크플로우 스크립트(.js). 저장된 워크플로우는 /명령어 로 재사용된다.
  • agent-memory/: 서브에이전트 영속 메모리. <agent>/MEMORY.md 를 서브에이전트가 스스로 쓰고 갱신한다. 메인 세션 자동 메모리와는 별개다.
  • settings.json: 권한, 훅, 상태줄, 모델, 환경변수 등을 담는다. 훅은 별도 폴더가 아니라 이 파일에 등록해야 실행된다.
  • settings.local.json: 개인 설정 오버라이드. 자동 gitignore 된다.

홈(전역) 디렉터리

---

~/
├── .claude.json
└── .claude/
    ├── CLAUDE.md
    ├── settings.json
    ├── keybindings.json
    ├── themes/
    ├── projects/
    │   └── <project>/memory/
    │       ├── MEMORY.md
    │       └── debugging.md
    ├── rules/
    ├── skills/
    ├── commands/
    ├── agents/
    ├── workflows/
    └── output-styles/

~/.claude/ 는 모든 프로젝트에 적용되는 개인 설정이며, 세션이 쓰는 자동 메모리도 여기 있다.

• .claude.json: 앱 상태와 UI 환경설정.
• .claude/: 프로젝트 레벨 설정, 규칙, 확장을 모은 폴더.
  • CLAUDE.md: 전역 개인 지침. 모든 프로젝트에 적용된다.
  • settings.json: 전 프로젝트 기본 설정.
  • keybindings.json: 커스텀 키보드 단축키.
  • themes/: 커스텀 색 테마.
  • projects/<project>/memory/MEMORY.md: 메인 세션 자동 메모리. Claude 가 스스로 쓰고 유지한다. MEMORY.md 가 길어지면 debugging.md 같은 토픽 노트로 분리한다.
  • rules/, skills/, commands/, agents/, workflows/, output-styles/: 프로젝트 쪽과 같은 종류이나 스코프가 전역이다.

전역 vs 프로젝트 차이

---

두 트리는 rules/, skills/, commands/, agents/, workflows/, output-styles/ 를 똑같이 갖는다. 구조가 겹쳐 보이는 이유는 같은 확장 메커니즘을 두 스코프에서 재사용하기 때문이다. 차이는 무엇이 담기느냐가 아니라 어디에 적용되고 누구와 공유되느냐다.

• 적용 범위: 프로젝트 .claude/ 는 그 저장소에서만, 전역 ~/.claude/ 는 내 모든 프로젝트에서 적용된다.
• 공유 여부: 프로젝트 쪽은 git commit 해서 팀과 공유한다. 전역 쪽은 커밋되지 않는 개인 설정이다.
• 병합과 우선순위: 둘 다 있으면 합쳐 로드된다. 충돌 시 더 구체적인 프로젝트가 전역을 이긴다.
  • settings 우선순위는 settings.local.json > 프로젝트 settings.json > 전역 settings.json 순이다.
• 한쪽에만 있는 것: .mcp.json, .worktreeinclude, settings.local.json 은 프로젝트 개념이다.
  • keybindings.json, themes/, .claude.json, projects/<project>/memory/ 는 전역에만 있다.
• 메모리 구분: 프로젝트의 agent-memory/ 는 서브에이전트 메모리, 전역 projects/<project>/memory/ 는 메인 세션 메모리다. 이름이 비슷해도 주체가 다르다.

판단 기준은 하나다. 팀 전체가 따라야 하면 프로젝트에, 나 개인의 취향이면 전역에 둔다.

파일 예시

---

각 확장의 최소 형태다. 실제 동작을 결정하는 것은 frontmatter 와 본문이다.

CLAUDE.md (프로젝트 지침):

# 결제 API 서버
Spring Boot 기반 결제 API 다.
 
## 명령어
- 빌드: `./gradlew build`
- 테스트: `./gradlew test`
 
## 규칙
- 모든 public 메서드에 JavaDoc 을 단다.

rules/testing.md (경로 스코프 규칙):

---
paths:
  - "src/test/**"
  - "**/*Test.java"
---
- 테스트는 given / when / then 주석으로 구획한다.
- 목은 최소화하고 실제 구현을 우선 검증한다.

skills/security-review/SKILL.md (스킬 엔트리포인트):

---
name: security-review
description: 보안 취약점을 점검할 때 사용한다. SQL 인젝션, 인증 우회 등.
---
1. 변경된 파일의 입력 처리 지점을 나열한다.
2. checklist.md 항목을 하나씩 대조한다.
3. 위험도와 함께 결과를 보고한다.

commands/fix-issue.md (슬래시 명령):

---
description: 깃허브 이슈 번호를 받아 원인을 찾아 고친다.
---
이슈 #$ARGUMENTS 를 읽고, 원인을 찾은 뒤 수정 패치를 작성한다.

agents/code-reviewer.md (서브에이전트):

---
name: code-reviewer
description: 코드 리뷰만 수행한다. 수정은 하지 않는다.
tools: Read, Grep, Bash
model: sonnet
---
너는 코드 리뷰어다. 정확성 버그와 단순화 지점만 지적한다.

output-styles/teaching.md (출력 스타일):

---
name: teaching
description: 변경 이유를 덧붙여 설명하는 형식.
---
코드를 바꿀 때마다 왜 그렇게 했는지 한 줄로 설명한다.

settings.json (권한과 훅 등록. 훅은 폴더가 아니라 이 파일에 둔다):

{
  "permissions": { "allow": ["Bash(./gradlew test:*)"] },
  "hooks": {
    "PostToolUse": [
      { "matcher": "Edit", "hooks": [{ "type": "command", "command": ".claude/scripts/format.sh" }] }
    ]
  }
}

projects/<project>/memory/MEMORY.md (자동 메모리 인덱스. Claude 가 유지):

# Memory Index
- [배포 브랜치](deploy.md): 배포는 v5 브랜치에서만 동작한다.

References

---

• Claude Code Docs - Explore the .claude directory
• Claude Code Docs - Orchestrate subagents at scale with dynamic workflows
• Claude - Steering Claude Code: skills, hooks, rules, subagents and more
• ClaudeLog - What is .claude/rules/ in Claude Code