🎯

Claude Code 実践検証 Day 7｜Commandsの引数展開と公式の落とし穴

に公開
AI
開発環境
Windows 11
Claude Code
tech

Commandsって使ってますか？

.claude/commands/にMarkdownファイルを置くと、/コマンド名で呼び出せる機能です。公式ドキュメントを読むと、引数を$ARGUMENTSや$1、$2で受け取れると書いてあるんですよね。

で、実際に試してみたんですが…公式通りには動かない部分がありました。

今回は、Commandsの引数展開について検証した記録です。特にWindows環境での日本語引数や特殊文字の扱いも確認しています。

公式ドキュメントの説明

まずは公式が何を言っているか整理しておきましょう。

公式ドキュメント（Slash commands）によると、Commandsでは以下の引数変数が使えるとされています。

  • $ARGUMENTS - コマンドに渡された全引数
  • $1, $2, $3... - 位置引数（スペース区切り）

フロントマターでallowed-toolsを指定すると、そのコマンド実行中に使えるツールを制限できるとのこと。

---
allowed-tools: Bash(git add:*), Bash(git commit:*)
description: コミット作成用コマンド
---

さらに、!コマンド``記法でシェルコマンドの出力をプロンプトに埋め込めるとも書いてあります。

…と、ここまでは公式ドキュメントに書いてある通りなんですが。

検証したい観点

実際に使おうとすると、いくつか疑問が出てきます。

疑問1：$1, $2は本当に動くのか？

公式には位置引数の記載があります。でも、これ、実際どういう挙動になるんでしょう。

引数がない場合はどうなる？空文字？エラー？引用符で囲んだ引数（"hello world"）は1つの引数として認識される？

疑問2：Windows環境での日本語、大丈夫？

日本語引数は文字化けしないか。バックスラッシュを含むWindowsパス（C:\Users\...）はちゃんと渡せるか。

日本語ファイル名のコマンド（/日本語コマンド）なんてのも試してみたいですね。

疑問3：allowed-toolsの構文は？

公式の例ではBash(git add:*)みたいな書き方になってますが、これってJSON配列でも書けるのか。settings.local.jsonと競合したらどちらが優先される？

正直、公式ドキュメントだけでは判断できない部分が多いんですよね。同じところで悩んでる人、結構いるんじゃないでしょうか。

検証環境と方法

今回の検証環境は以下の通りです。

項目 値
OS Windows 11 Pro
シェル Git Bash (MINGW64)
Claude Code v2.0.60
モデル Opus 4.5

検証用のコマンドファイルを8つ用意しました。引数パターン、日本語、特殊文字、Windowsパス、シェル実行など、カテゴリ別にテストできるようになっています。

判定基準

  • ✓ 成功：期待通りの動作
  • ✗ 失敗：エラーまたは予期しない動作
  • △ 制限あり：動作するが制約あり（ドキュメントに記載なし）

明日の予告

検証は完了しています。結果を先に言うと、公式ドキュメントとの差異がいくつか見つかりました。

特に$1、$2の位置引数については、公式に記載があるにもかかわらず動作しませんでした。これは結構大きな発見だと思います。

allowed-toolsの構文についても、30分くらい「なんで動かないんだ」と悩んだ末にようやく正解にたどり着きました。同じ罠にハマる人が減れば幸いです。

明日の記事では、全検証結果と実務での推奨パターンをまとめます。Windows環境でCommandsを使おうとしている方、ぜひ参考にしてください。

シリーズ情報

  • シリーズ名：Claude Code 実践検証ガイド 2025
  • 著者：Akira
  • 検証環境：Windows 11 / Git Bash / Claude Code v2.0.60

次回：Day 8「Commands検証結果：$1は動かない、allowed-toolsの正しい書き方」

Discussion