Claude Code를 매일 사용하다 보면, 반드시 이런 순간이 있습니다.

• "이 커밋 메시지, 평소 포맷으로 작성해줘"를 매번 직접 타이핑하고 있다
• 리뷰 요청 프롬프트가 길어서, 과거 채팅에서 복사해서 찾고 있다
• PR(Pull Request) 설명문을 생성하라는 지시가 사람마다 미묘하게 달라 출력이 흔들린다
• "테스트 작성해줘"라고 말할 때마다, 매번 "정상계와 이상계를 나누고, 모크(Mock)는 사용하지 말고..."라며 전제 조건을 다시 쓰고 있다

이것은 전부 같은 프롬프트를 매번 손으로 쓰고 있는 낭비입니다.

똑똑한 모델을 사용하더라도 입력이 매번 흔들리면 출력도 흔들립니다. 그리고 무엇보다, 같은 내용을 매일 계속 타이핑하는 것은 단순한 시간 낭비입니다.

이를 해결하는 것이 바로 **커스텀 슬래시 명령어(Custom Slash Commands)**입니다. .claude/commands/에 Markdown 파일을 하나 두는 것만으로, /명령어이름이라는 자체 제작 명령어가 탄생합니다. 자주 사용하는 프롬프트를 "명령어화"하여, 명령어 하나로 호출할 수 있게 만드는 기능입니다.

이 기사에서는 슬래시 명령어를 "어렴풋이 알고 있는" 상태에서 "반복 작업을 실제로 없앨 수 있는" 상태까지 이끌어 드립니다. 만드는 법, 인자(Arguments), 실례, 운용 팁까지 모두 복사해서 오늘부터 바로 시도해 볼 수 있습니다.

어렵게 생각할 필요는 없습니다. 커스텀 슬래시 명령어의 실체는 프롬프트를 작성한 Markdown 파일입니다.

위치는 두 군데가 있습니다.

파일명이 그대로 명령어 이름이 됩니다. .claude/commands/review.md를 만들면 /review가, commit.md를 만들면 /commit을 사용할 수 있게 됩니다.

먼저 최소한의 예시를 만들어 보겠습니다.

mkdir -p .claude/commands

.claude/commands/commit.md:

현재 스테이징된 변경 내용을 확인하고, Conventional Commits 형식으로
커밋 메시지를 하나 제안해 주세요.
규칙:
...

이것뿐입니다. Claude Code의 채팅에서 /commit이라고 치면, 이 파일의 내용이 그대로 프롬프트로서 실행됩니다.

Before (매번 직접 타이핑):

"스테이징된 변경 사항을 보고, Conventional Commits 형식으로
커밋 메시지 써줘. 첫 줄은 72자 이내로 하고, 본문에는
왜 바꿨는지를 쓰고, 일본어로..."
...

After (명령어화):

/commit

타이핑량이 1/20 이하로 줄어들며, 게다가 매번 완전히 동일한 품질 기준으로 출력됩니다. 팀에서 .claude/commands/를 Git에 넣어두면, 모든 팀원의 커밋 메시지 포맷이 통일됩니다.

고정된 프롬프트만으로도 편리하지만, 진가는 인자(Arguments)를 전달할 수 있다는 점에 있습니다.

명령어 이름 뒤에 쓴 문자열은 $ARGUMENTS라는 변수에 통째로 들어갑니다.

.claude/commands/explain.md:

다음 코드 또는 개념을 초보자도 이해할 수 있도록 설명해 주세요.
전문 용어에는 반드시 한 마디의 보충 설명을 붙일 것.
대상: $ARGUMENTS

사용법:

/explain useEffect의 클린업 함수

$ARGUMENTS 부분이 "useEffect의 클린업 함수"로 교체되어 실행됩니다.

여러 개의 인자를 별도로 다루고 싶을 때는 $1, $2와 같이 위치로 받을 수 있습니다.

.claude/commands/rename.md:

프로젝트 전체에서 심볼 이름 `$1`을 `$2`로 리네임해 주세요.
절차:
1. 먼저 `$1`의 정의 위치와 모든 참조 위치를 grep으로 찾아낸다
...

사용법:

/rename getUserData fetchUserProfile

