$ARGUMENTS 로 커맨드에 인수 받기

앞 편까지의 /meeting:summary는 전사 텍스트를 먼저 붙여 넣고 나서 커맨드를 불러야 했습니다. 커맨드가 "무엇을 대상으로" 일할지 스스로 받지 못했기 때문입니다. 이번 편은 그 빈칸을 채웁니다. 커맨드 이름 뒤에 적은 값을 본문 안에서 받는 자리표시자 $ARGUMENTS를 배우면, 같은 커맨드로 오늘 회의도, 어제 상담도, 특정 Issue도 처리할 수 있습니다.

읽고 나면 커맨드에 값을 넘기는 방법, 값이 본문 어디에 들어가는지, 인수를 안 넘겼을 때 무슨 일이 생기는지를 설명할 수 있게 됩니다. 값을 여러 개 받아 자리별로 쓰는 방법은 다음 편 위치 인수에서 이어집니다.

핵심 요약

• $ARGUMENTS는 커맨드 이름 뒤에 적은 텍스트 전체로 치환됩니다.
• 본문에 $ARGUMENTS가 없어도 인수를 넘기면 ARGUMENTS: <값>이 본문 끝에 덧붙습니다.
• 인수 없이 실행하면 빈 문자열로 치환되므로, 본문에 "값이 비어 있으면 물어보라"는 지시를 넣어 둡니다.
• 인수는 / 목록에서 커맨드를 고른 뒤 한 칸 띄고 이어 적습니다.
• 값이 여러 개여도 $ARGUMENTS에는 통째로 들어갑니다. 자리별로 나누려면 위치 인수를 씁니다.

$ARGUMENTS 는 어떻게 치환되나

공식 문서는 $ARGUMENTS를 "skill을 호출할 때 전달된 모든 인수"로 정의합니다. 커맨드 이름 다음에 오는 문자열이 통째로 그 자리에 들어갑니다. 예를 들어 본문이 다음과 같을 때

GitHub Issue $ARGUMENTS 를 우리 코딩 규칙에 맞춰 수정합니다.

/fix-issue 123을 실행하면 Claude는 "GitHub Issue 123 를 우리 코딩 규칙에 맞춰 수정합니다."를 받습니다. 치환은 Claude가 본문을 보기 전에 일어나므로, Claude 입장에서는 처음부터 그렇게 적힌 프롬프트를 받은 것과 같습니다.

두 가지 동작을 더 알아 두면 헷갈릴 일이 없습니다. 첫째, 본문에 $ARGUMENTS가 없는데 인수를 넘기면 공식 문서에 따라 ARGUMENTS: <입력값>이 본문 끝에 추가됩니다. 그러니 자리표시자를 깜빡해도 값이 사라지지는 않습니다. 둘째, 우리가 Claude Code 2.1.246에서 확인한 바로는 인수 없이 실행하면 $ARGUMENTS 자리가 빈 문자열이 됩니다. 문장 안에 빈칸이 생기는 셈이라, 본문에 빈 값 처리 지시를 넣는 습관이 필요합니다.

본문 안에서 글자 그대로 $1.00 같은 표기를 쓰고 싶다면 공식 문서대로 백슬래시로 이스케이프합니다(\$1.00). 숫자나 ARGUMENTS 앞의 $만 치환 대상이고 다른 $는 그대로 남습니다.

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

우리 3주차부터 가르치는 "뭔가 안 될 때" 질문법이 있습니다. "이 문제가 화면/서버/프로그램/데이터 중 어느 구간 문제인지 먼저 알려주고, 구간별로 하나씩 점검해줘." 이 문장을 매번 치는 대신 커맨드로 만들고, 에러 메시지를 인수로 넘깁니다.

~/.claude/commands/debug/where.md

---
description: 에러를 화면/서버/프로그램/데이터 4구간 중 어디 문제인지 먼저 판정한 뒤 점검
argument-hint: [에러 메시지 또는 로그]
allowed-tools: Read Grep
---
다음 에러를 분석합니다.

$ARGUMENTS

