[Claude Code] .claude 폴더 구조와 슬래시 명령어 완전 정복

 

AI 코딩 도구를 쓰다 보면 똑같은 요청을 반복하게 된다. "항상 한국어로 답해", "이 프로젝트는 TypeScript 5 기준으로 코딩해", "코드 리뷰할 때 보안 취약점도 봐줘" — 매번 새 세션마다 설명해야 한다면 효율이 반 토막이다.

Claude Code는 .claude/ 폴더 하나로 이 문제를 해결한다. 프로젝트별 지시사항, 권한, 슬래시 명령어, 스킬, 에이전트를 파일로 관리하고, 세션을 열 때 자동으로 로드된다.

 

Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 어시스턴트다. 단순한 코드 자동완성을 넘어 파일 읽기, 쓰기, 명령어 실행, 웹 검색, 외부 MCP 서버 연동까지 지원한다. 핵심은 .claude/ 폴더 구조를 이해하는 것이다 — 이 폴더 하나가 Claude의 행동 방식 전체를 결정한다.

 

전체 폴더 구조

 

.claude/ 폴더는 프로젝트 수준과 글로벌 수준 두 곳에 존재한다. 프로젝트 폴더는 Git에 커밋해 팀원과 공유하고, 글로벌 폴더(~/.claude/)는 모든 프로젝트에 공통 적용되는 개인 설정이다.

my-project/
├── CLAUDE.md                  # 팀 공유 지시사항 (필수)
├── CLAUDE.local.md            # 개인 설정 (gitignored)
└── .claude/
    ├── settings.json          # 도구 권한 및 설정
    ├── settings.local.json    # 로컬 권한 오버라이드 (gitignored)
    ├── commands/              # 커스텀 슬래시 명령어
    ├── rules/                  # 모듈식 지시사항 분리
    ├── skills/                 # 재사용 가능한 워크플로우
    └── agents/                 # 전문화된 서브에이전트

~/.claude/                     # 글로벌 개인 설정
├── CLAUDE.md                  # 전체 프로젝트 공통 지시사항
├── commands/                  # 개인 커스텀 명령어
├── skills/                    # 개인 스킬 (모든 프로젝트 적용)
└── agents/                    # 개인 에이전트

 

1단계: 핵심 파일 — CLAUDE.md 와 settings.json

 

세션을 시작하면 Claude가 가장 먼저 읽는 파일이 CLAUDE.md다. 시스템 프롬프트로 직접 로드되므로 여기 쓴 지시사항은 매번 자동으로 적용된다. 200줄 이하로 유지하는 것이 권장된다 — 파일이 길어질수록 Claude의 지시사항 준수율이 실제로 떨어진다.

# CLAUDE.md 예시

## 프로젝트 개요
Next.js 14 + TypeScript 5 기반 이커머스 플랫폼

## 빌드 & 테스트
npm run build       # 빌드
npm run test        # 전체 테스트
npm run lint        # ESLint 검사

## 코딩 규칙
- 모든 응답은 한국어로
- 함수형 컴포넌트 + React hooks 사용
- any 타입 사용 금지
- 에러 처리는 try/catch + 로깅 필수

 

settings.json은 Claude가 실행할 수 있는 도구와 명령어 권한을 제어한다. allow 목록은 승인 없이 자동 실행되고, deny 목록은 완전히 차단된다. 목록에 없으면 실행 전에 Claude가 사용자에게 확인을 구한다.

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Read",
      "Write",
      "Edit"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Read(./.env)"
    ]
  }
}

 

2단계: rules/, commands/, skills/, agents/ 폴더 상세

 

각 하위 폴더의 역할과 차이를 정확히 이해해야 효율적으로 활용할 수 있다.

 

폴더	역할	로드 시점	특징
rules/	모듈식 지시사항 분리	세션 시작 또는 파일 접근 시	경로 스코핑으로 특정 파일에만 적용 가능
commands/	커스텀 슬래시 명령어	/명령어 입력 시	마크다운 파일 하나 = 슬래시 명령어 하나
skills/	재사용 가능한 워크플로우	/명령어 입력 또는 자동 감지	폴더 단위 패키지, 지원 파일 포함 가능
agents/	전문화된 서브에이전트	위임 시	독립 컨텍스트, 도구·모델 별도 지정 가능

 

rules/ — CLAUDE.md 가 200줄을 넘으면 분리한다

경로 스코핑 기능이 핵심이다. 프론트매터에 paths를 지정하면 해당 경로의 파일을 건드릴 때만 규칙이 로드된다 — 불필요한 컨텍스트 소모를 막는다.

---
# .claude/rules/database.md
paths:
  - "src/db/**/*.ts"
  - "**/migrations/**"
---
## DB 규칙
- ORM 없이 raw SQL 사용 금지
- 마이그레이션은 반드시 롤백 스크립트 포함

 

commands/ — 파일명이 곧 슬래시 명령어 이름이 된다

review-pr.md를 만들면 /project:review-pr로 호출된다. $ARGUMENTS 변수로 인자를 전달받는다.

---
# .claude/commands/review-pr.md
description: PR 코드 리뷰 실행
argument-hint: [PR번호]
---
!`git diff main...HEAD`

PR #$ARGUMENTS 를 다음 기준으로 검토해줘:
1. 보안 취약점 (SQL 인젝션, XSS 등)
2. 성능 문제 (N+1 쿼리, 불필요한 렌더링)
3. 타입 안전성

 

skills/ — commands보다 강력한 패키지 단위 워크플로우

폴더 안에 SKILL.md가 있어야 하며, 지원 파일(스크립트, 참조 문서 등)을 함께 포함할 수 있다. description에 자동 호출 조건을 쓰면 Claude가 상황에 맞게 스스로 실행한다.

