Claude Code는 커스텀 슬래시 커맨드에서 --flag를 CLI처럼 파싱하지 않습니다. 하지만 네 가지 패턴으로 같은 사용자 경험을 만들 수 있으며, 이 중 세 가지는 CLI 파싱보다 훨씬 깔끔합니다. 오늘은 Claude Code 슬래시 커맨드에 플래그를 제대로 추가하는 방법과 오늘 바로 복사해 사용할 수 있는 .md 파일들을 소개합니다.

빠른 답변:
- Claude Code는 커스텀 커맨드에서 CLI 플래그( --json , --verbose )를 파싱하지 않습니다 — 하네스에 플래그 파서가 없습니다.
- CLI 스타일의 사용자 경험을 원하면 플래그를 $ARGUMENTS에 쓰고 LLM이 이를 자연어로 해석하게 합니다.
- 타입이 정해진 인자가 필요하면 위치 인자 $1 / $2 또는 프론트매터의 arguments 필드에 선언된 명명된 인자를 사용합니다.
- argument-hint에 예상되는 플래그를 문서화하면 / 자동완성 메뉴에 표시됩니다.

Claude Code 슬래시 커맨드 인자는 실제로 어떻게 작동하나요?

Claude Code의 하네스는 커맨드를 LLM에 보내기 전에 세 가지 종류의 토큰을 치환합니다: $ARGUMENTS(커맨드 이름 뒤의 전체 문자열), 위치 인자 $0 / $1 / $2(셸 스타일의 인용된 세그먼트), 그리고 프론트매터의 arguments 필드에 선언된 명명된 인자입니다. 내장 CLI 플래그 파서는 없습니다 — --dry-run은 리터럴 텍스트로 $ARGUMENTS에 들어갑니다.

사람들을 헷갈리게 하는 부분이 바로 이겁니다. /deploy --staging --dry-run 으로 입력하면 Claude Code는 --staging --dry-run에 대해 argparse를 실행하지 않습니다. 하네스는 그 전체 문자열을 .md 파일에서 $ARGUMENTS를 참조한 곳에 그대로 붙여넣고, 렌더링된 프롬프트를 모델에 보냅니다. LLM은 --staging --dry-run을 일반 영문 텍스트로 보고 어떻게 할지 결정합니다.

이것은 버그가 아닙니다 — 이것이 설계입니다. 하네스는 파서가 아니라 치환 레이어입니다. /clear와 /help 같은 내장 커맨드(공식 CLI 레퍼런스 참조)는 플래그를 가지지만, 직접 만드는 커스텀 커맨드는 다른 규칙을 따릅니다.

Claude Code 작업에서 가장 흔한 혼란이 바로 이것입니다 — 개발자들이 --verbose가 "감지되지 않는" 이유를 찾아내느라 한 시간을 쏟다가 LLM이 파서라는 걸 깨닫습니다. Claude Code v2.1.126 (2026년 5월) 기준으로 이 동작은 공식 슬래시 커맨드 문서에 기재되어 있으며 가까운 시일에 바뀌지 않을 것입니다. 슬래시 커맨드는 Claude Code 훅의 형제 원시 요소입니다 — 둘 다 하네스를 확장하지만, 커맨드는 사용자 입력에 반응하고 훅은 도구 이벤트에 반응합니다.

치환 모델을 증명하는 가장 작은 커스텀 커맨드입니다:

.claude/commands/echo-args.md로 저장하고, /echo-args hello world --foo를 입력한 후, LLM이 프롬프트에 치환된 리터럴 문자열 hello world --foo를 보는지 확인하세요. 이것이 전체 정신 모델입니다. 커맨드 파일이 광범위한 스킬 시스템과 어떻게 연관되는지에 대한 더 깊은 설명은 스킬 입문서를 참조하세요.

5분 안에 첫 파라메터 슬래시 커맨드 만들기

프론트매터 3줄과 $ARGUMENTS를 참조하는 프롬프트 한 줄로 .claude/commands/greet.md를 만듭니다. Claude Code를 다시 시작하고, /greet World를 입력하면 World가 LLM이 보기 전에 프롬프트로 치환되는 것을 볼 수 있습니다. 이것이 전부입니다 — 5단계, 빌드 도구 없음.

처음부터 끝까지 레시피입니다:

  • 디렉토리를 만듭니다. 프로젝트 루트에서 mkdir -p .claude/commands 를 실행합니다. .claude/ 폴더는 코드와 함께 있으며, Claude Code가 세션을 시작할 때 안의 커맨드들이 자동으로 발견됩니다.
  • 커맨드 파일을 작성합니다. 아래 코드를 .claude/commands/greet.md 로 저장합니다.
  • 세션을 다시 로드합니다. Claude Code를 종료했다가 다시 시작합니다(/reload를 지원하는 버전이라면 사용해도 됩니다). 커맨드는 세션 시작 때 한 번만 읽혀집니다.
  • 실행합니다. 채팅에 /greet World를 입력합니다.
  • 치환을 확인합니다. 트랜스크립트를 열어 LLM이 리터럴 토큰 $ARGUMENTS가 아닌 프롬프트 본문에 치환된 World를 보는지 확인합니다.

전체 파일입니다:

---
name: greet
description: Greet someone by name
argument-hint: <name>
---

Say a friendly hello to $ARGUMENTS.

그리고 터미널 상호작용:

/greet World

→ LLM sees: Say a friendly hello to World.

이제 파라메터 슬래시 커맨드가 생겼습니다. argument-hint 필드는 / 자동완성 메뉴에 커맨드 옆에 을 표시하게 하는 것입니다 — 작은 UX 터치이지만 큰 효과를 냅니다.

