課題：深夜2時のデバッグという悪夢
深夜2時。ターミナルは500エラーで真っ赤。複雑なレガシーコードと格闘し、データベースを1行修正しただけでフロントエンドが即座にダウンするような状況です。早く解決して寝ようとClaude Codeを開きます。しかし、エラーを直す代わりに、「ねえ、このプロジェクトはRepository Patternを使っているから、Prismaじゃなくて /lib/db のQuery Builderを使ってね」と説明するだけで15分も費やしてしまいます。
新しいセッションを始めるたびに、同じ説明の繰り返し。Claude Codeは非常に賢いですが、あなたのコードベースにとってはまだ「よそ者」です。暗黙のルールや、あなたが苦労して用意した便利なBashスクリプトを知りません。プロンプトに大量の指示をコピペしていると、血中のカフェインよりも先に忍耐力が底をついてしまいます。
分析：なぜClaudeは意図を汲み取れないのか？
問題は推論能力にあるのではありません。AIに欠けているのは、コンテキスト（文脈）とケイパビリティ（実行能力）です。デフォルトのClaude Codeは、ファイルの読み書きや一般的なシェルコマンドの実行といった基本的なツールしか持っていません。あなたのプロジェクト固有のプロセスに関する「専門知識」がないのです。
長いプロンプトにあらゆる情報を詰め込むと、2つの大きな壁にぶつかります：
- トークンの浪費： プロンプトが長すぎると、コンテキストウィンドウの20〜30%を消費してしまい、AIが混乱して本来のタスクを忘れてしまう原因になります。
- 操作のオーバーロード： 実行ルールをいちいち覚えて指示し直すのは疲れる作業であり、命令時のミスも招きやすくなります。
これらのプロセスをパッケージ化（カプセル化）できなければ、Claude Codeはプロジェクトの隅々まで把握したシニアエンジニアではなく、いつまでも「外部のヘルプ」のままです。
手動からプロフェッショナルな解決策まで
Claudeを「教育」するためにさまざまな方法を試してきました。その実体験を紹介します。
1. .clauderules ファイルの使用
これが最も手軽な方法です。プロジェクトのルートに .clauderules ファイルを作成し、コーディングスタイルのルールを記述します。Claude Codeは起動時にこのファイルを自動的に読み込みます。ただし、これはあくまで「リマインダー」の域を出ません。「ログを確認 -> エラーを解析 -> ファイルを特定 -> ユニットテストを実行」といった複雑なワークフローを実行することはできません。
2. 個別のBashスクリプト
以前、/scripts フォルダにスクリプトを用意し、Claudeに「DBエラーが出たら sh scripts/check-db.sh を実行して」と伝えていました。この方法は悪くないですが、Claudeはいつ本当に実行すべきか判断に迷ったり、スクリプトからの複雑な出力をうまく処理できなかったりすることがあります。
3. カスタムスキル — 最適な解決策
カスタムスキルは単なるスクリプトの集まりではなく、「能力の定義」です。「これが私のツールで、使い方はこうで、こういう時に呼び出すべきだ」とClaudeに教え込むことができます。この解決策により、本番環境での手動操作の時間を大幅に削減できました。
カスタムスキルを導入する3つのステップ
AIに推測させるのではなく、専用のツールセットを提供しましょう。以下は、私が実際にスキルを構築した際の手順です。
ステップ1：頻度の高いワークフローを選択する
すべてをやろうと欲張らないでください。最も頻繁に行う作業を選びましょう。例えば、最新のログを読み込み、Critical エラーをフィルタリングして、Gitの最新コミットと照らし合わせる analyze_production_error スキルなどが考えられます。
ステップ2：スキルの構造を定義する
Claude Codeは .claudecode/ ディレクトリ内の設定ファイルを通じてスキルを認識します。標準的なスキルには4つの要素が必要です：
- Name（名前）： 簡潔な名前（例：
deploy_hotfix）。 - Description（説明）： AIがいつそのスキルを「召喚」すべきか判断するための詳細な説明。
- Parameters（パラメータ）：
commit_idやservice_nameなどの入力変数。 - Implementation（実装）： 実際の実行コマンド。
私が使用している audit_security スキルの定義ファイルの例です：
### audit_security
変更されたファイル内のセキュリティ脆弱性をスキャンします。
**Usage:**
`audit_security --path <directory>`
**Steps:**
1. `git diff` を実行して変更されたファイルをリストアップ。
2. `grep` を使用して機密パターン（APIキー、ハードコードされたシークレット）を検索。
3. `npm audit` を実行して古いライブラリをチェック。
4. Markdownテーブル形式でレポートを出力。
ステップ3：テスト実行と微調整
「今日のコードにキーの漏洩がないかチェックして」と伝えるだけで、Claudeは意図を汲み取り、自動的に audit_security スキルを呼び出します。もう正確なコマンド名や複雑な引数を覚える必要はありません。
# 必要に応じて手動でスキルを有効化
/activate_skill audit_security
# または自然言語で指示
Claude、src/apiフォルダのセキュリティ監査を実行して。
実践的なアドバイス：「スーパースキル」を作らないこと
最大の失敗は、AからZまで何でもこなすスキルを作ってしまうことです。その結果、Claudeが混乱することがよくあります。単一責任（Single Responsibility）の原則に基づき、スキルを細分化しましょう。例えば、fetch_logs、parse_errors、suggest_fixes に分けます。Claudeはこれらを組み合わせて一連のアクションを完結させるのに十分な知能を持っています。
結論
Claude Codeのカスタムスキルを作成することは、バーチャルアシスタントにエンジニアとしての思考を注入することです。優れたスキルセットがあれば、本番環境の待機時間はそれほど恐ろしいものではなくなります。ログと格闘する代わりに、標準化されたプロセスに従ってAIに命令し、監視するだけで済むのです。
まずは今日、最も小さなタスクから始めてみてください。Claude Codeが単なる「コードが書けるチャットボット」ではなく、真に頼もしいパートナーになることを実感できるはずです。
