Claude Code：カスタムコマンドで出力品質が変わる理由
はじめに
同じ問題を同じAIに依頼しても、聞き方次第で結果は大きく変わります。
本記事では、CSSのスクロール問題を修正する際に実際に起きた出来事をお伝えします。通常のプロンプトでは何度試しても解決できなかった問題が、カスタムコマンドを使った途端に一発で解決しました。
なぜこのような違いが生まれたのか、実際のやり取りを振り返りながら解説します。
発生した問題
WordPressテーマの固定サイドバーで、メニューがスクロールできない問題が発生しました。
症状は3つありました。
- メニュー項目がサイドバーの枠からはみ出る
- スクロールバーが表示されない
- 枠線が途中で切れる
通常プロンプトでの対応
「サイドバーがスクロールできない問題を修正してください」と依頼しました。
以下のような修正が繰り返されました。
flowchart TD
A["修正依頼"] --> B["外側にoverflow-y-auto追加"]
B --> C["NG: メニュー見切れたまま"]
C --> D["内側にh-full overflow-y-auto追加"]
D --> E["NG: メニューがはみ出す"]
E --> F["overflow-y-autoを入れ替え"]
F --> G["NG: スクロールバー表示されず"]
G --> H["振り出しに戻る"]
3回の修正を経ても問題は解決せず、むしろ新たな症状が増えていきました。
カスタムコマンドでの対応
/investigate-bugコマンドを使用しました。このコマンドには、バグ調査の手順がプロンプトとして定義されています。
実行後、以下の分析が行われました。
flowchart TD
A["investigate-bug実行"] --> B["症状を分離して把握"]
B --> C["はみ出しとスクロール不可は別問題"]
C --> D["なぜスクロールバーが出ない"]
D --> E["overflow-y-autoが機能していない"]
E --> F["なぜ機能しない"]
F --> G["h-fullが効いていない"]
G --> H["なぜh-fullが効かない"]
H --> I["親要素の高さが未定義"]
I --> J["根本原因特定"]
J --> K["一度の修正で解決"]
根本原因は「親要素に明示的な高さがないため、h-full（100%）が機能しない」というCSSの仕様でした。
修正内容は以下の通りです。
- 外側のコンテナに
flex flex-col overflow-hiddenを追加 - 内側のコンテナから
h-fullを削除
この修正でスクロールバーが表示され、はみ出しも解消されました。
なぜ結果が違ったのか
2つのプロンプトの違いを比較します。
flowchart LR
subgraph normal ["通常プロンプト"]
A1["問題を伝える"] --> A2["解決策を試す"]
A2 --> A3["ダメなら別の策を試す"]
end
subgraph custom ["カスタムコマンド"]
B1["問題を伝える"] --> B2["症状を分解する"]
B2 --> B3["各症状の原因を特定"]
B3 --> B4["原因の原因を追跡"]
B4 --> B5["根本原因に対処"]
end
通常のプロンプトでは「症状を直す」アプローチになります。見えている問題に対して、思いつく解決策を順番に試していきます。
カスタムコマンドには「5 Whys」という分析手順が含まれています。これは「なぜ？」を5回繰り返して根本原因を特定する手法です。
実際に使用したカスタムコマンドには、以下の指示が書かれていました。
A. 因果解析 (Causal Analysis)
- 5 Whysを実行:
1. なぜこの現象が発生したか?
2. なぜその状態になったか?
3. なぜそのコードが実行されたか?
4. なぜその設計になっているか?
5. なぜそのような前提条件があるか?
この指示があることで、AIは「とりあえず直す」のではなく「まず原因を突き止める」という行動を取りました。
カスタムコマンドの作り方
Claude Codeでは、Markdownファイルを特定のフォルダに置くだけでカスタムコマンドを作成できます。
配置場所は2種類あります。
~/.claude/commands/– 個人用（全プロジェクトで使用可能）.claude/commands/– プロジェクト用（チームで共有可能）
ファイル名がコマンド名になります。investigate-bug.mdというファイルを作ると、/investigate-bugで呼び出せます。
基本的な構成例です。
---
description: "不具合の調査レポートを作成"
---
あなたは〇〇の専門家です。
以下の手順で問題を分析してください。
1. 現象を正確に把握する
2. 原因を特定する
3. 解決策を提案する
descriptionを書いておくと、コマンド一覧で説明が表示されます。
効果的なカスタムコマンドのポイント
今回の経験から得られた知見をまとめます。
分析手順を明示することが重要です。「問題を解決して」ではなく「まず原因を特定し、次に解決策を検討して」と書くことで、AIの行動が変わります。
チェックポイントを設けることも有効です。今回のコマンドには「再現性の確認」「影響範囲の特定」「仮説の検証」といった確認項目が含まれていました。これにより見落としが減ります。
出力形式を指定することで、構造化された回答が得られます。「根本原因」「修正内容」「確認方法」といったセクションを指定しておくと、必要な情報が漏れなく出力されます。
終わりに
同じAIでも、プロンプトの設計で出力は大きく変わります。
今回のケースでは、「5 Whys」という分析手法をプロンプトに組み込むことで、表面的な修正の繰り返しから脱却し、一度で問題を解決できました。
よく使う作業パターンがあれば、カスタムコマンドとして定義しておくことをお勧めします。
参考リンク
Claude公式ドキュメントでカスタムコマンドの詳細を確認できます。
日本語の解説記事も参考になります。
コメントを残す