Claude Codeベストプラクティス完全ガイド｜公式推奨の設定とコツを解説

最終更新日:2026/06/09

Claude Codeを使い始めたものの、思うような結果が得られず戸惑っていませんか。この記事では、公式ドキュメントに基づいたベストプラクティスを体系的に解説します。

本記事を読むことで得られるベネフィットは次の通りです。

• CLAUDE.mdやコンパクション機能（/clear・/compact）を活用してコンテキストを効率的に管理し、出力品質を安定させる方法
• プロンプトの書き方を改善して、意図通りの結果を得るテクニック
• /clearや/rewind、/renameなどのセッション管理コマンドを使いこなし、作業効率を最大化する手法

特に以下のような方に役立ちます。

• Claude Codeで期待した動作が得られず困っている開発者
• より高度な使い方を学んで生産性を向上させたいエンジニア
• チームでClaude Codeを導入し、ベストプラクティスを共有したいリーダー

実践的な具体例とともに、今日から使える改善策をお伝えします。

Claude Codeのベストプラクティスを理解するための前提知識

Claude Codeのベストプラクティスを理解するには、まずこのツールの本質を正しく把握する必要があります。Claude Codeは単なるチャットボットではなく、ファイルを読み込み、コマンドを実行し、問題を自律的に解決する「エージェント型ツール」です。そのため従来のAIチャットとは根本的に使い方が異なります。

公式ドキュメントは「Most best practices are based on one constraint: Claude’s context window fills up fast, and performance degrades as it fills.」と述べています。コンテキストウィンドウとは、セッション内のすべてのメッセージ、読み込んだファイル、コマンド出力を保持する上限のことを指します。

この上限が埋まるにつれて、Claude Codeは以前の指示を忘れたり、ミスが増えたりする傾向があります。つまりコンテキストウィンドウは有限であり、劣化し、注意力にも限界があるという3つの特性を持っています。

この仕組みを理解することが、効果的にClaude Codeを活用するための出発点となります。すべてのベストプラクティスは、この制約をいかに管理し、最大限の成果を引き出すかという視点から設計されています。

Claude Code Docs｜Claude Codeのベストプラクティス

コンテキストウィンドウの「有限・劣化・注意力の限界」という3つの特性

Claude Codeを効果的に使うには、まずコンテキストウィンドウの性質を正しく理解する必要があります。コンテキストウィンドウには3つの重要な特性があります。

1つ目は「有限性」です。トークン数には上限があり、会話が長引くほどその枠を消費していきます。

2つ目は「劣化」です。入力が長くなるほど、特に中間部の情報の参照精度が下がりやすいことが報告されています。

3つ目は「注意配分の制約」です。Transformerの自己注意は全トークン間で正規化された重みを分配するため、コンテキストが長いほど各トークンへ割ける注意が希薄化し、重要指示の取りこぼしが生じやすくなります。

ここで多くの人が陥る罠が「念のためこの情報も入れておこう」という発想です。関連しそうなファイルや過去のやり取りを大量に詰め込むと、かえってコンテキストが汚染され、AIのパフォーマンスが低下します。コンテキスト汚染のサインとしては、以下のような現象が現れます。

• 以前明確に指示した内容を忘れる
• 回答内容が矛盾し始める
• 関係ないファイルを編集し始める

これらの兆候が見えたら、セッションの要約・再構成や不要情報の削除などでコンテキストを整理・リセットすると安定しやすくなります。必要な情報だけを厳選して与えることが、Claude Codeを最大限に活用する第一歩なのです。

公式が示す5つの失敗パターンと修正方法

Claude Codeを使っていると、コンテキストウィンドウの特性を理解していないために陥りやすい失敗パターンがあります。公式ドキュメントでは、特に注意すべき5つの失敗パターンとその修正方法が明示されています。

1.無関係なコンテキストの蓄積
セッションが長引くと、現在のタスクとは無関係な過去のやり取りがコンテキストに残り続け、AIの判断精度が低下します。修正方法としては、タスクが変わるタイミングで/clearコマンドを使い、新しいセッションで再スタートすることが推奨されています。

2.失敗アプローチによるコンテキスト汚染
何度も失敗した試行錯誤の履歴がコンテキストに蓄積すると、AIが誤ったパターンを学習してしまいます。公式では「2回失敗した修正の後は/clearして学んだことを組み込んだ新しいプロンプトを書く」という具体的な対処法を推奨しています。

3.過剰指定のCLAUDE.md
CLAUDE.mdに詳細すぎるルールや制約を書き込むと、すべてのタスクでそれが参照され、かえって柔軟性が失われます。修正方法は、本当にセッション全体で必要な情報だけを記載し、個別の指示は都度プロンプトで与えることです。

4.検証なしの信頼
AIの出力を無批判に受け入れると、エラーやバグが蓄積していきます。公式の修正策は「テスト・スクリプト・スクリーンショット等で常に検証可能にする」ことです。加えて、必要に応じてdiff確認や/costによる支出確認を行うと実務上の安全性が高まります。

5.スコープ無限の探索
「プロジェクト全体を見て改善して」のような曖昧で広範な指示は、AIが膨大なファイルを読み込み、コンテキストを浪費します。修正方法としては、調査範囲を明確に絞るか、サブエージェントを用いて別コンテキストで探索させることが推奨されています。

