클로드 코드 커스텀 커맨드 정리

커스텀 슬래시 커맨드 기본 개념

커스텀 커맨드는 "마크다운 프롬프트를 명령어로 래핑한 것"이다.⁷

명령 형식은 /이름 [arguments] 이고, 실제 정의는 특정 디렉터리 아래의 .md 파일이다.⁷

프로젝트 범위로 공유할 수도 있고, 사용자 개인용으로 전역 범위에 둘 수도 있다.⁷

디렉터리 구조와 스코프

프로젝트 커맨드와 개인 커맨드는 디렉터리 위치로 구분된다.⁷

프로젝트 커맨드 .claude/commands/ 아래의 파일들. 저장소에 커밋해 팀과 공유하는 용도. 예: .claude/commands/optimize.md → /optimize 명령.⁷

개인 커맨드 ~/.claude/commands/ 아래의 파일들. 모든 프로젝트에서 재사용되는 개인 단축 명령. 예: ~/.claude/commands/security-review.md → /security-review.⁷

우선순위 같은 이름이 프로젝트/사용자에 동시에 있을 때는 프로젝트 버전이 우선된다.⁷

네임스페이스(서브디렉터리) 전략

서브디렉터리를 사용하면 이름 충돌 없이 도메인별로 묶을 수 있다.⁷

예를 들어 .claude/commands/frontend/component.md 와 .claude/commands/backend/component.md 모두 /component 로 호출되지만, 도움말에서는 (project:frontend), (project:backend) 처럼 설명에 섹션이 붙어 구분된다.⁷

실질적인 명령 이름은 파일명이고, 서브디렉터리는 "설명용 네임스페이스"라고 보면 된다.⁷

인자 전달: `$ARGUMENTS` vs `$1`, `$2` ...

커맨드에 동적인 값을 넣을 때는 플레이스홀더를 사용한다.⁷

$ARGUMENTS 명령 뒤에 온 모든 인자를 공백 포함 문자열로 통째로 받는다. 예: echo 'Fix issue #$ARGUMENTS' > .claude/commands/fix-issue.md 일 때 /fix-issue 123 high-priority → $ARGUMENTS는 "123 high-priority".⁷

$1, $2, $3 ... 쉘 스크립트와 비슷하게 위치별 인자를 다룰 때 쓴다. 예:

Review PR #$1 with priority $2 and assign to $3 정의 후 /review-pr 456 high alice → $1="456", $2="high", $3="alice".⁷

구조화된 커맨드(예: /deploy 환경 브랜치 전략)에는 위치 인자, 단일 문장/이슈 번호 등 자유도가 높은 케이스에는 $ARGUMENTS가 편하다.⁷

Bash 명령과 함께 쓰기

커맨드 안에서 특정 Bash 명령을 실행하고, 그 결과를 컨텍스트에 포함시킬 수 있다. 문법은 ! + 백틱이다.⁷

예를 들어 Git 커밋을 자동으로 만들도록 하는 커맨드는 다음과 같이 구성할 수 있다.⁷

맨 위 frontmatter의 allowed-tools에 허용할 Bash 명령을 whitelisting
본문에서 ! 백틱으로 git status, git diff 등을 실행하여 결과를 프롬프트에 포함

이 패턴을 쓰면 "항상 사전에 이 명령들을 실행해서 컨텍스트를 구성해 달라"는 템플릿을 만들 수 있다.⁷

파일 레퍼런스와 컨텍스트 구성

@경로 문법으로 파일이나 디렉터리를 커맨드 템플릿에서 직접 참조할 수 있다.⁷

예:

Review the implementation in @src/utils/helpers.js

또는

Compare @src/old-version.js with @src/new-version.js

이렇게 정의해두면 /refactor-helper utils/helpers.js 같은 식으로 호출했을 때 해당 파일 내용이 자동으로 포함된 상태에서 작업을 시작한다.⁷

Frontmatter로 메타데이터 관리

커맨드 파일 상단에는 YAML frontmatter를 둘 수 있다.⁷

주요 필드 요약:

allowed-tools 이 커맨드를 실행할 때 사용할 수 있는 도구 목록. 예: Bash(git commit:*), Edit 등. 기본값은 현재 대화의 허용 도구 세트 상속.⁷¹³

argument-hint 자동완성에 표시되는 인자 설명. 예: argument-hint: [pr-number] [priority] [assignee].⁷

description 커맨드의 짧은 설명. 지정하지 않으면 프롬프트의 첫 줄을 description으로 사용.⁷

