Claude Code 커스텀 슬래시 커맨드 입문: /review, /handoff, /release를 팀 표준으로 만들기

같은 리뷰 체크리스트를 또 붙여 넣습니다. 릴리스 직전에는 절차를 다시 떠올립니다. 긴 Claude Code 세션이 끝난 뒤에도 “무엇을 바꿨고, 무엇을 검증했고, 무엇이 위험한지”를 손으로 정리해야 합니다. AI 코딩 에이전트를 많이 쓸수록 이런 반복 작업은 개인 습관이 아니라 팀의 절차로 고정해야 합니다.

커스텀 슬래시 커맨드는 반복 프롬프트를 짧은 팀 공용 이름으로 바꾸는 기능입니다. /review, /handoff, /release 같은 명령은 단순한 단축키가 아닙니다. 잘 설계하면 코드 리뷰 기준, 작업 인수인계 방식, 릴리스 판단 기준을 저장하는 팀 표준이 됩니다.

이 글은 2026년 6월 3일에 확인한 Claude Code Skills 공식 문서와 Commands 레퍼런스를 기준으로 작성했습니다. 중요한 변화는 커스텀 커맨드가 Skills에 통합되었다는 점입니다. 기존 .claude/commands/*.md 파일은 계속 동작하지만, 새 팀 워크플로우는 보통 .claude/skills/<name>/SKILL.md로 설계하는 편이 좋습니다.

핵심: 커맨드는 재사용 가능한 작업 절차다

Claude Code에서 커맨드는 세션 안에서 /로 시작하는 메시지입니다. 공식 레퍼런스는 커맨드가 메시지 맨 앞에서 인식되며, 커맨드 이름 뒤의 텍스트는 인수로 전달된다고 설명합니다. 따라서 /release 1.8.0은 1.8.0을 버전으로 넘기고, /handoff frontend reviewer는 인수인계 노트의 대상 독자를 알려줄 수 있습니다.

Skill은 Claude가 재사용할 수 있는 지침 묶음입니다. 쉽게 말하면 작은 작업 플레이북입니다. 언제 사용할지, 어떤 단계를 따를지, 어떤 입력이 중요한지, 어떤 출력 형식이 필요한지를 담습니다. 오래된 .claude/commands/ 파일도 유효하지만, Skills는 디렉터리 구조, frontmatter, 보조 파일, 이름 있는 인수, 리뷰 가능한 변경 이력을 더 잘 지원합니다.

실무에서 가장 먼저 확인할 것은 이름 충돌입니다. 현재 Claude Code에는 /review, /code-review, /security-review 같은 내장 또는 번들 명령이 이미 보일 수 있습니다. 직접 /review를 만들기 전에 Claude Code에서 /를 입력해 메뉴를 확인하세요. 이름이 이미 있으면 /team-review, /review-note처럼 팀 전용 이름을 쓰는 것이 안전합니다. 이 글은 review라는 패턴을 다루지만, 실제 이름은 환경에 맞춰야 합니다.

파일 배치: Skills를 우선하고 Commands는 호환용으로 유지

팀 규칙은 개인 홈 디렉터리가 아니라 프로젝트 안에 있어야 합니다. 프로젝트 Skill은 Git에 커밋하고 pull request에서 리뷰할 수 있으며, 저장소와 함께 진화합니다. 개인 Skill도 유용하지만 모든 사람이 의존하는 규칙을 담기에는 적합하지 않습니다.

위치	예시	적합한 용도
프로젝트 Skill	.claude/skills/team-review/SKILL.md	팀 리뷰, 릴리스 준비, 조사, 온보딩
프로젝트 Command	.claude/commands/handoff.md	기존 가벼운 명령, 마이그레이션 중 호환
개인 Skill	~/.claude/skills/my-note/SKILL.md	개인 메모와 일상 루틴
개인 Command	~/.claude/commands/my-command.md	임시 개인 단축 명령

다음과 같은 구조가 관리하기 쉽습니다.

.claude/
├── commands/
│   └── handoff.md
└── skills/
    ├── team-review/
    │   ├── SKILL.md
    │   └── checklists/
    │       └── review.md
    └── release-prep/
        ├── SKILL.md
        └── scripts/
            └── collect-release-notes.sh

흐름은 단순합니다. 저장소가 팀 절차를 보관하고, / 메뉴가 그것을 명령으로 보여주며, 사용자가 인수를 넘기고, Claude Code가 현재 작업 컨텍스트와 절차를 결합합니다.

flowchart LR
  A[".claude/skills 또는 .claude/commands"] --> B["/team-review 같은 커맨드"]
  B --> C["인수: $ARGUMENTS 또는 $version"]
  C --> D["Claude Code가 지침을 로드"]
  D --> E["리뷰, 인수인계, 릴리스 준비"]
  E --> F["사람이 확인하고 머지 또는 배포 결정"]

Skill을 추가하거나 수정한 뒤에는 / 메뉴에 나타나는지 확인합니다. 현재 세션에서 반영되지 않으면 /reload-skills를 사용하거나 새 Claude Code 세션을 여세요. 설명 문구도 확인해야 합니다. 팀원이 그 문구를 보고 어떤 워크플로우인지 판단하기 때문입니다.

바로 복사해 쓸 수 있는 시작 템플릿

처음에는 작게 시작하세요. 아래 예시는 내장 /review와 충돌하지 않도록 /team-review를 만듭니다.

mkdir -p .claude/skills/team-review
cat > .claude/skills/team-review/SKILL.md <<'EOF'
---
description: Review the current change with the team's checklist before a pull request or merge.
argument-hint: [target-branch-or-path]
disable-model-invocation: true
---

You are performing a read-only team review.

Target: $ARGUMENTS

If the target is empty, ask which diff, branch, or path to review before scanning broadly.
Do not edit files.
Do not run destructive commands.

Review from these perspectives:
1. Correctness bugs and edge cases
2. Security and privacy risks
3. Test coverage and missing verification
4. Consistency with existing code patterns
5. Documentation, migration notes, and user-facing copy

Output:
- Findings first, ordered by severity
- File path and line number when available
- One short suggestion for each issue
- "No blocking findings" only if you found none
EOF

이후 /team-review main, /team-review src/auth처럼 좁은 대상을 지정해 호출합니다. disable-model-invocation: true는 Claude가 이 Skill을 자동으로 선택하지 못하게 합니다. 리뷰와 릴리스는 사람이 명시적으로 시작해야 하는 통제 지점이므로 이 설정이 유용합니다.

사용 사례 1: /review를 팀 리뷰 체크리스트로 만들기

리뷰 커맨드의 가치는 일관성입니다. 공통 체크리스트가 없으면 어떤 사람은 이름만 보고, 다른 사람은 보안만 보고, 또 다른 사람은 테스트만 봅니다. 커맨드는 심각도, 범위, 출력 형식을 정해 Claude와 사람이 같은 기준으로 읽게 해야 합니다.

환경에 이미 /review가 있다면 team-review.md 또는 team-review Skill을 사용하세요. 충돌이 없다면 .claude/commands/review.md로 /review를 만들 수도 있습니다.

---
description: Team review checklist for the current branch or specified path.
argument-hint: [branch-or-path]
disable-model-invocation: true
---

Review target: $ARGUMENTS

Read the diff or files related to the target and report only review findings.
Do not rewrite code unless the user asks for fixes after the review.

Severity:
- P0: data loss, auth bypass, secret leak, production outage
- P1: correctness bug, missing validation, broken user flow
- P2: maintainability, unclear naming, duplicated logic
- P3: optional cleanup

Required checks:
1. Is the change scoped to the request?
2. Are tests or manual verification enough for the risk?
3. Are error paths and empty states handled?
4. Does the code follow existing local patterns?
5. Could the change break monetization links, analytics, or release notes?

Return a short summary after the findings.

핵심은 “Do not rewrite code”입니다. 리뷰 명령이 몰래 파일을 고치면 더 이상 리뷰가 아니라 구현 작업입니다. 첫 단계는 읽기 전용으로 두고, findings를 확인한 뒤 별도 수정 작업을 시작하는 편이 안전합니다.

사용 사례 2: /handoff로 다음 사람이나 에이전트에게 넘기기

긴 세션은 마지막 컨텍스트가 흐려질 때 가치가 줄어듭니다. /handoff는 작업 마무리를 내일의 나, 팀원, 또는 다음 에이전트가 읽을 구조화된 노트로 바꿉니다.

---
description: Create a concise handoff note for the current task.
argument-hint: [next-owner-or-audience]
disable-model-invocation: true
---

Create a handoff note for: $ARGUMENTS

Include these sections:
1. Goal: what the task was trying to achieve
2. Changed files: important files and why they changed
3. Decisions: tradeoffs or assumptions made during the work
4. Verification: commands run, screenshots checked, or checks not run
5. Risks: unresolved issues, fragile areas, or things needing human review
6. Next steps: the smallest useful next action

Keep it factual. Do not hide failed attempts. If something was not verified, say so clearly.

수익화된 콘텐츠 사이트나 운영 중인 애플리케이션에서는 특히 효과가 큽니다. 내부 링크, CTA, 분석 이벤트, 스크린샷, 수동 확인은 여러 파일을 건드리는 작업에서 쉽게 빠집니다. handoff 명령은 이런 세부 사항을 다시 보이게 합니다.

사용 사례 3: /release는 배포가 아니라 준비용으로 쓰기

릴리스 커맨드는 보수적으로 설계해야 합니다. 목표는 Claude에게 배포를 맡기는 것이 아닙니다. 목표는 컨텍스트를 모으고, 릴리스 노트를 초안으로 만들고, 차단 요소를 정리하고, 최종 판단은 사람이 하게 두는 것입니다.

아래 템플릿은 이름 있는 인수를 사용합니다. 현재 문서에 따르면 arguments는 위치 인수에 이름을 매핑하므로 첫 번째 인수가 $version이 됩니다.

---
description: Prepare a release checklist and changelog draft without publishing.
argument-hint: [version]
arguments: [version]
disable-model-invocation: true
---

Prepare release $version.

Allowed work:
1. Inspect the current diff, package metadata, and changelog
2. Draft a changelog section for $version
3. Suggest verification commands
4. List release blockers and rollback notes
5. Propose a commit message

Safety rules:
- Do not run git push
- Do not publish packages
- Do not deploy to production
- Do not delete files
- Ask before changing version files

Output:
- Release summary
- Checklist
- Blockers
- Commands the user should run manually

이것은 release-prep 명령이지 배포 버튼이 아닙니다. 실제 배포 자동화는 승인, 로그, 롤백 규칙이 명확한 CI/CD 쪽에 두는 편이 안전합니다.

인수: 먼저 $ARGUMENTS부터 사용하기

대부분의 커스텀 명령은 $ARGUMENTS만으로 충분합니다. /handoff backend reviewer는 backend reviewer를 $ARGUMENTS에 넣습니다. 현재 문서는 $ARGUMENTS[0], $0, 그리고 frontmatter에 선언한 $issue, $branch 같은 이름 있는 인수도 지원합니다.

---
description: Prepare an issue-specific work plan.
argument-hint: [issue] [branch]
arguments: [issue, branch]
disable-model-invocation: true
---

Issue: $issue
Branch: $branch
All arguments: $ARGUMENTS

Create a plan that:
1. Restates the issue in plain language
2. Lists files to inspect first
3. Identifies likely tests
4. Names one thing that should not be changed

여러 단어를 하나의 인수로 유지하려면 /plan-issue "login redirect bug" fix-login처럼 따옴표를 사용합니다. 오래된 예시에서 $1을 첫 번째 인수라고 설명한다면 현재 문서와 맞는지 확인하세요. 현재 문서는 $0을 첫 번째 위치 인수의 축약형으로 설명합니다.

버전 관리와 리뷰 운영

프로젝트 Skills와 Commands는 코드처럼 다루어야 합니다. 무엇을 리뷰하고, 무엇을 놓치고, 팀이 무엇을 “완료”로 보는지에 영향을 주기 때문입니다. .claude/skills/release-prep/SKILL.md의 변경은 관련 없는 기능 diff 안에 묻히지 말고 pull request에서 보여야 합니다.

규칙	목적
.claude/skills/를 Git으로 관리	누가 언제 workflow를 바꿨는지 남긴다
커맨드만 바꾸는 PR 허용	절차 변경이 앱 코드에 묻히지 않는다
README나 CLAUDE.md에 명령 목록 작성	신규 팀원이 쉽게 찾는다
프롬프트에 파괴적 작업 금지	push, publish, deploy, 삭제 사고를 막는다
매달 명령 목록 정리	오래된 절차가 혼란을 만들지 않는다

팀 도입을 설계할 때는 Claude Code 시작 가이드, CLAUDE.md 베스트 프랙티스, Claude Code Hooks 가이드와 함께 정리하면 좋습니다.

함정과 보안 주의점

가장 큰 실수는 커맨드가 짧으니 안전하다고 생각하는 것입니다. 커맨드는 여전히 강한 프롬프트입니다. ! 백틱을 이용한 동적 컨텍스트 주입을 쓰면 Claude Code가 shell 명령을 먼저 실행하고 그 출력을 Skill 내용에 삽입합니다. 편리하지만 반드시 읽기 전용으로 제한해야 합니다.

---
description: Collect read-only git context for release notes.
disable-model-invocation: true
---

Current status:
!`git status --short`

Recent commits:
!`git log --oneline -20`

Summarize the release notes from the information above.
Do not run write operations.

이런 명령은 git status, git log 같은 안전한 조회로 제한하세요. rm, git clean, git push, npm publish, curl ... | sh, 운영 환경에 영향 주는 스크립트는 넣지 않습니다. allowed-tools도 조심해야 합니다. Bash 권한을 넓게 허용하면 팀이 기대한 확인 단계가 줄어들 수 있습니다. 읽기 도구부터 시작하고 실제로 필요한 권한만 추가하세요.

실패 사례는 흔합니다. 커스텀 /review가 내장 명령과 충돌합니다. Skill이 한 사람의 home 디렉터리에만 있습니다. Skill 본문이 너무 길어 매번 컨텍스트를 낭비합니다. 인수가 비어 있는데 전체 저장소를 훑게 됩니다. 릴리스 명령에 publish가 들어갑니다. 모두 편하게 만들려다 생기는 문제입니다. 읽기 전용, 작은 대상, 사람의 최종 확인을 기본값으로 두세요.

CTA: 템플릿을 팀 운영으로 고정하기

이 템플릿은 저장소에 맞게 바꿔야 가치가 생깁니다. 혼자 시작한다면 무료 Claude Code 치트시트로 안전한 명령 패턴을 손에 두세요. 재사용 가능한 review, release, handoff 템플릿이 필요하면 ClaudeCodeLab 제품을 확인하세요. 팀에서 권한, CLAUDE.md, Skill 리뷰, CI 경계, 온보딩을 함께 설계해야 한다면 Claude Code 교육 및 컨설팅이 더 빠릅니다.

Masa의 workflow에서 실제로 적용해 보니 결론은 분명했습니다. 세 가지 명령이면 충분했습니다. /team-review, /handoff, /release-prep가 반복 작업 대부분을 덮었고, Claude Code를 위험한 배포 도구로 만들지 않았습니다. 가장 큰 개선은 /release를 “게시하는 명령”이 아니라 “사람이 판단할 증거를 모으는 명령”으로 정의한 데서 나왔습니다. 커스텀 슬래시 커맨드는 팀이 같은 기준으로 멈추고, 확인하고, 넘길 때 가장 실용적입니다.