$1이 getUserData, $2가 fetchUserProfile이 됩니다.

전개됩니다. 인수의 의미가 고정되므로, "어느 쪽이 구버전이고 신버전이었지?"라고 매번 고민할 필요가 없습니다.

여기서부터가 슬래시 명령어 (Slash Command)를 정말로 효과적으로 만들기 위한 핵심 팁입니다.

명령어 파일은 단순한 정형 문구 저장소가 아닙니다. "이 작업을 수행할 때의 절차와 규칙"을 모두 기록한 실행 절차서로 설계하면, 매번 내리는 지시의 품질이 단번에 안정됩니다.

예시로, PR (Pull Request) 설명문을 생성하는 명령어를 "대충 만든 버전"과 "절차서 버전"으로 비교해 보겠습니다.

대충 만든 버전 (.claude/commands/pr.md):

이 브랜치의 변경 사항을 바탕으로 PR 설명문을 작성해줘.

이렇게 해도 작동은 하지만, 출력 결과가 매번 제각각입니다. 차이점(Diff)을 놓치기도 하고, 포맷도 일정하지 않습니다.

절차서 버전:

현재 브랜치와 main의 차이점으로부터 PR 설명문을 작성해 주세요.
## 절차
1. `git diff main...HEAD --stat`를 사용하여 변경된 파일의 전체상을 파악한다
...

/pr이라고 입력하기만 하면, 매번 이 절차와 포맷에 따라 PR 설명문이 나옵니다. 리뷰어 관점의 "동작 확인 체크리스트"까지 자동으로 포함되므로, PR의 품질 자체가 향상됩니다.

포인트는 세 가지입니다.

• 절차(무엇을 읽을 것인가)를 작성한다 — Claude에게 "어떤 명령어로 정보를 수집할지"까지 지시하면 누락이 줄어듭니다.
• 출력 포맷을 고정한다 — 템플릿을 채우도록 하면 출력이 흔들리지 않습니다.
• 금지 사항을 작성한다 — "추측해서 쓰지 마라"와 같은 제약이 할루시네이션 (Hallucination)을 억제합니다.

복사해서 .claude/commands/에 바로 사용할 수 있는 것들을 나열합니다. 자신의 프로젝트에 맞춰 내용을 조정해 주세요.

.claude/commands/review.md:

스테이징된 변경 사항(없다면 working tree)을 셀프 리뷰해 주세요.
관점:
- 버그, 예외 처리 누락, null 체크 누락
...

.claude/commands/test.md:

$ARGUMENTS에 대한 테스트를 작성해 주세요.
전제 (매번 이를 따름):
- 정상 케이스, 경계값, 이상 케이스를 반드시 구분하여 작성할 것
...

사용법: /test src/utils/parseDate.ts

.claude/commands/doc.md:

$ARGUMENTS에 대해 문서 주석 (JSDoc / docstring 등, 언어에 맞출 것)을 추가해 주세요.
- 인수, 반환값, 발생 가능한 예외를 명시할 것
...

.claude/commands/refactor.md:

$ARGUMENTS를 리팩터링(Refactoring)해 주세요.
철칙:
- 외부에서 보이는 동작은 바꾸지 말 것 (입출력 및 공개 API 유지)
...

.claude/commands/onboard.md:

이 프로젝트의 전체상을 파악하고 다음 내용을 보고해 주세요.
1. 어떤 프로젝트인가 (README / package.json 등을 통해 파악)
2. 주요 디렉터리 구성과 각 역할
...

새로운 리포지토리(Repository)를 연 직후나 세션을 재개할 때 /onboard를 입력하면, 매번 동일한 관점으로 프로젝트를 파악할 수 있습니다.

명령어가 늘어나면 목록이 어지러워집니다. .claude/commands/ 아래에 폴더를 만들면 명령어 이름에 네임스페이스 (Namespace)가 붙습니다.

.claude/commands/
├── git/
│   ├── commit.md → /git:commit
...

git/commit.md는 /git:commit으로 호출할 수 있습니다. 종류별로 폴더를 나누어 두면 자동 완성 후보를 보기 편하고, 팀과 공유했을 때 "어디에 무엇이 있는지" 한눈에 알 수 있습니다.