순서:
1. 화면, 서버, 프로그램, 데이터 네 구간 중 어디 문제인지 근거와 함께 판정합니다.
2. 판정한 구간부터 하나씩 점검하되, 코드를 고치기 전에 원인 분석을 먼저 보고합니다.
3. 수정은 최소 범위로 하고, 마지막에 변경 내용을 정리합니다.
4. 에러 메시지가 비어 있으면 어떤 에러인지 먼저 묻습니다.

호출은 /debug:where TypeError: Cannot read properties of undefined (reading 'map')처럼 에러 줄을 그대로 붙입니다. 공백과 괄호가 섞여 있어도 $ARGUMENTS는 전체를 한 덩어리로 받으므로 따옴표가 필요 없습니다. 3번 항목은 우리 과정의 "좋은 요청 황금 문장"인 원인 분석, 최소 수정, 변경 정리를 그대로 옮긴 것입니다.

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

숫자 하나만 받는 경우도 많습니다. 공식 문서 예시와 같은 구조로, 우리 CRM 레포에서 쓰는 형태를 만들면 다음과 같습니다.

.claude/commands/fix-issue.md

---
description: GitHub Issue 번호를 받아 원인 분석 → 최소 수정 → 테스트 → 커밋까지 진행
argument-hint: [issue-number]
allowed-tools: Bash(gh issue view *) Bash(git status *) Bash(git diff *)
disable-model-invocation: true
---
GitHub Issue #$ARGUMENTS 를 처리합니다.

1. gh issue view $ARGUMENTS 로 본문과 댓글을 읽습니다.
2. 재현 조건을 정리하고 원인을 분석해 먼저 보고합니다.
3. 최소 범위로 수정하고 관련 테스트를 실행합니다. 테스트 출력이 통과 증거입니다.
4. 변경 내용을 정리해 보고합니다. 커밋과 푸시는 사용자가 확인한 뒤 진행합니다.

/fix-issue 212를 실행하면 두 곳의 $ARGUMENTS가 모두 212로 바뀝니다. 같은 자리표시자를 본문에 여러 번 써도 됩니다. 프로젝트 레포의 Issue를 다루는 커맨드이므로 개인 폴더가 아니라 프로젝트의 .claude/commands/에 두고 팀과 공유합니다.

인수는 어떻게 입력하나

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

공식 대화형 모드 문서에 따르면 /를 입력하면 호출 가능한 목록이 뜨고, 이어서 글자를 치면 목록이 걸러집니다. /deb까지 치면 /debug:where가 좁혀지고, 이 상태에서 Tab을 누르면 이름이 완성됩니다. 그다음 한 칸 띄고 인수를 적은 뒤 Enter로 실행합니다. 이름을 끝까지 손으로 치다 오타가 나면 "Unknown command"가 뜨니, 목록에서 고르고 Tab으로 완성하는 습관이 안전합니다. 앞 편에서 붙인 argument-hint가 이때 이름 옆에 보여서 무엇을 적을지 알려 줍니다.

값을 여러 개 넘기는 경우

/fix-issue 212 hotfix처럼 값을 여러 개 적어도 $ARGUMENTS에는 212 hotfix가 통째로 들어갑니다. 따옴표로 묶은 값도 따옴표째 들어갑니다. 우리가 2.1.246에서 note.txt "hello world"를 넘겨 확인했을 때 $ARGUMENTS는 note.txt "hello world" 그대로였습니다. 그래서 $ARGUMENTS는 "문장 하나를 통째로 받는 용도"에 맞고, 첫 값은 파일, 둘째 값은 형식처럼 자리별로 나눠 쓰려면 다음 편의 위치 인수 $0, $1을 써야 합니다.

정리

• $ARGUMENTS는 커맨드 이름 뒤 텍스트 전체로 치환되며, 본문에 여러 번 써도 됩니다.
• 자리표시자가 없어도 ARGUMENTS: <값>으로 덧붙고, 인수가 없으면 빈 문자열이 됩니다.
• 에러 메시지처럼 공백이 섞인 긴 값은 따옴표 없이 그대로 넘겨도 됩니다.
• 입력은 / 목록에서 고른 뒤 Tab으로 이름 완성, 한 칸 띄고 값, Enter 순서입니다.
• 값을 자리별로 나눠 써야 하면 위치 인수로 넘어갑니다.

자주 묻는 질문