Claude Code 커스텀 슬래시 커맨드 만들기 — 나만의 개발 워크플로우

커스텀 슬래시 커맨드란?

Claude Code에는 /help나 /clear 같은 기본 슬래시 커맨드가 있지만, 자신만의 커맨드를 쉽게 추가할 수 있다는 사실을 아시나요? 커스텀 슬래시 커맨드는 자주 사용하는 프롬프트나 정형화된 작업을 짧은 키워드로 호출할 수 있게 해주는 기능으로, 잘 활용하면 일상적인 개발 속도를 극적으로 향상시킬 수 있습니다.

예를 들어 “현재 브랜치의 코드를 리뷰해 줘”라는 긴 프롬프트를 매번 입력하는 대신, /review만 입력하면 동일한 처리를 실행할 수 있습니다. 팀 전체에서 공유하면 리뷰 기준이나 릴리스 절차를 표준화할 수도 있습니다.

저장 위치와 파일 형식

커스텀 슬래시 커맨드는 단순한 Markdown 파일입니다. 저장 위치는 두 가지입니다.

• 프로젝트 전용: .claude/commands/<커맨드명>.md
• 사용자 전역: ~/.claude/commands/<커맨드명>.md

프로젝트 전용으로 두면 저장소에 포함해 팀과 공유할 수 있고, 사용자 전역에 두면 개인의 모든 프로젝트에서 사용할 수 있습니다. 파일명이 그대로 커맨드명이 되므로 review.md를 만들면 /review로 호출할 수 있습니다.

첫 커맨드 만들기

가장 단순한 커맨드부터 만들어 봅시다. 프로젝트 루트에서 다음을 실행하세요.

mkdir -p .claude/commands
cat > .claude/commands/review.md <<'EOF'
현재 Git 스테이징에 있는 변경 사항을 모두 읽어, 다음 관점에서
리뷰해 주세요.

- 버그 가능성
- 명명 일관성
- 테스트가 부족한 부분
- 보안상의 우려

문제를 발견하면 파일명과 줄 번호를 함께 보고해 주세요.
EOF

이것으로 끝입니다. Claude Code에서 /review라고 입력하면 파일 내용이 그대로 프롬프트로 전송됩니다.

인수 받기

커맨드를 더 실용적으로 만들려면 인수를 받을 수 있도록 합시다. Markdown 안에서 $ARGUMENTS 플레이스홀더를 사용하면, 호출 시 전달한 문자열이 그 위치에 삽입됩니다.

# .claude/commands/explain.md

다음 파일 또는 심볼을 초보자도 이해할 수 있도록 자세히 설명해 주세요.

대상: $ARGUMENTS

설명에는 다음을 포함해 주세요:
1. 코드가 무엇을 하는지 (1~2문장으로 요약)
2. 주요 줄의 단계별 해설
3. 실제 사용 예
4. 자주 빠지는 함정

이 커맨드는 /explain src/utils/parser.ts처럼 호출합니다. $ARGUMENTS가 src/utils/parser.ts로 치환되어 실행되는 구조입니다.

여러 파일을 참조하는 커맨드

인수로 파일 경로를 전달하는 것 외에, 커맨드 내부에서 @ 문법을 사용해 특정 파일을 명시적으로 로드할 수도 있습니다.

# .claude/commands/check-types.md

@tsconfig.json 과 @package.json 을 확인한 뒤,
프로젝트 전체의 타입 에러를 검출해 주세요.

순서:
1. `npx tsc --noEmit` 실행
2. 파일 단위로 에러를 그룹화
3. 수정 우선순위 제안
4. 영향 범위가 큰 것부터 정렬

출력은 표 형식으로 부탁드립니다.

커맨드 실행 시 Claude가 자동으로 tsconfig.json과 package.json을 읽은 후 작업을 시작합니다.

실전: 릴리스 준비 커맨드

정형화된 릴리스 작업을 한 커맨드로 묶는 예를 살펴봅시다.

# .claude/commands/release.md

버전 $ARGUMENTS 의 릴리스 준비를 진행해 주세요.

진행 단계:
1. package.json 의 version 을 $ARGUMENTS 로 갱신
2. CHANGELOG.md 최상단에 새 섹션 추가
   - 이전 태그 이후의 git log 를 참조
   - feat / fix / docs / chore 로 분류
3. `npm run test` 실행, 모든 테스트 통과 확인
4. `npm run build` 실행, 빌드 에러 없음 확인
5. 변경 내용 요약 및 커밋 메시지 초안 제시

주의: 실제 git push 나 npm publish 는 실행하지 마세요.
마지막 확인은 사용자에게 맡깁니다.

/release 1.4.0이라고 입력하기만 하면 버전 업데이트부터 테스트 실행까지 자동화됩니다. 안전을 위해 파괴적 작업은 수행하지 않고 사람이 최종 확인하도록 설계하는 것이 요령입니다.

플래그와 옵션 시뮬레이션

Markdown 측에 분기 로직을 기술하면 의사 플래그도 구현할 수 있습니다.

# .claude/commands/test.md

인수: $ARGUMENTS

아래 규칙에 따라 동작해 주세요:

- 인수가 비어 있는 경우: 모든 테스트 실행
- 인수에 `--unit` 이 포함된 경우: 유닛 테스트만 실행
- 인수에 `--e2e` 가 포함된 경우: E2E 테스트만 실행
- 인수에 파일 경로가 포함된 경우: 해당 파일과 관련된 테스트만 실행

실행 후 실패한 테스트가 있다면 원인을 분석해 주세요.

/test --unit이나 /test src/auth.ts처럼 유연한 호출이 가능해집니다.

팀 공유 베스트 프랙티스

프로젝트 전용 커맨드를 .claude/commands/에 두고 Git으로 관리하면, 팀 멤버 전원이 같은 커맨드를 사용할 수 있습니다. 그때는 다음을 염두에 두세요.

• 명명 규칙을 통일: 동사로 시작하는 짧은 이름(review, fix, explain)
• README에 목록 작성: 어떤 커맨드가 있는지 쉽게 찾을 수 있게
• 파괴적 작업 회피: git push --force나 rm -rf는 명시적으로 금지
• 출력 포맷 지정: 리뷰 결과 등은 표나 체크리스트로 통일

마치며

커스텀 슬래시 커맨드는 Claude Code를 “나만의 AI 어시스턴트”로 키우는 최단 경로입니다. 처음에는 간단한 커맨드 한두 개부터 시작해, 반복 작업을 발견할 때마다 추가해 나가면 어느새 손에서 놓을 수 없는 동반자가 될 것입니다.

Claude Code 기본 조작은 입문 가이드를, 고급 자동화는 Agent SDK 입문을, 컨텍스트 관리 팁은 컨텍스트 관리도 함께 참고하세요.

공식 문서는 Anthropic 공식 문서를 참조해 주세요.