パターン	こんな状況で起きる	なぜ問題か	公式推奨の修正方法
キッチンシンクセッション （無関係なコンテキストの蓄積）	バグ修正の途中で「そういえばこっちも聞いておこう」と別のことを質問し、また最初のタスクに戻る	関連のない情報でコンテキストが埋まり、最初のタスクに戻ったときに精度が落ちている	無関係なタスクに切り替えるたびに /clear を実行してコンテキストをリセットする
コンテキスト汚染 （失敗アプローチの蓄積）	Claudeが間違えたコードを出力→修正を依頼→また間違える→修正を繰り返す	失敗したアプローチの履歴がコンテキストに残り続け、新しい回答にも悪影響を与える	2回失敗したら/clear。学んだことを取り込んだ新しいプロンプトで最初から書き直す。「試したこと」「残っている課題」を整理してから再開するとなお効果的
過剰指定のCLAUDE.md （長すぎる設定ファイル）	「念のため」とCLAUDE.mdに情報を追加し続け、ファイルが肥大化している	重要なルールがノイズに埋もれてClaudeが半分を無視するようになる	「これを削除するとClaudeが間違いを犯すか？」と自問し、そうでなければ容赦なく削除する。Claudeが指示なしでもすでに正しくやっていることはフックに変換するか削除する
検証なしの信頼 （動いて見えるが壊れている）	「それっぽく動いているから大丈夫」とテストなしで実装を採用し、あとからエッジケースのバグが発覚する	Claudeはもっともらしく見える実装を生成するが、エッジケースの考慮漏れがある。人間が唯一のフィードバックループになり、ミスを見落とす	常に検証を提供する（テスト・スクリプト・スクリーンショット）。検証できないものは出荷しない
無限探索 （スコープなしの調査依頼）	「このあたりを調査して」と曖昧に依頼し、Claudeが数百ファイルを読み込んでコンテキストを使い果たす	コンテキストが膨大な調査結果で埋まり、実装フェーズに入るころには品質が低下している	調査を狭くスコープして依頼する（「〇〇ファイルの認証まわりだけ調査して」など）。またはサブエージェントに委譲してメインのコンテキストを汚染しないようにする

【初心者向け】まず3つだけ実践するクイックウィン

ここまで多くのポイントを紹介してきましたが、「情報量が多くて何から始めればいいかわからない」と感じた初心者の方もいるかもしれません。そこで、使い始めの段階でまず実践したい、即効性が高く学習コストの低い3つのクイックウィンに絞って紹介します。

• /clearを徹底する（タスクが切り替わるたびに会話をリセットし、前のタスクの情報を次の作業に持ち込まない）
• 曖昧な指示を排除する（「いい感じにして」ではなく、どのファイルのどこをどうしたいかを一文で具体的に伝える）
• テストコマンドを提供する（「実装後にnpm testを実行してすべて通ることを確認して」のように検証手段をセットで渡す）

これら3つを最初に選んだのは、5つのベストプラクティスの中でも効果が出るまでが早く、特別な設定や知識を必要としないためです。

環境設定やセッション管理の高度な使い分けといった残りの要素は、基本操作に慣れてから習慣として取り入れれば十分です。まずはこの3つを今日の作業から取り入れてみてください。

ベストプラクティス①：検証手段を与えて出力品質を高める

Claude Codeを使ううえで公式が「最も効果の高い取り組み」と明言しているのが、Claudeに自分の作業を検証する方法を与えることです。

これは単に「動くコードを書いて」と依頼するだけでなく、「どうやって動作を確認するか」という検証手段まで指示に含めることを意味します。

検証手段が与えられていない場合、Claudeは構文的には正しく、一見すると完璧に見えるコードを生成することがありますが、実際に実行すると期待通りに動かないという問題が頻発します。

これはClaude自身が出力を確かめる術を持たないために起こる現象です。

一方で、プロンプトに検証手段を明示的に組み込むと状況は劇的に改善します。具体的には次のような方法が有効です。

• ユニットテストやE2Eテストを書いて実行させる
• 実装後にスクリーンショットを撮影して視覚的に確認させる
• curlコマンドやBashスクリプトでAPIの応答を検証させる
• ログ出力を確認して期待値と一致するか判定させる

これらの検証手段を与えることで、Claude自身がフィードバックループを回せるようになります。特にAuto modeを有効にすれば、「実装→検証→修正→再検証」というサイクルを自律的に繰り返し、人間が介入しなくても出力品質を高められます。

なお、UIの視覚検証についてはPlaywright MCPのようなブラウザ操作ツールと連携することで、自動的にページを開いて比較し、動作するまで反復させることも可能です。検証可能な状態を作ることが、Claude Codeの能力を最大限に引き出す第一歩と言えます。

プロンプトに検証基準を組み込む3つの書き方

プロンプトに検証基準を組み込む方法は、大きく分けて3つのパターンがあります。それぞれの書き方を理解することで、Claudeが自律的に品質を確認できる状態を作れます。

1つ目は「成功基準を数値で指定する」方法です。例えば、validateEmail関数を作成する際に「RFC 5322に準拠し、テストケース10件すべてでtrue/falseが正しく返ることを確認してください」と指示します。Claude Codeのようなターミナル実行環境がある場合は、実装後にテストを実行して結果を報告できます。実行環境がない場合でも、テストコードと期待結果を明示することで、人手またはCIでの検証が容易になります。

2つ目は「UIの変更はスクリーンショットで差分を確認させる」方法です。デザイン変更を依頼する際、期待する画面イメージを貼り付けて「このスクリーンショットと同じレイアウトになるように実装してください」と伝えます。視覚的な基準を与えることで、曖昧さを排除できます。実装後は、生成されたコードのスクリーンショットを撮影してClaudeに添付し、差分の指摘を求めることで、視覚的な検証サイクルを回すことができます。