.claude/skills/security-review/
├── SKILL.md          # 스킬 진입점
└── checklist.md      # 참조 체크리스트

---
# SKILL.md 프론트매터
name: security-review
description: 보안 감사. 코드 리뷰, 배포 전, 보안 언급 시 자동 사용
allowed-tools: Read, Grep, Glob
---
@checklist.md 기준으로 전체 보안 감사를 수행해줘.

 

agents/ — 독립 컨텍스트에서 실행되는 전문가 페르소나

별도의 컨텍스트 창에서 실행되어 결과만 보고한다. 무거운 분석 작업을 메인 세션에 영향 없이 위임할 때 쓴다. 모델도 별도 지정할 수 있어 — 읽기 전용 작업엔 Haiku, 복잡한 리팩토링엔 Sonnet 식으로 최적화한다.

---
# .claude/agents/code-reviewer.md
name: code-reviewer
description: PR 검토 요청 시 사용. 버그·보안 중심 리뷰
model: claude-sonnet-4-6
tools: Read, Grep, Glob
---
당신은 수석 코드 리뷰어다.
검토 시 반드시 아래를 확인한다:
- 버그 및 엣지 케이스 누락
- 보안 취약점 (OWASP Top 10 기준)
- 구체적인 개선안을 코드로 제시

 

3단계: 슬래시 명령어 전체 목록

 

Claude Code는 60개 이상의 슬래시 명령어를 제공한다. 터미널에서 /만 입력하면 전체 목록을 확인할 수 있고, 이름 일부를 입력하면 필터링된다.

claude   # Claude Code 실행 (대화형 모드 진입)
/        # 전체 명령어 목록 보기
/help    # 도움말

 

카테고리	명령어	기능
세션 관리	/clear	대화 기록 완전 초기화 (새 세션 시작)
	/compact	오래된 컨텍스트 요약 압축 (토큰 절약)
	/fork	현재 지점에서 대화 포크 생성
	/resume	이전 세션 ID로 재개
	/rename	세션에 이름 지정
모델 & 성능	/model	Opus / Sonnet / Haiku 모델 전환
	/effort	처리 수준 설정 (low / medium / high / max)
	/fast	빠른 모드 토글 (Opus Fast)
코드 품질	/review	최근 변경사항 코드 리뷰 실행
	/security-review	보안 취약점 분석
	/diff	변경사항 대화형 뷰어
	/simplify	최근 파일 코드 품질 검토 및 정리
컨텍스트 & 비용	/context	현재 컨텍스트 사용량 시각화
	/cost	세션 토큰 사용량 및 비용 확인
	/usage	요금제 한도 및 속도 제한 현황
설정 & 구성	/init	프로젝트 CLAUDE.md 자동 생성
	/config	설정 인터페이스 열기
	/theme	색상 테마 변경
	/vim	Vim 편집 모드 토글
통합 & 확장	/mcp	MCP 서버 관리
	/plugin	플러그인 설치 및 관리
	/skills	사용 가능한 스킬 목록 확인
진단 & 정보	/doctor	환경 및 설정 문제 진단
	/status	버전, 모델, 계정 정보 표시
자동화	/batch	병렬 에이전트로 대규모 변경 수행
	/loop	반복 프롬프트 실행 (정기 작업)
	/voice	음성 입력 모드 (20개 이상 언어)

 

적용 전후 비교

 

Before:

# 매 세션마다 수동 입력
"이 프로젝트는 TypeScript 5야. 한국어로 답해줘.
 함수형 컴포넌트만 써. any 타입은 금지야.
 코드 리뷰 시 보안 취약점도 확인해줘..."
# + 코드 리뷰할 때마다 기준 재설명

 

After:

# CLAUDE.md에 한 번 작성 → 세션마다 자동 적용
# 반복 작업은 커스텀 슬래시 명령어로 실행
/project:review-pr 142   # PR #142 자동 리뷰
/project:security-check  # 보안 감사 실행
/compact                 # 토큰 압축
/cost                    # 비용 확인

 

.claude/ 폴더를 구성하면 반복 설명이 사라지고 명령어 하나로 복잡한 워크플로우가 실행된다.

 

기대 효과

 

1. 세션마다 설명 반복 제거

CLAUDE.md에 한 번 작성하면 이후 모든 세션에서 자동 적용된다. 팀원이 같은 폴더를 Git으로 공유하면 전체 팀이 동일한 AI 행동을 보장받는다.

 

2. 복잡한 워크플로우를 명령어 하나로

PR 리뷰, 보안 감사, 배포 전 체크리스트 같은 다단계 작업을 커스텀 슬래시 명령어나 스킬로 패키징하면 /project:review-pr 142 한 줄로 실행된다.

 

3. 컨텍스트 최적화로 비용 절감

rules/의 경로 스코핑으로 필요한 규칙만 로드하고, skills/는 호출 시에만 컨텍스트를 소비한다. /compact와 /cost 명령어로 사용량을 실시간 모니터링할 수 있다.

 

4. 전문화된 에이전트로 병렬 처리

agents/에 정의된 서브에이전트는 독립 컨텍스트에서 실행된다. 코드 리뷰, 문서화, 테스트 생성을 동시에 여러 에이전트에 위임하면 메인 세션 흐름을 끊지 않고 복잡한 작업을 병렬로 처리한다.

 

참고 자료:

https://codewithmukesh.com/blog/anatomy-of-the-claude-folder/

https://blog.dailydoseofds.com/p/anatomy-of-the-claude-folder

https://www.gradually.ai/en/claude-code-commands/

https://dev.to/numbpill3d/the-complete-claude-code-power-user-guide-slash-commands-hooks-skills-more-6ep