環境設定から並列セッションの活用まで、Claude Codeを最大限に生かすための実践ヒントと設計パターン集。
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）
Normal 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のように、ターミナル出力やログを直接渡せます。 - 自律的な情報取得：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レベルの隔離環境を適用する。作業の中断頻度を抑えつつ、安全性を両立できます。
標準設定では、ファイルの書き換え、シェルコマンド実行、MCPツール呼び出しなど、環境に変更を及ぼす操作のたびに確認プロンプトが表示されます。
安全ではあるものの、実行のたびに承認を求められると作業効率が低下します。
確認が頻繁に続くと内容を精査せず機械的に承認してしまい、セキュリティ上の形骸化を招きかねません。
承認による作業の中断を減らすアプローチは主に2つあります。
- 権限の許可リスト登録：影響が限定的なコマンドを事前承認します（例：
npm run lintやgit commitなど）。 - サンドボックス機能：ファイルアクセスやネットワーク通信をOSレベルで制限し、隔離された安全領域内でClaudeに作業を完結させます。
あるいは、--dangerously-skip-permissionsオプションを付与すると、静的解析エラーの修正や雛形生成などの定型作業に限り、すべての承認プロセスを一括でスキップできます。
⚠️ 警告：任意のコマンド実行を無制限に許可すると、データの消失、環境の破損、プロンプトインジェクションに伴う機密流出のリスクが生じます。
--dangerously-skip-permissionsフラグは、外部ネットワークから切り離されたサンドボックス環境でのみ利用してください。
CLIツールを連携させる
クラウドサービスや外部APIとの連携には、
gh、aws、gcloud、sentry-cliなどの専用CLIを活用するよう指示する。
CLIツールは、コンテキスト消費を最小限に抑えながら外部サービスとやり取りできる効率的な手段です。
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や、個別指定に対応した$1、$2などの変数を利用できます。
---
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/スラッシュコマンドとは異なり、スキルはコマンド実行ではなく作業文脈に応じて自動で読み込まれます。プロジェクトやチームの固有ルールをスキルとして定義しておくことで、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の操作ごとにチェックポイントが自動生成される。
過去の任意の時点へ、会話履歴、コード変更、あるいはその両方を復元できます。
Claude Codeはファイル変更を行う直前に、自動でチェックポイントを記録します。
Escapeキーを2回押すか、/rewindを実行してチェックポイント管理画面を開きます。
会話履歴のみ復元、コード変更のみ復元、両方を同時に復元のいずれかを選択できます。
最初から完璧な手順を練り込まずとも、不確実な変更を気軽にClaudeへ試させることができます。
期待通りの結果にならなければ、チェックポイントから直前の状態へ巻き戻して別のアプローチを取り直せます。
チェックポイントはセッション終了後も保持されるため、ターミナルを終了した後でも復元操作が可能です。
⚠️ 注意：チェックポイント機能が追跡するのは、Claude自身が編集した差分のみです。
外部プロセスや開発者自身による手動変更は追跡されません。
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を指定します。
claude -p "your prompt"を指定することで、インタラクティブ画面を介さずにClaudeをバックグラウンド実行できます。
ヘッドレスモードを利用すれば、CI/CDパイプラインやコミット前フックなど、既存のスクリプトへ容易に組み込めます。
テキスト、JSON、ストリーミングJSONなどの出力形式を選択できるため、後続のプログラムで出力を簡単にパースできます。
# 1回限りのクエリ
claude -p "このプロジェクトが何をするか説明して"
# スクリプト用の構造化出力
claude -p "すべてのAPIエンドポイントをリストして" --output-format json
# リアルタイム処理用のストリーミング
claude -p "このログファイルを分析して" --output-format stream-json
複数の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を指定します。
大規模なリファクタリングや一括解析では、複数のClaudeプロセスへ処理を分散できます。
- 対象タスクの一覧化：修正対象となる全ファイルをClaudeにリストアップさせます（例：「変更が必要なPythonファイル2,000件をリスト化して」など）。
- リストをループするスクリプトの作成：
for file in $(cat files.txt); do
claude -p "$fileをReactからVueに移行して。OKまたはFAILを返して" \
--allowedTools "Edit,Bash(git commit:*)"
done
- 少数ファイルでの事前検証：最初の2〜3件で試行してプロンプトや動作の不備を改善し、問題が解消してから全件の一括処理へ移行します。
--allowedToolsオプションを指定して実行権限をあらかじめ制限しておく運用が、無人実行時の安全確保に欠かせません。
社内のデータ処理や既存のバッチパイプラインへClaudeを組み込むことも可能です。
claude -p "<your prompt>" --output-format json | your_command
開発中の動作確認には--verboseフラグを有効化し、本番運用の自動スクリプトでは無効化します。
安全に自律モードを運用する
claude --dangerously-skip-permissionsオプションを使うと、すべての権限確認をスキップしてClaudeを中断なしに作業させることができます。
リントエラーの一括修正やボイラープレートの自動生成など、低リスクな作業で大きな威力を発揮します。
⚠️ 警告：任意のコマンド実行を無制限に許可すると、予期せぬデータ消失やシステム破損、プロンプトインジェクション等による情報流出のリスクを伴います。
これらの脅威を最小限に抑えるため、インターネット接続を遮断したコンテナ環境に限定して
--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の使い方の記事は、ほかにもあります。