3つ目は「エラー文を貼り付けて根本原因に対処させる」方法です。ビルドエラーが発生した場合、エラーメッセージ全文をコピーして「このエラーの根本原因を特定し、再発防止策も含めて修正してください」と指示します。

これらの検証基準は、テストスイート、リンター、出力をチェックするBashコマンドといった具体的な手段に落とし込むことが重要です。「品質を確認して」という抽象的な指示ではなく、「npm testを実行してすべてグリーンになることを確認」のように実行可能な形で伝えることで、実行環境やCIと連携しながら品質保証のサイクルを効率的に回せるようになります。

なお、検証基準を組み込むときにあわせて指定しておきたいのが「打ち切り制約」です。検証手段を与えても、修正を繰り返してなおテストが通らない状態に陥ることがあります。これは誤った前提のまま修正を重ね、失敗の履歴がコンテキストを汚染してさらに精度が落ちていく「無限ループ（幻覚の連鎖）」と呼ばれる現象です。

これを防ぐには、「3回修正を試みてもテストが通らなければ、それ以上進めずに現状と原因の仮説を報告して、人間の判断を仰ぐこと」という制約をプロンプトにあらかじめ明示しておきます。

こうしておくと、Claudeが袋小路で延々とトークンを浪費するのを防ぎ、早い段階で人間が軌道修正できるようになります。

パターン	検証基準なしの指示例	検証基準ありの指示例	なぜ有効か	使える場面
成功基準を数値・具体例で指定してテストを実行させる	「メールアドレスを検証する関数を実装する」	「validateEmail関数を書く。テストケースの例：user@example.comはtrue、invalidはfalse、user@.comはfalse。実装後にテストを実行する」	合否の基準が数値・具体例で明示されているため、Claudeがテストを実行して自分で正誤を判断できる。人間がチェックしなくてもフィードバックループが回る	ロジック関数の実装・バリデーション処理・ユーティリティ関数の追加など
スクリーンショットを貼り付けて視覚的に差分を確認させる	「ダッシュボードをより良く見えるようにする」	「[スクリーンショットを貼り付け] このデザインを実装する。結果のスクリーンショットを撮り、元のものと比較する。違いをリストアップして修正する」	「より良く」という曖昧な目標ではなくデザインの画像が正解として機能し、Claudeが実装→スクリーンショット→比較→修正のループを自律的に回せる	UIデザインの変更・レイアウト調整・既存デザインを再現したコード生成など
エラー文を貼り付けて根本原因への対処を指示する	「ビルドが失敗している」	「ビルドがこのエラーで失敗している：[エラーを貼り付け]。修正して、ビルドが成功することを確認する。根本原因に対処し、エラーを抑制しない」	症状だけを伝えるとClaudeがエラーを隠す修正（ログを消す・例外を握りつぶすなど）を選ぶリスクがある。「根本原因に対処」と明示することで本質的な修正に誘導できる	ビルドエラー・テスト失敗・ランタイムエラーのデバッグ全般

diff確認・テスト実行・コスト確認の30秒チェック習慣

Claude Codeが変更を提案したら、すぐに受け入れる前に30秒だけ時間を取って確認する習慣をつけましょう。具体的には次の3点をチェックします。

• diffに意図しない変更が含まれていないか
• テストを実行して正常に通るか
• /costコマンドでトークン消費が想定内か

特に重要なのがdiffの確認です。Claudeは指示された箇所以外にも、コードフォーマットやインポート文を「ついでに」修正することがあります。これらが意図しない副作用を生むケースは少なくありません。

次にテストの実行です。「動いたから大丈夫」という判断は危険です。表面的には動作していても、エッジケースで問題が起きたり、既存機能が壊れていたりする可能性があります。テストを通すことで、変更の影響範囲を客観的に検証できます。

最後にコスト確認です。/costコマンドで現在のセッションのトークン・費用を確認しておくと、想定以上にコンテキストが肥大化していないかを早期に気づけます。

この3点チェックを習慣化すると、手戻りが劇的に減ります。結果として開発速度が上がり、Claudeへの信頼度も高まります。最初は面倒に感じるかもしれませんが、30秒の投資が後の数時間を節約してくれるのです。

ベストプラクティス②：「探索→計画→実装→検証」の4段階で進める

Claude Codeに「この機能を実装して」といきなり指示すると、一見動くコードが生成されても、実は間違った問題を解決している場合があります。これは、Claudeが現在のコードベースの構造や設計意図を十分に理解しないまま実装に進んでしまうためです。

公式が推奨する基本の流れは、探索（Explore）→計画（Plan）→コード（Code）→コミット（Commit）の4段階です。

まず探索フェーズでは、関連するファイルやコードの構造を調査し、既存の実装パターンや依存関係を把握します。次に計画フェーズで、どのファイルをどう変更するか、どんなテストが必要かを明確にします。

そして実装フェーズで実際にコードを書き、テストを実行して意図通りに動くか検証します。最後にコミットフェーズで変更を確定させます。なお、検証（テストや期待結果の確認）は特に実装段階で行うことが強く推奨されています。

この4段階アプローチが重要な理由は、トークンコストと手戻りの削減にあります。いきなり実装すると、間違った方向で大量のコードを生成し、後で全面的な修正が必要になることがあります。一方、探索と計画に時間をかければ、実装は一度で正しく完了し、結果的にトークン消費も少なくなります。

