---
title: ".claude/ 폴더 완전 해부 — Claude Code를 제대로 길들이는 법"
published: 2026-03-27T14:35:45.000Z
canonical: https://jeff.news/article/1336
---
# .claude/ 폴더 완전 해부 — Claude Code를 제대로 길들이는 법

Claude Code의 .claude/ 폴더 내부 구조를 전부 파헤치는 글. CLAUDE.md, rules/, commands/, skills/, agents/, settings.json까지 각 파일과 폴더의 역할, 설정법, 실전 팁을 상세히 다룸.

Claude Code 쓰면서 `.claude/` 폴더 한 번도 안 열어본 사람 꽤 많을 텐데, 이 폴더 구조를 제대로 이해하면 Claude Code의 동작을 프로젝트에 맞게 완전히 커스터마이징할 수 있다는 이야기임.

## 두 개의 .claude 폴더

- `.claude/` 폴더는 사실 **두 군데**에 존재함. 프로젝트 루트의 `.claude/`는 팀 공유 설정이고, 홈 디렉토리의 `~/.claude/`는 개인 설정 + 세션 히스토리 저장소임
- 프로젝트 레벨 폴더는 git에 커밋해서 팀 전체가 동일한 규칙을 공유하는 게 핵심임

## CLAUDE.md — 가장 중요한 파일

- `CLAUDE.md`는 Claude Code가 세션 시작할 때 **제일 먼저** 읽어서 시스템 프롬프트에 넣는 파일임. 여기 적힌 건 세션 내내 따름
- "테스트 먼저 작성해", "console.log 대신 커스텀 로거 써" 같은 지시를 넣으면 진짜로 지킴
- 프로젝트 루트, `~/.claude/CLAUDE.md`(글로벌), 하위 디렉토리별로 각각 둘 수 있고, Claude는 이걸 전부 읽어서 합침

> [!IMPORTANT]
> CLAUDE.md는 **200줄 이하**로 유지할 것. 그 이상 길어지면 컨텍스트를 너무 많이 잡아먹어서 오히려 지시 준수율이 떨어진다는 거임.

- 넣어야 할 것: 빌드/테스트/린트 커맨드, 아키텍처 결정사항, 비자명한 gotcha, import 컨벤션, 폴더 구조
- 넣지 말아야 할 것: 린터/포매터가 이미 처리하는 것, 장문의 이론 설명, 링크로 대체 가능한 문서
- `CLAUDE.local.md`는 개인 전용 오버라이드 파일로, 자동으로 gitignore 처리됨. 팀 설정 건드리지 않고 개인 취향 반영할 때 씀

## rules/ 폴더 — CLAUDE.md가 커지면 이걸로 분리

- `.claude/rules/` 안의 모든 마크다운 파일이 `CLAUDE.md`와 함께 자동 로드됨
- `api-conventions.md`, `testing.md`, `database.md` 식으로 관심사별로 쪼개면 각 담당자가 자기 영역만 관리할 수 있음
- **경로 스코핑**이 진짜 강력함 — YAML frontmatter에 `paths`를 지정하면 해당 경로 파일 작업할 때만 로드됨. 예를 들어 `src/api/**` 스코프를 걸면 React 컴포넌트 수정할 때는 로드 안 됨

## commands/ 폴더 — 커스텀 슬래시 명령어