model 이 커맨드를 실행할 때 사용할 모델을 지정. 예: claude-3-5-haiku-20241022. 지정하지 않으면 현재 세션의 모델 사용.⁷

disable-model-invocation SlashCommand 도구에서 이 커맨드를 호출하지 못하게 막을지 여부. 기본값 false.⁷

frontmatter를 잘 써두면 /help에서 커맨드 목록을 봤을 때 의미가 바로 드러나고, 도구/모델도 커맨드 단위로 튜닝할 수 있다.⁷

Frontmatter 예시 모음

1. 가장 기본적인 커맨드 frontmatter 예시

---
description: "선택한 코드에 대해 간단한 리팩터링 제안을 해주세요."
argument-hint: "[파일 경로 또는 선택한 코드 설명]"
---

선택된 코드 또는 @경로로 지정한 파일 코드를 읽고,
다음 기준으로 간단한 리팩터링 제안을 해주세요.

- 가독성 향상
- 중복 코드 제거
- 명명 규칙 일관성 유지

변경 제안은 코드 블록과 함께 제시하고, 각 변경 이유를 한 줄로 덧붙여 주세요.

description만 지정해도 /help 목록에서 이 커맨드의 용도가 바로 드러난다.
argument-hint는 자동완성 시 어떤 인자를 넣어야 하는지 힌트를 제공한다.

2. Bash 도구를 제한적으로 허용하는 예시 (`allowed-tools`)

---
description: "현재 git 변경 사항을 요약해서 커밋 메시지 초안을 만들어주세요."
argument-hint: "[선택 사항: 커밋 타입/스콥]"
allowed-tools:
  - Bash(git status)
  - Bash(git diff)
  - Bash(git diff --cached)
---

다음 순서로 진행하세요.

1. !`git status --short` 결과를 읽고, 변경된 파일 유형을 파악합니다.
2. !`git diff` 결과를 읽고, 주요 변경 사항을 항목별로 요약합니다.
3. Conventional Commits 형식을 기준으로, 제안 커밋 메시지 3개를 제시합니다.
4. 각 메시지마다 "언제 이 메시지를 선택하면 좋은지" 한 줄 설명을 덧붙입니다.

allowed-tools에 명시된 Bash 명령만 사용할 수 있으므로, 보안/안정성 측면에서 안전하다.
이 패턴은 git, 빌드, 테스트처럼 항상 같은 CLI를 호출하는 커맨드에 유용하다.

3. 모델을 커맨드별로 고정하는 예시 (`model`)

---
description: "대규모 파일에 대한 구조 위주 코드 리뷰"
argument-hint: "[파일 또는 디렉터리 경로]"
model: claude-3-5-haiku-20241022
---

@경로로 지정된 파일 또는 디렉터리의 코드를 읽고, 다음 관점으로 리뷰하세요.

- 모듈/레이어 구조가 적절한지
- 관심사 분리가 잘 되어 있는지
- 디렉터리/파일 구조가 확장에 유리한지

구체적인 코드 수정보다는, 구조 수준의 개선 방향을 중심으로 피드백을 작성해 주세요.

세션 기본 모델이 무엇이든, 이 커맨드는 항상 지정된 model로 실행된다.
빠른 응답이 좋은 "구조 리뷰/요약용 커맨드"와, 더 정밀한 "보안 리뷰/치밀한 리팩터링 커맨드"를 모델로 분리할 때 유용하다.

4. SlashCommand 도구에서는 숨기고 싶은 커맨드 예시 (`disable-model-invocation`)

---
description: "내 로컬 설정을 점검하고 필요 시 수정 가이드를 제안"
argument-hint: "[옵션 없음]"
allowed-tools:
  - Bash(cat ~/.claude/settings.json)
disable-model-invocation: true
---

!`cat ~/.claude/settings.json` 결과를 읽고 다음을 수행하세요.

1. 현재 설정에서 보안/권한 관련 위험 요소가 있는지 점검합니다.
2. 성능이나 사용성 측면에서 개선할 수 있는 옵션을 제안합니다.
3. 수정이 필요한 경우, 각 옵션에 대해
   - 무엇을 바꾸어야 하는지
   - 예상 효과
   - 주의할 점
   을 간단히 설명해 주세요.

disable-model-invocation: true이면, SlashCommand 도구에서 이 커맨드를 자동으로 호출하지 않는다.
개인용/실험용 커맨드처럼 도구 자동 호출 목록에는 숨기고 싶지만, 내가 직접 /이름으로는 쓰고 싶은 경우에 적합하다.