Plan Modeは、この探索と実行を分離するために設計された機能です。Plan Modeを有効にすると、Claudeはまず変更計画を提示し、承認を得てから実装に進みます。これにより、間違った方向に進む前に軌道修正でき、公式が推奨するワークフローの核心となっています。

4段階ワークフローの具体的な進め方

4段階ワークフローは、大規模な変更や複雑なタスクに取り組む際に特に有効です。まず第1段階の「探索」では、Plan Modeに入ってClaudeにプロジェクト全体を調査させます。この段階ではShift+Tabキーで権限モードを切り替えてPlan Modeに入り、「このプロジェクトの構造を分析して、認証機能を追加するための影響範囲を調査してください」といった指示を出します。Claudeはファイルを読み込みながら、変更が必要な箇所を特定していきます。

第2段階の「計画」では、Claudeに詳細な実装計画を作成させます。「先ほどの調査結果をもとに、ステップバイステップの実装計画を作成してください」と依頼すると、Claudeは変更すべきファイルと具体的な修正内容をリストアップします。ここで重要なのは、生成された計画をCtrl+Gでテキストエディタに取り込み、人間が直接レビュー・編集することです。不要な変更を削除したり、優先順位を調整したりすることで、実装の方向性を正確にコントロールできます。

第3段階の「実装」では、編集した計画をもとにPlan Modeを抜けて実際のコーディングを進めます。「この計画に従って実装を開始してください」と指示すれば、Claudeは計画に沿ってファイルを順次修正していきます。Plan Modeは読み取り専用のため、実装段階ではdefault（都度確認）またはacceptEdits（自動承認）モードに切り替える必要があります。

最後の第4段階「検証」では、変更内容を確認し、説明的なコミットメッセージやPRの作成を依頼します。「今回の変更内容を要約して、わかりやすいコミットメッセージとPR説明文を作成してください」と指示することで、チーム全体が理解しやすいドキュメントが生成されます。

Plan Modeを使う場面と直接実行してよい場面の判断基準

Plan Modeを使うべきか直接実行してよいかの判断は、タスクの複雑さと影響範囲によって決まります。Plan Modeが有効な場面としては、アプローチが不確かで試行錯誤が必要な場合、変更が複数ファイルに及ぶ場合、慣れていないコードベースを扱う場合などが挙げられます。一方で直接実行してよい場面は、タイポ修正やログ行の追加、1文で説明できる小さな変更など、影響範囲が明確で限定的なタスクです。

具体的な判断基準として、以下のような使い分けが推奨されています。

【Plan Modeを使うべき場面】

• 複数のファイルにまたがる変更が必要なとき
• 実装方法が複数考えられ、最適なアプローチを検討したいとき
• 既存コードの構造を理解してから変更する必要があるとき

【直接実行してよい場面】

• 単純なタイポや文字列の修正
• 1行のログ出力やコメントの追加
• 明確で局所的な変更

公式の目安としては、変更が2〜3ファイルを超える場合はPlan Modeで計画から始めることが推奨されています。Planの作成自体にも数百トークン程度のオーバーヘッドがあるため、極めて小さな変更は直接実行が効率的です。迷った場合は、変更の影響範囲が広いかどうかを基準に判断すると良いでしょう。

判断	条件	タスクの例	理由
Plan Mode を使う	アプローチが不確かで、どう実装するか迷っている	「認証にGoogle OAuthを追加したい。何のファイルを変えればいい？」	方向性が決まる前にコードを書くと、間違った問題を解決するコードが生成されるリスクがある
	変更が複数のファイルにまたがる	「決済フローをStripe v2からv3に移行する」	影響範囲を把握してから実装しないと、変更漏れや整合性の崩れが起きやすい
	慣れていないコードや新規参画したコードベースを触る	「初めて触るサービスの認証まわりにバリデーションを追加する」	既存の実装パターンや依存関係を理解せずに書くと、一貫性を崩す変更になりやすい
	手作業で5分以上かかる規模のタスク（5分ルール）	「APIエンドポイントに認証ミドルウェアを追加する」	事前計画に数分かけることで、大きな手戻りを防げる。トークンコストでも事前投資のほうが得
直接実行してよい	スコープが明確で変更が小さい	タイポの修正・ログ行の追加・変数名の変更	差分を1文で説明できるレベルの変更は、計画のオーバーヘッドのほうがコストになる
	差分を1文で説明できる	「README のインストール手順の誤字を直す」	公式が明示する最もシンプルな判断基準。1文で言えるなら計画は不要
	手作業で5分未満で終わる規模のタスク（5分ルール）	「コメントを英語から日本語に書き直す」	小さな作業に計画フェーズを挟むと、かえって時間とトークンを消費する

ベストプラクティス③：具体的なプロンプトとリッチコンテキストの提供

Claude Codeに対する指示は、具体的であればあるほど期待通りの結果が得られやすくなります。公式ドキュメントでも「指示がより正確であるほど必要な修正が少なくなる」と明記されており、これはトークン消費の観点からも重要な原則です。

曖昧な指示を出すと、Claudeは意図を推測しながら複数回の試行錯誤を繰り返すことになり、結果として不要なトークンを浪費してしまいます。たとえば「データベースを最適化して」という指示では、インデックスを追加するのか、クエリを書き換えるのか、テーブル設計を見直すのか判断がつきません。一方「usersテーブルのemailカラムにインデックスを追加して検索速度を改善して」と具体的に伝えれば、一度で正確な実装が可能になります。

さらに重要なのが、リッチコンテキストを積極的に提供することです。Claude Codeには文脈を正確に伝えるための複数の手段が用意されています。

