Claude Code 커스텀 슬래시 명령어 작성 베스트 프랙티스 완벽 가이드
Claude Code 커스텀 슬래시 명령어로 개발 워크플로우 자동화하기
Claude Code는 AI 기반 터미널 코딩 도우미로, 커스텀 슬래시 명령어를 통해 반복적인 개발 작업을 자동화할 수 있습니다. 이 가이드에서는 Bash 스크립트, 프롬프트 템플릿, 프로젝트별 워크플로우, 팀 공유 명령어 라이브러리를 활용한 실전 베스트 프랙티스를 다룹니다.
커스텀 슬래시 명령어의 구조 이해
Claude Code의 슬래시 명령어는 .claude/commands/ 디렉토리에 Markdown 파일로 정의됩니다. 프로젝트 레벨과 사용자 레벨 두 가지 범위로 관리할 수 있습니다.
디렉토리 구조
프로젝트 명령어 (팀 공유):
.claude/commands/
├── review.md
├── test-gen.md
└── deploy-check.md
사용자 개인 명령어:
~/.claude/commands/
├── my-snippet.md
└── daily-standup.md
1단계: 기본 슬래시 명령어 생성
가장 간단한 형태의 커스텀 명령어를 만들어 봅시다.
코드 리뷰 명령어
.claude/commands/review.md 파일을 생성합니다:
현재 Git 스테이징된 변경사항을 분석하고 다음 기준으로 코드 리뷰를 수행해주세요:
- 보안 취약점 (OWASP Top 10 기준)
- 성능 문제 및 최적화 기회
- 코드 스타일 일관성
- 테스트 커버리지 누락 여부
각 항목에 대해 심각도(높음/중간/낮음)를 표시하고 구체적인 수정 제안을 포함해주세요.
이제 Claude Code 터미널에서 /review를 입력하면 이 명령어가 실행됩니다.
2단계: 동적 변수를 활용한 프롬프트 템플릿
슬래시 명령어에서 $ARGUMENTS 변수를 사용하면 실행 시 동적으로 값을 전달할 수 있습니다.
컴포넌트 생성 명령어
.claude/commands/component.md 파일:
다음 이름으로 React 컴포넌트를 생성해주세요: $ARGUMENTS
규칙:
- TypeScript 사용
- 함수형 컴포넌트로 작성
- Props 인터페이스 별도 정의
- 기본 단위 테스트 파일 함께 생성
- Storybook 스토리 파일 생성
src/components/ 디렉토리에 배치사용법:
/component UserProfileCard
API 엔드포인트 생성 명령어
.claude/commands/api-endpoint.md 파일:
다음 사양으로 REST API 엔드포인트를 생성해주세요: $ARGUMENTS
포함 사항:
- Express.js 라우터 핸들러
- 입력 유효성 검사 (zod 스키마)
- 에러 핸들링 미들웨어 적용
- JSDoc 주석
통합 테스트 파일
3단계: Bash 스크립트와 연동하기
Claude Code 명령어에서 Bash 스크립트 실행 결과를 활용하는 고급 패턴입니다.
배포 전 체크리스트 명령어
.claude/commands/deploy-check.md 파일:
배포 전 점검을 수행해주세요.
다음 명령어들을 순서대로 실행하고 결과를 분석해주세요:
git status로 커밋되지 않은 변경사항 확인npm run lint로 린트 오류 확인npm run test -- --coverage로 테스트 통과 및 커버리지 확인npm run build로 빌드 성공 여부 확인git log --oneline -5로 최근 커밋 이력 확인
모든 항목이 통과하면 배포 준비 완료 보고서를 작성하고,
실패 항목이 있으면 수정 방법을 제안해주세요.
데이터베이스 마이그레이션 검증 명령어
.claude/commands/db-migrate.md 파일:
데이터베이스 마이그레이션을 검증해주세요: $ARGUMENTS
절차:
npx prisma migrate diff로 스키마 변경사항 확인- 마이그레이션 SQL이 안전한지 검토 (데이터 손실 가능성 확인)
- 롤백 전략 제안
대용량 테이블에 대한 성능 영향 분석
4단계: 팀 공유 명령어 라이브러리 구축
프로젝트 루트의 .claude/commands/에 명령어를 저장하면 Git을 통해 팀 전체가 공유할 수 있습니다.
권장 팀 명령어 세트
| 명령어 파일 | 용도 | 실행 예시 |
|---|---|---|
review.md | 코드 리뷰 자동화 | /review |
component.md | 컴포넌트 스캐폴딩 | /component Button |
test-gen.md | 테스트 코드 생성 | /test-gen src/utils/parser.ts |
doc.md | 문서 자동 생성 | /doc src/api/ |
refactor.md | 리팩토링 제안 | /refactor 성능 최적화 |
bug-hunt.md | 버그 탐색 및 분석 | /bug-hunt 로그인 오류 |
.claude/commands/test-gen.md 파일:
다음 파일에 대한 테스트를 작성해주세요: $ARGUMENTS
테스트 규칙:
- Jest + Testing Library 사용
- 행복 경로(happy path)와 엣지 케이스 모두 포함
- 모킹은 외부 의존성에만 사용
- describe/it 블록으로 논리적 그룹화
- 테스트 파일은 tests/ 디렉토리에 배치
최소 80% 라인 커버리지 목표
5단계: CLAUDE.md와 연동한 프로젝트 워크플로우
프로젝트 루트의 CLAUDE.md 파일에 컨벤션을 정의하면 슬래시 명령어가 이를 자동으로 참조합니다.
# CLAUDE.md 예시
프로젝트 컨벤션
- 패키지 매니저: pnpm
- 테스트 프레임워크: Vitest
- 스타일: Tailwind CSS v4
- 상태관리: Zustand
- API: tRPC
코드 스타일
- 함수명: camelCase
- 컴포넌트: PascalCase
- 파일명: kebab-case
최대 파일 길이: 300줄이렇게 설정하면 모든 슬래시 명령어가 프로젝트 컨벤션을 준수하여 일관된 결과를 생성합니다.
Pro Tips: 파워 유저를 위한 고급 팁
- 명령어 체이닝: 슬래시 명령어 실행 후 추가 지시를 이어서 작성하면 결과를 정제할 수 있습니다. 예:
/review실행 후 “보안 항목만 자세히 설명해줘”- CLAUDE.md 계층화: 루트, 서브디렉토리 각각에 CLAUDE.md를 배치하면 디렉토리별 컨텍스트가 자동 적용됩니다.- 명령어 네이밍 규칙: 팀에서동사-목적어패턴(예:gen-test.md,check-deps.md)으로 통일하면 검색성이 향상됩니다.- 복잡한 워크플로우 분리: 하나의 명령어가 너무 길어지면 여러 단계로 분리하고, 각 단계를 별도 명령어로 만드세요.- 환경 변수 활용: 명령어에서$ARGUMENTS를 구조화하여/deploy staging verbose처럼 여러 인자를 전달할 수 있습니다.
Troubleshooting: 자주 발생하는 문제와 해결법
| 문제 | 원인 | 해결 방법 |
|---|---|---|
| 슬래시 명령어가 목록에 표시되지 않음 | 파일 경로 또는 확장자 오류 | .claude/commands/ 디렉토리에 .md 확장자로 저장되었는지 확인 |
$ARGUMENTS가 치환되지 않음 | 변수명 오타 | 정확히 $ARGUMENTS(대문자)로 작성했는지 확인 |
| 명령어 실행 시 컨텍스트 누락 | CLAUDE.md 미설정 | 프로젝트 루트에 CLAUDE.md를 생성하고 컨벤션을 명시 |
| 팀원에게 명령어가 공유되지 않음 | Git 미추적 | .claude/commands/ 디렉토리가 .gitignore에 포함되지 않았는지 확인 후 커밋 |
| 명령어 실행 결과가 일관되지 않음 | 프롬프트가 모호함 | 구체적인 규칙, 예시 출력 형식, 제약 조건을 명시 |
.claude/commands/pr-ready.md 파일:
PR 제출 준비를 도와주세요.
git diff main...HEAD --stat으로 변경 파일 목록 확인- 각 변경 파일의 주요 수정사항 요약
- 다음 형식으로 PR 설명 초안 작성:
-
변경 사항 요약
-
변경 동기
-
테스트 방법
-
체크리스트
-
- 커밋 메시지가 Conventional Commits 규칙을 따르는지 확인
누락된 테스트나 문서가 있으면 알려주세요
자주 묻는 질문 (FAQ)
Q1: 커스텀 슬래시 명령어와 CLAUDE.md의 차이점은 무엇인가요?
CLAUDE.md는 프로젝트의 전반적인 컨텍스트와 컨벤션을 정의하는 설정 파일로 모든 대화에 자동으로 적용됩니다. 반면 커스텀 슬래시 명령어는 특정 작업을 수행하기 위한 재사용 가능한 프롬프트 템플릿으로, 사용자가 명시적으로 호출할 때만 실행됩니다. 두 가지를 함께 사용하면 CLAUDE.md의 컨벤션을 준수하면서 슬래시 명령어로 특정 작업을 빠르게 자동화할 수 있습니다.
Q2: 팀 전체가 동일한 슬래시 명령어를 사용하도록 관리하려면 어떻게 해야 하나요?
프로젝트 루트의 .claude/commands/ 디렉토리에 명령어 파일을 저장하고 Git으로 버전 관리하세요. PR 리뷰 과정에서 명령어 변경사항도 함께 검토하고, README에 사용 가능한 명령어 목록과 용도를 문서화하면 팀 전체의 일관성을 유지할 수 있습니다. 개인용 명령어는 ~/.claude/commands/에 별도 관리합니다.
Q3: 슬래시 명령어에서 외부 API를 호출하거나 복잡한 스크립트를 실행할 수 있나요?
네, 슬래시 명령어 내에서 CLI 도구나 스크립트 실행을 지시할 수 있습니다. Claude Code가 해당 명령을 터미널에서 실행하며, 필요에 따라 사용자 승인을 요청합니다. 예를 들어 curl로 API 상태를 확인하거나, 프로젝트의 빌드 스크립트를 실행하는 등의 작업이 가능합니다. 다만 민감한 작업(삭제, 배포 등)은 항상 사용자 확인 단계를 포함하도록 명령어를 설계하는 것이 좋습니다.