Markdown 파일로 재사용 가능한 slash command를 정의하고 git으로 팀 전체에 공유. 코드 리뷰, 테스트 생성, PR 설명 등 고빈도 작업을 커버한다.
Claude Code에는 기본 slash command가 몇 가지 내장되어 있다——/help, /clear, /compact. 하지만 실제로 워크플로를 빠르게 만드는 건 직접 작성한 것들이다.
이 글은 재사용 가능한 slash command 체계를 설계하는 방법을 다룬다. 팀 모두가 동일한 프롬프트 라이브러리를 공유하고, 매번 작업 설명을 처음부터 다시 작성하지 않아도 되게 만드는 것이 목표다.
Claude Code에서 커스텀 slash command는 Markdown 파일 하나다. 지정된 디렉토리에 넣으면 Claude Code 시작 시 자동으로 인식하고, /파일명을 입력하면 실행된다.
파일 내용이 Claude에게 전달되는 프롬프트다. 그게 전부다.
특별한 문법도 없고, 설정 포맷도 없다. .md 파일 하나가 곧 명령어 하나다.
두 곳에 저장할 수 있고, 역할이 다르다:
| 위치 | 경로 | 범위 |
|---|---|---|
| 프로젝트 | .claude/commands/ |
현재 프로젝트만, git에 커밋 가능 |
| 사용자 | ~/.claude/commands/ |
모든 프로젝트, 개인용 |
프로젝트 레벨이 팀 공유의 핵심이다. .claude/commands/를 git에 커밋하면 저장소를 clone하는 모든 사람이 자동으로 이 명령어 세트를 갖게 된다.
사용자 레벨은 개인 습관에 맞는 명령어를 두기에 적합하다——본인이 선호하는 코드 스타일 검사 방식이나 본인만 쓰는 도구 통합 등.
프로젝트 루트에서:
mkdir -p .claude/commands
.claude/commands/review.md 생성:
현재 변경사항의 코드 품질을 검토해주세요. 중점 확인 사항:
1. 논리 오류와 경계 조건
2. 명명이 명확한지
3. 추출할 수 있는 중복 코드가 있는지
4. 보안 문제 (SQL 인젝션, XSS, 민감 정보 노출)
구체적인 수정 제안을 제시하세요. 추상적인 조언은 필요 없습니다.
Claude Code를 재시작하고 /review를 입력하면 실행된다.
고정 내용의 명령어는 활용 범위가 제한적이다. $ARGUMENTS를 사용하면 명령어가 유연해진다——/command 뒤에 사용자가 입력한 내용이 프롬프트에 삽입된다.
예시 .claude/commands/test.md:
다음 코드의 테스트를 작성해주세요: $ARGUMENTS
요구사항:
- 정상 경로와 경계 조건 커버
- 테스트 이름은 자체 설명적으로
- 실제 데이터를 사용할 수 있는 곳은 mock하지 않기
사용 예:
/test UserAuthentication 클래스의 login 메서드
Claude가 받는 실제 프롬프트:
다음 코드의 테스트를 작성해주세요: UserAuthentication 클래스의 login 메서드
요구사항:
- 정상 경로와 경계 조건 커버
...
$ARGUMENTS는 프롬프트 어디에나 쓸 수 있고, 여러 번 사용할 수도 있다.
하나의 command, 하나의 책임
모든 작업을 담은 "만능" command는 만들지 않는다. /review는 코드 리뷰 전용, /test는 테스트 작성 전용, /pr은 PR 설명 생성 전용. 세분화된 command일수록 기억하기 쉽고 재사용하기도 쉽다.
프롬프트는 구체적으로 작성
나쁜 예:
이 코드를 최적화해줘
좋은 예:
```
이 코드의 성능을 최적화해주세요. 우선순위:
1. 불필요한 데이터베이스 쿼리 줄이기 (N+1 문제)
2. 루프 내 반복 연산 피하기
3. 선형 탐색을 더 효율적인 자료구조로 교체
인터페이스는 유지하고, 내부 구현만 변경.
```
구체적인 제약 조건이 있어야 Claude가 맥락에 맞는 결과를 낸다.
command에 frontmatter 추가
파일 상단에 메타데이터를 추가하면 Claude Code의 명령어 목록에 description이 표시되어 팀원이 용도를 빠르게 파악할 수 있다:
---
description: 현재 변경사항을 검토하고 코드 품질 피드백 제공
---
현재 변경사항의 코드 품질을 검토해주세요...
Rails 프로젝트를 예로, 일상 개발에서 자주 쓰는 시나리오를 커버하는 명령어들:
.claude/commands/review.md — 코드 리뷰
git diff의 변경사항을 검토하세요. 확인 사항:
- 논리 오류와 경계 조건 처리
- SQL 인젝션, 권한 검사 등 보안 문제
- 명명 가독성
- 추출할 수 있는 중복 로직
각 문제에 대해 구체적인 위치와 수정 제안을 제시하세요.
```
.claude/commands/test.md — 테스트 생성
이 코드의 테스트를 작성해주세요: $ARGUMENTS
RSpec 사용. 커버 범위: 정상 경로, 경계값, 오류 상황.
테스트 명명 형식: describe ... context ... it ...
기본적으로 실제 객체 사용, 외부 의존성만 필요시 mock.
```
.claude/commands/pr.md — PR 설명
git diff와 commit log를 바탕으로 PR 설명을 생성하세요.
형식:
(무엇을 했는지 2-3문장)
(배경과 동기)
(이 변경을 어떻게 검증할지)
간결하게, code reviewer를 대상으로 작성.
```
.claude/commands/explain.md — 코드 설명
$ARGUMENTS의 역할을 설명해주세요:
- 전체적인 책임은 무엇인가
- 핵심 로직은 어떻게 동작하는가
- 주의해야 할 경계 케이스는 무엇인가
이 코드를 처음 접하는 개발자를 대상으로, "무엇을 하는지"가 아닌 "왜 그렇게 하는지"를 중심으로 설명.
```
팀 전체에 강요하기에는 너무 개인적인 습관들. ~/.claude/commands/에 두기:
~/.claude/commands/standup.md — 스탠드업 준비
```markdown
오늘의 git log와 미완료 TODO를 바탕으로 스탠드업 요약을 작성해주세요:
- 어제 완료한 것
- 오늘 계획
- 블로커가 있는지
5문장 이내로.
```
~/.claude/commands/refactor.md — 리팩토링 제안
```markdown
$ARGUMENTS를 분석하고 리팩토링 제안을 해주세요.
리팩토링을 위한 리팩토링은 하지 않기. 진짜 가치 있는 변경만 제시.
각 제안에는: 어떤 문제를 해결하는지, 작업량이 어느 정도인지, 리스크가 어떤지 설명.
```
커스텀 command의 가장 큰 가치는 개인 생산성 향상이 아니라, 팀의 공통 언어를 만드는 것이다.
.claude/commands/를 저장소에 커밋하고 README나 CLAUDE.md에 사용 가능한 명령어와 용도를 정리한다. 신규 팀원은 저장소를 clone하는 순간 팀이 쌓아온 프롬프트 자산을 스스로 탐색할 필요 없이 바로 사용할 수 있다.
프로젝트가 발전하면서 command도 발전한다. 효과가 떨어지는 프롬프트를 발견하면 한 줄 수정해서 push하면 팀 전체에 적용된다. 이것이 팀 레벨에서 프롬프트 엔지니어링을 정착시키는 가장 낮은 비용의 방법이다.
.claude/
├── commands/
│ ├── review.md # 코드 리뷰
│ ├── test.md # 테스트 생성
│ ├── pr.md # PR 설명
│ └── explain.md # 코드 설명
└── settings.json