• @記法でファイルやフォルダを直接参照する
• 画像をチャットに貼り付けて視覚情報を共有する
• URLを指定してウェブページの内容を読み込ませる
• パイプ機能でコマンド出力やログを直接渡す

これらの方法を使うことで、口頭で説明するよりも遥かに正確な情報をClaudeに伝えられます。特に@記法は強力で、「@src/components/Button.tsxのスタイルを参考に新しいコンポーネントを作って」のように指定すれば、既存コードの文脈を完全に理解した上で作業を進めてくれます。

エラーが発生した場合も、スクリーンショットを貼り付けるだけで状況を即座に把握できるため、説明の手間が大幅に削減されます。具体的な指示とリッチコンテキストの組み合わせが、Claude Codeを最大限に活用する鍵となります。

曖昧な指示と具体的な指示のビフォー・アフター比較

Claude Codeに指示を出す際、曖昧な表現と具体的な表現では出力品質に大きな差が生まれます。公式ドキュメントでは、効果的な指示を作るための4つの改善戦略が示されています。

第一に「タスクをスコープする」では、「コードを修正して」という曖昧な指示ではなく、「src/utils/parser.pyの行50-65にあるJSON解析ロジックを修正して、ネストした配列を正しく処理できるようにして」と範囲と目的を明示します。

第二に「ソースを指摘する」では、「エラーが出る」ではなく「実行時にTypeError: ‘NoneType’ object is not subscriptableが発生する」と具体的な症状を伝えます。第三に「既存のパターンを参照する」では、「良い感じにして」ではなく「models/user.pyと同じバリデーション方式を適用して」と参照先を示します。

第四に「症状を説明する」では、「動かない」ではなく「APIレスポンスが200を返すがデータベースに保存されない」と観察事実を記述します。

具体的な指示を作るには、次の5項目チェックリストが有効です。

• 何を(対象ファイル・機能・コンポーネント)
• どこを(行番号・関数名・クラス名)
• なぜ(背景・目的・解決したい問題)
• どこまで(完了条件・期待する動作)
• 制約(使用技術・パフォーマンス要件・互換性)

このうち最低限「何を」と「どこまで」の2項目を含めることで、Claude Codeの出力精度は大きく向上しやすくなります。

改善戦略	曖昧な指示（ビフォー）	具体的な指示（アフター）	改善のポイント
タスクをスコープする （どのファイル・どのシナリオ・テスト設定を指定する）	「foo.pyのテストを追加する」	「ユーザーがログアウトしているエッジケースをカバーするfoo.pyのテストを書く。モックを避ける」	「何のケースを」「どんな制約で」を明示する。制約（モック不使用など）が特に重要
ソースを指摘する （Claudeが答えを見つけられるソースに向ける）	「ExecutionFactoryがこんなに奇妙なAPIを持っているのはなぜですか？」	「ExecutionFactoryのgit履歴を調べて、そのAPIがどのようになったかを要約する」	答えが存在するソース（git履歴・コメント・ドキュメントのURL）を具体的に指定する
既存のパターンを参照する （コードベース内の具体例をClaudeに見せる）	「カレンダーウィジェットを追加する」	「ホームページで既存のウィジェットがどのように実装されているかを見て、パターンを理解する。HotDogWidget.phpが良い例。パターンに従って月選択・ページネーション付きのカレンダーウィジェットを実装する。コードベースで既に使用されているもの以外のライブラリを使わない」	参照させる具体的なファイル名・「既存のパターンに従う」という制約・使ってよいライブラリの範囲を明示する
症状を説明する （症状・場所・「修正」の姿を伝える）	「ログインバグを修正する」	「ユーザーはセッションタイムアウト後にログインが失敗すると報告している。src/auth/の認証フロー、特にトークン更新を確認する。問題を再現する失敗するテストを書き、修正する」	「いつ起きるか（再現条件）」「どこを見るか（調査対象）」「修正が完了した状態（テストが通る）」の3点を含める

@参照・画像貼り付け・パイプでコンテキストを正確に渡す方法

Claude Codeに正確なコンテキストを渡すには、3つの主要な手段を使い分けることが重要です。

1つ目は「@ファイルパス」による直接参照です。プロンプト内で「@src/components/Button.tsx」のように記述すると、そのファイルの内容全体がコンテキストとして読み込まれます。複数ファイルを同時に参照したい場合は@を複数列挙するか、作業対象を広げたいディレクトリはCLIの–add-dirまたは対話中の/add-dirで追加してください（例：claude –add-dir ./src ./packages/ui）。

2つ目は画像やスクリーンショットの貼り付けです。エラー画面やデザインモックアップ、UIの完成イメージなどを直接コピー＆ペーストでチャット欄に貼り付けることで、言葉では説明しにくい視覚情報を正確に伝えられます。特にUIの実装やバグ修正では、実際の画面を見せることで認識のズレを大幅に減らせます。

3つ目はパイプを使ったコマンド出力の受け渡しです。ターミナルで「cat error.log | claude -p ‘このエラーの原因を要約して’」や「git diff | claude -p ‘この差分をレビューして’」のように実行すると、ログやdiff結果を直接Claudeに渡せます。エラーログが長大な場合や、複数のファイル変更を一度に確認してほしい場合に特に有効です。これらの手段を組み合わせることで、曖昧さを排除した正確なコンテキスト提供が実現できます。

ベストプラクティス④：環境設定でセッション全体の効率を高める

