Claude Code カスタムスラッシュコマンド入門: /review・/handoff・/releaseをチームの型にする

毎回同じレビュー観点を貼り付ける。リリース前だけ長い手順を思い出す。セッションの終わりに「何をどこまでやったか」を手でまとめる。Claude Codeを使い込むほど、このような繰り返し作業が増えます。

カスタムスラッシュコマンドは、その繰り返しを短い名前に変える仕組みです。/review、/handoff、/releaseのようなコマンドをチームの型として持てば、個人のプロンプト術ではなく、レビュー基準、引き継ぎ、リリース判断をリポジトリに残せます。

この記事では、2026年6月3日時点のClaude Codeの公式SkillsドキュメントとCommandsリファレンスに合わせて、いま安全に使える作り方だけを扱います。古い記事にある未確認の構文をそのまま写さず、ファイル配置、引数、レビュー運用、スクリプト実行時の注意点まで実務向けに整理します。

まず結論: コマンドはチームの作業手順を短い名前にする

Claude Codeのコマンドは、セッション中に先頭が/で始まるメッセージとして入力する操作です。公式リファレンスでは、コマンド名の後ろに続くテキストは引数として渡される、と説明されています。つまり/release 1.8.0なら、1.8.0をリリース対象バージョンとして扱えます。

現在の公式ドキュメントでは、従来の「カスタムコマンド」はSkillsに統合されています。.claude/commands/deploy.mdのような既存ファイルは引き続き動きますが、推奨される設計は.claude/skills/<name>/SKILL.mdです。Skillは「Claudeに読み込ませる再利用可能な手順書」と考えると分かりやすいです。専門用語で言えば、Claudeの振る舞いを拡張する小さな手順パッケージです。

注意点もあります。現在のClaude Codeには、環境によって/reviewや/code-reviewなどの組み込みコマンドやバンドルSkillが表示されます。自分の環境で/を入力して一覧を確認し、名前が衝突する場合は/team-review、/pr-review-noteのようなチーム用の名前に変えてください。この記事では概念として/reviewを扱いますが、実運用では衝突確認を必ず入れます。

ファイル配置: commandsは動くがskills基準で考える

チームで使うなら、個人のホームディレクトリではなくプロジェクト配下に置くのが基本です。リポジトリに含めれば、レビュー対象にもなり、変更履歴も残せます。

置き場所	例	向いている用途
プロジェクト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	一時的な個人コマンド

実務では次のような構成が扱いやすいです。複雑なチェックリストや補助スクリプトはSkillディレクトリに寄せ、単純な互換コマンドだけ.claude/commands/に残します。

.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

この状態でClaude Codeを開き、/team-review mainや/team-review src/authのように呼び出します。disable-model-invocation: trueは、Claudeが勝手にこのSkillを自動起動しないようにする設定です。レビューやリリースのように人間が明示的に実行したい手順では、誤起動を防ぐために入れておくと扱いやすくなります。

ユースケース1: /reviewをチームのレビュー観点にする

レビュー用コマンドの価値は、毎回同じ観点で読めることです。人によって「品質」の意味が違うと、ある人は命名だけを見て、別の人はセキュリティだけを見る、というばらつきが出ます。コマンドに優先順位と出力形式を入れておくと、AIの回答も人間のレビューも比較しやすくなります。

既に組み込み/reviewがある環境では、ファイル名をteam-review.mdまたはSkill名をteam-reviewにしてください。衝突しない環境で短い名前を使うなら、.claude/commands/review.mdとして置くこともできます。

---
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.

ポイントは「読んでほしい観点」だけでなく「やらないこと」も明記することです。レビューコマンドに修正まで許すと、レビューのつもりが実装タスクに変わります。まず読み取り専用のレビュー、その後に必要なら修正、という二段階にすると差分が追いやすくなります。

ユースケース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.

Masaの運用では、記事更新や小さな実装でもこの引き継ぎが効きました。特に収益CTA、内部リンク、翻訳更新のように翌日見返すポイントが散らばる作業では、最後の5分で/handoff editorを実行するだけでレビュー時間が短くなります。

ユースケース3: /releaseでリリース前チェックを固定する

