Claude Code를 업무에서 사용하다 보면, "이 차이점(diff)을 리뷰해 줘. 관점은 ~", "테스트를 작성해 줘. 규약은 ~"와 같은 정형화된 프롬프트를 매번 다시 입력하고 있다는 사실을 깨닫게 된다. 나 또한 리뷰 요청을 할 때마다 10줄 가까운 지시 사항을 복사해서 붙여넣고 있었고, 역시 낭비라고 생각했다.

이러한 정형 작업은 **커스텀 슬래시 명령어 (Custom Slash Command)**로 분리할 수 있다. .claude/commands/에 Markdown 파일을 두기만 하면 /review와 같은 자체 명령어가 생성되며, 인자(argument)도 전달할 수 있다. 이 기사에서는 최소 구성부터 인자 및 명령어 실행 결과 임베딩까지의 절차와, 내가 실제로 겪었던 3가지 주의점(ハマりどころ)을 정리한다.

• 예상 독자: Claude Code를 일상적으로 사용하며, 정형 프롬프트를 복사해서 붙여넣는 운영 방식에서 벗어나고 싶은 사람

• 환경: Claude Code v2.x (2026년 7월 시점) / macOS (Linux에서도 동일)

• .claude/commands/<name>.md를 만들면 /<name> 명령어가 된다 (파일명 = 명령어 이름). 본문 중의 $ARGUMENTS가 호출 시의 인자로 치환된다. $1, $2로 개별 참조도 가능하다.

• frontmatter의 allowed-tools를 작성하지 않으면, !를 통한 명령어 사전 실행이 작동하지 않는다.

프로젝트 직하에서:

mkdir -p .claude/commands
cat > .claude/commands/review.md <<'EOF'
다음 관점에서 현재의 차이점(diff)을 리뷰해 주길 바란다.
...
EOF

Claude Code를 실행하고 /review라고 입력하면, 이 본문이 그대로 프롬프트로서 전송된다. /를 입력한 시점의 자동 완성 목록에도 review (project)로 나타난다. 이것만으로 복사/붙여넣기 운영은 끝난다.

$ARGUMENTS 플레이스홀더(placeholder)를 본문에 작성하면, /review src/api.ts의 src/api.ts 부분이 통째로 삽입된다.

---
description: 지정 파일을 중점 리뷰
argument-hint: <file-path>
...

frontmatter의 description은 자동 완성 목록에 설명으로 표시되며, argument-hint는 인자 힌트 표시가 된다. 인자가 여러 개인 경우 $1, $2로 개별적으로 가져올 수 있다. /compare old.ts new.ts라면 $1=old.ts, $2=new.ts가 된다.

행 내의 ! 표기법으로 쉘(shell) 명령어의 실행 결과를, @로 파일 내용을 프롬프트에 임베딩(embedding)할 수 있다. 커밋 메시지 생성 명령어의 예:

---
description: 현재의 차이점(diff)으로부터 커밋 메시지를 생성
allowed-tools: Bash(git status:*), Bash(git diff:*)
...

동작 확인: 변경 사항을 git add한 후 /commit-msg라고 입력하면, staged 된 차이점이 임베딩된 프롬프트가 구성되어 feat: ... 형식의 메시지 안이 반환되었다. 차이점을 수동으로 붙여넣을 필요가 없어진다.

팀에서 사용하는 리뷰 관점은 프로젝트 측에, 개인의 습관적인 지시는 사용자 측에 두는 것이 운영하기 쉽다.

${ARGUMENTS}나 $ARGUMENT (단수형)라고 적으면 치환되지 않는다. 유효한 것은 중괄호가 없고, 대문자이며, 복수형인 $ARGUMENTS뿐이다.

또 하나 혼동하기 쉬운 것은, 본문에 $ARGUMENTS를 적지 않고 인자를 포함하여 호출했을 경우이다. 이때 인자는 프롬프트 끝에 추가되는 사양이기 때문에, "인자가 작동하지 않는 것처럼 보이지만 실제로는 끝에 있는" 상태가 된다. 의도한 위치에 삽입하고 싶다면 플레이스홀더를 명시적으로 작성해야 한다.

원인은 allowed-tools에 해당 명령어를 작성하지 않았기 때문이다. 위의 예처럼 Bash(git diff:*) 형식으로 나열한다. 이 표기법은 settings.json의 permissions와 동일하며, Bash(git diff:*)...

는 「git diff로 시작하는 명령어를 허용」한다는 의미이다. : *를 붙이는 것을 잊으면 완전 일치(exact match)로 취급되어, git diff --staged와 같이 옵션이 붙는 순간 매칭되지 않게 된다. 여기서 20분을 허비했다.

정리할 목적으로 .claude/commands/frontend/component.md와 같이 배치하면, 명령어는 /frontend/component가 아니라 **/component**가 된다. 디렉터리 이름은 자동 완성 목록에 (project:frontend)라고 표시될 뿐, 호출 이름에는 포함되지 않는다. 다른 디렉터리에 동일한 이름의 파일을 두면 충돌하므로, 파일 이름 자체를 고유하게(unique) 유지해야 한다. 슬래시 명령어(Slash command)는 「프롬프트 템플릿 전개」이지, 별도의 컨텍스트(context)에서 동작하는 메커니즘이 아니다. 유사한 기능인 서브 에이전트(.claude/agents)는 독립된 컨텍스트에서 자율적으로 동작하므로 역할이 다르다.

• 현재 대화에 정형화된 지시를 삽입하고 싶다 → 슬래시 명령어
• 조사나 검증을 별도의 컨텍스트로 던지고 싶다 → 서브 에이전트

이렇게 구분하여 사용하고 있다. 우선은 복사해서 붙여넣고 있는 프롬프트를 그대로 파일 하나로 만드는 것부터 시작하는 것이 가장 빠르다.

• 정형 프롬프트는 .claude/commands/*.md로 분리하면 /명령어로 호출할 수 있다.
• $ARGUMENTS / $1로 인수를 전달하고, ! + allowed-tools로 명령어 실행 결과를 임베딩(embedding)할 수 있다.
• 막힌다면 「철자($ARGUMENTS 고정)」, 「allowed-tools의 : * 누락」, 「서브 디렉터리 네임스페이스(namespace)」 세 가지를 의심하라.
• 팀 공유용은 프로젝트 스코프(project scope)에, 개인용은 유저 스코프(user scope)에 둔다.