Claude Code의 커스텀 슬래시 명령어로 개발 루틴 자동화하기

서론

Claude Code를 사용하다 보면 매번 똑같은 프롬프트를 입력하고 있다는 사실을 깨닫게 됩니다.

• "git diff를 보고 PR의 제목과 본문을 작성해줘"
• "git status를 보고 커밋되지 않은 파일을 푸시해줘"

이것을 커스텀 슬래시 명령어 (Custom Slash Command)로 등록해 두면 한 번에 호출할 수 있습니다.

이 기사에서는 .claude/commands/에 파일을 두는 것만으로 만들 수 있는 Claude Code의 커스텀 명령어 기능을 실제 사례와 함께 소개합니다.

커스텀 슬래시 명령어란

Claude Code에는 /help나 /clear와 같은 내장 명령어가 있지만, 직접 추가할 수도 있습니다.

방법은 간단합니다. 프로젝트의 .claude/commands/ 디렉토리에 Markdown 파일을 두기만 하면 됩니다.

프로젝트 루트/
└── .claude/
└── commands/
...

파일명이 그대로 명령어 이름이 됩니다. Claude Code를 실행한 디렉토리의 .claude/commands/가 읽히기 때문에, 프로젝트마다 명령어를 구분해서 사용할 수도 있고, 루트에 집약하여 전체적으로 사용할 수도 있습니다.

/pr-description

실례 ①: git diff로부터 PR 문을 자동 생성하기
PR을 내기 전에 매번 "git diff를 읽고 적절하게 PR 문을 작성해줘"라고 입력하던 것을 명령어로 만들었습니다.

.claude/commands/pr-description.md

# /pr-description — PR 제목·본문 제너레이터
git의 차이 정보로부터 GitHub PR의 제목과 본문을 생성한다.
베이스 브랜치는 인수로 지정하며, 생략 시 main을 사용한다.
...
```bash
git branch --show-current
git log $BASE_BRANCH..HEAD --oneline
git diff --stat $BASE_BRANCH
git diff $BASE_BRANCH

STEP 2: PR 제목을 생성한다

다음 포맷으로 생성한다.

<type>: <변경 요약> (50자 이내)

type 선택 기준:

• feat : 신규 기능 추가
• fix : 버그 수정
  ...

## 개요
## 변경 내용
## 테스트 방법
## 관련 Issue
## 체크리스트

결과는 코드 블록으로 출력하여 그대로 GitHub에 복사할 수 있는 형태로 만든다.

사용법은 이것뿐입니다:

/pr-description # main과의 차이로 생성
/pr-description develop # develop과의 차이로 생성

### 포인트: 왜 잘 작동하는가

커스텀 명령어 안에서 `git diff $BASE_BRANCH`와 같이 **셸 명령어 (Shell Command)를 실행하라는 지시를 쓸 수 있습니다**. Claude Code는 bash 도구를 가지고 있기 때문에, 명령어 내의 지시에 따라 실제로 터미널 명령어를 실행하고 그 결과를 읽어 PR 문을 생성해 줍니다.

"차이(diff)를 전달한다"라는 절차를 매번 직접 할 필요가 없어진다는 점이 매우 큽니다.

## `/zenn`

실례 ②: Zenn 기사 관리 명령어
Zenn 기사의 백로그를 YAML 파일로 관리하고 있는데, 상태 업데이트 → git push까지를 명령어 한 번으로 만들었습니다.

/zenn # 기사 상태 목록 표시
/zenn done <slug> # 게시 완료 상태로 변경 후 push
/zenn review <slug> # draft → review로 승격 후 push
...

명령어 파일 안에서는 "`push.yml`을 읽어 상태를 표시한다", "`articles/` 하위에 add되지 않은 파일이 있으면 commit 하여 push한다"와 같은 절차를 일본어로 적어 두었습니다. Claude Code가 그대로 동작해 줍니다.

## 여러 리포지토리를 가로질러 사용하는 방법

저처럼 여러 리포지토리(학습용·기사용·로그용)를 하나의 워크스페이스에서 관리하는 경우, **워크스페이스 루트의 .claude/commands/에 집약하면 편리합니다**.

XXX/ ← 여기서 claude 실행
├── .claude/
│ └── commands/
...

각 명령어 안에서 `cd rdb-learning-postgres`와 같이 **조작 대상 디렉터리로의 이동을 명시**함으로써, 어떤 명령어가 어떤 리포지토리 (Repository)를 조작할지 제어할 수 있습니다.

## 명령어 파일을 작성하는 팁

실제로 사용해 보며 알게 된 점들을 정리합니다.

**절차를 번호로 작성하기**: Claude Code는 절차서대로 동작하므로, "STEP 1 → STEP 2 → STEP 3"와 같이 명확하게 작성하면 망설임 없이 동작합니다.

**인수는 $ARGUMENTS로 받기**: 명령어 실행 시 전달한 인수는 `$ARGUMENTS`로 참조할 수 있습니다. `/zenn done my-article`라고 입력하면 `$ARGUMENTS`는 `done my-article`이 됩니다.

**"무엇을 하지 않을지"도 작성하기**: 예를 들어 `articles/`와 `push.yml` 이외에는 커밋 (Commit) 대상에 포함하지 않는 것과 같이 제약 사항을 명시하면 오작동을 방지할 수 있습니다.

**일본어(또는 한국어)로 작성해도 OK**: 영어가 아니어도 문제없이 동작합니다. 가독성을 우선하여 작성하세요.

## 요약

Claude Code의 커스텀 슬래시 명령어 (Slash Command)는 `.claude/commands/`에 마크다운 (Markdown) 파일을 두는 것만으로 만들 수 있습니다.

매번 같은 프롬프트 (Prompt)를 입력하고 있는 작업을 발견했다면, 그것이 명령어화할 신호입니다. PR 문 생성, git push, 백로그 (Backlog) 업데이트 등 루틴 작업을 명령어로 구현하면, Claude Code가 워크플로 (Workflow)의 일부로서 자연스럽게 통합됩니다.

꼭 자신의 프로젝트에 맞춰 커스터마이징해 보세요.

## 관련 리포지토리

### Discussion

![](https://static.zenn.studio/images/drawing/discussion.png)