토큰은 대소문자를 구분하며 정확해야 합니다. $ARGUMENTS는 작동합니다. $arguments, $args, $ARGS, ${ARGUMENTS}는 모두 조용히 실패합니다 — LLM에 리터럴 텍스트로 전송되고 모델은 그냥 쓰레기를 봅니다. 더 깊은 버그라고 가정하기 전에 철저히 철자를 확인하세요.

어떤 프론트매터 필드가 인자 처리를 제어하나요?

다섯 가지 프론트매터 필드가 슬래시 커맨드의 인자 처리를 형성합니다: argument-hint(자동완성이 표시하는 내용), allowed-tools(커맨드가 호출할 수 있는 것), arguments(명명된 인자 선언), model(어느 Claude 버전이 실행할지), 그리고 disable-model-invocation(커맨드를 사용자 전용 호출로 잠급니다). 함께 이들은 당신이 필요로 할 거의 모든 파라메터 패턴을 다룹니다.

Claude Code v2.1.x 커스텀 커맨드의 전체 프론트매터 레퍼런스입니다:

---
name: command-slug
description: Human-readable description
argument-hint: <arg1> [arg2]
allowed-tools: Tool1 Tool2(scope:*) Tool3
arguments:
  - name: arg1
    description: The first argument
    required: true
  - name: arg2
    description: The second, optional
    required: false
model: claude-opus-4-8
disable-model-invocation: false
---

Your prompt body, which can reference $ARGUMENTS, $1, $2, and $arg1, $arg2.

모니터에 고정할 두 가지 주의사항이 있습니다. 첫째, allowed-tools는 공백으로 구분되며 쉼표로 구분되지 않습니다. Bash(git:*), Read, Edit를 쓰면 어떤 것도 화이트리스트로 만들지 않고 조용히 실패합니다 — 파서는 전체 문자열을 하나의 잘못된 항목으로 취급합니다. Bash(git:*) Read Edit를 사용하세요. 우리는 이것을 어렵게 배웠습니다. 이 같은 패턴들에 대한 자세한 내용은 설정 파일 관례에 대한 CLAUDE.md 모범 사례를 참조하세요.

둘째, model: 필드는 사용자가 현재 세션에서 선택한 모델을 무시합니다. 커맨드가 계산상 저렴하고 더 작은 버전으로 강제하길 원할 때 유용합니다 — 다양한 커맨드 타입에 대해 Opus 4.7과 Sonnet 중에서 선택하는 것에 대한 가이드를 참조하세요.

disable-model-invocation: true 필드는 파괴적인 커맨드를 위한 안전망입니다. /deploy-prod나 /drop-database 같은 커맨드에 설정하면 다른 에이전트가 이 커맨드들을 프로그래밍 방식으로 호출할 수 없습니다 — 오직 채팅에 직접 입력하는 사람만 이들을 트리거할 수 있습니다.

실제로 사용할 4가지 인자 패턴은 무엇인가요?

네 가지 패턴으로 실제 Claude Code 슬래시 커맨드의 약 95%를 다룹니다: (1) /deploy --dry-run 같은 불린 플래그로 $ARGUMENTS에서 LLM이 파싱, (2) /test --filter auth 같은 값 플래그로 $ARGUMENTS에서 추출, (3) /fix-issue 123 --priority high 같은 필수 위치 인자 + 선택적 플래그로 $1과 $ARGUMENTS 혼합, (4) /migrate-component SearchBar React Vue 같은 순전히 타입이 정해진 위치 인자로 $0 / $1 / $2 사용.

당신의 커맨드 형태와 맞는 것을 고르세요. 각각에 대한 작동하는 .md 파일이 있습니다.

패턴 1: 불린 플래그 ( --dry-run )

플래그가 단순히 온/오프이고 CLI 플래그 UX를 원할 때는 LLM이 $ARGUMENTS 안에서 이를 감지하도록 의존합니다. 파싱 로직이 없고, 위치 인자도 없습니다 — 프롬프트에 규칙만 설명합니다.

/deploy --dry-run을 입력하면 LLM이 플래그를 보고, 계획을 출력하고, 멈춥니다. /deploy를 입력하면 배포합니다. 하네스는 파싱을 하지 않았습니다 — LLM이 모든 일을 했으며, 이것이 LLM이 잘하는 일입니다.

패턴 2: 값 플래그 ( --filter )

같은 생각이지만 이번에는 플래그가 값을 가집니다. LLM이 $ARGUMENTS에서 --filter auth를 읽고 그 뒤의 부분 문자열을 사용합니다.

/test --filter auth는 auth 테스트만 실행합니다. /test는 모두 실행합니다. LLM이 --filter 뒤의 패턴을 안정적으로 추출합니다. Claude는 이런 종류의 구조화된 텍스트 추출에 정말 좋으니까요 — 사람들이 예상하는 것보다 훨씬 더 신뢰할 수 있습니다.

패턴 3: 필수 위치 인자 + 선택적 플래그

이것이 우리가 자신의 커맨드 라이브러리에서 가장 많이 사용하는 하이브리드입니다. $1은 필수 인자를 가지고, $ARGUMENTS는 전체를 가지므로(LLM이 선택적 플래그를 여전히 찾을 수 있음) 한 인자는 필수이고 나머지는 자유 형식 맥락일 때 가장 깔끔한 조합입니다.

/fix-issue 1234 --priority high the login form blanks the email field after a failed attempt로 호출합니다. $1은 1234로 해석됩니다. $ARGUMENTS는 전체 뒤따르는 문자열로 해석되며, LLM은 priority 플래그와 자유 형식 설명 모두를 행복하게 파싱합니다.

...

출처 바로가기