Claude Codeには、セッション全体の効率を大きく左右する環境設定が用意されています。主要なものは「CLAUDE.md」「Hooks」「パーミッション（Permissions）」「Skills」「サブエージェント（Subagents）」の5つです。

加えて、出力スタイル（Output styles）を使うとトーンや形式を統一できます。公式ドキュメントでは「数回のセットアップでセッション全体の効率が大きく変わる」と明言されており、これらの設定を適切に行うことで、毎回同じ指示を繰り返す手間を省き、一貫性のある出力を得られるようになります。

特に重要なのが、HooksとCLAUDE.mdの使い分けです。公式は明確な基準を示しています。

• 例外なく毎回起きてほしい処理はHooksで設定する（決定論的）
• 判断が必要なガイダンスや方針はCLAUDE.mdに記述する（助言的）

この違いを理解すると、設定の効果が飛躍的に高まります。たとえば「コミット前にテストを実行する」は、原則としてCLAUDE.mdに”Always do X”のルールとして記述し、確実な強制が必要ならPreToolUseなどのHookで実行・ブロックを組み合わせる二段構えが推奨です。

「コードスタイルはできるだけ関数型で書く」といった方針はCLAUDE.mdでガイダンスとして示します。パーミッションは外部APIやファイルアクセスの権限を制御し、Skillは特定のタスクに特化した機能を追加します。

さらにサブエージェントを活用すれば、調査や検証といった補助的なタスクを別のコンテキストで実行でき、メインセッションのコンテキストウィンドウを節約できます。これらの設定は一度行えば継続的に効果を発揮するため、プロジェクト開始時に時間をかけて整備する価値があります。

効果的なCLAUDE.mdの書き方と公式推奨テンプレート

CLAUDE.mdは、プロジェクトのルートディレクトリまたはホームディレクトリ（~/.claude/）に配置することで、Claudeが自動的に読み込む特別な設定ファイルです。

作業ディレクトリから上位にあるCLAUDE.md/CLAUDE.local.mdは会話開始時に自動で読み込まれ、子ディレクトリ配下のCLAUDE.mdは該当ディレクトリのファイルを参照する際にオンデマンドで取り込まれます。

このファイルを適切に設定すると、Bashコマンドの実行方法、コードスタイルの指定、ワークフロールール、プロジェクト固有のアーキテクチャなど、「コードだけからは推測できない永続的なコンテキスト」をClaudeに与えることができます。

CLAUDE.mdに含めるべき項目と除外すべき項目を整理すると、次のようになります。

【含めるべき項目】

• プロジェクト固有のBashコマンドやビルドスクリプト
• デフォルトと異なるコードスタイルルール
• テスト実行の指示や検証手順
• プロジェクト固有のアーキテクチャやディレクトリ構成
• よくある落とし穴や注意事項

【除外すべき項目】

• コードを読めば分かる情報
• 一般的な言語規約や標準的なベストプラクティス
• 詳細なAPIドキュメント
• 頻繁に変わる情報やタスクリスト

公式が推奨する判断基準は、「これを削除するとClaudeがミスを犯すか？」と自問することです。この問いに「いいえ」と答えられるなら、その情報は削除して構いません。

また、CLAUDE.mdでは「@path/to/import」記法（例：@README、@docs/guide.md）で外部ファイルを取り込むこともできます。

置き場所については、グローバル設定は~/.claude/CLAUDE.md、プロジェクト固有の設定はプロジェクトルートのCLAUDE.md、個人用のローカル設定はCLAUDE.local.md、特定のサブディレクトリ用の設定は子ディレクトリのCLAUDE.mdに記述します。

含めるべき項目	判断基準	記述例
Claudeが推測できないBashコマンド	コードを読んでも正確なコマンドがわからない・プロジェクト独自のスクリプトが存在する	npm run dev（開発サーバー起動）/ npx prisma migrate dev（マイグレーション実行）
デフォルトと異なるコードスタイルルール	チームが独自に定めた命名・ファイル配置・記法のルール	「ES modules（import/export）を使う。CommonJS（require）は使わない」/ 「importはdestructuringで書く」
テスト指示と推奨テストランナー	テストのフレームワーク・実行コマンド・方針がプロジェクト固有のもの	「テストはVitestで。npm run testで実行。テストスイート全体より単体テストを優先してパフォーマンスを保つ」
リポジトリのエチケット（ブランチ命名・PR規約）	チーム独自のGitワークフロー・コミットメッセージ規約	「コミットメッセージは日本語。1コミット1機能。ブランチ名はfeature/〇〇形式」
プロジェクト固有のアーキテクチャ決定	「なぜこの構成にしたか」がコードから読み取れない設計判断	「src/legacy/は段階的移行中のため触らない」/ 「認証はNextAuth v5で統一する」
開発者環境の癖（必須環境変数）	ローカル環境固有の設定・前提条件	「実行前にDATABASE_URLとSESSION_SECRETの環境変数が必要」
一般的な落とし穴や非自明な動作	過去に問題が起きた箇所・初見では気づきにくい制約	「外部ライブラリを追加するときは必ず確認してから」/ 「src/legacy/は移行中のため変更禁止」

