Claude Code에 나만의 슬래시 커맨드 정의하기

매번 같은 프롬프트를 복붙하고 있다면, 그 흐름을 파일 하나로 정리해둘 수 있어요. .claude/commands 폴더 안에 .md 파일을 만들면 Claude Code가 그걸 슬래시 커맨드로 인식해요. 실밸개발자 채널 강의에서 이 구조를 직접 데모로 보여줬는데, 진짜 간단해서 한 번 만들어두면 계속 쓰게 되더라고요.

예를 들어 PR 설명 초안 작성, 코드 리뷰 체크리스트 실행, 커밋 메시지 생성 같은 작업은 매번 프롬프트를 새로 쓰기엔 너무 반복적이에요. 이런 걸 커맨드 파일로 만들어두면 /pr-draft 한 줄로 끝나요.

준비물

• Claude Code 설치된 환경 (최신 버전 권장)
• 터미널 또는 VS Code 통합 터미널
• 슬래시 커맨드로 만들고 싶은 반복 작업 하나

스텝

1. .claude/commands 폴더 만들기

프로젝트 루트에 폴더가 없으면 새로 만들어요. 이 폴더가 Claude Code가 커맨드 파일을 찾는 기준 위치예요.

mkdir -p .claude/commands

2. 커맨드 파일 작성하기

파일 이름이 곧 슬래시 커맨드 이름이 돼요. pr-draft.md로 만들면 /pr-draft로 호출할 수 있어요. 파일 안에는 Claude에게 전달할 프롬프트를 그대로 적으면 돼요.

touch .claude/commands/pr-draft.md

현재 스테이징된 변경사항을 기반으로 PR 설명을 작성해줘.

형식은 다음과 같이:
- 제목: 변경 내용을 한 줄로 요약
- 배경: 왜 이 변경이 필요했는지
- 변경 내용: 주요 수정 사항 목록
- 테스트 방법: 검증 방법 간단히

한국어로 작성하고, 기술적인 내용은 구체적으로 써줘.

3. Claude Code에서 호출하기

Claude Code 채팅창에서 /를 입력하면 등록된 커맨드 목록이 자동완성으로 뜨는 걸 확인할 수 있어요. 파일 이름 그대로 나와요.

/pr-draft

확인 방법

Claude Code 채팅창에 /만 입력해보세요. 자동완성 목록에 pr-draft가 보이면 정상적으로 등록된 거예요. 선택하면 .md 파일 내용이 프롬프트로 그대로 전달돼요.

응용

커맨드 파일 안에서 $ARGUMENTS 변수를 쓰면 호출할 때 인자를 넘길 수 있어요. 예를 들어 /review backend/auth.ts처럼 파일 경로를 넘기고 싶을 때 유용해요.

다음 파일을 코드 리뷰해줘: $ARGUMENTS

체크 항목:
- 엣지 케이스 처리 여부
- 에러 핸들링 패턴
- 네이밍 컨벤션

팀 프로젝트라면 .claude/commands 폴더를 git에 올려두면 팀원 모두가 같은 커맨드를 쓸 수 있어요. 온보딩할 때도 꽤 편해요.

트러블슈팅

슬래시 커맨드 목록에 안 뜰 때: 폴더 위치가 프로젝트 루트의 .claude/commands인지 확인해요. 홈 디렉토리에 만들면 안 돼요.

파일 수정 후 반영이 안 될 때: Claude Code를 재시작하거나 채팅 세션을 새로 열면 돼요. 실시간 감지가 안 되는 경우가 있어요.

파일 이름에 공백 넣으면: 커맨드 이름에 공백이 들어가서 호출이 어려워져요. kebab-case로 쓰는 게 안전해요.

커맨드 파일 몇 개만 만들어두면 Claude Code 쓰는 방식이 꽤 달라져요. 이 설정으로 반복 작업을 파일 단위로 관리할 수 있게 돼요.