"재사용 가능한 스킬 파일"이라는 한 단계 더 나아간 메커니즘도 있습니다. 두 방식은 비슷하지만 적합한 용도가 다릅니다.

요약하자면,

• 매번 직접 호출하고 싶은 정형 작업 $\rightarrow$ 슬래시 명령어
• 작업 방식 그 자체(방법론)를 재사용하고 싶을 때 $\rightarrow$ 스킬 파일

이렇게 구분됩니다. 우선 슬래시 명령어부터 시작해서, "같은 절차를 몇 번이고 명령어로 쓰고 있다"라고 느껴질 때 그 절차를 스킬 파일로 분리하는 순서가 현실적입니다.

명령어는 만드는 것으로 끝나지 않습니다. 실제로 "계속 사용되는" 상태로 만들기 위한 팁을 정리합니다.

처음부터 완벽한 명령어 모음을 만들려고 하면 좌절하게 됩니다. 같은 프롬프트를 두 번 직접 쓰는 순간이 바로 명령어화의 신호입니다. "이거 전에도 썼는데"라고 생각되면 파일로 만드세요. 이것만으로도 자연스럽게 필요한 명령어만 갖춰지게 됩니다.

하나의 명령어에 "테스트 작성하고, 문서도 쓰고, 커밋도 해"라고 몰아넣으면 매번 결과가 부실해질 수 있습니다. /test, /doc, /commit과 같이 나누어 필요한 것을 순서대로 입력하는 편이 결과가 더 안정적입니다.

앞서 언급했듯이, 템플릿을 채우는 방식으로 만들면 출력이 흔들리지 않습니다. "불렛 포인트로", "이 헤더를 사용하여", "마지막에 체크리스트를" 등 출력 형식을 명시하는 것이 효과가 큽니다.

프로젝트용 명령어는 리포지토리(Repository)에 커밋할 수 있습니다. 팀원 모두가 동일한 /review, /pr을 사용하면 리뷰 관점과 PR 형식도 자동으로 통일됩니다. 명령어 모음 = 팀 작업 표준의 코드화입니다.

너무 늘리면 스스로도 무엇이 있는지 파악할 수 없게 됩니다. 한 달 동안 사용하지 않은 명령어는 삭제하세요. 명령어 모음은 "자산"이 아니라 "자주 쓰는 도구함"으로서 최소한으로 유지하는 것이 요령입니다.

커스텀 슬래시 명령어는 "매번 같은 프롬프트를 쓰는 낭비"를 구조적으로 제거하기 위한 기능입니다.

포인트는 명령어를 "정형문의 저장소"가 아니라 "실행 절차서"로서 작성하는 것입니다. 절차, 포맷, 제약 사항까지 기록된 명령어는 똑똑한 모델의 출력 편차를 억제하고 매번 안정적인 결과를 반환합니다.

우선 가장 자주 직접 입력하는 프롬프트(대부분의 사람은 /commit 또는 /review)를 파일 하나로 만드는 것부터 시작해 보세요. 타이핑 양과 출력 품질 모두 그날부터 달라질 것입니다.

본 기사의 내용을 실제 프로젝트에서 테스트하려면 토대가 되는 CLAUDE.md와 폴더 구조가 있으면 원활합니다. 제가 사용하는 스타터 구성을 무료로 공개하고 있습니다.

무료 스타터 (GitHub):

더 나아가 워크플로우나 서브 에이전트(Sub-agent) 설계를 "실행 가능한 스킬 파일"로 정리한 패키지도 준비되어 있습니다. 사용자의 환경에서 /명령어로 호출할 수 있는 형태입니다.

• 스타터 팩 (¥1,980): CLAUDE.md 템플릿 7종, Hooks, MCP 설정
  https://streamsolty.gumroad.com/l/gliwz
• 워크플로우 OS (¥9,800): 79개의 스킬 + 워크플로우 3개 + 프롬프트 10종

우선 무료 리포지토리부터 시도해 보시고, 더 체계적으로 사용하고 싶을 때 검토해 주셔도 충분합니다. 기사의 내용만으로도 효과는 나타날 것입니다.

최신 팁은 X에서도 발신하고 있습니다: @k___n___t_1125