Claude Code ベストプラクティスガイド

概要

Claude Codeは、単にコードをレビューするだけでなく、ファイルを読み取り、コマンドを実行し、自律的にソリューションを実装できるエージェント型コーディング環境です。その効果を最大限に引き出すには、ウィンドウが一杯になるとパフォーマンスが低下するため、すべてのメッセージ、ファイル読み取り、コマンド出力が保存されるコンテキストウィンドウを管理する必要があります。

自律的な検証の実装

ユーザーが唯一の検証ループにならないようにするために、タスクが完了したかどうかを判断するための決定論的なシグナルをClaude Codeに提供する必要があります。

検証戦略

  • 検証基準: 曖昧な要求の代わりに、具体的なテストケース（例：「validateEmail関数を書いてください。user@example.comはtrue、無効なものはfalseです」）を提供し、Claudeにそれらを実行するよう指示します。
  • 視覚的検証: UIの変更については、デザインのスクリーンショットを提供し、結果のスクリーンショットを撮って差異をリストアップするようClaudeに指示します。
  • 根本原因分析: ビルドの修正を行う際は、特定のエラーを提供し、エラーを抑制せずにビルドが成功することを要求します。

ゲーティングメカニズム

必要な自律性のレベルに応じて、検証は以下のように実装できます：

  • シングルプロンプト: 1つのメッセージでチェックと反復を要求する。
  • ゴール条件 (/goal): 別の評価者を使用して、ターンごとに条件を再チェックする。
  • ストップフック: 特定のチェックがパスするまでターンの終了をブロックするスクリプト。
  • 検証サブエージェント: 新しいモデルを使用して、プライマリエージェントの結果に反論させる。

ワークフロー：探索、計画、およびコーディング

いきなりコーディングを始めると、間違った問題を解決してしまう可能性があります。Anthropicは、探索と実行を分離するために plan mode を使用した4フェーズのワークフローを推奨しています：

  1. Explore (探索): コードベースと問題を理解する。
  2. Plan (計画): 実装戦略を定義する。
  3. Code (コーディング): 計画を実行する。
  4. Verify (検証): ソリューションが基準を満たしていることを確認する。

プロンプトとコンテキストの最適化

具体的なコンテキストの提供

プロンプトの精度を高めることで、曖昧さを減らしエラーを防ぐことができます。効果的な戦略には以下が含まれます：

  • タスクのスコープ設定: 正確なファイル、シナリオ、テストの好み（例：「mockの使用を避けてください」）を指定する。
  • ソースの指示: アーキテクチャに関する質問に答えるために、特定のgit履歴やファイルをClaudeに指し示す。
  • パターンの参照: 一貫性を確保するために、既存のコードベースの例（例：「HotDogWidget.php」）をClaudeに指示する。
  • 症状の説明: エラー、発生しそうな場所、「修正済み」の定義を提供する。

リッチなコンテンツの統合

  • @ 参照: @ を使用してファイルを直接参照し、Claudeが応答する前にそれらを読み取るようにする。
  • 直接入力: 画像を貼り付ける、ドキュメントのURLを提供する、または cat error.log | claude を使用してデータをパイプする。
  • 自律的な取得: BashコマンドやMCPツールを使用して、必要なコンテキストを取得するようClaudeに指示する。

環境設定

CLAUDE.md ファイル

CLAUDE.md は、すべてのセッションの開始時に読み込まれる永続的なコンテキストファイルです。コンテキストウィンドウの肥大化を避けるために、簡潔に保つ必要があります。

  • 含めるべきもの: 非自明なBashコマンド、カスタムコードスタイルルール、推奨されるテストランナー、リポジトリのエチケット、プロジェクト固有のアーキテクチャの決定。
  • 含めるべきでないもの: 標準的な言語の慣習、詳細なAPIドキュメント（代わりにリンクを使用）、頻繁に変更される情報。

権限と自動化

  • Auto Mode: 分類モデルを使用して、リスクの高いアクション（例：権限の昇格）のみをブロックし、手動承認の必要性を減らします。
  • 権限許可リスト: npm run lint のような安全なツールを明示的に許可する。
  • サンドボックス化: ファイルシステムとネットワークへのアクセスを制限するためのOSレベルの隔離。

拡張機能とツール

  • CLIツール: GitHub CLI (gh) のようなツールをインストールすると、ClaudeはAPI経由よりも効率的にIssueやPRを管理できます。
  • MCPサーバー: ClaudeをIssueトラッカー、データベース、Figmaデザインに接続します。
  • フック: 特定のポイントで実行される決定論的なスクリプト（例：編集のたびに eslint を実行する）。
  • スキル: /skill-name で呼び出すことができる、.claude/skills/ に保存されたプロジェクト固有の知識。
  • サブエージェント: メインセッションを乱さないように、大規模な調査や対抗レビューに使用される独立したコンテキスト。
  • プラグイン: スキル、フック、MCPサーバーのバンドルされたユニット。型付き言語用のコードインテリジェンスプラグインを含む。

セッション管理

コンテキストの維持

コンテキストウィンドウが主要な制約であるため、積極的な管理が必要です：

  • /clear: 「何でもありセッション」を防ぐために、無関係なタスクの間でコンテキストをリセットする。
  • /compact: 会話履歴の要約を手動でトリガーする。
  • /btw: 会話履歴に保存すべきでないサイド質問に使用する。
  • 軌道修正: Claudeが同じ問題で2回失敗した場合は、セッションを /clear し、より具体的なプロンプトでやり直す。

状態制御

  • 巻き戻しとチェックポイント: Esc + Esc または /rewind を使用して、以前のコード状態または会話履歴を復元する。
  • 再開: claude --continue または claude --resume を使用して、以前のセッションを継続する。

スケーリングと自動化

非対話モード

claude -p "prompt" を使用すると、CIパイプラインやpre-commitフックへの統合が可能になり、出力はプレーンテキスト、JSON、またはストリーミングJSONで利用できます。

並列実行

  • Worktrees: 個別のCLIセッションのための隔離されたgitチェックアウト。
  • エージェントチーム: チームリーダーによる複数のセッションの自動調整。
  • Writer/Reviewerパターン: バイアスを排除するために、実装とレビューに別のセッションを使用する。

Fan-outパターン

大規模な移行の場合、ユーザーはファイルを特定し、タスクのリストを生成し、並列の非対話呼び出しを実行することで、作業を分散させることができます。

避けるべき一般的な失敗パターン

  • The Kitchen Sink Session (何でもありセッション): 1つのセッションに無関係なタスクを混ぜる。/clear を使用して解決。
  • 過剰な修正: 同じエラーを繰り返し修正する。より良いプロンプトでセッションを再起動して解決。
  • 詳細すぎる CLAUDE.md: ルールが多すぎてClaudeが指示を無視する。整理して解決。
  • 信頼と検証のギャップ: 妥当だがテストされていないコードをリリースする。決定論的な検証を要求して解決。
  • 無限の探索: コンテキストを埋め尽くすスコープのない調査。サブエージェントを使用して解決。

Sources

関連