Claude Code 実践Tips集

CLAUDE.mdには以下の情報を記述すると効果的です。

• コマンド一覧：ビルド・テスト・デプロイのコマンドをまとめる
• コーディング規約：命名規則、インデント、ファイル命名ルールを明記
• アーキテクチャ概要：ディレクトリ構造と役割を表形式で記述
• パターン集：APIクライアントやテストの既存パターンを明示

ポイントは「助言的に書く」こと。厳密すぎるルールは柔軟性を失わせます。「原則としてkebab-caseを使う」のように、方向性を示しつつ例外を許容する書き方が理想です。

Claude Codeは複数のCLAUDE.mdを階層的に読み込みます。

• グローバル（~/.claude/CLAUDE.md）：パッケージマネージャーやワークフロー等、全プロジェクト共通の設定
• プロジェクト（ルート）：スタック情報、ディレクトリ構造、ビルドコマンド等の固有設定
• ディレクトリ（サブディレクトリ）：モノレポの各パッケージ固有の設定

3階層の使い分けで、設定の重複を避けつつきめ細かなAI制御が可能です。

Claude Codeで利用可能な主要なhookは以下のとおりです。

• PreToolUse hook：ツール実行前に発火。リントチェックや危険コマンドのブロックに使えます
• PostToolUse hook：ツール実行後に発火。自動フォーマットやテスト自動実行に活用できます
• Notification hook：通知送信時に発火。Slack通知などの外部連携に使えます

hooksは.claude/settings.jsonに記述します。シェルコマンドを直接指定できるため、既存スクリプトとの連携も容易です。

効果的なhook設定例を紹介します。

• 自動フォーマット：ファイル保存時にBiomeを自動実行し、スタイルを統一
• テスト自動実行：変更後に関連テストを自動実行し、失敗時は即フィードバック
• 危険操作ブロック：git push --force等の危険コマンドを事前にブロック

使い分けの原則は「効かないルールはhooksで強制する」です。CLAUDE.mdで従わないルールはhooksで機械的にチェックしましょう。

• 1セッション1タスク：1つのセッションでは1つのタスクに集中する。無関係なタスクを同じセッションで行うと、コンテキストが汚染されて精度が落ちます
• 定期的にセッションをリセット：同じ問題で2回失敗したら、新しいセッションを開始する。古いコンテキストが残っていると、同じ間違いを繰り返しやすくなります
• 参照ファイルを絞る：「このプロジェクト全体を見て」ではなく「このファイルを見て」と指定する。必要最小限のファイルだけを参照させることで、精度が向上します
• 中間出力を保存する：長いタスクでは途中経過をファイルに保存し、新しいセッションでそのファイルから再開する
• CLAUDE.mdに頻出情報をまとめる：毎回説明する必要がある情報（プロジェクト構造、コーディング規約など）はCLAUDE.mdに書いておく。セッションごとの説明コストがゼロになります

複数ファイル変更で品質を保つテクニックを紹介します。

• 段階的に進める：型定義→関数→テストと段階的に指示する。一度に全変更すると整合性が崩れやすい
• テストを先に書く：期待動作をテストで定義し、テストが通るように実装を変更させる
• 既存パターンを手本にする：「このファイルを参照して同じパターンで」と明示的に指示する

大規模変更こそ「小さなステップの積み重ね」が重要です。問題発生時のデバッグが容易になります。

Claude Codeでは、独立したサブタスクを並列に処理するエージェント活用が可能です。

• worktreeを活用した並列作業：Git worktreeを使って複数のブランチを同時に作業できます。「このバグ修正をworktreeで進めて」と指示すれば、メインの作業を中断せずに別タスクを並行処理できます
• Task toolによるサブタスク分離：大きなタスクを独立したサブタスクに分割し、それぞれを並列に実行させることで処理速度を向上させます
• レビューの分離：コードレビューは「微視的視点（コード品質）」と「巨視的視点（設計・仕様）」に分けて、別々のエージェントに任せると品質が向上します

Claude Codeを使ったデバッグの最適なフローは以下のとおりです。

• Step 1：エラーログを貼る：エラーメッセージをそのままClaude Codeに貼り付け、原因調査を指示します
• Step 2：再現テストを書かせる：バグを再現するテストを生成し、修正後のリグレッション防止に活用します
• Step 3：修正を適用する：原因箇所が特定済みなので、ピンポイントで修正を実行します
• Step 4：テストで検証：修正が正しく機能し、他に影響がないことを確認します

ポイントは「先にバリデーション手段を用意する」こと。再現テストにより品質が2〜3倍向上します。GitHub社の調査でもAIツール導入により開発サイクルタイムが75%短縮（9.6日→2.4日）されたと報告されており（GitHub 2024年）、テスト駆動のデバッグフローがこの高速化を支えています。

• ログ出力をサマリー化する：テストの詳細出力はログファイルに保存し、Claude Codeにはサマリーだけを見せる。コンテキストの節約になり、本質的な問題に集中できます
• 型エラーを最初に解消する：TypeScriptの型エラーはバグの早期発見に直結します。「型エラーをすべて修正して」を最初に実行し、型レベルの不整合を解消してからロジックのデバッグに入ります
• git diffで変更範囲を確認する：Claude Codeの修正内容はgit diffで必ず確認しましょう。想定外のファイルが変更されていないか、変更量が適切かをチェックすることで、二次バグを防げます

デバッグスキルをさらに磨きたい方は、あなたの副業タイプを診断することで、自分に合ったスキルアップの方向性が見えてきます。