Claude Code 슬래시 명령에 플래그를 추가하는 방법: 실제로 작동하는 4가지 패턴
Claude Code는 커스텀 슬래시 명령에 대해 여러분이 기대하는 방식으로 --flags를 실제로 파싱하지 않지만, 4가지 패턴으로 동일한 UX를 얻을 수 있으며 그중 3가지는 CLI 파싱보다 오히려 더 깔끔합니다. 오늘은 바로 복사해 사용할 수 있는 작동하는 .md 파일과 함께, Claude Code 슬래시 명령에 플래그를 올바르게 추가하는 방법을 소개합니다.
빠른 답변:
- Claude Code는 커스텀 명령에 대한 CLI 플래그(
--json,--verbose)를 파싱하지 않으며, 해당 사용 방식에는 플래그 파서가 없습니다. - CLI 스타일 UX를 원한다면 플래그를
$ARGUMENTS에 작성하고 LLM이 이를 자연어로 해석하도록 하세요. - 타입이 지정된 인수가 필요하면 위치 기반
$1/$2또는arguments:frontmatter 필드에 선언된 명명된 인수를 사용하세요. /자동완성이 사용자에게 표시할 수 있도록 예상 플래그를argument-hint:에 문서화하세요.
Claude Code 슬래시 명령어 인수는 실제로 어떻게 작동할까?
Claude Code는 명령어를 LLM에 전송하기 전에 세 가지 종류의 토큰을 치환합니다. $ARGUMENTS(명령어 이름 뒤의 전체 문자열), 위치 인수 $0/$1/$2(셸 스타일의 따옴표로 묶인 세그먼트), 그리고 frontmatter에서 선언된 이름 있는 $variableName입니다. 내장 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는 토큰을 치환한 다음 렌더링된 프롬프트를 LLM에 전달합니다. 플래그 파서는 없습니다.
저희가 직접 Claude Code를 사용하면서 가장 많이 겪는 혼란이 바로 이것입니다. 개발자들은 LLM이 곧 파서라는 사실을 깨닫기 전에, 왜 --verbose이 "감지되지 않는지" 알아내려고 한 시간을 허비합니다. Claude Code v2.1.126(2026년 5월) 기준으로, 이 동작은 공식 슬래시 명령어 문서에 문서화되어 있으며 당분간 바뀌지 않을 것입니다. 슬래시 명령어는 Claude Code hooks와 형제 관계에 있는 기본 요소로, 둘 다 이 기능을 확장하지만 명령어는 사용자 입력에서 트리거되고 hooks는 도구 이벤트에서 트리거됩니다.
치환 모델을 증명하는 가장 작은 커스텀 명령어는 다음과 같습니다.
---
description: Echo whatever the user types after the command
argument-hint: [anything]
---
The user passed these arguments: $ARGUMENTS
Repeat them back verbatim, then describe what the user probably meant.이것을 .claude/commands/echo-args.md로 저장하고 /echo-args hello world --foo를 입력하면, LLM은 프롬프트에 치환된 리터럴 문자열 hello world --foo를 그대로 보게 됩니다. 이것이 멘탈 모델의 전부입니다. 명령어 파일이 더 넓은 skills 시스템과 어떻게 연관되는지 더 자세히 알아보려면 저희 Skills 입문서를 참고하세요.
5분 만에 첫 파라메트릭 슬래시 명령어 만들기
$ARGUMENTS를 참조하는 프롬프트 한 줄과 세 줄의 frontmatter로 .claude/commands/greet.md를 만드세요. Claude Code를 재시작하고 /greet World를 입력하면, LLM에 전달되기 전에 World가 프롬프트에 대입되는 것을 확인할 수 있습니다. 이게 절차의 전부입니다. 다섯 단계, 빌드 도구는 필요 없습니다.
처음부터 끝까지 전 과정은 다음과 같습니다:
- 디렉터리를 만듭니다. 프로젝트 루트에서
mkdir -p .claude/commands를 실행하세요..claude/폴더는 코드와 같은 위치에 있으며, Claude Code가 세션을 시작할 때 그 안의 명령어들이 자동으로 감지됩니다. - 명령어 파일을 작성합니다. 아래 스니펫을
.claude/commands/greet.md로 저장하세요. - 세션을 다시 불러옵니다. Claude Code를 종료했다가 다시 실행하세요(또는 해당 버전에서 지원한다면
/reload를 실행하세요). 명령어는 세션 시작 시 한 번만 읽힙니다. - 실행합니다. 채팅창에
/greet World를 입력하세요. - 대입을 확인합니다. 트랜스크립트를 열고 LLM이 리터럴 토큰
$ARGUMENTS가 아니라World가 프롬프트 본문에 삽입된 것을 확인했는지 점검하세요.
전체 파일은 다음과 같습니다:
---
description: Greet someone enthusiastically
argument-hint: <name>
---
You are a friendly assistant. Greet the person named "$ARGUMENTS" with one short, warm sentence. Then ask them what they're working on today.그리고 터미널에서의 상호작용은 다음과 같습니다:
> /greet World
Hey World, great to see you! What are you working on today?이것으로 끝입니다. 이제 파라메트릭 슬래시 명령어를 갖게 되었습니다. argument-hint 필드는 / 자동완성 메뉴에서 명령어 옆에 <name>을 표시해 주는 요소로, 작은 UX 디테일이 큰 효과를 냅니다.
$ARGUMENTS가 대입되지 않는다면, 열에 아홉은$args나$ARGS로 입력했기 때문입니다. 이 토큰은 정확히 대문자여야 합니다.
이 토큰은 대소문자를 구분하며 정확해야 합니다. $ARGUMENTS는 작동합니다. $arguments, $args, $ARGS, ${ARGUMENTS}는 모두 아무런 오류 없이 실패합니다. 리터럴 텍스트 그대로 LLM에 전달되어 모델은 그저 의미 없는 문자열을 보게 됩니다. 더 깊은 버그를 의심하기 전에 철자를 세 번씩 확인하세요.
어떤 Frontmatter 필드가 인수 처리를 제어할까?
5개의 frontmatter 필드가 슬래시 명령어의 인수 처리 방식을 결정합니다: argument-hint(자동완성에 표시되는 내용), allowed-tools(명령어가 호출할 수 있는 항목), arguments(명명된 인수 선언), model(실행할 Claude 변형), 그리고 disable-model-invocation(명령어를 사용자 전용 호출로 고정)입니다. 이 필드들을 조합하면 필요한 거의 모든 매개변수 패턴을 처리할 수 있습니다.
다음은 Claude Code v2.1.x 사용자 정의 명령어를 위한 frontmatter 전체 참조입니다:
| 필드 | 용도 | 예시 | 필수 여부 |
|---|---|---|---|
description: | / 메뉴에 표시되는 한 줄 요약 | Run staging deploy | 권장 |
argument-hint: | 명령어 이름 뒤에 표시되는 자동완성 힌트 | [--dry-run] [--region us] | 권장 |
allowed-tools: | 명령어가 호출할 수 있는 도구의 화이트리스트 | Bash(git:*) Read Edit | 선택 |
arguments: | 명명된 인수 선언 | [issue, branch] | 선택 |
model: | 이 명령어의 모델 재정의 | claude-opus-4-7 | 선택 |
disable-model-invocation: | 에이전트가 이 명령어를 호출하는 것을 차단 | true | 선택 |
context: fork | 격리된 컨텍스트에서 실행 | fork | 선택 |
모니터에 붙여둘 만한 두 가지 함정이 있습니다. 첫째, 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) 불리언 플래그는 LLM이 $ARGUMENTS에서 파싱하는 /deploy --dry-run 같은 형태이고, (2) 값 플래그는 $ARGUMENTS에서 추출하는 /test --filter auth 같은 형태이며, (3) 필수 위치 인수 + 선택적 플래그는 $1과 $ARGUMENTS를 혼합하는 /fix-issue 123 --priority high 같은 형태이고, (4) 엄격하게 타입이 지정된 위치 인수는 $0/$1/$2를 사용하는 /migrate-component SearchBar React Vue 같은 형태다.
명령어의 형태에 맞는 것을 선택하면 된다. 각각에 대해 동작하는 .md 파일은 다음과 같다.
패턴 1: 불리언 플래그 (--dry-run)
CLI 플래그 UX를 원하는데 해당 플래그가 단순한 on/off에 불과하다면, $ARGUMENTS 안에서 플래그를 감지하는 일은 LLM에게 맡기세요. 파싱 로직도, 위치 인수를 이리저리 다루는 작업도 필요 없이, 그저 프롬프트에 규칙을 설명하면 됩니다.
---
description: Deploy to staging or production
argument-hint: [--dry-run]
allowed-tools: Bash(git:*) Bash(npm:*) Read
---
Deploy the current branch to staging.
Arguments passed: $ARGUMENTS
If "$ARGUMENTS" contains "--dry-run", DO NOT actually deploy. Instead, print the deployment plan: which files would change, which env vars would be set, and which commands would run. Stop after printing the plan.
Otherwise, proceed with the real deployment using `git push staging main` and `npm run deploy:staging`./deploy --dry-run을 입력하면 LLM이 플래그를 인식해 계획을 출력한 뒤 멈춥니다. /deploy를 입력하면 그대로 배포합니다. 사용자는 파싱을 전혀 하지 않았고, 모든 작업은 LLM이 처리했으며, 이는 바로 LLM이 잘하는 일입니다.
패턴 2: 값 플래그 (--filter <pattern>)
동일한 개념이지만, 이번에는 플래그가 값을 가집니다. LLM은 $ARGUMENTS에서 --filter auth를 읽어 그 뒤의 부분 문자열을 사용합니다.
---
description: Run the test suite, optionally filtered
argument-hint: [--filter <pattern>]
allowed-tools: Bash(npm:*) Read
---
Run the project's test suite.
Arguments: $ARGUMENTS
If "$ARGUMENTS" contains "--filter <pattern>", run only tests matching <pattern>. Use `npm test -- --grep <pattern>` for the actual command.
If no `--filter` is present, run the full suite with `npm test`.
Report pass/fail counts at the end./test --filter auth는 인증(auth) 테스트만 실행합니다. /test는 모든 테스트를 실행합니다. LLM은 --filter 뒤의 패턴을 안정적으로 추출하는데, 이는 Claude가 이러한 구조화된 텍스트 추출에 정말 뛰어나기 때문이며, 사람들이 기대하는 것보다 훨씬 더 신뢰할 수 있습니다.
패턴 3: 필수 위치 인수 + 선택적 플래그
이것은 저희 자체 명령 라이브러리에서 가장 많이 사용하는 하이브리드 방식입니다. $1은 필수 인수를 전달하고, $ARGUMENTS는 모든 것을 전달합니다(그래서 LLM이 선택적 플래그도 여전히 찾아낼 수 있습니다). 하나의 인수는 반드시 필요하고 나머지는 자유 형식 컨텍스트일 때 가장 깔끔한 조합입니다.
---
description: Fix a GitHub issue
argument-hint: <issue-number> [--priority high|medium|low] [context...]
allowed-tools: Bash(gh:*) Bash(git:*) Read Edit
---
Fix GitHub issue #$1.
Full arguments: $ARGUMENTS
Steps:
1. Run `gh issue view $1` to load the issue body.
2. Read the codebase to locate the relevant file(s).
3. If "$ARGUMENTS" contains "--priority high", create a hotfix branch off main. Otherwise branch off develop.
4. Apply the fix, run tests, and open a PR linked to the issue.
Anything else in $ARGUMENTS after the issue number is freeform context — fold it into your understanding of the bug./fix-issue 1234 --priority high the login form blanks the email field after a failed attempt처럼 호출합니다. $1은 1234로 해석됩니다. $ARGUMENTS는 뒤에 오는 문자열 전체로 해석되며, LLM은 이를 priority 플래그와 자유 형식 설명 모두에 대해 기꺼이 파싱합니다.
저희는 /fix-issue 명령에서 바로 이 $1 + $ARGUMENTS 조합을 사용하는데, $1은 이슈 번호로, 나머지는 LLM이 파싱하는 자유 형식 컨텍스트로 씁니다. 1년간 매일 Claude Code를 사용하면서 가장 높은 ROI를 보여준 패턴이었습니다.
패턴 4: 엄격한 위치 지정 (타입 지정)
모든 인수가 필수이고 순서가 중요한 경우 $ARGUMENTS를 완전히 생략하세요. 모호함 없는 타입 지정 슬롯을 위해 $0/$1/$2(또는 arguments: frontmatter 필드를 통한 명명된 인수)를 사용하세요.
---
description: Migrate a component between frameworks
argument-hint: <component> <from-framework> <to-framework>
arguments: [component, fromFramework, toFramework]
allowed-tools: Read Edit Write
---
Migrate the component named "$component" from $fromFramework to $toFramework.
1. Read the existing component file (search for `$component.{jsx,tsx,vue,svelte}`).
2. Translate the component idioms from $fromFramework to $toFramework: lifecycle methods, state handling, prop syntax, event binding.
3. Write the new file in the matching extension for $toFramework.
4. Print a diff summary at the end.
If $fromFramework or $toFramework is unsupported, abort and tell the user which frameworks ARE supported (React, Vue, Svelte, Solid)./migrate-component SearchBar React Vue처럼 호출합니다. 명명된 인수 선언은 자동 완성 및 프롬프트 본문을 자체적으로 문서화하므로, migrate-component.md를 읽는 누구나 어떤 슬롯이 어떤 역할을 하는지 한눈에 파악할 수 있습니다. 이 패턴은 3개 이상의 필수 인수를 가진 명령에서 진가를 발휘합니다. GitHub의 wshobson/commands와 같은 커뮤니티 라이브러리 전반에서도 이 스타일을 확인할 수 있습니다.
불리언 플래그와 값 플래그가 작동하는 이유는 LLM이 유연한 파서이기 때문입니다. 엄격한 위치 지정이 작동하는 이유는 LLM의 지능이 전혀 필요하지 않기 때문입니다. 이 두 가지를 혼합하는 것이 비결입니다.
$ARGUMENTS vs 위치 인수 vs 이름 지정 인수, 언제 사용해야 할까?
인수가 CLI 플래그 스타일이고 LLM의 유연한 파싱을 원할 때는 $ARGUMENTS를 사용하세요. 인수가 타입이 지정되고 순서가 정해져 있으며 LLM의 모호성을 완전히 없애고 싶을 때는 위치 인수 $1/$2를 사용하세요. 인수가 3개 이상이고 자동완성에서 간결성보다 명확성이 더 중요할 때는 이름 지정 arguments:를 사용하세요. 다음은 결정 매트릭스입니다:
| 사용 사례 | 최적의 선택 | 구문 | 장점 | 단점 | 예시 |
|---|---|---|---|---|---|
| 선택적 인수가 있는 CLI 플래그 UX | $ARGUMENTS | 본문에 $ARGUMENTS | 유연하며 Unix UX를 반영 | LLM 측 파싱, 검증 없음 | /deploy --staging --dry-run |
| 타입이 지정되고 순서가 있는 필수 인수 | 위치 인수 $0/$1 | 본문에 $0 $1 $2 | 모호성 제로, 빠름 | 인수 순서에 취약 | /migrate Button React Vue |
| 명확성이 중요한 3개 이상의 인수 | arguments:를 통한 이름 지정 | arguments: [a, b, c] 그 다음 $a $b $c | 자체 문서화 | 장황한 frontmatter | /issue 123 main high |
| 필수 + 선택 혼합 | 하이브리드 ($1 + $ARGUMENTS) | $1 then $ARGUMENTS | 양쪽 장점 모두 | 하나의 파일에 두 가지 멘탈 모델 | /fix-issue 123 --priority high |
대부분의 개발자가 갖는 본능은 익숙한 bash 세계와 가장 가깝게 느껴지기 때문에 먼저 $ARGUMENTS에 손을 뻗는 것입니다. 프로토타입에는 그것으로 충분하지만, 계약이 안정적일 때는 타입이 지정된 위치 인수가 진정으로 더 낫습니다. LLM은 $1을 파싱할 필요가 없으며, 이미 깨끗한 문자열입니다.
대략적인 경험칙: 명령의 시그니처를 "or"과 "optionally"라는 단어 없이 한 영어 문장으로 설명할 수 있다면, 위치 인수를 사용하세요. 그런 단어가 필요하다면, $ARGUMENTS를 사용하세요.
이제 슬래시 명령어는 스킬과 같은 건가요?
Anthropic은 2026년 봄에 사용자 정의 명령어를 더 넓은 스킬 시스템으로 통합했지만, .claude/commands/*.md 파일은 여전히 작동하며 동일한 frontmatter를 사용합니다. 스킬은 디렉터리(.claude/skills/foo/SKILL.md와 지원 파일)이며 disable-model-invocation 같은 추가 호출 제어 기능을 제공합니다. 명령어는 단일 .md 파일입니다. 대체 규칙은 동일하고 패키징만 다릅니다.
실질적인 차이점은 다음과 같습니다:
| 항목 | .claude/commands/foo.md | .claude/skills/foo/ |
|---|---|---|
| 파일 형태 | 단일 .md 파일 | SKILL.md + 지원 파일이 포함된 디렉터리 |
| 적합한 용도 | 빠른 일회성 명령어, 프로젝트 로컬 자동화 | 템플릿, 참고 자료, 하위 파일을 포함한 재사용 가능한 번들 |
| 호출 제어 | Frontmatter만 | Frontmatter + 파일별 disable-model-invocation |
| 인수 처리 | 동일 ($ARGUMENTS, $1, 이름 지정) | 동일 ($ARGUMENTS, $1, 이름 지정) |
따라서 아니요, .claude/commands/는 지원이 중단된 것이 아닙니다. Anthropic은 시스템을 통합할 때 파일 형태가 계속 작동하도록 명시적으로 유지했는데, 이는 너무 많은 프로젝트가 명령어 라이브러리를 버전 관리에 고정해 두고 있기 때문입니다. 지원 파일(스킬이 불러오는 CONTRIBUTING.md 참고 자료나 복사하는 template.json 등)이 필요하다면 스킬을 사용하세요. 그렇지 않다면 명령어를 그대로 사용하시면 됩니다.
이번 통합은 오픈 표준인 agentskills.io를 향한 더 큰 흐름의 일환이며, 알아두면 좋을 여러 v2.1.x 변경 사항 중 하나입니다. 전체 기능 현황은 Claude Code v2.1 기능 정리를, 스킬에 대한 더 자세한 안내는 스킬 튜토리얼을 참고하세요.
내 $ARGUMENTS는 왜 치환되지 않을까? 흔한 버그 해결
$ARGUMENTS가 치환되지 않는 다섯 가지 흔한 이유: (1) 소문자 또는 단축 토큰 사용 ($args, $ARGS, $arguments, 반드시 리터럴 $ARGUMENTS여야 함), (2) 여러 단어로 된 인수를 따옴표로 감싸지 않음 (/cmd hello world는 분리됨, /cmd \"hello world\"는 하나로 유지됨), (3) allowed-tools를 공백 구분 대신 쉼표로 구분함, (4) 명령 파일이 .claude/commands/ 또는 .claude/skills/에 있지 않음, (5) 파일 수정 후 Claude Code 세션을 다시 로드해야 함.
LLM 프롬프트에 $ARGUMENTS가 그대로 표시됨
증상: 프롬프트의 $ARGUMENTS가 모델 응답에 일반 텍스트로 그대로 나타나, 마치 무시된 것처럼 보입니다. 원인: 대소문자 또는 철자가 잘못된 것입니다. 해당 토큰은 정확히 $ARGUMENTS이며, 대문자 8자입니다. 해결 방법: .md 파일을 열어 $args, $ARGS, $arguments, ${ARGUMENTS}를 grep으로 검색한 후 $ARGUMENTS로 바꾸세요. $args 오타 버그는 저희 팀의 모든 개발자가 적어도 한 번씩은 겪은 문제로, "알 수 없는 슬래시 명령어" 계열 버그 중 가장 빈번하게 발생합니다.
여러 단어로 된 인수가 예기치 않게 분할되는 현상
증상: /migrate-component Search Bar React Vue를 실행했더니 $1은 Search, $2는 Bar입니다. 원인: 공백 문자가 위치 인수를 분할합니다. 해결 방법: 여러 단어로 된 인수를 따옴표로 감싸세요: /migrate-component "Search Bar" React Vue. 이제 $1은 Search Bar입니다. 이는 셸의 동작 방식과 일치하며, use가 의도적으로 따르는 멘탈 모델입니다.
allowed-tools가 적용되지 않는 문제
증상: 명령은 실행되지만, 화이트리스트에 등록했다고 생각한 도구를 Claude가 호출하지 않거나, 목록에 없는 도구를 호출합니다. 원인: 공백 대신 쉼표로 구분했기 때문입니다. 해결책: allowed-tools: Bash, Read, Edit을 allowed-tools: Bash Read Edit으로 변경하세요. 도구 하위 패턴은 Bash(git:*) Bash(npm:*) Read 형식으로 작성합니다.
/ 자동완성에 명령어가 표시되지 않음
증상: /를 입력했는데 명령어가 목록에 없습니다. 원인: 파일 위치 문제, frontmatter 누락, 또는 disable-model-invocation이 잘못 설정된 경우입니다. 해결 방법: 파일이 프로젝트 루트 기준으로 .claude/commands/yourcmd.md(또는 .claude/skills/yourcmd/SKILL.md)에 있는지 확인하세요. frontmatter에 최소한 description: 필드가 있는지 확인하세요. disable-model-invocation: true로 설정하면 해당 명령어는 다른 에이전트에게는 노출되지 않지만, 사람이 직접 입력하는 / 메뉴에는 계속 표시됩니다.
.md 파일을 수정했는데 아무것도 바뀌지 않아요
증상: 버그를 고치고, 파일을 저장하고, 명령어를 다시 실행했는데도 똑같은 오류가 발생합니다. 원인: Claude Code는 세션 시작 시점에 명령어 파일을 캐시합니다. 해결 방법: Claude Code를 종료한 뒤 다시 실행하거나, 사용 중인 버전이 지원한다면 /reload를 실행하세요.
Claude Code는 세션 시작 시점에
.md파일을 읽습니다. 명령어를 수정했는데도 '변경이 안 된다면', 더 깊은 버그라고 단정하기 전에 먼저 세션을 재시작해 보세요.
이 다섯 가지 외의 엣지 케이스는 Claude Code 저장소 이슈에서 검색하는 것이 가장 좋습니다. 저희가 확인한 대부분의 이상한 치환 버그는 위 항목 중 하나의 변형이었습니다.
FAQ: Claude Code 슬래시 명령어 인자
Claude Code 슬래시 명령에 인수를 전달하려면 어떻게 하나요?
명령어 이름 뒤에 인수 문자열을 입력하세요: /greet World. 명령의 .md 파일 안에서는 값을 $ARGUMENTS(전체 문자열), $1(첫 번째 위치 인수) 또는 $variableName(frontmatter에 arguments: [variableName]을 선언한 경우)으로 참조하세요. 사용자가 LLM에 프롬프트를 전송하기 전에 토큰을 대체합니다.
Claude Code의 $ARGUMENTS란?
$ARGUMENTS는 사용자 정의 슬래시 명령어 파일에 사용되는 대체 토큰으로, 사용자가 명령어 이름 뒤에 입력한 전체 인수 문자열을 Claude Code가 대신 치환해 줍니다. 사용자가 /deploy --staging --dry-run을 실행하면, LLM이 프롬프트를 확인하기 전에 렌더링된 프롬프트 내부에서 $ARGUMENTS는 문자 그대로의 문자열 --staging --dry-run이 됩니다.
Claude Code 슬래시 명령어는 --json 같은 CLI 스타일 플래그를 받을 수 있나요?
네이티브로는 지원하지 않습니다. 사용자 정의 명령어에는 플래그 파서가 없습니다. --json을 $ARGUMENTS에 작성하면, 프롬프트가 LLM에게 이를 감지하고 그에 맞게 동작하도록 지시하는 방식입니다. Claude는 구조화된 텍스트를 유연하게 파싱할 수 있기 때문에 이것이 가능합니다. /clear나 /help 같은 내장 명령어에는 실제 플래그가 있지만, 사용자가 직접 만든 사용자 정의 명령어는 오직 치환(substitution) 규칙만을 따릅니다.
Claude Code에서 $1, $ARGUMENTS, $name의 차이점은 무엇인가요?
$1은 공백으로 구분된 첫 번째 위치 인수입니다($2는 두 번째, 이하 동일). $ARGUMENTS는 모든 위치 요소와 플래그를 포함한 인수 문자열 전체를 그대로 나타냅니다. $name은 프론트매터의 arguments: [name] 필드에서 선언하는 명명된 인수로, 숫자 인덱싱 없이 자체 문서화된 위치 슬롯을 사용하고 싶을 때 유용합니다.
Claude Code에서 argument-hint는 어떻게 작동하나요?
argument-hint는 / 자동완성 메뉴에서 명령어 이름 옆에 표시될 내용을 제어하는 frontmatter 필드입니다. argument-hint: <issue-number> [--priority high]로 설정하면 사용자가 /를 입력한 후 해당 템플릿이 그대로 표시됩니다. 순수하게 UX 용도로만 사용되며, 인수를 검증하거나 파싱하지 않습니다. 그래도 작성할 수 있는 가장 간편한 문서화 방법이기 때문에 설정해 둘 가치가 있습니다.
여러 개의 인수를 가진 사용자 지정 슬래시 명령은 어떻게 만드나요?
깔끔한 방법 두 가지가 있습니다. 위치 기반 방식의 경우, 프롬프트 본문에서 $1, $2, $3을 참조하세요. 이름 기반 방식의 경우, frontmatter에 arguments: [first, second, third]를 선언하고 $first, $second, $third를 참조하세요. 인수가 세 개 이상이라면 이름 기반 방식이 더 읽기 쉽습니다. $ARGUMENTS는 필수 위치 인수 슬롯 뒤에 오는 자유 형식의 후행 문자열을 LLM이 파싱하도록 하고 싶을 때만 사용하세요.
.claude/commands/는 .claude/skills/로 대체되어 더 이상 사용되지 않나요?
아닙니다. Anthropic은 2026년 봄 두 시스템을 통합했지만, .claude/commands/*.md가 동일한 치환 규칙으로 계속 작동하도록 명시적으로 유지했습니다. 단일 파일 자동화에는 commands를, 다중 파일 번들(템플릿 또는 참조를 포함한 SKILL.md)에는 skills를 사용하세요. frontmatter와 $ARGUMENTS 동작은 동일하며, 패키징 방식만 다릅니다. v2.1.126 기준 둘 모두 일급(first-class)으로 지원됩니다.
내 명령어에서 $ARGUMENTS가 치환되지 않는 이유는?
가장 흔한 원인 세 가지를 빈도순으로 보면 다음과 같습니다: 대소문자 오류($args나 $arguments가 아닌 대문자 $ARGUMENTS여야 함), 잘못된 파일 위치(.claude/commands/ 또는 .claude/skills/에 있어야 함), 또는 오래된 세션(Claude Code는 세션 시작 시 명령어 파일을 읽으므로 편집 후 재시작 필요). 세 가지 모두 문제가 없다면, H2 #1의 최소 예제로 /echo-args foo를 실행해 문제를 격리해 보세요.
특정 인수를 필수로 지정할 수 있나요?
사용 수준에서는 불가능합니다. 네이티브 필수 인수 검증 기능은 없습니다. 대신 프롬프트에서 LLM에게 지시하는 패턴을 사용합니다. "$1이 비어 있으면 작업을 중단하고 사용자에게 이슈 번호를 제공하라고 요청하세요."와 같이요. 모델이 이 계약을 강제합니다. 완벽하게 안전하지는 않지만, 실제로는 일상적인 용도로 충분히 신뢰할 수 있으며, 특히 명확한 argument-hint와 함께 사용하면 더욱 그렇습니다.
frontmatter의 model:이 CLI 플래그를 재정의하나요?
네, frontmatter가 우선합니다. 명령 파일에서 model: claude-haiku-4를 선언하면, 사용자가 세션에서 어떤 모델을 선택했든 해당 명령은 Haiku에서 실행됩니다. 이는 Opus에서 제외하고 싶은, 비용이 저렴하고 자주 호출되는 명령에 유용합니다. 명령 유형별로 적합한 변형을 선택하는 방법은 Claude 모델 전환하기 가이드를 참조하세요.
마무리하며
네 가지 패턴이 있습니다. 커맨드의 형태에 맞는 것을 선택하세요.
- 불리언 플래그(
--dry-run)는$ARGUMENTS에 그대로 써넣고, LLM이 이를 감지하도록 맡깁니다. - 값 플래그(
--filter <pattern>)도 같은 방식이며, LLM이 값을 추출합니다. - 필수 위치 인수 + 선택적 플래그는 반드시 필요한 값에는
$1을, 나머지에는$ARGUMENTS를 사용합니다. - 엄격한 위치 인수는 모든 슬롯이 필수이고 순서가 정해져 있을 때
$0/$1/$2(또는arguments:를 통한 이름 지정)를 사용합니다.
이제 커맨드가 매개변수화되었으니, 다음 단계는 이를 에이전트 워크플로우에 연결하는 것입니다. 다중 파일 패키징 업그레이드를 위해 Claude Skills 튜토리얼부터 시작하거나, 하네스를 비교 중이라면 대안 AI 코딩 도구를 둘러보세요. 어떤 쪽이든, .claude/commands/ 폴더는 이제 훨씬 더 유용해졌습니다.