- `.claude/commands/`에 마크다운 파일을 넣으면 그대로 슬래시 커맨드가 됨. `review.md` → `/project:review`
- `` ` `` 백틱에 `!` 붙이면 셸 명령어 실행 결과를 프롬프트에 주입할 수 있음. 단순 저장 텍스트가 아니라 **동적 프롬프트**가 되는 거임
- `$ARGUMENTS`로 인자 전달도 가능 — `/project:fix-issue 234` 하면 이슈 234 내용을 자동으로 가져와서 프롬프트에 넣어줌
- 프로젝트 커맨드는 `.claude/commands/`에, 개인 커맨드는 `~/.claude/commands/`에 두면 `/user:command-name`으로 접근 가능

## skills/ 폴더 — 알아서 발동하는 워크플로우

- commands와 비슷하게 생겼지만 결정적 차이가 있음: **슬래시 커맨드 없이도 Claude가 대화 맥락 보고 알아서 발동**시킴
- `SKILL.md`에 YAML frontmatter로 설명을 적어두면, 대화 내용이 해당 설명과 매칭될 때 자동 호출됨
- commands는 단일 파일이지만 skills는 **폴더 단위 패키지** — 보조 문서 파일을 함께 번들링할 수 있음

## agents/ 폴더 — 전문 서브에이전트

- `.claude/agents/`에 마크다운으로 서브에이전트 페르소나를 정의할 수 있음. 각 에이전트는 별도 시스템 프롬프트, 사용 가능 도구, 모델 설정을 가짐
- 예를 들어 `code-reviewer.md`를 만들면 코드 리뷰 요청 시 **독립된 컨텍스트 윈도우**에서 작업하고 결과만 돌려줌. 메인 세션이 토큰으로 더러워지지 않음
- `tools` 필드로 에이전트가 할 수 있는 걸 제한함 — 보안 감사용 에이전트는 Read/Grep/Glob만 허용하고 Write는 막는 식
- `model` 필드로 저렴한 모델 지정 가능. 읽기 전용 탐색은 Haiku로 충분하고, Sonnet/Opus는 진짜 필요한 작업에만 쓰면 됨

## settings.json — 권한 관리

- `.claude/settings.json`에서 Claude가 뭘 할 수 있고 뭘 못 하는지 제어함
- **allow 리스트**: 확인 없이 바로 실행 가능한 명령어 (`npm run *`, `git *`, 파일 읽기/쓰기 등)
- **deny 리스트**: 무조건 차단 (`rm -rf`, `curl`, `.env` 접근 등)
- 둘 다 아닌 건 실행 전에 물어봄 — 이 중간 지대가 의도된 안전장치임
- `settings.local.json`은 개인용 권한 오버라이드. 자동 gitignore 처리됨

## 글로벌 ~/.claude/ 폴더

- `~/.claude/projects/`에 프로젝트별 세션 기록과 자동 메모리가 저장됨. Claude가 작업하면서 발견한 명령어, 패턴, 아키텍처 인사이트를 알아서 기록함
- Claude가 "알려준 적 없는 걸 기억하는" 것처럼 보이면 여기 저장된 자동 메모리 때문임. `/memory`로 확인·수정 가능

> [!TIP]
> 처음 시작할 때 권장 순서: `/init`으로 CLAUDE.md 생성 → settings.json에 allow/deny 설정 → 자주 쓰는 워크플로우를 commands로 만들기 → CLAUDE.md가 커지면 rules/로 분리 → 개인 취향은 ~/.claude/CLAUDE.md에

- 결국 `.claude/` 폴더는 "나는 누구고, 이 프로젝트는 뭐고, 어떤 규칙을 따라야 하는지"를 Claude에게 알려주는 프로토콜임. 이걸 명확하게 정의할수록 Claude를 교정하는 시간은 줄고 실제 작업 시간은 늘어남

## 핵심 포인트

- .claude/ 폴더는 프로젝트 레벨과 홈 디렉토리 레벨 두 군데 존재하며 각각 팀 공유/개인 설정 용도
- CLAUDE.md가 가장 중요한 파일로, 200줄 이하로 유지해야 지시 준수율이 떨어지지 않음
- rules/ 폴더로 지시사항을 관심사별로 분리하고 경로 스코핑으로 특정 디렉토리에서만 활성화 가능
- commands는 사용자가 직접 호출하는 슬래시 명령어, skills는 대화 맥락에 따라 Claude가 자동 발동하는 워크플로우
- agents/ 폴더로 전문 서브에이전트를 정의해 독립 컨텍스트에서 작업하게 할 수 있음

## 인사이트

대부분 CLAUDE.md 하나만 대충 쓰고 마는데, rules 경로 스코핑이나 skills 자동 발동 같은 기능을 활용하면 팀 단위 AI 코딩 워크플로우를 체계적으로 관리할 수 있음.