$ARGUMENTS 로 커맨드에 인수 받기

$ARGUMENTS 는 커스텀 커맨드를 실행할 때 넘긴 인수 전체를 프롬프트 안에서 받는 플레이스홀더입니다. 이것 하나로 Issue 번호, 파일 경로, 검색 키워드처럼 실행할 때마다 달라지는 값을 커맨드에 넘길 수 있어, 커맨드 하나로 다양한 상황에 대응하게 됩니다.

커맨드 파일을 만드는 기본은 커스텀 커맨드 입문에서, 이 글에서 함께 쓰는 argument-hint 는 커스텀 커맨드 프론트매터 설정에서 다뤘습니다.

핵심 요약

• $ARGUMENTS 는 커맨드 실행 시 넘긴 인수 전체를 받는 플레이스홀더입니다.
• /mycommand foo bar 로 실행하면 $ARGUMENTS 는 foo bar 로 치환됩니다.
• Issue 번호, 파일 경로, 에러 메시지 등 어떤 텍스트든 받을 수 있습니다.
• 인수가 없으면 빈 문자열이 되므로 프롬프트에서 보완을 고려해야 합니다.
• argument-hint 를 함께 설정하면 후보 목록에 인수 형식이 표시됩니다.

$ARGUMENTS 는 어떻게 치환되나

$ARGUMENTS 는 프롬프트 안 어디서든 쓸 수 있고 구조도 단순합니다. 아래 같은 커맨드 파일이 있다고 합시다.

---
description: 지정된 Issue의 제목을 표시
---
Issue 번호 $ARGUMENTS 의 제목을 표시해 주세요.

이 커맨드를 /show-issue-title 123 으로 실행하면 $ARGUMENTS 가 123 으로 치환되어, Claude에게는 "Issue 번호 123 의 제목을 표시해 주세요."라는 프롬프트가 넘어갑니다.

마지막 줄이 주의할 지점입니다. 인수를 넘기지 않으면 빈 문자열이 되어 "Issue 번호 의 제목을 표시해 주세요." 같은 의미 없는 프롬프트가 만들어집니다.

사용 예 — 에러 메시지를 분석하는 커맨드

개발 현장에서 자주 쓰이는 것이 에러 메시지를 받아 원인을 조사하는 커맨드입니다. 아래 내용을 .claude/commands/search-error.md 로 저장합니다.

---
description: 에러 메시지를 검색해 원인을 조사
argument-hint: <error-message>
---
아래 에러에 대해 조사하고, 원인과 수정 방법을 제안해 주세요.

$ARGUMENTS

TypeError: Cannot read property 'map' of undefined 라는 에러를 조사하고 싶다면 이렇게 실행합니다.

/search-error TypeError: Cannot read property 'map' of undefined

에러 메시지 전체가 $ARGUMENTS 자리에 들어가고, Claude는 프로젝트 안에서 원인을 찾아 수정 방법을 제안합니다. 에러 메시지에 스페이스나 기호가 섞여 있어도 $ARGUMENTS 는 통째로 받으므로 따로 손볼 것이 없습니다.

프론트매터의 argument-hint: <error-message> 는 / 입력 시 후보 목록에 인수 형식을 표시해 줍니다. 팀 멤버가 커맨드를 처음 볼 때도 무엇을 넘겨야 하는지 바로 알 수 있으니 인수를 받는 커맨드에는 함께 설정해 두는 편이 좋습니다.

사용 예 — Issue 번호를 받아 수정하는 커맨드

같은 요령으로 Issue 번호를 받는 커맨드도 만들 수 있습니다. .claude/commands/fix-issue.md 에 아래처럼 적으면 /fix-issue 123 으로 호출할 때 123 이 프롬프트에 들어갑니다.

---
description: 지정한 Issue를 수정
argument-hint: <issue-number>
---
Issue 번호 $ARGUMENTS 의 내용을 확인하고, 원인을 찾아 수정해 주세요.
수정이 끝나면 변경한 파일 목록을 알려 주세요.

$ARGUMENTS 는 프롬프트 안 어디든, 몇 번이든 쓸 수 있습니다. 다만 인수 하나가 프롬프트 전체의 의미를 좌우하므로, 인수 없이 실행됐을 때를 대비해 "번호가 비어 있으면 어떤 Issue인지 먼저 물어볼 것" 같은 보완 지시를 한 줄 넣어 두면 헛도는 실행을 막을 수 있습니다.

인수는 어떻게 입력하나

인수가 있는 커맨드를 호출할 때는 입력 방법에 약간의 요령이 있습니다.

Tab 키로 커맨드를 먼저 고른다

/fix-issue 라고 타이핑하고 바로 Enter를 누르면 인수 없이 커맨드가 실행됩니다. 인수를 넘기려면 아래 순서로 조작합니다.

1. /fix-issue 를 타이핑합니다.
2. Tab 키로 커맨드를 선택합니다 (또는 화살표 키로 고른 뒤 Tab).
3. 스페이스를 입력합니다.
4. 인수를 입력합니다 (예: 123).
5. Enter로 실행합니다.

이 흐름만 익혀 두면 인수 딸린 커맨드를 매끄럽게 실행할 수 있습니다.

값을 여러 개 넘기는 경우

$ARGUMENTS 는 인수 전체를 하나의 문자열로 받습니다. 그래서 스페이스로 구분해 여러 값을 넘기는 것도 가능은 합니다.

다만 "무엇을, 어디로"처럼 값마다 역할이 다른 경우라면 $0, $1 같은 위치 인수로 개별로 받는 편이 확실합니다. 위치 인수는 $0/$1/$2 로 여러 인수 다루기에서 다룹니다.

정리

• $ARGUMENTS 는 커맨드 뒤에 입력한 텍스트 전체를 받는 플레이스홀더이며, 프롬프트 안 어디서든 쓸 수 있습니다.
• 인수가 없으면 빈 문자열이 되므로, 인수가 필요한 커맨드에는 argument-hint 를 설정하고 프롬프트에 보완 지시를 적어 두는 편이 좋습니다.
• 커맨드명 입력 후 Tab → 스페이스 → 인수 → Enter 순서로 입력해야 인수가 넘어갑니다.
• 역할이 다른 값을 여러 개 받을 때는 위치 인수 $0/$1/$2가 맞습니다.
• 먼저 자주 쓰는 조작 중 "매번 값이 달라지는 것"을 하나 골라 커맨드로 만들어 보세요.