Claude Code .claude 폴더 사용 가이드

Commands, Skills, Plugins로 AI 개발 워크플로우 자동화하기

---

.claude 폴더 구조

프로젝트 루트나 홈 디렉토리(~/.claude)에 다음과 같은 구조로 폴더를 만듭니다.

.claude/
├── commands/          # 슬래시 커맨드
├── skills/            # AI 스킬

---

Commands - 슬래시 커맨드

사용자가 직접 호출하는 커스텀 명령어

파일 위치

.claude/commands/커맨드명.md

커밋 메시지 생성기

파일: .claude/commands/commit.md

---
description: Git 커밋 메시지 자동 생성
---

현재 스테이징된 변경사항을 분석하여 명확한 커밋 메시지를 생성하세요.

형식:
- [타입] 제목 (50자 이내)
- 상세 설명 (필요시)

타입 예시: feat, fix, docs, refactor, test

사용 방법

/commit

파일명이 commit.md면 /commit 명령어로 사용!

---

Skills - AI가 자동으로 사용하는 기술

Claude가 작업 맥락을 보고 자동으로 활용하는 전문 지식
명시적 호출 없이 자동 발동됩니다.

파일 위치

.claude/skills/스킬명/SKILL.md

예제: 코드 리뷰 스킬

파일: .claude/skills/code-review/SKILL.md

---
description: 체계적인 코드 리뷰
---

# 코드 리뷰 스킬

코드 변경 시 자동으로 다음을 체크:

1. **버그 가능성**
   - null/undefined 체크
   - 예외 처리 누락

2. **성능 이슈**
   - 불필요한 반복문
   - 메모리 누수

3. **보안 취약점**
   - SQL Injection
   - XSS 가능성

4. **코딩 컨벤션**
   - 네이밍 규칙
   - 들여쓰기

사용 방법

자동 발동! 별도 명령어 불필요

---

Plugins - 재사용 가능한 패키지

Commands, Skills, Agents를 묶어 팀/프로젝트 간 공유

플러그인 구조

my-plugin/
├── .claude-plugin/
│   └── plugin.json       # 메타데이터
├── commands/
│   └── hello.md
├── skills/
│   └── review/
│       └── SKILL.md
├── agents/
│   └── helper.md
└── README.md

plugin.json 예제

{
  "name": "my-plugin",
  "description": "내 워크플로우 플러그인",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

플러그인 명령어

명령어 설명

claude --plugin-dir ./my-plugin	로컬 플러그인 테스트
/plugin marketplace add 조직명/저장소명	마켓플레이스 추가
/plugin install 플러그인명@마켓플레이스	플러그인 설치
/plugin	플러그인 관리 메뉴 (대화형)
/help	설치된 커맨드 확인

---

실전 사용 시나리오

시나리오 1: PR 리뷰 자동화

• Command: /pr-review
• Skill: code-quality (자동 발동)
• 결과: PR 생성 + 코드 품질 자동 체크

시나리오 2: API 문서 생성

• Command: /api-doc
• Skill: openapi-spec (자동 발동)
• 결과: OpenAPI 스펙 자동 생성

시나리오 3: 테스트 코드 작성

• Command: /test
• Skill: testing-best-practices (자동 발동)
• 결과: 테스트 케이스 자동 생성

---

주요 Claude Code 명령어

명령어 설명

/help	사용 가능한 모든 명령어 확인
/명령어명	커스텀 커맨드 실행
/plugin	플러그인 관리 메뉴
/plugin marketplace add	마켓플레이스 추가
/plugin install	플러그인 설치
/plugin list	설치된 플러그인 목록
/agents	에이전트 목록 확인
/hooks	훅 관리
claude --plugin-dir	로컬 플러그인 테스트

---

유용한 팁

Command vs Skill

• Command: 사용자가 명시적으로 /명령어 호출
• Skill: Claude가 맥락을 보고 자동 발동

파일명 규칙

• commit.md → /commit 명령어
• code-review/ 폴더 → Claude가 코드 리뷰 시 자동 사용

Frontmatter 필수

모든 .md 파일 상단에 메타데이터 작성:

---
description: 명령어 설명
---

로컬 테스트

배포 전 --plugin-dir로 충분히 테스트:

claude --plugin-dir ./my-plugin

공식 문서

• Claude Code 공식 문서: https://code.claude.com/docs
• 플러그인 가이드: https://code.claude.com/docs/en/plugins
• Skills 문서: https://code.claude.com/docs/en/skills