5. 여러 필드를 함께 활용하는 실전형 예시

---
description: "PR 번호를 기반으로 변경된 파일을 분석하고 리뷰 플랜을 세워주세요."
argument-hint: "[pr-number] [priority] [assignee]"
allowed-tools:
  - Bash(gh pr view:*)
  - Bash(gh pr diff:*)
model: claude-3-5-sonnet-20241022
---

다음 형식의 인자를 받습니다.

- $1: GitHub PR 번호 (필수)
- $2: 리뷰 우선순위 (예: high, medium, low)
- $3: 리뷰 담당자 이름 또는 아이디

진행 절차:

1. !`gh pr view $1 --json title,author,headRefName,baseRefName` 로 PR 메타데이터를 가져옵니다.
2. !`gh pr diff $1` 결과를 읽고 변경 범위를 파악합니다.
3. 우선순위($2)에 따라 리뷰 깊이를 조절해,
   - high: 위험 변경, 복잡한 로직 중심으로 상세 리뷰 계획
   - medium: 기능 영향 범위와 핵심 로직 위주 요약
   - low: 린트/스타일, 작은 리팩터링 기회 중심
4. $3에 맞춰, 담당자가 바로 실행할 수 있는 TODO 리스트를 작성합니다.

argument-hint와 $1, $2, $3 위치 인자를 맞춰 두면, 팀원이 /review-pr 123 high alice처럼 문서 없이도 사용할 수 있는 커맨드가 된다.
allowed-tools·model을 함께 쓰면, PR 리뷰라는 특정 작업에 최적화된 "전용 에이전트"를 Slash 커맨드 한 줄로 만드는 셈이다.

VS Code 환경과 연계

VS Code에서는 Claude Code 확장을 통해 터미널 모드(실제 CLI)나 그래픽 패널로 Claude Code를 쓸 수 있다.¹

기본 Slash 커맨드와 함께, 방금 설명한 커스텀 커맨드들도 그대로 사용 가능하다.⁶ 프로젝트 루트의 .claude/commands/를 저장소에 커밋해두면 팀원이 같은 커맨드를 /help에서 보고 바로 사용할 수 있다.⁷¹³

VS Code 확장 설정은 ~/.claude/settings.json 과 공유되기 때문에, 권한(permissions) 설정이나 MCP 서버 설정 등도 한 번 정의하면 CLI/확장 양쪽에서 재사용된다.¹¹³

실무용 패턴 몇 가지

프로젝트 온보딩 커맨드 새 팀원이 프로젝트에 들어왔을 때, 코어 파일/테스트/런 스크립트 등을 안내하는 /onboard 커맨드를 .claude/commands/에 만들어 두면, Claude가 코드와 문서를 읽고 개요를 정리해 주는 패턴을 만들 수 있다.¹³

Git 이슈/PR 플로우 템플릿 /fix-github-issue $ARGUMENTS 같이 이슈 번호를 입력하면 gh CLI로 조회 → 관련 코드 탐색 → 수정 → 테스트 → 커밋/PR까지 한 번에 수행하는 템플릿을 만들어 둘 수 있다.¹³

리뷰/리팩터링 가이드 /security-review, /optimize, /refactor-module 같은 커맨드를 만들어, 어떤 관점(보안/성능/구조)을 우선할지, 어떤 파일을 우선 보게 할지 명시하면 "리뷰 스타일"을 표준화할 수 있다.⁷¹³

요약 정리

Claude Code 커스텀 커맨드는 "반복되는 고급 프롬프트 + 도구 호출 패턴"을 파일로 저장하고 명령어로 재사용하는 기능이다.⁷

디렉터리 위치로 스코프를 나누고, frontmatter·인자·Bash·파일 레퍼런스를 적절히 조합하면 팀 차원의 코딩 워크플로우를 강력하게 자동화할 수 있다.⁷¹³

실무에서는 Skills로 기본 맥락을 자동 로딩하고, Subagent로 복잡한 절차를 쪼개고, 커스텀 커맨드로 이를 한 줄 명령으로 래핑한 뒤, 필요하면 Plugin으로 공유하는 구조로 설계하는 것이 효율적이다.¹¹¹³

참고

¹Use Claude Code in VS Code

⁶External Agents | Zed Code Editor Documentation

⁷Slash commands - Claude Code Docs

⁸Cooking with Claude Code: The Complete Guide

¹¹Understanding Claude Code: Skills vs Commands vs Subagents vs Plugins | Young Leaders Tech

¹³Claude Code Best Practices