除外すべき項目	除外する理由	書いてしまうとどうなるか
Claudeがコードを読めばわかること	関数の役割・変数名の意味・ファイルの依存関係はコードを読めば自明	CLAUDE.mdが無意味に長くなり、本当に重要なルールの優先度が下がる
Claudeが既に知っている標準言語規約	インデントの幅・セミコロンの有無など、その言語の標準的なルール	Claudeはすでに知っているため書いても効果がなく、ファイルが膨らむだけ
詳細なAPIドキュメント（代わりにリンクを貼る）	外部ライブラリのメソッド一覧・引数の型定義などは公式ドキュメントにある	内容が古くなってもClaudeが信じ続け、ドキュメントと食い違うコードが生成される
頻繁に変わる情報	現在のバージョン番号・一時的な実装の詳細・WIPの機能仕様	CLAUDE.mdのメンテナンスコストが上がり、古い情報に基づいた誤った実装が増える
長い説明やチュートリアル	背景説明や使い方の解説はドキュメントに置くべき	CLAUDE.mdが膨れ上がり、Claudeが重要なルールを見落とすようになる
ファイルごとのコードベースの説明	各ファイルの役割説明はClaude自身がコードを読んで把握できる	不要な情報でコンテキストが埋まり、実際の指示への注意力が下がる
「きれいなコードを書く」のような自明な方針	Claudeがデフォルトで守っている常識的な原則	書いても動作に影響しないため、ファイルが無意味に長くなるだけ

【発展編】Hooks・パーミッション・Skillの設定方法と使い分け

Claude Codeでは、Hooksを使うことで「ファイル編集後に毎回ESLintを自動実行する」「migrationsフォルダへの書き込みをブロックする」といった決定論的な自動実行を設定できます。

Hooksは.claude/settings.jsonなどに設定ブロックを記述し、イベントごとにシェルコマンドやスクリプトを実行する仕組みです。LLMの判断に依存せず決定論的に動作するため、毎回同じ指示を繰り返す手間を省けます（自然言語で要件を伝えてClaudeに設定を生成させることも可能です）。

パーミッション制御には複数のモード（default／acceptEdits／plan／auto／dontAsk／bypassPermissions）と、allow/ask/denyのルール、サンドボックスなどの手段があり、目的に応じて組み合わせます。ここでは代表的な使い分け例を3つ紹介します。

• Auto mode：分類器による安全性チェックを通過した操作はプロンプトなしで実行し、危険と判断された操作はブロック（または手動承認にフォールバック）します。探索的な作業や長時間タスクでプロンプト疲労を軽減したいときに有効
• ホワイトリスト：特定のディレクトリやコマンドだけ許可するallow/askルールを設定。本番環境や重要なファイルを保護したいときに使う
• サンドボックス：テスト環境に限定して実行。未検証のコードや実験的な変更を安全に試したい場合に適している

さらに、.claude/skills/ディレクトリにドメイン知識やワークフローを分離して定義できるSkill機能も重要です。たとえばAPIコーディング規約やIssueの修正手順を`.claude/skills/<スキル名>/SKILL.md`というディレクトリ構造で定義しておけば、CLAUDE.mdに長々と書き込む必要がなくなります。

これによりCLAUDE.mdをシンプルに保ちながら、プロジェクト固有の知識を体系的に管理できるようになります。Skillは再利用可能なので、複数のセッションで同じ手順を何度も説明する無駄も省けます。

【発展編】サブエージェントでコンテキストを分離して調査・検証する方法

サブエージェントは独立したコンテキストウィンドウで動作するため、メインセッションを汚染することなく調査や検証を委譲できる強力な機能です。

例えば大量のログファイルを調べたり、実装後のエッジケースを網羅的にレビューしたりする際、メインの会話履歴に膨大な情報が混入すると本来の作業効率が低下してしまいます。こうした場面でサブエージェントを活用すれば、調査結果の要約だけをメインセッションに持ち帰ることができます。

基本的な使い方として、自然文でサブエージェント名を明示するか（例:”Use the test-runner subagent to …”）、@メンションで指定すると、そのタスクで確実にサブエージェントが実行されます。必要に応じて/agentsコマンドで作成や管理もできます。

さらに高度な使い方として、.claude/agents/ディレクトリにカスタムサブエージェントを定義することもできます。具体的には以下の要素を含むYAMLフロントマター付きのMarkdownファイル（.md）を作成します。

• name:サブエージェントの名前
• description:役割や目的の説明
• tools:利用可能なツールのリスト
• model:使用するClaudeモデルの指定

この設定により、特定の用途に特化したサブエージェントを繰り返し呼び出せるようになり、コンテキストの分離と作業効率の両立が実現できます。

ベストプラクティス⑤：セッション管理とコンテキストの積極的なコントロール

Claude Codeの公式ドキュメントは「会話は永続的で可逆的（persistent and reversible）」であることを活用するよう推奨しています。会話はローカルに保存され、既定では30日で自動クリーンアップされます（設定で変更可能）。これはつまり、セッションを単なる一方通行のやり取りとして捉えるのではなく、必要に応じて巻き戻したり圧縮したりできる柔軟な作業空間として扱うべきだという考え方です。

コンテキストウィンドウは有限であり、会話が長引くほど注意力が分散し、応答品質が劣化していきます。そこで重要になるのが、3つのコマンドを使った積極的なコンテキスト管理です。

まず/clearは、現在のコンテキストをリセットして新しい会話を開始するコマンドです。全く異なるタスクに移行する際や、コンテキストが混乱してきたと感じたときに使用します。なお、直前の会話は/resumeで再開できます（プロジェクトのメモリは保持されます）。

次に/compactは、会話履歴を要約して圧縮し、トークン使用量を削減しながら重要な情報は保持するコマンドです。長い会話の中で本質的な情報だけを残したい場合に有効です。

そして/rewindは、チェックポイントに基づいて会話やコードを過去の状態に復元できるコマンドです。

