3.2 커맨드 만드는 방법
마크다운 파일(Claude Code) 또는 TOML 파일(Gemini CLI)을 지정 경로에 생성하면 즉시 슬래시 커맨드로 사용 가능하다. 업데이트: 2026-03-08
핵심 요약
| 구분 | 내용 |
|---|---|
| 📖 정의 | .claude/commands/ 폴더에 마크다운 파일을 넣으면 파일 이름이 곧 커맨드 이름이 된다 |
| 💡 핵심 | Claude Code는 .md, Gemini CLI는 .toml 파일을 사용하며, 변경 즉시 반영된다 |
| 🎯 대상 | 반복 작업을 커맨드로 자동화하려는 개발자 |
| ⚠️ 주의 | 인자 전달은 Claude Code의 $ARGUMENTS로만 가능하며, Gemini CLI는 미지원이다 |
문서 탐색
목차
- Claude Code 커스텀 커맨드 만들기
- Gemini CLI 커스텀 커맨드 만들기
- Claude Code vs Gemini CLI 커맨드 비교
- 좋은 커맨드를 만드는 팁
- 자주 하는 실수
1. Claude Code 커스텀 커맨드 만들기
원리 — 딱 하나만 기억하면 된다
파일을 만들면 그게 커맨드가 된다.
.claude/commands/ 폴더에 마크다운 파일을 넣으면, 파일 이름이 곧 커맨드 이름이 된다.
.claude/commands/review.md → /review 로 호출
.claude/commands/deploy.md → /deploy 로 호출
파일 만들기 (3단계)
Step 1. 폴더 만들기
mkdir -p .claude/commandsStep 2. 마크다운 파일 작성
파일 안에는 Claude에게 전달할 지시사항을 적는다.
<!-- .claude/commands/review.md -->
이 코드를 꼼꼼하게 리뷰해줘.
아래 항목을 확인하고 문제가 있으면 정리해줘:
1. 로직 오류나 버그 가능성
2. 성능 문제 (느린 연산, 불필요한 반복)
3. 보안 취약점 (하드코딩된 값, XSS, SQL Injection)
4. 코딩 컨벤션 위반
각 문제는 **심각도(높음/중간/낮음)** 와 **파일명:라인번호** 를 함께 알려줘.
문제가 없으면 "이상 없음"으로 짧게 답해줘.Step 3. 바로 사용
Claude Code에서 /review 를 입력하면 바로 동작한다. 재시작 불필요.
인자(파라미터) 넘기기
커맨드 뒤에 추가 정보를 전달할 수 있다.
/review auth.ts ← auth.ts 파일만 리뷰
/translate 영어로 ← "영어로"를 인자로 전달
파일 안에서 인자를 받으려면 $ARGUMENTS 또는 $1, $2를 사용한다.
<!-- .claude/commands/translate.md -->
아래 텍스트를 $ARGUMENTS 로 번역해줘.
자연스러운 표현을 사용하고, 기술 용어는 원문을 괄호로 함께 표기해줘.사용:
/translate 일본어로 ← $ARGUMENTS 자리에 "일본어로" 가 들어감
/translate 영어로
저장 위치: 프로젝트 vs 글로벌
| 위치 | 경로 | 사용 시점 |
|---|---|---|
| 프로젝트 전용 | .claude/commands/ | 이 프로젝트에서만 쓸 커맨드 |
| 글로벌 (모든 프로젝트) | ~/.claude/commands/ | 어디서나 쓸 공통 커맨드 |
💡
/review,/translate같은 범용 커맨드는 글로벌에,/deploy처럼 프로젝트마다 다른 커맨드는 프로젝트에 저장한다.
YAML frontmatter로 커맨드 설명 추가 (선택사항)
/help에 커맨드 설명이 표시되게 하려면 frontmatter를 추가한다.
---
description: 코드를 심층 리뷰하고 문제점을 심각도별로 정리한다
---
이 코드를 꼼꼼하게 리뷰해줘...팀과 공유하기
.claude/commands/ 폴더를 Git으로 관리하면 팀 전체가 같은 커맨드를 사용할 수 있다.
git add .claude/commands/
git commit -m "팀 공통 커맨드 추가"
git push팀원이 git pull 하면 바로 /review, /deploy 등을 사용할 수 있다.
2. Gemini CLI 커스텀 커맨드 만들기
Gemini CLI는 마크다운 대신 TOML 형식 파일을 사용한다.
파일 만들기
# 폴더 생성
mkdir -p .gemini/commands
# TOML 파일 생성
touch .gemini/commands/review.tomlTOML 파일 구조
# .gemini/commands/review.toml
description = "코드를 리뷰하고 문제점을 정리한다"
prompt = """
이 코드를 꼼꼼하게 리뷰해줘.
아래 항목을 확인하고 문제가 있으면 정리해줘:
1. 로직 오류나 버그 가능성
2. 성능 문제
3. 보안 취약점
각 문제는 심각도와 파일명:라인번호를 함께 알려줘.
"""description:/help에 표시되는 설명prompt: 실제 Claude에 전달되는 지시사항
변경 사항 즉시 적용
/commands reload
파일을 수정한 뒤 이 커맨드를 입력하면 재시작 없이 바로 반영된다.
네임스페이스로 정리하기
커맨드가 많아지면 폴더로 묶어 네임스페이스를 만들 수 있다.
.gemini/commands/
├── git/
│ ├── commit.toml → /git:commit
│ └── pr.toml → /git:pr
└── code/
├── review.toml → /code:review
└── test.toml → /code:test
/git:commit ← git 관련 커밋 커맨드
/code:review ← 코드 리뷰 커맨드
3. Claude Code vs Gemini CLI 커맨드 비교
| 항목 | Claude Code | Gemini CLI |
|---|---|---|
| 파일 형식 | .md (마크다운) | .toml |
| 문법 | 자연어로 작성 | description =, prompt = """...""" |
| 인자 전달 | $ARGUMENTS, $1, $2 | 미지원 (프롬프트에 직접 포함) |
| 변경 적용 | 즉시 자동 반영 | /commands reload 필요 |
| 네임스페이스 | 미지원 | /폴더:커맨드 형식 |
| 초보자 난이도 | 더 쉬움 | 약간 복잡 |
4. 💡 좋은 커맨드를 만드는 팁
구체적으로 작성하기
# 나쁜 예 — 너무 막연함
코드를 확인해줘.
# 좋은 예 — 무엇을, 어떤 형식으로 알려줄지 명시
이 코드에서 버그와 성능 문제를 찾아줘.
결과는 [심각도] [파일:라인] [문제] [해결방법] 형식으로 정리해줘.
문제가 없으면 "이상 없음"이라고만 답해줘.출력 형식을 정해두기
매번 다른 형식으로 출력되면 불편하다. 커맨드 안에 출력 형식을 명시하면 일관된 결과를 얻을 수 있다.
결과는 아래 형식으로 작성해줘:
## 리뷰 결과
**전체 평가**: (한 줄)
| 심각도 | 위치 | 문제 | 해결방법 |
|--------|------|------|---------|
| 높음 | ... | ... | ... |자주 쓰는 것부터 만들기
처음부터 커맨드를 많이 만들려고 하지 말고, 매일 반복하는 작업 1~2개에 커맨드를 만들어본다.
추천 첫 번째 커맨드:
/review— 코드 리뷰/commit— 커밋 메시지 자동 생성/translate— 번역
5. 자주 하는 실수
| 실수 | 해결방법 |
|---|---|
| 커맨드가 안 보임 | 폴더 이름이 .claude/commands/ 가 맞는지 확인 |
| 인자가 전달 안 됨 | 파일 안에 $ARGUMENTS 가 있는지 확인 |
| 변경이 반영 안 됨 (Gemini) | /commands reload 입력 |
| 커맨드 이름에 공백 | 파일명에 공백 대신 - 또는 _ 사용 |
문서 탐색
참고 자료
- Claude Code 슬래시 커맨드 공식 문서
- Gemini CLI 커스텀 커맨드 공식 문서
- BioErrorLog: Claude Code 커스텀 커맨드 만들기
- CloudArtisan: Claude Code 슬래시 커맨드 팁
- 커뮤니티 커맨드 모음 (awesome-claude-code)