リリース手順は危険な操作を含みやすいので、コマンド化するときほど保守的に作ります。ここではargumentsで名前付き引数$versionを使う例にします。公式ドキュメントでは、argumentsに定義した名前が位置引数に対応すると説明されています。

---
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

このテンプレートは「リリースを実行するコマンド」ではなく「リリース判断を助けるコマンド」です。npm publishや本番デプロイまで自動化したい場合でも、最初はCI/CD側に任せ、Claude Code側はチェックリストと差分整理に限定する方が事故が少なくなります。

引数の使い方: $ARGUMENTSから始める

引数は難しく考えず、最初は$ARGUMENTSだけで十分です。/handoff backend reviewerと入力すれば、$ARGUMENTSにはbackend reviewerが入ります。現在の公式ドキュメントでは、特定位置の引数は$ARGUMENTS[0]や$0で参照でき、arguments: [issue, branch]のように書けば$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

複数語を1つの引数にしたいときは、/plan-issue "login redirect bug" fix-loginのように引用符で囲みます。古いサンプルで「$1が最初の引数」と説明しているものを見かけたら、現在の公式仕様とずれていないか確認してください。現在の説明では$0が最初の引数です。

バージョン管理とレビュー運用

プロジェクト用のSkillやCommandは、アプリコードと同じくらいレビュー対象にするべきです。理由は単純で、コマンドがチームの作業結果を変えるからです。レビュー観点が変われば、見つかるバグも、見逃すリスクも変わります。

おすすめの運用は次の形です。

ルール	目的
.claude/skills/をGit管理する	だれがいつ手順を変えたか残す
コマンド変更だけのPRを許可する	手順変更をアプリ差分に紛れ込ませない
READMEやCLAUDE.mdに一覧を書く	新メンバーが発見しやすくなる
破壊的操作を禁止する文を入れる	push、publish、削除の事故を防ぐ
月1回だけ棚卸しする	増えすぎたコマンドを減らす

Claude Codeの基礎ルールはClaude Code入門ガイド、リポジトリ固有の指示はCLAUDE.mdベストプラクティス、自動実行の境界はHooksガイドと一緒に整理すると導入しやすくなります。

落とし穴とセキュリティ

一番危ない落とし穴は、コマンドを「安全なショートカット」だと思い込むことです。実際には、コマンドは強いプロンプトです。さらに動的コンテキスト注入の!バッククォート構文を使うと、Claudeが読む前にシェルコマンドの出力を取り込めます。便利ですが、ここに破壊的な操作を入れてはいけません。

---
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、本番環境へ影響するコマンドはSkill本文にも補助スクリプトにも入れないでください。allowed-toolsを使う場合も、Bashを広く許可しすぎると確認なしで実行できる範囲が広がります。まず読み取りツールだけから始め、必要な権限を1つずつ足すのが現実的です。

具体的な失敗例も押さえておきます。組み込み/reviewと同名にして呼び出せない。個人ディレクトリにだけ置いてチームメイトが使えない。Skill本文が長すぎて毎回コンテキストを圧迫する。引数が空なのに全リポジトリを読ませてしまう。リリースコマンドにpublishまで任せてしまう。どれも「便利にしよう」とした結果起きるので、最初は読み取り専用、小さな対象、人間の最終確認を前提に設計してください。

CTA: テンプレートを自分の運用に固定する

ここまでのテンプレートは、そのまま使うよりも自分のリポジトリに合わせて育てることで価値が出ます。個人で始めるなら無料チートシートで日常コマンドと安全な依頼の型を手元に置き、繰り返し使うレビューやリリース手順はClaude Code教材一覧のテンプレート集で補強してください。チームで導入する場合は、権限設計、CLAUDE.md、Skillレビュー、CIとの分担までまとめて決める必要があるため、Claude Code研修・導入相談でリポジトリに合わせて設計するのが早いです。

この記事で紹介した内容を実際に試した結果、Masaの作業では/team-review、/handoff、/release-prepの3つに絞る構成が一番安定しました。特に/releaseを「公開するコマンド」ではなく「公開前に人間が判断するための材料を集めるコマンド」にしたことで、誤ってpushやpublishまで進む不安が消えました。カスタムスラッシュコマンドは、自動化を増やす道具ではなく、チームが同じ基準で止まり、確認し、次へ渡すための道具として使うのが現実的です。