誤った方向に進んでしまったと気づいたとき、やり直したい分岐点まで戻ることができます。また「そこから先だけ要約」や「そこまでを要約」で一部のみを圧縮することもできます。

これらのコマンドを適切に使い分けることで、コンテキストウィンドウの限界に達する前に予防的に管理でき、常に高品質な応答を維持できます。

公式は「コンテキストが重くなってきたと感じたら躊躇せずリセットする」という直感を養うことを推奨しており、受動的に待つのではなく能動的にセッションをコントロールする姿勢が、Claude Codeを使いこなす上での重要なベストプラクティスとなります。

/clear・/compact・/rewindの使い分け基準と活用のコツ

Claude Codeでは、セッションの状態を管理する3つのコマンドが用意されており、それぞれ適切な場面で使い分けることで作業効率が大きく向上します。

まず、無関係なタスクに切り替えるときは/clearを使用します。これは現在の会話コンテキストをリセットして新しいセッションを開始するコマンドです。前の会話は/resumeから再開でき、プロジェクトメモリ（CLAUDE.mdなど）は保持されるため、前のタスクの情報が次のタスクに影響を与えないようにしたい場合に有効です。

次に、同じタスクを続けながらコンテキストを圧縮したいときは/compactを使います。このコマンドは会話履歴を要約して保持しながらトークン数を削減するため、長時間の作業でコンテキストウィンドウが圧迫されてきたときに役立ちます。特に焦点を指定した使い方、例えば「/compact APIの変更に集中して」のように実行すると、重要な情報を優先的に保持できます。

そして、方向性が間違っていたと気づいたときは/rewindまたはEsc×2でチェックポイントへ巻き戻すことができます。これにより、誤った実装を進める前の状態に戻って、別のアプローチを試すことが可能になります。

3つのコマンドの使い分けを整理すると次のようになります。

• /clear：全く別のタスクに移行するとき、会話コンテキストをリセットしたいとき
• /compact：同じタスクを継続しながらトークン数を削減したいとき、特定の焦点に絞りたいとき
• /rewind：誤った方向に進んだと気づいたとき、以前の状態に戻りたいとき

さらに高度な活用方法として、CLAUDE.mdに「コンパクション時は変更ファイルの一覧とテストコマンドを常に保持すること」のような指示を記述することで、/compact実行時の動作をカスタマイズできます。

コマンド	操作方法	コンテキストへの影響	使うタイミング
/clear	セッション内で/clearを実行	会話履歴をすべて完全にリセットしてゼロに戻す	無関係なタスクに切り替えるとき・同じ問題を2回以上修正しても解決しないとき
/compact	/compactまたは/compact <焦点の指示>	会話履歴を要約して圧縮する。重要なコード・決定・ファイル状態は保持される	同じタスクを続けたいがコンテキストが膨らんできたとき
/rewind （またはEsc×2）	/rewindを実行またはEscを2回押す	以前のチェックポイントに戻る。「会話のみ」「コードのみ」「両方」の3択で復元できる	方向性が間違っていると気づいたとき・別のアプローチを試したいとき

セッションの命名・再開と公式が推奨する直感の養い方

セッション管理を効率化するには、まず/renameコマンドで作業内容を表すわかりやすい名前を付けることが重要です。

例えば「oauth-migration」や「api-refactoring」のように命名すると、後から見返したときに何を作業していたかが一目で把握できます。この命名されたセッションは、Gitのブランチのように管理でき、複数のタスクを並行して進める際に混乱を防げます。

セッションを再開する主な方法は次のとおりです。

• claude –continue:直前のセッションを続ける
• claude –resume <セッション名>:特定の名前付きセッションを再開する

なお、セッション内では/resumeコマンドでも再開でき、claude –resumeを引数なしで実行するとセッションピッカーが開きます。これらのコマンドを使い分けることで、中断した作業を素早く再開でき、コンテキストを最初から説明し直す手間が省けます。

ただし公式ドキュメントでは重要な指摘がされています。それは「ガイドのパターンは固定されていない」という点です。つまり、いつ具体的な指示を出すべきか、いつ計画モードを使うべきか、いつコンテキストをクリアすべきかは、状況によって変わるということです。

公式は画一的なルールではなく、実際の使用を通じて「この場面ではこうする」という直感を養うことを推奨しています。セッションを重ねるごとに、自分のプロジェクトに最適な使い方が見えてくるはずです。

まとめ

Claude Codeを効果的に活用するためには、AIの特性を理解した上で適切な使い方を身につけることが重要です。

本記事では、検証手段の提供、4段階ワークフローの実践、具体的なプロンプトとリッチコンテキストの活用、環境設定による効率化、そしてセッション管理とコンテキストのコントロールという5つのベストプラクティスを紹介しました。

これらの手法を組み合わせることで、Claude Codeの出力品質を高め、開発効率を大幅に向上させることができます。特に重要なのは、コンテキストウィンドウの限界を意識しながら、適切なタイミングで/clearや/compactを使い分けることです。

また、CLAUDE.mdによる環境設定やサブエージェントの活用により、セッション全体の生産性を底上げできます。まずは検証基準を組み込んだプロンプトと30秒チェック習慣から始めて、徐々に高度なテクニックを取り入れていくことをお勧めします。実践を重ねながら自分なりの使い方を確立し、Claude Codeを開発パートナーとして最大限に活用してください。

アイスマイリーでは、生成AI のサービス比較と企業一覧を無料配布しています。課題や目的に応じたサービスを比較検討できますので、ぜひこの機会にお問い合わせください。