Claude Code 슬래시 명령어 만들기 - 반복 작업을 한 줄로

Claude Code를 처음 쓸 땐 매번 비슷한 프롬프트를 복붙해서 던지곤 했습니다. "이 코드 리뷰해줘", "이 함수 테스트 작성해줘", "이 로그 표로 정리해줘"... 매일 반복하다 보니 결국 단축키가 그리워지더라고요. 그때 알게 된 게 슬래시 명령어(/command)입니다. 한 번 정의해두면 /review만 쳐도 알아서 동작해요. 오늘은 슬래시 명령어를 직접 만들고 활용하는 법을 정리해보겠습니다.

개념 / 원리

슬래시 명령어는 Claude Code에서 자주 쓰는 프롬프트나 워크플로를 재사용 가능한 명령어로 등록하는 기능입니다. 터미널에서 alias 만드는 거랑 비슷한 느낌이에요.

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

위치	경로	범위
프로젝트	.claude/commands/이름.md	해당 프로젝트에서만
전역	~/.claude/commands/이름.md	모든 프로젝트에서

파일 이름이 곧 명령어 이름이 됩니다. .claude/commands/review.md로 저장하면 /review로 호출됩니다.

명령어 파일은 그냥 마크다운이에요. 안에 적힌 내용이 그대로 프롬프트가 되어서 Claude에게 전달됩니다. 추가로 frontmatter에 메타정보를, 본문에 $ARGUMENTS 같은 변수를 쓸 수 있어요.

실전 예제

1. 가장 단순한 명령어 만들기

.claude/commands/today.md:

오늘 할 일을 다음 세 가지로 정리해서 알려줘.

1. 지금 가장 중요한 작업
2. 코드 리뷰 중인 PR
3. 막혀있는 이슈

이제 /today만 치면 Claude가 위 프롬프트를 받은 것처럼 응답합니다.

2. 인자 받기 ($ARGUMENTS)

.claude/commands/explain.md:

다음 코드를 신입 개발자에게 설명하듯이 한국어로 풀어줘.

$ARGUMENTS

설명에는 다음을 포함해줘.
- 이 코드의 목적
- 핵심 로직 한 줄 요약
- 주의해야 할 함정

사용:

/explain function debounce(fn, ms) { ... }

$ARGUMENTS 자리에 사용자가 친 인자가 그대로 들어갑니다.

3. frontmatter로 설명 붙이기

.claude/commands/review.md:

---
description: "현재 변경된 파일을 코드 리뷰합니다"
---

지금 git diff에 잡힌 변경사항을 리뷰해줘.

다음 관점으로 봐줘.
- 버그 가능성
- 가독성/네이밍
- 테스트가 필요한 부분
- 보안 이슈

각 항목은 파일:라인 형태로 위치를 명시해줘.

description을 적어두면 / 자동완성 목록에서 친절하게 표시됩니다.

4. 도구 제한 (allowed-tools)

명령어가 특정 도구만 쓰게 제한할 수 있습니다.

---
description: "Git 상태와 최근 커밋만 확인"
allowed-tools: ["Bash(git status:*)", "Bash(git log:*)"]
---

git status와 최근 커밋 5개를 보여주고 짧게 요약해줘.

읽기 전용 작업으로 한정하면 안전합니다.

5. 멀티스텝 워크플로 묶기

자주 하는 5단계 작업을 명령어 하나로:

.claude/commands/release-notes.md:

---
description: "최근 PR로 릴리스 노트 초안 작성"
---

다음 순서대로 실행해줘.

1. `git log --oneline main..HEAD`로 최근 커밋 목록 확인
2. 커밋 메시지를 feature / fix / chore로 분류
3. 각 항목을 한 줄로 사용자 관점에서 풀어쓰기
4. 마크다운 릴리스 노트 형식으로 출력
5. 노트 마지막에 "변경된 파일 N개" 통계 추가

이제 /release-notes만 치면 끝.

6. 명령어 확인과 디버깅

Claude Code에서 /만 치면 자동완성으로 등록된 명령어가 다 뜹니다. description이 적혀 있으면 거기에 같이 나와요.

명령어가 안 보이면 경로부터 확인:

# 프로젝트 단위
ls .claude/commands/

# 전역 (Linux/macOS)
ls ~/.claude/commands/

# 전역 (Windows PowerShell)
dir $env:USERPROFILE\.claude\commands\

자주 하는 실수

1. 파일 확장자 빠뜨림

.md를 안 붙이면 명령어로 인식이 안 됩니다. review.md는 OK, review는 NG.

2. $ARGUMENTS 위치 잘못

$ARGUMENTS는 단순 문자열 치환이라 따옴표나 코드블록 안에 넣으면 그대로 텍스트로 들어갑니다. 인자가 길거나 코드일 경우 별도 단락으로 분리해서 받는 게 깔끔해요.

3. 너무 많은 일을 한 명령어에 몰기

"리뷰하고 테스트 짜고 PR도 올리고" 식으로 한 명령어에 다 넣으면 결과 품질이 떨어집니다. 단계마다 명령어를 따로 두고, 멀티스텝 명령어는 정말 정형화된 절차만 묶으세요.

4. 프로젝트 명령어와 전역 명령어 충돌

같은 이름이 두 곳에 다 있으면 보통 프로젝트 쪽이 우선합니다. 의도와 다른 결과가 나오면 양쪽 다 확인해보세요.

5. 민감한 정보 하드코딩

API 키나 사내 비밀번호를 명령어 파일에 박아두면 안 됩니다. 명령어 파일은 깃에도 올라가는 경우가 많으니까 환경 변수나 외부 설정으로 빼두세요.

마무리

정리하면 세 줄입니다.

• 슬래시 명령어는 .claude/commands/이름.md(또는 ~/.claude/commands/)에 마크다운 한 장이면 끝.
• $ARGUMENTS로 인자 받고, frontmatter description과 allowed-tools로 깔끔·안전하게 묶기.
• 반복하는 프롬프트가 보이면 그 자리에서 명령어로 만들기 - 일주일이면 워크플로가 확 가벼워진다.