Claude Code公式ベストプラクティスをもとに、環境設定からセッション管理までを日本語で解説します。
逐語訳ではなく、仕様変更に合わせた補足を含みます。
2026年10月23日に主要な設定・CLI仕様を公式資料と再照合しました。
掲載手順すべての実機検証は行っていません。
Claude Codeは自律的に動作するエージェント型のコーディング環境です。
質問に答えて待機するチャットボットとは異なり、Claude Codeはファイルの読み込み、コマンドの実行、コードの変更を自律的に進めます。
作業を見守りながら指示を出すことはもちろん、離席中も問題解決を継続できます。
この自律性により、開発の進め方そのものが大きく変わります。
開発者が自らコードを書いてClaudeにレビューを依頼するのではなく、実現したい内容を提示してClaude自身に構築手順を検討させます。
Claude自身がコードベースを探索し、計画を立てて実装を進めます。
ただし、このエージェントを使いこなすには特有の勘所を押さえる必要があります。
効果的に活用するには、Claudeの設計上の制約を正しく把握しておくことが重要です。
このガイドでは、Anthropic社内チームや多様な言語・環境のエンジニアによって実証された実用パターンを解説します。
チェックポイントの巻き戻しやフォークの具体的な操作画面は、以下の記事で解説しています。
最も重要な制約：コンテキストウィンドウ
大半のベストプラクティスは、次の単一の制約への対策に基づいています。
Claudeのコンテキストウィンドウは操作を重ねるほど消費され、容量が逼迫するにつれて性能が低下する
コンテキストウィンドウには、会話履歴全体のほか、読み込んだ全ファイルの内容や実行したコマンドの出力結果が含まれます。
1回のデバッグや探索処理だけでも、数万トークンを消費するケースが珍しくありません。
コンテキストの消費管理が重要なのは、容量が埋まるほどLLMの推論精度が落ちるためです。
コンテキストウィンドウが上限に近づくと、Claudeは以前の指示を見落としたり、意図しないミスを起こしやすくなったりします。
コンテキストウィンドウは、開発者が最も意識して管理すべき中核リソースです。
Claudeに自己検証させる仕組みを用意する
テスト実行、画像確認、期待される出力定義を渡し、Claude自身に検証させる。
これが最も成功率を高める手法です。
テストの実行、画面キャプチャの突合、出力結果の検証など、自身で成否を判断できる環境を用意すると、成果物の品質が飛躍的に向上します。
明確な検証基準を与えない場合、一見動くように見えて実際には動作しないコードが生成されるリスクが高まります。
検証環境がないと開発者自身が唯一のレビュアーとなり、すべてのエラーを手動で指摘し続けなければなりません。
| 戦略 | 改善前 | 改善後 |
|---|---|---|
| 検証基準を提供する | 「メールアドレスを検証する関数を実装して」 | 「validateEmail関数を書いて。テストケース例：user@example.comはtrue、invalidはfalse、user@.comはfalse。実装後にテストを実行して」 |
| UI変更を視覚的に検証する | 「ダッシュボードをもっと良くして」 | 「[スクリーンショットを貼り付け] このデザインを実装して。結果のスクリーンショットを撮って元と比較して。違いをリストアップして修正して」 |
| 症状ではなく根本原因に対処する | 「ビルドが失敗している」 | 「このエラーでビルドが失敗している：[エラーを貼り付け]。修正してビルドが成功することを確認して。エラーを抑制するのではなく、根本原因に対処して」 |
検証手段はテストスイートに限らず、リンターの実行やBashコマンドによる出力確認でも十分に機能します。
自動検証できるパイプラインの整備に時間を充ててください。
探索・計画・実装の順に進める
調査と設計をコーディングと分離し、的外れな実装を防ぐ。
事前の確認なしに直接実装へ入らせると、本来の要件と異なる方向でコードを生成してしまう恐れがあります。
Plan Modeを活用し、調査と実装のステップを明確に分けましょう。
推奨されるワークフローは次の4フェーズです。
1. 探索（Explore）
Plan Modeに切り替えます。
Claudeはファイル内容を調査し、コード変更を行わずに現状把握の質問へ回答します。
/src/authを読んで、セッションとログインの処理方法を理解して。
また、シークレット用の環境変数の管理方法も確認して。2. 計画（Plan）
具体的な実装ステップと変更方針の計画案を作成させます。
Google OAuthを追加したい。
どのファイルを変更する必要がある？
セッションフローは？
計画を作成して。3. 実装（Implement）
Plan Modeを終了し、策定した計画に沿って実装作業を実行させます。
計画に基づいてOAuthフローを実装して。
コールバックハンドラのテストを書いて、テストスイートを実行して失敗があれば修正して。4. コミット（Commit）
変更理由を明記したコミットメッセージを作成させ、プルリクエストを作成させます。
説明的なメッセージでコミットしてPRを開いて⚠️ 注意：Plan Modeは堅実ですが、セッションのやり取りが増加します。
修正範囲が自明で軽微なタスク（誤字修正、ログ追加、変数名の変更など）であれば、計画を挟まず直接実行させてください。
計画フェーズが真価を発揮するのは、実装方針が定まっていない場合、変更が複数ファイルにまたがる場合、未把握のコード領域を変更する場合です。
差分の内容を1文で簡潔に説明できるタスクなら、計画ステップは省略して問題ありません。
プロンプトに具体的なコンテキストを提供する
指示の解像度を高めるほど、手戻りや修正の発生を減らせる。
Claudeは文脈を推測できますが、暗黙の前提までは汲み取れません。
対象ファイルを明示し、前提条件や制約を箇条書きにし、参考とすべき実装パターンを指定してください。
| 戦略 | 改善前 | 改善後 |
|---|---|---|
| タスクのスコープを定める | 「foo.pyのテストを追加して」 | 「foo.pyのテストを書いて、ユーザーがログアウトしているエッジケースをカバーして。モックは避けて」 |
| ソースを指し示す | 「ExecutionFactoryのAPIがなぜこんなに変なの？」 | 「ExecutionFactoryのgit履歴を調べて、そのAPIがどのように生まれたかを要約して」 |
| 既存パターンを参照する | 「カレンダーウィジェットを追加して」 | 「ホームページの既存ウィジェットの実装を見てパターンを理解して。HotDogWidget.phpが良い例。そのパターンに従って、月を選択し前後にページネーションして年を選べる新しいカレンダーウィジェットを実装して。コードベースで既に使われているライブラリ以外は使わずにゼロから構築して」 |
| 症状を説明する | 「ログインバグを直して」 | 「ユーザーからセッションタイムアウト後にログインが失敗するという報告。src/auth/の認証フロー、特にトークンリフレッシュを確認して。問題を再現する失敗するテストを書いてから修正して」 |
あえて抽象的なプロンプトを投げる手法は、初期探索で幅広いアイデアを洗い出したい段階で効果的です。
「このファイルで改善すべき箇所はあるか」といった問いかけは、想定外の課題や盲点を発見するきっかけになります。
リッチコンテキストの入力手法
@によるファイル参照、スクリーンショットや画像の添付、標準入力パイプを活用する。
Claudeへ外部データやコンテキストを渡す主な手段は以下の通りです。
@によるファイル参照：ファイルの場所を言葉で説明する代わりに使用します。
Claudeはプロンプトの処理開始前に対象ファイルを直接読み込みます。- 画像の直接添付：UIやエラー画面のコピー＆ペースト、またはドラッグ＆ドロップに対応しています。
- URLの参照指定：Web上の公式ドキュメントやAPI仕様の参照に適しています。
/permissionsで頻繁に利用する参照元ドメインを許可リストへ追加できます。 - 標準入力パイプ：
cat error.log | claude -p "このエラーの原因を説明して"のように、ターミナル出力やログを直接渡せます。 - 自律的な情報取得：Bashコマンドの実行、MCPツール、ファイル読み込みコマンドを指示し、必要な情報をClaude自身に収集させます。
作業環境を整える
初期設定を整えておくだけで、以後のセッション全体の作業効率と精度が大きく高まります。
効果的なCLAUDE.mdを作成する
/initを実行してプロジェクト構成に応じたCLAUDE.mdの雛形を出力し、運用しながら継続的にチューニングする。
CLAUDE.mdは、プロジェクトの指示をClaudeへ渡すファイルです。
適用されるルートや親ディレクトリの内容は開始時、子ディレクトリの内容は対象ファイルを扱う際に読み込まれます。
権限設定を上書きするファイルではありません。
日常的に使うBashコマンド、コーディング規約、開発ワークフローのルールを記載します。
記述しておくことで、ソースコードだけからは推測できない背景情報を常にClaudeへ共有できます。
/initコマンドを実行すると、ビルドツール、テストフレームワーク、コーディング規約を自動検出し、プロジェクトに合わせた設定の土台を生成します。
厳密な構文規定はありませんが、短く明瞭で人間にも読みやすい状態を維持してください。
# コードスタイル
- CommonJS（require）ではなくESモジュール（import/export）構文を使用
- 可能な場合はインポートを分割代入（例：import { foo } from 'bar'）
# ワークフロー
- 一連のコード変更が終わったら必ず型チェックを実行
- パフォーマンスのため、テストスイート全体ではなく単一テストの実行を優先
あらゆるルールを記載したくなりますが、内容は最小限に絞り込むことが肝要です。
各記述に対して「この1行を削った場合、Claudeは本当に誤動作するか」と精査してください。
影響がない記述は削除します。
不要な情報で肥大化したCLAUDE.mdは、肝心な個別プロンプトの指示埋もれを招きます。
| ✅ 記載すべき内容 | ❌ 記載を避けるべき内容 |
|---|---|
| コードから推測不能な固有のBashコマンド | コードベースを読めば自明な仕様 |
| プロジェクト独自の非標準なスタイル規約 | 一般的なプログラミング言語の標準作法 |
| テスト実行手順と優先するテストランナー | 網羅的なAPIドキュメント（URLリンクで代用） |
| リポジトリの運用規約（ブランチ名、PR作法） | 更新頻度の高い一時的な情報 |
| プロジェクト固有のアーキテクチャ設計方針 | 長文の解説記事やチュートリアル |
| 開発環境特有の注意点（必須の環境変数など） | 全ファイルを網羅した詳細な構成説明 |
| 頻出する落とし穴や直感に反する挙動 | 「綺麗に書く」といった抽象的で自明な助言 |
Claudeがルール違反を繰り返す場合、設定ファイルが肥大化して指示が埋もれている可能性があります。
CLAUDE.mdに明記されているはずの仕様を尋ねてくる場合は、記述が曖昧である疑いがあります。
CLAUDE.mdもソースコードと同様に扱い、意図通りに動かない場合は見直し、定期的に不要箇所を削り、挙動の変化を検証してください。
特に遵守させたい指示には、「IMPORTANT」や「YOU MUST」などの強調語句を付与すると順守率が向上します。
CLAUDE.mdはGit管理下に置き、チーム全体で改善できるようにしておきましょう。
継続的にメンテナンスすることで、設定資産としての価値が高まっていきます。
CLAUDE.md内では、@path/to/import構文を使って外部ファイルを読み込むことも可能です。
プロジェクト概要は@README.mdを、利用可能なnpmコマンドは@package.jsonを参照。
# 追加指示
- Gitワークフロー：@docs/git-instructions.md
- 個人オーバーライド：@~/.claude/my-project-instructions.mdCLAUDE.mdファイルの配置場所
- ユーザーのホームディレクトリ（
~/.claude/CLAUDE.md）：全プロジェクトのセッションへ横断して適用されます。 - プロジェクトのルートディレクトリ（
./CLAUDE.md）：Gitへコミットしてチーム共有するか、個人用としてCLAUDE.local.mdというファイル名にして.gitignoreへ指定します。 - 親ディレクトリ：
root/CLAUDE.mdとroot/foo/CLAUDE.mdの両方を階層的に自動読み込みできるため、モノレポ構成で有効です。 - 子ディレクトリ：該当ディレクトリ配下のファイルを編集するタイミングで、子階層のCLAUDE.mdが必要に応じて読み込まれます。
権限と安全性を設定する
/permissionsで安全なコマンドをホワイトリストへ登録するか、/sandboxでOSレベルの隔離環境を適用する。作業の中断頻度を抑えつつ、安全性を両立できます。
Manualモードでは、事前に許可していないファイル編集やシェルコマンド、MCPツールの操作などで確認を求められます。
現行の公式の権限モード説明では、v2.1.283以降の対話型ターミナルとVS Codeはautoを初期モードとし、設定や組織の制限、対応モデルによってManualになる場合もあります。
claude -pの初期モードはManualなので、対話セッションと同じ動作だと決めつけず、必要なモードを明示してください。
安全ではあるものの、実行のたびに承認を求められると作業効率が低下します。
確認が頻繁に続くと内容を精査せず機械的に承認してしまい、セキュリティ上の形骸化を招きかねません。
承認による作業の中断を減らすアプローチは主に2つあります。
- 権限の許可リスト登録：影響が限定的なコマンドを事前承認します（例：
npm run lintやgit commitなど）。 - サンドボックス機能：ファイルアクセスやネットワーク通信をOSレベルで制限し、隔離された安全領域内でClaudeに作業を完結させます。
あるいは、--dangerously-skip-permissionsオプションを付与すると、権限の確認を省略します。
このオプション自体が処理を定型作業や低リスクな操作だけに制限するわけではありません。
⚠️ 警告：任意のコマンド実行を無制限に許可すると、データの消失、環境の破損、プロンプトインジェクションに伴う機密流出のリスクが生じます。
--dangerously-skip-permissionsフラグは、外部ネットワークから切り離されたサンドボックス環境でのみ利用してください。
CLIツールを連携させる
クラウドサービスや外部APIとの連携には、
gh、aws、gcloud、sentry-cliなどの専用CLIを活用するよう指示する。
CLIツールは外部サービスとやり取りする手段です。
必要な項目に出力を絞ると、Claudeへ渡す情報量を減らせます。
GitHubと連携する場合は、事前にghを導入しておきましょう。
Issueの作成、プルリクエストの発行、コメントの取得などをClaudeが自律的に実行できるようになります。
ghがない環境でもAPIを直接叩くことは可能ですが、認証なしのリクエストは早期にレートリミットへ達する原因となります。
ClaudeにCLIのヘルプ出力を読ませ、構文と利用条件を確認させることもできます。
実行結果が目的に合うかは別途確認してください。
「'foo-cli --help'で仕様を確認し、そのコマンドを使ってA、B、Cの処理を実行して」といった指示が有効です。
MCPサーバーを接続する
claude mcp addを実行し、NotionやFigma、社内DBなどの外部ツールを連携させる。
MCPサーバーを接続することで、Issue管理ツールからの課題取得、DBへのデータ抽出、監視ログの調査、Figmaデザインのコード化など、多様な外部連携ワークフローをClaudeへ任せられます。
カスタムスラッシュコマンドを作成する
頻出する一連の指示はプロジェクト固有のコマンドとして
.claude/commands/配下に、全プロジェクト共通のコマンドなら~/.claude/commands/配下にMarkdown形式で定義する。
カスタムコマンド内では、引数全体を展開する$ARGUMENTSや、個別指定に対応した$0（先頭）、$1（2番目）などの変数を利用できます。
現在はカスタムコマンドとスキルが統合されていますが、既存のcommands配下のファイルも利用できます。
---
description: GitHubのissueを修正する
---
GitHubのissueを分析して修正してください：$ARGUMENTS。
以下の手順に従ってください：
1. `gh issue view`を使用してissueの詳細を取得
2. issueに記載されている問題を理解
3. 関連するファイルをコードベースで検索
4. issueを修正するために必要な変更を実装
5. 修正を検証するテストを書いて実行
6. コードがリンティングと型チェックをパスすることを確認
7. 説明的なコミットメッセージを作成
8. プッシュしてPRを作成
ファイルを作成すると、/fix-github-issue 1234のような形式でカスタムコマンドを実行できるようになります。
プラグインを導入する
/pluginを実行してマーケットプレイスからプラグインを導入する。プラグインに応じてコマンドやツールを追加できます。
外部サービスの認証や依存ツールの設定が必要な場合もあります。
プラグインを利用することで、公式やコミュニティが提供する機能を導入できます。
提供元、必要な権限、設定手順を確認してください。
インストール後も、必要な認証や設定が完了し、目的の機能が動作するかを確認します。
プラグインによって追加される代表的な要素は以下の通りです。
- カスタムコマンド：ワークフローに特化したスラッシュコマンド群（例：
/deploy、/review、/migrateなど）。 - MCPサーバー：データベース、API、各種SaaS製品へあらかじめ構成された接続設定。
- サブエージェント：セキュリティ診断、仕様書作成、テスト生成などを専門に担うアシスタント。
- スキル：関連する処理の発生時に自動適用されるドメイン知識。
フックを活用する
/hooksコマンドでClaude Codeの実行フローを決定論的に制御する。Claudeが自主的にルールを遵守することに頼らず、指定の処理を機械的かつ確実に強制できます。
フックを登録すると、Claudeの作業ライフサイクルに合わせて所定のスクリプトが自動実行されます。
- コードの自動整形：ファイル編集が行われるたびに、
.tsにはPrettierを、.goにはgofmtを自動適用。 - 静的解析（Lint）：変更されたファイルを即座にリントし、構文エラーや警告を自動検出。
- ガードレール：
.envやsecrets/、本番環境向け設定ファイルの書き換えを拒否。 - 監査ログ記録：セキュリティ監査やデバッグ用途として、実行されたコマンド履歴をすべて保存。
- ユーザー通知：Claudeがユーザーの入力待ち状態になった際にデスクトップ等へ通知。
フック用スクリプトの作成自体もClaudeに依頼できます。
「ファイル編集後に毎回eslintを実行するフックを作成して」「migrationsディレクトリへのファイル書き込みを阻止するフックを書いて」のように依頼してください。
例外を許さず必ず毎回実行すべきタスク（フォーマット適用、静的チェック、機密ファイルの保護など）にはフックを採用します。
一方、文脈に応じた柔軟な判断が求められる指針（命名規則の好み、設計思想など）はCLAUDE.mdに記述してください。
フックは機械的な強制、CLAUDE.mdは文脈的な判断基準という役割分担です。
カスタムサブエージェントを作成する
Claudeが処理を委譲できる専門アシスタントを
ディレクトリ内に定義する。
.claude/agents/各サブエージェントは独立したコンテキストウィンドウ、権限ツール、プロンプト指示を保持します。明示的に呼び出されるプロンプトテンプレートであるスラッシュコマンドと異なり、サブエージェントは独立したメモリ空間と限定されたツール権限で稼働します。
単なる固定スクリプトではなく、自律的な判断を委ねられるアシスタントとして振る舞います。
サブエージェントの活用が適したケースは以下の通りです。
---
name: security-reviewer
description: セキュリティの脆弱性についてコードをレビュー
tools: Read, Grep, Glob, Bash
model: opus
---
あなたはシニアセキュリティエンジニアです。以下についてコードをレビューしてください：
- インジェクション脆弱性（SQL、XSS、コマンドインジェクション）
- 認証と認可の欠陥
- コード内のシークレットまたは資格情報
- 安全でないデータ処理
具体的な行参照と提案される修正を提供してください。
コードレビュー
- ：メインセッションの作業経緯に囚われない客観的な視点で成果物を検証。コードベース調査
- ：初見のソースコードを読み込む際、メインセッションのコンテキストを圧迫せずに探索。特化タスク
- ：セキュリティ監査、ドキュメントの自動生成、単体テスト作成などの専門処理。独立検証
- ：メインエージェントが生成した成果物の妥当性を別エージェントに検査させる。「サブエージェントを使用してこのコードのセキュリティ懸念を精査して」のように、サブエージェントの稼働を明示的に指示してください。
エージェントスキルを追加する
ディレクトリ配下にMarkdownファイルを配置し、Claudeが状況に応じて自律適用するドメイン知識を登録する。
.claude/skills/スキル名/SKILL.mdに保存します。スキルはClaudeの判断による適用と、
/スキル名による手動呼び出しの両方に対応し、frontmatterで呼び出し方を制御できます。プロジェクトやチームの固有ルールをスキルとして定義しておくことで、Claudeの前提知識を無理なく拡張できます。
Claudeは登録されたスキル群を読み、現在のタスク内容に合わせて適用すべきスキルを自ら判断します。
スキルと他機能の違い
---
name: api-conventions
description: サービス用のREST API設計規約
---
# API規約
- URLパスにはkebab-caseを使用
- JSONプロパティにはcamelCaseを使用
- リストエンドポイントには常にページネーションを含める
- URLパスでAPIをバージョン管理（/v1/、/v2/）
機能
| 機能 | 起動トリガー | 最適な用途 |
|---|---|---|
| CLAUDE.md | 適用範囲に応じて読み込み | プロジェクト全体の基本方針・共通ルール |
| カスタムスラッシュコマンド | ユーザーによる手動指定（/command） | 定型化された反復ワークフロー。現在はスキルに統合 |
| スキル | 文脈に応じた判断または手動呼び出し | ドメイン知識や再利用する手順 |
| サブエージェント | エージェントからの委譲 | コンテキストを分離する独立タスク |
意図通りの成果を得るコミュニケーション術
Claude Codeに対する指示の出し方は、出力される成果物の品質を直接左右します。
コードベースの疑問を直接質問する
シニアエンジニアへ相談するように、コードの背景や設計をClaudeに質問する。
不慣れなコードベースに参加した直後のキャッチアップやコード探索に、Claude Codeを存分に活用してください。
チームメンバーへ確認するような感覚で、そのまま質問を投げかけられます。
- このシステムのログ出力の仕組みはどうなっていますか。
- 新しいAPIエンドポイントを追加する手順を教えてください。
foo.rsの134行目にあるasync move { ... }ブロックは何を処理していますか。CustomerOnboardingFlowImplクラスはどのようなエッジケースを考慮していますか。- このコードの333行目で
bar()ではなくfoo()を呼び出している理由は何ですか。
Claude Codeを活用したコード把握はオンボーディングの効率化に直結し、立ち上げ期間の短縮や既存メンバーへの質問負荷軽減につながります。
過剰に工夫したプロンプトは不要です。
知りたい内容をストレートに尋ねてください。
Claude側から要件をヒアリングさせる
規模の大きな機能開発では、実装前にClaudeから要件の逆質問を行わせる。
大まかな概要だけを伝え、
AskUserQuestionツールを使って必要な論点をヒアリングするようClaudeへ指示します。
開発者が当初想定していなかった仕様の抜け漏れについて、Claudeが論点を洗い出して質問してくれます。
技術的なアーキテクチャ、UI/UXの振る舞い、エッジケース、懸念点、トレードオフなどを網羅的に整理できます。
[簡単な説明]を構築したい。AskUserQuestionツールを使って詳細にインタビューして。
技術的な実装、UI/UX、エッジケース、懸念事項、トレードオフについて聞いて。
明らかな質問はせず、考慮していないかもしれない難しい部分を掘り下げて。
すべてをカバーするまでインタビューを続けてから、完全な仕様をSPEC.mdに書いて。
仕様が固まったら、実装作業は新しいセッションを立ち上げて進めてください。
要件定義の長いやり取りを切り離すことで、クリーンなコンテキスト内で明確な仕様書を参照しながら実装に集中できます。
セッションを効率的に管理する
通常のローカルセッションでは会話履歴が保存され、保持されているチェックポイントから追跡対象の変更を巻き戻せます。
保存を無効にしたセッションや追跡対象外の変更は別です。
このセッション管理機能を活用して開発を進めましょう。
ずれを検知したら早期に軌道修正する
Claudeのアプローチが意図とずれていることに気付いたら、作業の完了を待たずに即座に修正を指示する。
フィードバックのループを短く回すことが、最も手戻りを防ぐ運用方法です。
一度の指示で完璧に完了する場合もありますが、迷走の兆候が見えた段階で素早く軌道修正したほうが、結果的に短時間で品質の高いコードに仕上がります。
Esc：Escキーを押すと実行中の処理を即時中断できます。
それまでのコンテキストは維持されるため、すぐに別の方向性を指示できます。Esc + Escまたは/rewind：入力欄が空の状態でEscを2回押すか/rewindを実行すると巻き戻しメニューが表示され、過去の会話履歴やコード状態へ復元できます。- 「変更を元に戻して」：直前の変更をClaude自身に取り消させます。
/clear：別のタスクへ移る際にコンテキストを初期化します。
無関係な履歴が蓄積したセッションを使い続けると、精度の低下を招きます。
同じセッション内で同じ課題に対して2回以上修正を指示している場合、コンテキスト内は失敗した試行錯誤のノイズで埋もれています。
/clearでコンテキストをクリアし、それまでの試行で得られた前提条件を盛り込んだ具体的なプロンプトで仕切り直してください。
不要な試行錯誤が多い場合は、判明した条件を整理して新しいセッションへ渡す方法を試せます。
重要な経緯を失わないよう、必要な情報を保存してから切り替えてください。
コンテキストを意識して管理する
タスクの合間に
/clearを実行し、不要になったコンテキストウィンドウをこまめに初期化する。
Claude Codeはコンテキストの上限に近づくと自動で会話履歴を要約し、重要なコードや決定事項を残しながら空き容量を確保します。
しかし長時間のセッションでは、無関係な会話や過去のファイル内容、大量のコマンド出力が蓄積しがちです。
コンテキストの肥大化は応答精度の低下を招き、指示への集中を阻害する要因になります。
- タスクを切り替える際は、
/clearを実行してコンテキストをまっさらな状態へリセットします。 - 自動要約が走ると、コードパターン、ファイル状態、重要な意思決定などの中核情報だけが要約されます。
- 要約の焦点を細かく指定したい場合は、
/compact <指示>を実行してください（例：/compact API変更に焦点を当てて）。
調査タスクはサブエージェントへ逃がす
「サブエージェントを使って〇〇を調査して」と指示し、調査プロセスを委譲する。
メインセッションのコンテキストを実装作業用に温存しながら、別空間でコード探索を行えます。
コンテキストウィンドウの制限を回避する上で、サブエージェントの活用は極めて有効です。
Claudeがコードベースを詳しく調査する際、多数のファイルを読み込むことで大量のトークンが消費されます。
サブエージェントを立ち上げれば、別のコンテキスト空間でファイルを探索し、結果の要点だけをメインセッションへ報告させることができます。
サブエージェントを使って、認証システムがトークンリフレッシュをどう処理するか、
再利用すべき既存のOAuthユーティリティがあるかを調査して。サブエージェントがコードベースを探索して該当ファイルを読み解き、調査結果の要約のみを返します。
調査中の詳細な履歴を別のコンテキストに置き、メインの会話には結果を返せます。
結果の要約や委譲の指示はメイン側にも残ります。
機能実装後のレビューや動作確認をサブエージェントに担当させることも可能です。
サブエージェントを使ってこのコードのエッジケースをレビューしてチェックポイント機能で安全に巻き戻す
ターンを開始するユーザーのプロンプトごとに、チェックポイントが作られる。
保持されているチェックポイントを選び、会話履歴、追跡対象のファイル変更、または両方を復元できます。
Claude Codeのファイル編集ツールによる変更が追跡対象です。
現行資料では直近100チェックポイントのファイルスナップショットを保持すると案内されており、無期限に全変更を復元できる機能ではありません。
入力欄が空の状態でEscapeキーを2回押すか、/rewindを実行してチェックポイント管理画面を開きます。
会話履歴のみ復元、コード変更のみ復元、両方を同時に復元のいずれかを選択できます。
最初から完璧な手順を練り込まずとも、不確実な変更を気軽にClaudeへ試させることができます。
期待通りの結果にならなければ、チェックポイントから直前の状態へ巻き戻して別のアプローチを取り直せます。
チェックポイントはセッション終了後も保持されるため、ターミナルを終了した後でも復元操作が可能です。
⚠️ 注意：チェックポイントの復元対象は、そのセッションで追跡されているファイルです。
Bashだけで変更したファイルは追跡されませんが、Claudeが編集ツールで先に編集したファイルでは、その後のBashや手動の変更も巻き戻される場合があります。
復元前に対象ファイルを確認し、長期保存や追跡されない変更の復元にはGitなどのバージョン管理を使ってください。
Gitのようなバージョン管理システムの完全な代替にはならない点にご留意ください。
中断したセッションを再開する
claude --continueを実行して直前のセッションを継続するか、--resumeで過去のセッション一覧から選択して再開する。
Claude Codeは会話履歴をローカル環境へ永続化して保存します。
作業が日をまたぐ場合や別タスクで中断した場合でも、前回の前提条件を最初から説明し直す必要はありません。
claude --continue # 最新の会話を再開
claude --resume # 最近の会話から選択/renameコマンドを使い、セッションへ分かりやすい名前を付けておきましょう（例：「oauth-migration」「debugging-memory-leak」など）。
後から再開する際に目的のセッションをすばやく特定できます。
セッションはGitブランチと同じ感覚で運用してください。
並行する開発テーマごとにセッションを分けることで、それぞれ独立したコンテキストを維持できます。
自動化とスケールアウト
単一セッションでの扱いに慣れたら、並列セッション、ヘッドレス実行、ファンアウトパターンを取り入れて作業効率を何倍にも引き上げましょう。
これまでは「1人の開発者が1つのセッションで対話する」前提の使い方でした。
しかし、Claude Codeは複数の処理を水平展開して並列処理できます。
本セクションでは、複数のタスクを自動化して高速に処理する手法を紹介します。
ヘッドレスモードでバッチ実行する
💡 CIやpre-commitフック、各種自動化スクリプト内で
claude -p "prompt"を実行する。ストリーミング形式でJSON出力を受け取りたい場合は、
--output-format stream-json --verboseを指定します。
claude -p "your prompt"を指定することで、インタラクティブ画面を介さずにClaudeを非対話で実行できます。
ヘッドレスモードを利用すれば、CI/CDパイプラインやコミット前フックなど、既存のスクリプトへ容易に組み込めます。
テキスト、JSON、ストリーミングJSONなどの出力形式を選択できるため、後続のプログラムで出力を簡単にパースできます。
# 1回限りのクエリ
claude -p "このプロジェクトが何をするか説明して"
# スクリプト用の構造化出力
claude -p "すべてのAPIエンドポイントをリストして" --output-format json
# リアルタイム処理用のストリーミング
claude -p "このログファイルを分析して" --output-format stream-json --verbose
複数のClaudeセッションを並行稼働させる
実装の高速化、独立した検証実験、複雑なワークフローの並行処理のために、複数のClaudeセッションを同時に走らせる。
セッションを並列実行する主な手段は次の2つです。
- Claude Desktop：複数のローカルセッションをGUI上で視覚的に管理できます。
Gitワークツリーを使う場合は作業ファイルを分離できますが、外部サービスや共有リソースへの影響も確認してください。 - Web版Claude Code：Anthropicが管理するクラウド基盤上の隔離VM内で実行されます。
単純な並列作業にとどまらず、複数セッションを組み合わせることでコード品質の向上を図る運用も可能です。
履歴のない独立したセッションを用いると、コードレビューの精度が高まります。
自身が直前に書いたコードに対する先入観を持たずに、客観的な指摘を行えるためです。
代表的な例として「Writer/Reviewerパターン」が挙げられます。
| セッションA（実装担当：Writer） | セッションB（レビュー担当：Reviewer） |
|---|---|
| 「APIエンドポイント用のレートリミッターを実装して」 | |
| 「@src/middleware/rateLimiter.tsのレートリミッター実装をレビューして。エッジケース、競合状態、既存ミドルウェア設計との整合性をチェックして」 | |
| 「セッションBから次のレビュー指摘を受けた：[セッションBの出力を貼付]。これらの課題を修正して」 |
テスト駆動開発にも応用できます。
一方のセッションでテストコードを先に作成させ、もう一方のセッションでそのテストをパスする実装を行わせます。
複数ファイルへのファンアウト展開
対象ファイルやタスクの一覧をループ処理し、各要素に対して
claude -pを実行する。
--allowedToolsは確認なしで実行を許可するツールを指定します。組み込みツールの種類を限定するには
--toolsを使い、MCPツールは別に制御します。
大規模なリファクタリングや一括解析では、複数のClaudeプロセスへ処理を分散できます。
- 対象タスクの一覧化：修正対象となる全ファイルをClaudeにリストアップさせます（例：「変更が必要なPythonファイル2,000件をリスト化して」など）。
- リストをループするBashスクリプトの作成：
while IFS= read -r file || [ -n "$file" ]; do
[ -z "$file" ] && continue
claude -p "対象ファイル: ${file}。ReactからVueへ移行して。変更点と未検証事項を返して" \
--tools "Read,Edit,Write" --allowedTools "Read,Edit,Write" \
--disallowedTools "mcp__*" < /dev/null
done < files.txt
- 少数ファイルでの事前検証：最初の2〜3件で試行してプロンプトや動作の不備を改善し、問題が解消してから全件の一括処理へ移行します。
--allowedToolsだけを利用可能ツールの制限と考えないでください。上の例はRead・Edit・Writeだけを使い、MCPを拒否します。コマンドによるテストやコミットは実行しないため、変更後の検証は別途必要です。
社内のデータ処理や既存のバッチパイプラインへClaudeを組み込むことも可能です。
claude -p "<your prompt>" --output-format json | your_command
ログの出力量は用途に合わせます。
-pとstream-jsonを組み合わせる例では--verboseも指定し、本番でも出力形式が要求するオプションを外さないでください。
安全に自律モードを運用する
確認の中断を減らすには、利用可能な環境でclaude --permission-mode auto -p "リントエラーを修正して"のようにautoモードを指定できます。
autoモードでは別の判定モデルが操作を審査するため、権限確認を省略する--dangerously-skip-permissionsとは動作が異なります。
autoモードを利用できるかは、対応モデルと組織の設定を確認してください。
⚠️ 警告：任意のコマンド実行を無制限に許可すると、予期せぬデータ消失やシステム破損、プロンプトインジェクション等による情報流出のリスクを伴います。
これらの脅威を最小限に抑えるため、インターネット接続を遮断したコンテナ環境に限定して
--dangerously-skip-permissionsを実行してください。サンドボックス機能（
/sandbox）は、対応環境でファイルやネットワークのアクセス範囲を制限します。権限確認の省略とは別の機能で、設定した範囲と例外を確認する必要があります。
すべてのチェックを一括で外すのではなく、事前に操作可能な境界を明確に定義して安全性を担保します。
よくある失敗アンチパターンを回避する
以下は、初心者が陥りやすい典型的な失敗パターンです。
早期に兆候を察知して適切に対処することで、無駄な試行時間を削減できます。
何でも詰め込むセッション（キッチンシンク）
1つのタスクを開始した後に無関係な質問を挟み、再び元の作業に戻る運用。
コンテキストが無関係なやり取りで圧迫されてしまいます。
改善策：別のタスクへ移る際は、必ず
/clearを実行してコンテキストをリセットします。
セッション内で修正を繰り返す泥沼化
Claudeが生成ミスをし、その場で修正を指示するものの再び失敗し、さらに修正指示を重ねる悪循環。
コンテキスト内が過去の失敗したコードや試行錯誤のノイズで埋め尽くされます。
改善策：2回連続で修正に失敗した時点で粘らず、
/clearを実行してコンテキストを初期化し、判明した制約を反映したプロンプトで最初からやり直します。
ルールを詰め込みすぎたCLAUDE.md
CLAUDE.mdの記述量が多すぎると、重要な制約がノイズに埋もれて重要な指示が見落とされる原因になります。
改善策：不要な指示を大胆に削減します。
指示なしでも正しく動作している内容は削るか、絶対に守らせたいルールはフックによる機械的制御へ移行してください。
ノーチェックで信頼してしまうギャップ
エッジケースへの配慮が欠けているにもかかわらず、一見それらしく動くコードを無批判に受け入れてしまう。
改善策：単体テスト、検証用スクリプト、画面キャプチャ突合など、必ず客観的な検証手段を併用します。
検証プロセスを通していないコードは、本番環境へデプロイしてはなりません。
目的のない無限探索
調査範囲を絞り込まずに「コードベース全体を調査して」と漠然と依頼してしまう。
Claudeが何百ものファイルを際限なく読み込み、コンテキスト容量を一気に使い果たしてしまいます。
改善策：調査対象のディレクトリやファイルを厳密に限定するか、サブエージェントに調査を任せてメインセッションのコンテキスト消費を防ぎます。
Claude運用の直感を養う
本ガイドで紹介したテクニックは、絶対不変の固定ルールではありません。
標準的な出発点として有効ですが、すべての開発現場で常に正解とは限りません。
複雑な単一の不具合に深く挑んでおり過去の経緯が不可欠な場合は、あえてコンテキストを蓄積させたほうが良いケースもあります。
探索的な初期段階では、Claudeの自由な推論に任せるために事前計画をスキップしたほうが有効な場合もあります。
要件を狭める前にClaudeがどうアプローチするかを観察したい局面では、あえて曖昧なプロンプトを投げることが効果を発揮します。
どのような進め方で成功したのかを常に意識してください。
期待通りの優れたコードが得られた際は、プロンプトの組み立て方、提供したコンテキスト、使用した動作モードなど、成功要因を振り返ってみましょう。
逆に思うような成果が出なかったときは、その原因を掘り下げてください。
コンテキストに余計な情報が混ざっていたか、プロンプトの指示が漠然としていたか、あるいは一度に頼んだタスクが大きすぎたのかを検証します。
経験を重ねることで、マニュアルだけでは得られない実践的な勘所が身についていきます。
指示を具体化すべきか委ねるべきか、計画を立てるか即時実行するか、コンテキストを初期化するか保持するかの判断が、自然と下せるようになります。
ほかの記事は生成AIの使い方まとめからご覧いただけます。
この記事で紹介しているコードは、GitHubのMOTOKI-LLC/cg-method-codeにもまとめています。
AIの使い方の記事は、ほかにもあります。
よくある質問：Claude Codeのベストプラクティス
Claude Codeを使いこなすうえで、最も重要な制約は何ですか？
コンテキストウィンドウが最も重要な制約とされています。
無関係な会話や過去のファイル内容、大量のコマンド出力が蓄積するとコンテキストが肥大化し、応答精度の低下や、指示への集中を阻害する要因になります。
タスクを切り替えるときは /clear でコンテキストをまっさらな状態へリセットし、要約の焦点を指定したいときは /compact に指示を添えて実行します。
Claudeの成果物の品質を上げるには、どうすればよいですか？
Claudeに自己検証させる仕組みを用意するのが、最も成功率を高める手法とされています。
テストの実行、画面キャプチャの突合、出力結果の検証など、自身で成否を判断できる環境があると、品質が大きく向上します。
検証基準を与えないと、一見動くように見えて実際には動作しないコードが生成されるリスクが高まります。
たとえば、関数を頼むときにテストケース例を添えて実装後にテストを実行させる、UI変更ではスクリーンショットを貼って結果を撮って比較させる、ビルド失敗ではエラーを貼ってエラーを抑制せず根本原因に対処させる、といった指示です。
検証手段は、テストスイートに限らず、リンターの実行やBashコマンドによる出力確認でも機能します。
的外れな実装を防ぐには、どう進めればよいですか？
調査と設計をコーディングと分離し、探索（Explore）、計画（Plan）、実装（Implement）、コミット（Commit）の4フェーズで進めます。
探索はPlan Modeに切り替えて、コード変更を行わず現状把握の質問へ回答させ、計画は具体的な実装ステップと変更方針の案を作らせ、実装はPlan Modeを終了して計画に沿って実行させます。
事前の確認なしに直接実装へ入らせると、本来の要件と異なる方向でコードを生成してしまう恐れがあります。
プロンプトには、どんな情報を添えればよいですか？
具体的なコンテキストを提供します。
記事では、@によるファイル参照（ファイルの場所を言葉で説明する代わりに使い、処理開始前に対象ファイルを直接読み込みます）、画像の直接添付（UIやエラー画面のコピー＆ペーストやドラッグ＆ドロップ）、URLの参照指定（/permissions で頻繁に使う参照元ドメインを許可リストへ追加できます）、標準入力パイプ（ログを直接渡せます）、自律的な情報取得（Bashコマンドの実行、MCPツール、ファイル読み込みで、必要な情報をClaude自身に収集させます）が挙げられています。
「ログインバグを直して」より、症状と確認すべき場所、再現する失敗するテストを書いてから修正するなどを添えた指示のほうが効果的です。
CLAUDE.mdは、どう整えればよいですか？ 権限の確認が多くて作業が止まるときは？
/init を実行してプロジェクト構成に応じたCLAUDE.mdの雛形を出力し、運用しながら継続的にチューニングします。
配置場所は、ホームディレクトリ（全プロジェクトに横断して適用）、プロジェクトルート（Gitにコミットしてチーム共有するか、CLAUDE.local.md にして .gitignore へ指定）、親ディレクトリ（モノレポで有効）、子ディレクトリ（該当ディレクトリ配下のファイルを編集するときに読み込まれる）です。
権限の確認が頻繁だと、内容を精査せず機械的に承認してしまい、セキュリティが形骸化しかねないので、/permissions で影響が限定的なコマンド（npm run lint や git commit など）を事前承認するか、/sandbox でOSレベルの隔離環境を適用します。
スキル、スラッシュコマンド、CLAUDE.md、サブエージェントは、どう使い分けますか？
CLAUDE.mdは適用範囲に応じて読み込まれる共通指示、スキルは自動判断または手動呼び出しで使う知識・手順、サブエージェントはコンテキストを分離する独立タスク向けです。
現在はカスタムコマンドがスキルに統合され、既存のcommands配下のファイルも利用できます。
フックは、/hooks でClaudeの作業ライフサイクルに合わせて所定のスクリプトを機械的に実行させ（コードの自動整形、リント、.env などの書き換えを拒否するガードレール、監査ログ、通知など）、Claudeが自主的にルールを守ることに頼らず、処理を確実に強制できます。
同じ修正を何度頼んでも直らないときは、どうしますか？ 巻き戻しや再開は？
同じセッション内で同じ課題に2回以上修正を指示している場合、コンテキスト内は失敗した試行錯誤のノイズで埋もれています。
/clear でコンテキストをクリアし、それまでの試行で得られた前提条件を盛り込んだ具体的なプロンプトで仕切り直します。
新しいセッションへ移る場合は、判明した条件と必要な経緯を先に保存します。
切り替えだけで成果が必ず良くなるわけではありません。
Escを2回押すか /rewind で、過去の会話履歴やコード状態へ復元でき、claude --continue で直前のセッションを、--resume で過去のセッション一覧から選んで再開できます。
セッションはGitブランチと同じ感覚で運用し、/rename で分かりやすい名前（例：「oauth-migration」）を付けます。
コードベースの調査は、サブエージェントに任せると、メインセッションのコンテキストを実装作業用に温存できます。
自動化や大量のファイル処理は、どうすればよいですか？ 気をつけることは？
claude -p "プロンプト"で非対話実行でき、CI/CDやコミット前フックなどに組み込めます。
ストリーミング形式のJSON出力には、--output-format stream-json --verboseを追加します。
多数のファイルは、対象を一覧化させ、ループで各要素に claude -p を実行し、最初の2〜3件で試してから全件へ移ります。
無人実行では、確認を省略するツールを--allowedToolsで指定し、利用できる組み込みツールを限定する場合は--toolsも使います。
MCPツールやファイル・ネットワークの境界は別途設定します。
--dangerously-skip-permissions は通常の権限確認を省略しますが、予期せぬデータ消失、システム破損、プロンプトインジェクションによる情報流出のリスクがあるため、インターネット接続を遮断したコンテナ環境に限定して使い、/sandbox は対応環境でアクセス範囲を制限する別の機能で、設定と例外の確認が必要です。
初心者が陥りやすい失敗パターンは？ このガイドは絶対のルールですか？
記事では、何でも詰め込むセッション（キッチンシンク）、セッション内で修正を繰り返す泥沼化、ルールを詰め込みすぎたCLAUDE.md、ノーチェックで信頼してしまうギャップ、目的のない無限探索（「コードベース全体を調査して」と頼むと、何百ものファイルを読み込んでコンテキスト容量を使い果たすため、調査対象を厳密に限定するか、サブエージェントに任せる）が挙げられています。
紹介されたテクニックは絶対不変の固定ルールではなく、複雑な単一の不具合に深く挑み、過去の経緯が不可欠な場合は、あえてコンテキストを蓄積させたほうが良いこともあり、探索的な初期段階では、事前計画をスキップしたほうが有効な場合もあります。
うまくいった要因と、そうでなかった原因を振り返り、判断の勘所を養うことが勧められています。
最新の仕様は、公式ドキュメントで確認してください。
