Claude Code ベストプラクティスの要約

Posted at 2026-01-24

はじめに

AnthropicがClaude Code公式ドキュメントにベストプラクティスガイドを公開しました。

本記事では、この公式ガイドの内容を日本語で要約し、実践的なポイントを解説します。

この記事は公式ドキュメントの要約に、自身の経験から補足を加えたものです。
最新情報は原文をご確認ください。

TL;DR

成功基準を明確にする - 検証手段を与えて手戻りを防ぐ
探索→計画→実装 - 段階を分けて問題を解決
具体的なコンテキスト - 精度を上げて修正サイクルを減らす
多様な入力手段を活用 - ファイル参照、画像、パイプなど
環境を整える - CLAUDE.md、Skills、Hooks、MCPを活用
効果的にコミュニケーション - 質問や壁打ちでClaudeを活用
セッション管理 - /clear、巻き戻し、サブエージェントで効率化
自動化とスケール - ヘッドレスモードと並列セッションで拡張
失敗パターンを避ける - キッチンシンク、過剰修正、無限探索に注意
直感を養う - パターンを観察し、柔軟に適用する

最重要原則：コンテキストウィンドウの管理

Claude Codeにおける最大の制約はコンテキストウィンドウです。コンテキストが埋まるにつれてパフォーマンスが低下するため、これを最優先で最適化する必要があります。

10のベストプラクティス

1. 成功基準を明確にする

ユーザーとClaudeの間で「何をもって完了とするか」の認識を揃えることで、手戻りの発生を防ぎます。曖昧な指示では、Claudeの解釈がユーザーの意図と異なり、修正のやり取りでコンテキストを浪費してしまいます。

最も効果的な手法は、Claude自身が要求達成を判断するための基準をプロンプトとして伝える事です。

ポイント	❌ 悪い事例	✅ 良い事例
検証基準を提供	「メールアドレスを検証する関数を実装して」	「validateEmail関数を書いて。テストケース: test@example.comはtrue、invalidはfalse。実装後にテストを実行して」
UI変更を視覚的に検証	「ダッシュボードを改善して」	「(スクリーンショットを貼付したうえで) このデザインを実装して。スクリーンショットを撮って元と比較し、差分をリストアップして修正して」
根本原因に対処	「ビルドが失敗している」	「ビルドが`{エラーメッセージやスタックトレース}`で失敗。修正してビルド成功を確認して。エラーを抑制せず根本原因に対処して」

活用できるツール：

テストスイート（Jest、pytest、PlaywrightによるE2Eテストなど）
Linter（ESLint、Prettierなど）
スクリーンショット検証（Claude in Chrome拡張、Playwrightのビジュアル比較）
Bashによる検証コマンド（npm run build、curlでAPIレスポンス確認など）

2. 探索→計画→実装の順で進める

人間に実装を依頼する場合もそうですが、調査・計画が不十分な状態で実装を始めると後から大幅な手戻りが発生することがあります。
これの原因を振り返ると、解決したい課題の理解が不十分な状態で見切り発車してしまう事だったというのは経験があると思います。

Claude Codeの場合、実装の前にPlanモードで調査・計画を行い、こういったリスクを防ぎます。

逆に課題が単純で、一文で説明できるような場合は計画をスキップしても問題ありません。

1. 探索（Plan Mode）
   - ファイル(コード、仕様書、ルール)を読む、質問に答える
   - 変更は行わない

2. 計画（Plan Mode）
   - 詳細な実装計画を作成
   - ファイル変更とフローを概説

3. 実装（Normal Mode）
   - 計画に沿ってコーディング
   - テストして失敗を修正

4. コミット（Normal Mode）
   - 説明的なメッセージでPRを作成

3. プロンプトに具体的なコンテキストを提供

プロンプトの精度を上げることで、修正サイクルを減らせます。
曖昧な指示はClaudeの解釈に任せることになり、意図と異なる実装が生まれやすくなります。

パターン	❌ 悪い事例	✅ 良い事例
タスクのスコープを絞る	「foo.pyのテストを追加して」	「foo.pyのテストを書いて。ユーザーがログアウトした場合のエッジケースをカバー。モックは避けて」
情報源を指定	「ExecutionFactoryのAPIが変なのはなぜ？」	「ExecutionFactoryのgit履歴を見て、APIがどう進化したかまとめて」
既存パターンを参照	「カレンダーウィジェットを追加して」	「ホームページの既存ウィジェットの実装を見て。HotDogWidget.phpが良い例。そのパターンに従ってカレンダーウィジェットを実装して」
症状を説明	「ログインバグを修正して」	「セッションタイムアウト後にログインが失敗する報告あり。src/auth/、特にトークンリフレッシュを確認。問題を再現する失敗するテストを書いてから修正して」

用語補足

プロンプト: ユーザーがClaudeに入力する指示や質問のこと
コンテキスト: Claudeが応答を生成するために参照する情報（会話履歴、ファイル内容、プロジェクト設定など）

4. 多様な入力手段を活用する

テキストで説明するより、ファイルや画像を直接渡した方が正確で手軽です。
Claude Codeには様々な入力手段が用意されています。

入力方法：

@参照: @filename - プロンプトにファイル参照を挿入する
画像: スクリーンショットをコピペまたはドラッグ＆ドロップ
URL: ドキュメントやAPIリファレンス（/permissionsでドメインを許可リストに追加）
パイプ: cat error.log | claude
Claudeに取得させる: Bash、MCP、ファイル読み込みでコンテキストを取得させる

5. 環境を設定する

5.1 効果的なCLAUDE.mdを書く

プロジェクトの立ち上げ時には、/initでスターターファイルを生成します。
ポイントとしては、事前にReadme.mdなどでリポジトリの概要を整理しておくと、より適切な初期設定が生成されます。

以下はCLAUDE.mdのポイントです。

✅ 記載するべき内容：

Claudeが推測できないBashコマンド
- 例: package.jsonのカスタムスクリプトのパターンなど
各言語の既定のコードスタイルとは異なる、独自のコーディング規約
テスト手順
リポジトリの作法
- ブランチ命名規則やコミットコメントの規則など
アーキテクチャ上の決定
- 数が増えてCLAUDE.mdファイルが肥大化しやすいポイントでもあるため、背景や詳細は書かず、方針のみ書くようにしておく
- 必要であればdocs/adr/*.mdなどに詳細情報を切り出して適宜参照させる

❌ 含めない内容：

Claude Codeがコードから読み取れる情報
言語の標準的な慣例
詳細なAPIドキュメント
- 別途切り出したドキュメントへのリンクを記載し、適宜参照させる
長い説明やチュートリアル

ポイント：

簡潔な記載を維持し続ける事
- 最大でも500行程度
- CLAUDE.mdは確実に読み込まれるので、肥大化すればコンテキストを圧迫する
- Claude Codeの応答・生成結果が記載内容とずれている場合、肥大化による見落としが発生している可能性を疑う
"重要"や"必須"というキーワードを含めることで、Claude Codeの遵守率を上げることができる
@{ファイル/ディレクトリパス}形式で、外部ファイルをインポートできる
- インポートした場合、毎回その参照先も読み込まれるため、結果として肥大化してしまう事に注意が必要

5.2 権限(permission)を設定

Claude Codeがコマンドを実行する際、その実行許可をユーザに求めます。
それが頻発するとユーザ体験としては非常に煩わしくなるので、事前に実行していいコマンドを設定しておくとハンズオフにできます。

但し中断を減らしつつ安全な制御を維持するために、安全なコマンドのみを許可設定するよう注意が必要です。

方法：
/permissionsで安全なコマンドを許可リストに追加、または/sandboxでOS分離を使用。

実行許可確認を発生させずにClaude Codeを動かすには：

claude --dangerously-skip-permissions

⚠️ 全許可すると、データ損失、破損、流出のリスクがあるのでSandbox環境内でのみ使用する事

5.3 CLIツールを活用

CLIツールが使える場合は積極的に活用しましょう。APIを直接叩くよりもコンテキスト効率が良いです。

代表的なのはgh（GitHub CLI）で、issue作成、PR操作、コメント読み取りなどをClaudeに指示できます。
他にもaws、gcloud、sentry-cliなど、認証済みのCLIツールがあれば活用できます。

5.4 MCPサーバーを接続

MCP（Model Context Protocol）を使うと、外部サービスとClaudeを連携できます。
Claudeが直接アクセスできない情報源からデータを取得したり、操作を実行したりできるようになります。

コンテキスト効率のポイント：
MCPサーバーを多数接続するとコンテキストを圧迫します。
Tool Search機能を有効にすると、必要なツールのみがオンデマンドで読み込まれるため、コンテキスト効率が向上します。

# 環境変数で設定（autoはコンテキストの10%超で自動有効化）
ENABLE_TOOL_SEARCH=auto

5.5 Hooksを設定

毎回必ず実行すべきアクションにはHooksを使用します。
CLAUDE.mdのルールは「助言的」でLLMが従うかは提案次第ですが、Hooksは決定論的に実行を保証します。

よくあるHooksの事例：

ユースケース	トリガー	内容
コードフォーマット自動実行	PostToolUse	編集後にPrettier/ESLint実行
危険な操作のブロック	PreToolUse	`.env`や`.git`へのアクセス防止
テスト自動実行	PostToolUse	テストファイル変更時に自動テスト
監査ログ記録	PreToolUse/PostToolUse	実行コマンドをログに記録

5.6 Skillsを作成

Skillsはプロジェクト・チーム・ドメイン固有の知識でClaudeを拡張する仕組みです。.claude/skills/に配置します。

CLAUDE.mdとの違い：

CLAUDE.md: 毎セッション読み込まれる → 肥大化するとコンテキストを圧迫
Skills: オンデマンド読み込み → 呼び出された時だけコンテキストに含まれる

特定のワークフロー（PRレビュー手順、DBマイグレーション手順など）の詳細な指示はSkillsに移動することで、CLAUDE.mdを簡潔に保ちながらコンテキスト効率を向上できます。

補足：

旧来のSlash Commands（.claude/commands）はSkillsに統合されました（既存コマンドは引き続き動作）
サブエージェントと組み合わせることで、コンテキストを保護しながらスキルを実行できます

5.7 カスタムサブエージェントを作成

サブエージェントは別のコンテキストで作業を実行し、結果だけをメインに返す仕組みです。
.claude/agents/にカスタム定義を配置できます。

メリット：

メインのコンテキストを保護しながら、調査や検証を委任できる
専門的なタスク（セキュリティレビュー、コード探索など）を専用エージェントに任せられる
5.6で述べたSkillsと組み合わせて使うことで、さらに効果的に運用できる

特性：

複数のサブエージェントを並列実行できる（作業効率化）
サブエージェント同士は直接対話できない
- サブエージェントはメインエージェントのみ対話可能

5.8 Pluginsをインストール

Pluginsは、Skills・Hooks・MCP・サブエージェントをバンドルしたパッケージです。
コミュニティが作成したPluginsをインストールすることで、自分で一から設定する手間を省けます。

6. 効果的にコミュニケーションする

6.1 コードベースについて質問する

従来はシニアエンジニアに聞くようなことをClaudeに質問することで、人間の負担を大きく減らせます。
コードの仕組み、設計意図、実装方法など、コードベースに関するあらゆる質問が可能です。

活用場面：

新しいプロジェクトへのオンボーディング
不慣れなコード領域の理解
他のエンジニアに質問する前の事前調査

6.2 Claudeにインタビューさせる

アイデアの壁打ち相手としてClaudeを活用できます。
AskUserQuestionツールを使うよう指示すると、Claudeがユーザーに質問を投げかけ、要件の曖昧さや考慮漏れを引き出してくれます。

大きな機能を実装する前にインタビューを行い、インタビューの結果の成果物をファイルに書き出します。
その後、新しいセッションを開始してクリーンなコンテキストで実装に入ります。

7. セッションを管理する

コンテキストウィンドウは最重要リソースです。セッションを適切に管理することで、パフォーマンスを維持できます。

7.1 軌道修正は早期・頻繁に実施する

Claudeが間違った方向に進んでいると気づいたら、コンテキストの浪費を抑えるためすぐに止めて軌道修正するべきです。
間違った方向に長く進むほど、失敗したアプローチでコンテキストが汚染され、軌道修正自体が困難になります。

もし同じ問題で2回修正しても解決しない場合、コンテキストが汚染されている可能性が高いです。
その場合は/clearでリセットし、学んだことを反映した新しいプロンプトで再スタートする方が効率的です。

経験則としては、1回のセッションで取り組む課題は事前に計画したうえでセッションを開始するのがよいでしょう。
逆に言えば、取り組みたい課題のサイズが膨大である場合、修正・実装に仕掛かる前に課題を詳細化してブレイクダウンするセッションを挟むべきです。

7.2 コンテキストを積極的に解放する

長いセッションでは、無関係な会話履歴やファイル内容でコンテキストが埋まっていきます。
これがパフォーマンス低下の原因となるため、意識的にコンテキストを解放する必要があります。

対策：

無関係なタスク間では/clearでコンテキストをリセット
- 全く別の課題に着手する場合はクリアを選択
コンテキスト制限に近づくとClaudeが自動で履歴を圧縮（AutoCompact → 重要な情報は保持）
/compactで手動圧縮も可能
- 継続して同一課題に取り組むが、コンテキストを軽くしたい場合（作業途中でのAutoCompact発生が予測される場合など）
- 保持したい情報を指示できる（例：「変更したファイルと決定事項を保持」）

7.3 調査にはサブエージェントを使用

コードベースの調査は多くのファイルを読むため、コンテキストを大量に消費します。
サブエージェントに調査を委任すると、メインのコンテキストを保護しながら結果だけを受け取れます。

活用場面：

実装前のコードベース調査
実装後のコードレビュー・検証

7.4 チェックポイントで巻き戻し

Claudeのすべてのアクションはチェックポイントを作成します。
失敗しても簡単に巻き戻せるため、リスクのあるアプローチを気軽に試せます。

ただし、試行錯誤が増えるほどコンテキスト消費と利用コストも増加します。
探索的に進めるか、事前に計画を立ててから実装するかは、タスクの性質に応じて判断してください。

⚠️ チェックポイントはClaudeの変更のみを追跡。外部プロセスの変更にはgitを使用してください。

7.5 会話を再開

Claude Codeは会話をローカルに保存します。
タスクが中断されても後日再開でき、コンテキストを再説明する必要がありません。

/renameでセッションに名前をつけると（例："oauth-migration"）、複数の作業を並行管理できます。
gitブランチのように、作業ごとにセッションを分けて運用するのが効果的です。

8. 自動化とスケール

単一セッションでの効率化には限界があります。Claude Codeは水平スケールできるため、並列セッションやヘッドレスモードで出力を増やせます。

8.1 ヘッドレスモード

claude -p "{プロンプト}"で対話なしで実行できます。
以下のようなFire and Forgetできるタスクに適しています。

CI/CD
pre-commitフック
スクリプト実行

8.2 複数セッションの並列実行

複数のターミナルウィンドウで別々のClaudeセッションを同時に動かせます。
作業を分担して並列に進めることで、スループットを向上できます。

活用例 - Writer/Reviewerパターン：
実装セッションとは別のターミナルでレビューセッションを開くことで、Claudeが自分で書いたコードへのバイアスなく、客観的にレビューできます。

8.3 ファンアウト

ヘッドレスモードをシェルスクリプトのループで大量に呼び出すパターンです。
対話セッションからではなく、スクリプトによるバッチ処理として実行します。

活用シーン：

大規模マイグレーション（例：React→Vue移行）
一括リファクタリング
大量ファイルの定型処理

基本的な流れ：

対象ファイルのリストを生成
forループで各ファイルにclaude -pを実行
最初は少数でテストし、プロンプトを改善してからフルセット実行

8.4 自律モード

--dangerously-skip-permissionsで許可確認をスキップし、Claudeを中断なく動作させられます。

活用シーン：

Lintエラーの一括修正
ボイラープレートの生成

⚠️ データ損失やシステム破損のリスクがあるため、以下の環境でのみ使用してください：

インターネットアクセスのないコンテナ
/sandboxでサンドボックスを有効化した環境

9. よくある失敗パターンを避ける

パターン	問題	解決策
Kitchen sink session	1つのタスクの後に無関係なタスク、コンテキストが無関係な情報で埋まる	タスクの切替わりで`/clear`する
修正の繰り返し	失敗したアプローチでコンテキストが汚染	2回修正してもダメなら`/clear`してやり直す
Claude.mdの肥大化	Claudeが記載を無視する	簡潔に保ち続ける、Claudeが既にできること(※)は削除
過信しないこと	適切なように見えて、壊れた実装を作ってしまう	常に検証方法を伝える（テスト、スクリプト、スクリーンショット）
無限に探索してしまう	無際限に大量のファイルを読む	スコープを決めるか、サブエージェントを使用する

※「Claudeが既にできること」の見極め方：
まずCLAUDE.mdに書かずに使ってみて、問題が起きたらルールを追加します。
逆に、既存ルールを削除しても正しく動作するなら、そのルールは不要です。

10. 直感を養う

本ガイドのパターンは出発点であり、すべての状況に最適とは限りません。
検証・振り返りを積み重ね、状況に応じて柔軟に適用する判断基準を養いましょう。

パターンは固定ではありません。時にはすべきこともあります：

コンテキストを蓄積させる（深く複雑な問題）
計画をスキップする（探索的なタスク）
曖昧なプロンプトを使う（制約する前にClaudeがどう解釈するか見る）

うまくいくことに注目：

成功したプロンプト構造に気づく
提供したコンテキストに気づく
使っていたモードに気づく

Claudeが苦戦したら、なぜか問う：

コンテキストがノイズだらけ？
プロンプトが曖昧すぎ？
タスクが大きすぎ？

時間とともに、具体的vs.オープンエンド、計画vs.探索、クリアvs.蓄積の使い分けの直感が身につきます。

機能の使い分け早見表

機能	最適な用途	使わない場面
Plan Mode	アプローチが不確実、複数ファイル変更	シンプルで明確な修正
Rules	CLAUDE.mdの分割、パス指定でのルール適用	小規模プロジェクト
Skills	ドメイン知識、再利用可能なワークフロー	頻繁に変わる情報
Subagents	調査、ファイル重視のリサーチ	タイトループの実装
Hooks	毎回必ず実行すべきアクション	助言的なルール
MCP Servers	外部サービス（Notion、Figma、DB）	ローカルのみの作業
Headless Mode	CI/CD、自動化、スクリプト	インタラクティブな開発
Multiple Sessions	並列作業、コードレビュー	単一の集中タスク

参考リンク

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up