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

環境の設定から並列セッションでのスケールまで、Claude Code を最大限に活用するためのヒントとパターン。

Claude Code はエージェント型のコーディング環境です。質問に答えて待つだけのチャットボットとは異なり、Claude Code はファイルを読み、コマンドを実行し、変更を加え、あなたが見守ったり方向修正したり、完全に離席している間でも自律的に問題を解決できます。

これは働き方を変えます。自分でコードを書いて Claude にレビューを頼む代わりに、やりたいことを説明すれば、Claude がそれをどう構築するかを考えます。Claude は探索し、計画し、実装します。

ただし、この自律性には学習曲線があります。Claude は、理解しておくべきいくつかの制約の中で動作します。

このガイドでは、Anthropic の社内チームや、さまざまなコードベース・言語・環境で Claude Code を使っているエンジニアたちの間で効果が実証されているパターンを紹介します。エージェントループが内部でどのように動作するかについては、Claude Code の仕組み を参照してください。

ほとんどのベストプラクティスは、1 つの制約に基づいています。それは Claude のコンテキストウィンドウはすぐにいっぱいになり、埋まるにつれて性能が低下する という点です。

Claude のコンテキストウィンドウには、すべての会話内容（すべてのメッセージ、Claude が読んだすべてのファイル、すべてのコマンド出力）が含まれます。しかし、これはすぐに埋まります。1 回のデバッグセッションやコードベース探索だけで、数万トークンを生成・消費することもあります。

これは重要です。LLM はコンテキストが埋まるにつれて性能が低下するからです。コンテキストウィンドウがいっぱいに近づくと、Claude は以前の指示を「忘れ」たり、ミスが増えたりします。コンテキストウィンドウは管理すべき最も重要なリソース です。トークン使用量を減らす詳細な戦略については、トークン使用量を減らす を参照してください。

Claude が自分で作業を検証できるようにする

Claude は、テストを実行したり、スクリーンショットを比較したり、出力を検証できる場合、劇的にパフォーマンスが向上します。

明確な成功基準がないと、見た目は正しそうでも実際には動かないものを作ってしまうことがあります。その場合、あなた自身が唯一のフィードバックループとなり、すべてのミスにあなたの注意が必要になります。

UI の変更は Claude in Chrome 拡張 を使って検証できます。ブラウザを開き、UI をテストし、コードが動くまで反復します。

検証方法は、テストスイート、リンター、出力を確認する Bash コマンドでも構いません。検証を堅牢にすることに投資してください。

まず探索、次に計画、そしてコードを書く

Claude にいきなりコーディングさせると、間違った問題を解決するコードが生成されることがあります。Plan Mode を使って、探索と実行を分離してください。

推奨されるワークフローは 4 つのフェーズで構成されます。

Explore（探索）

Plan Mode に入ります。Claude はファイルを読み、変更を加えずに質問に答えます。

 /src/auth を読んで、セッションとログインをどのように扱っているかを理解してください。
また、シークレット用の環境変数をどのように管理しているかも確認してください。

Plan（計画）

Claude に詳細な実装計画を作成させます。

Google OAuthを追加したいです。どのファイルを変更する必要がありますか？
セッションのフローはどうなりますか？計画を作成してください。

Ctrl+G を押して計画をテキストエディタで開き、Claude が続行する前に直接編集できます。

Implement（実装）

Normal Mode に戻し、計画に沿って Claude にコードを書かせます。

計画に基づいてOAuthフローを実装する。コールバックハンドラのテストを書き、
テストスイートを実行して、失敗があれば修正する。

Commit（コミット）

説明的なメッセージでコミットし、PR を作成させます。

説明的なメッセージでコミットして、PRを作成する

プロンプトには具体的なコンテキストを与える

Claude は意図を推測できますが、あなたの心を読むことはできません。具体的なファイルを参照し、制約を明示し、例となるパターンを指し示してください。

探索段階であれば、曖昧なプロンプトが役立つこともあります。「このファイルで改善できる点は？」 のようなプロンプトは、自分では思いつかなかった点を引き出してくれます。

リッチなコンテンツを提供する

Claude にリッチなデータを提供する方法はいくつかあります。

• @ でファイルを参照：コードの場所を説明する代わりに指定します。Claude は応答前にファイルを読みます。
• 画像を直接貼り付け：コピー＆ペースト、またはドラッグ＆ドロップ。
• URL を渡す：ドキュメントや API リファレンス用。頻繁に使うドメインは /permissions で許可リストに追加できます。
• データをパイプ：cat error.log | claude のようにしてファイル内容を直接送信します。
• Claude に取得させる：Bash コマンド、MCP ツール、またはファイル読み込みで必要なコンテキストを自分で取得するよう指示します。

環境を設定する

いくつかのセットアップを行うだけで、すべてのセッションにおいて Claude Code の効果が大きく向上します。拡張機能の全体像と使い分けについては、Claude Code を拡張する を参照してください。

効果的な CLAUDE.md を書く

CLAUDE.md は、すべての会話の開始時に Claude が読む特別なファイルです。Bash コマンド、コードスタイル、ワークフロールールを含めます。これにより、コードだけでは推測できない永続的なコンテキスト を Claude に与えられます。

/init コマンドはコードベースを解析し、ビルドシステム、テストフレームワーク、コードパターンを検出して、洗練のための堅実な土台を提供します。

CLAUDE.md に必須の形式はありませんが、短く人間が読みやすいものにしてください。例:

# コードスタイル
- CommonJS（require）ではなく、ES モジュール（import/export）構文を使用する
- 可能な場合は、インポートを分割代入する（例：import { foo } from 'bar'）

# ワークフロー
- 一連のコード変更を終えたら、必ず型チェックを行う
- パフォーマンスのため、テストスイート全体ではなく、単体のテストを実行することを優先する

CLAUDE.md は毎セッション読み込まれるため、広く適用される内容のみを含めてください。特定の状況でのみ関連するドメイン知識やワークフローは、skills を使ってください。Claude は必要なときだけ読み込み、会話全体を肥大化させません。

簡潔さを保ってください。各行について「これを削除したら Claude はミスをするか？」と自問してください。しないなら削除しましょう。肥大化した CLAUDE.md は、Claude が実際の指示を無視する原因になります。

Claude が、禁止しているはずのことを繰り返す場合、ファイルが長すぎてルールが埋もれている可能性があります。CLAUDE.md に答えがある質問を Claude がしてくる場合、表現が曖昧かもしれません。CLAUDE.md はコードと同様に扱ってください。問題が起きたら見直し、定期的に整理し、変更によって Claude の挙動が本当に変わるか観察してください。

強調（例: 「重要」「必ず」）を加えることで遵守率を高めることもできます。CLAUDE.md は git にコミットして、チームで育てていきましょう。ファイルは時間とともに価値が積み上がります。

CLAUDE.md では @path/to/import 構文で追加ファイルをインポートできます。

プロジェクト概要は @README.md を参照し、利用可能な npm コマンド
一覧は @package.json を参照してください。

# 追加の指示
- Git ワークフロー: @docs/git-instructions.md
- 個人用オーバーライド: @~/.claude/my-project-instructions.md

CLAUDE.md は複数の場所に置けます。

• ホームフォルダ (~/.claude/CLAUDE.md)：すべての Claude セッションに適用
• プロジェクトルート (./CLAUDE.md)：git にコミットしてチーム共有、または CLAUDE.local.md にして .gitignore
• 親ディレクトリ：モノレポで有用。root/CLAUDE.md と root/foo/CLAUDE.md が自動的に読み込まれる
• 子ディレクトリ：そのディレクトリ内のファイルを扱うときにオンデマンドで読み込まれる

権限を設定する

デフォルトでは、Claude Code はシステムを変更する可能性のある操作（ファイル書き込み、Bash コマンド、MCP ツールなど）ごとに許可を求めます。安全ですが煩雑です。10 回目の承認になる頃には、もう確認せずにクリックしているでしょう。割り込みを減らす方法は 2 つあります。

• 権限の許可リスト：npm run lint や git commit など、安全だと分かっているツールを許可
• サンドボックス：ファイルシステムやネットワークアクセスを制限する OS レベルの分離を有効化し、定義された境界内でより自由に作業させる

また、--dangerously-skip-permissions を使えば、lint 修正やボイラープレート生成のような限定的ワークフローで、すべての権限チェックをスキップできます。

詳細は 権限の設定 と サンドボックスの有効化 を参照してください。

CLI ツールを使う

CLI ツールは、外部サービスとやり取りする最もコンテキスト効率の良い方法です。GitHub を使っているなら gh CLI をインストールしてください。Claude は Issue 作成、PR オープン、コメント閲覧に使いこなせます。gh がない場合も GitHub API は使えますが、未認証リクエストはレート制限にかかりやすくなります。

Claude は、知らない CLI ツールを学ぶのも得意です。foo-cli-tool --help を使って学ばせ、その後で問題を解かせてみてください。

MCP サーバーを接続する

MCP サーバー を使うと、Issue トラッカーからの機能実装、データベースクエリ、監視データ分析、Figma デザインの統合、ワークフロー自動化などを Claude に任せられます。

フックを設定する

Hooks は、Claude のワークフロー内の特定ポイントで自動的にスクリプトを実行します。助言的な CLAUDE.md と異なり、フックは決定的で、必ず実行されます。

Claude にフックを書かせることもできます。「毎回ファイル編集後に eslint を実行するフックを書いて」 や 「migrations フォルダへの書き込みをブロックするフックを書いて」 などと試してください。/hooks で対話的に設定するか、.claude/settings.json を直接編集します。

スキルを作成する

Skills は、プロジェクト・チーム・ドメイン固有の情報で Claude の知識を拡張します。関連するときに自動適用されるほか、/skill-name で直接呼び出せます。

.claude/skills/ にディレクトリと SKILL.md を追加してスキルを作成します。

---
name: api-conventions
description: 当社サービス向けのREST API設計規約
---
# API 規約
- URL パスには kebab-case を使用する
- JSON プロパティには camelCase を使用する
- リスト系エンドポイントには必ずページネーションを含める
- API は URL パスでバージョニングする（/v1/、/v2/）

スキルでは、直接呼び出せる再利用可能なワークフローも定義できます。

---
name: fix-issue
description: GitHub の Issue を修正する
disable-model-invocation: true
---
GitHub の Issue を分析して修正してください: $ARGUMENTS。

1. `gh issue view` を使用して Issue の詳細を取得する
2. Issue に記載されている問題を理解する
3. 関連するファイルをコードベース内で検索する
4. Issue を修正するために必要な変更を実装する
5. 修正を検証するためのテストを書いて実行する
6. コードが lint および型チェックを通過することを確認する
7. 分かりやすいコミットメッセージを作成する
8. push して PR を作成する

/fix-issue 1234 のように実行します。副作用のあるワークフローを手動でトリガーしたい場合は disable-model-invocation: true を使ってください。

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

サブエージェント は独自のコンテキストと許可ツールセットで実行されます。多くのファイルを読む調査や、専門的な集中が必要なタスクで、メイン会話を汚さずに済みます。

---
名前: security-reviewer
説明: コードのセキュリティ脆弱性をレビューします
ツール: Read, Grep, Glob, Bash
モデル: opus
---
あなたは上級セキュリティエンジニアです。コードを以下の点でレビューしてください：
- インジェクション脆弱性（SQL、XSS、コマンドインジェクション）
- 認証および認可の欠陥
- コード内の秘密情報や認証情報
- 安全でないデータ処理

具体的な行番号の参照と修正案を提供してください。

「このコードをセキュリティ観点でレビューするためにサブエージェントを使って」 のように、明示的に使うよう指示してください。

プラグインをインストールする

Plugins は、スキル、フック、サブエージェント、MCP サーバーを 1 つのインストール単位にまとめたものです。型付き言語を使う場合は、編集後の正確なシンボルナビゲーションや自動エラー検出を提供する コードインテリジェンス プラグイン をインストールしてください。

スキル、サブエージェント、フック、MCP の使い分けについては、Claude Code を拡張する を参照してください。

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

Claude Code とのコミュニケーション方法は、結果の質に大きく影響します。

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

新しいコードベースにオンボーディングする際、Claude Code は学習と探索に使えます。実際のエンジニアに聞くような質問をそのまま投げてください。

• ロギングはどう動いている？
• 新しい API エンドポイントはどう作る？
• foo.rs の 134 行目にある async move { ... } は何をしている？
• CustomerOnboardingFlowImpl はどんなエッジケースを扱っている？
• 333 行目でなぜ bar() ではなく foo() を呼んでいる？

この使い方はオンボーディングを効率化し、立ち上がり時間を短縮し、他のエンジニアの負荷を減らします。特別なプロンプトは不要です。普通に質問してください。

Claude にインタビューさせる

Claude は、技術実装、UI/UX、エッジケース、トレードオフなど、あなたがまだ考えていない点を掘り下げて質問します。

私は[簡単な説明]を作りたいです。AskUserQuestionツールを使って、詳細に私にインタビューしてください。

技術的な実装、UI/UX、エッジケース、懸念点、トレードオフについて質問してください。明白な質問はせず、私が考慮していないかもしれない難しい部分に深く掘り下げてください。

すべてカバーできるまでインタビューを続け、その後、完全な仕様書をSPEC.mdに作成してください。

仕様が完成したら、新しいセッションで実行を開始してください。新しいセッションは実装に完全に集中したクリーンなコンテキストを持ち、参照できる仕様書もあります。

セッションを管理する

会話は永続的で、巻き戻し可能です。これを活用してください。

早めに、頻繁に軌道修正する

最良の結果は、タイトなフィードバックループから生まれます。最初から完璧なこともありますが、早期修正の方が一般に速く良い解決策に到達します。

• Esc：Esc キーで途中停止。コンテキストは保持されるので方向修正できます。
• Esc + Esc または /rewind：巻き戻しメニューを開いて、以前の会話やコード状態に戻します。
• 「Undo that」：変更を元に戻させます。
• /clear：無関係なタスク間でコンテキストをリセットします。

同じ問題で 1 セッション中に 2 回以上修正している場合、コンテキストは失敗アプローチで汚れています。/clear して、学んだことを反映したより具体的なプロンプトでやり直してください。クリーンなセッションは、長い修正履歴のあるセッションよりほぼ常に優れます。

コンテキストを積極的に管理する

コンテキスト制限に近づくと、Claude Code は自動的に会話履歴を要約し、重要なコードや決定を保持しつつ空きを作ります。

長いセッションでは、無関係な会話、ファイル内容、コマンドが溜まり、性能低下や注意散漫の原因になります。

• 無関係なタスク間では頻繁に /clear
• 自動要約時、重要なコードパターン、ファイル状態、主要な決定が保持される
• より細かく制御したい場合は /compact <instructions>（例: /compact API の変更に集中して）
• CLAUDE.md に「要約時は変更ファイル一覧とテストコマンドを必ず保持する」などの指示を追加可能

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

コンテキストが根本的な制約であるため、サブエージェントは非常に強力です。調査で多くのファイルを読むとコンテキストを消費しますが、サブエージェントは別コンテキストで探索し、要約だけを返します。

実装後の検証にも使えます。

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

Claude は変更前に自動チェックポイントを作成します。Esc を 2 回、または /rewind でメニューを開き、会話のみ、コードのみ、または両方を復元できます。

すべてを慎重に計画する代わりに、リスクのあることを試させても構いません。うまくいかなければ巻き戻して別案を試します。チェックポイントはセッションをまたいで保持されます。

会話を再開する

Claude Code は会話をローカルに保存します。複数日にまたがるタスクでも、再説明は不要です。

claude --continue    
# 最近の会話から選択
claude --resume      

/rename でセッションに名前を付けてください（「oauth-migration」「debugging-memory-leak」など）。セッションはブランチのように扱えます。

自動化とスケール

1 つの Claude に慣れたら、並列セッション、ヘッドレスモード、ファンアウトで生産性を拡大しましょう。

ここまでは「人 1 人、Claude 1 つ、会話 1 つ」を前提にしていましたが、Claude Code は水平スケールできます。

ヘッドレスモードを使う

claude -p "your prompt" で、対話なしに Claude を実行できます。CI パイプラインや自動化の中核です。出力形式（テキスト、JSON、ストリーミング JSON）により、プログラムで解析できます。

claude -p "Explain what this project does"

# スクリプト向け構造化出力
claude -p "List all API endpoints" --output-format json

# リアルタイム処理用ストリーミング
claude -p "Analyze this log file" --output-format stream-json

複数の Claude セッションを実行する

主な方法は 2 つです。

• Claude Desktop：複数のローカルセッションを視覚的に管理。各セッションは独立した worktree。
• Web 版 Claude Code：Anthropic の安全なクラウド VM 上で実行。

並列化だけでなく、品質重視のワークフローにも有効です。新しいコンテキストは、直前に書いたコードへのバイアスがありません。

例：Writer / Reviewer パターン

ファイル横断でファンアウトする

大規模移行や分析では、多数の Claude 呼び出しに分散できます。

タスクリストを生成

移行対象ファイルを列挙させる（例: 「移行が必要な 2,000 個の Python ファイルを列挙」）

ループ用スクリプトを書く

for file in $(cat files.txt); do
  claude -p "React から Vue へ $file を移行します。OK または FAIL を返します。" \
--allowedTools "Edit,Bash(git commit *)"
done

少数でテストしてから全体実行

最初の 2～3 ファイルで問題点を洗い出し、プロンプトを改善してから全体に適用します。

既存のデータ処理パイプラインにも統合できます。

claude -p "<your prompt>" --output-format json | your_command

開発中は --verbose、本番ではオフにしてください。

セーフな自律モード

claude --dangerously-skip-permissions を使うと、すべての権限チェックをスキップし、割り込みなく作業させられます。lint 修正やボイラープレート生成に適しています。

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

早期に認識すれば時間を節約できます。

• キッチンシンク セッション：無関係なタスクを混ぜる

  対策：無関係なタスク間で /clear

• 何度も同じ修正：失敗アプローチでコンテキストが汚れる

  対策：2 回失敗したら /clear して、より良い初期プロンプトで再開

• 肥大化した CLAUDE.md：重要ルールが埋もれる

  対策：徹底的に削減。不要なら削除かフックへ

• 信頼して検証しない：それっぽいが欠陥のある実装

  対策：必ず検証（テスト、スクリプト、スクショ）

• 無限探索：スコープなし調査でコンテキスト消費

  対策：調査を狭くするかサブエージェントを使う

直感を育てる

このガイドのパターンは出発点です。常に最適とは限りません。

複雑な問題ではコンテキストを溜めるべきこともあります。探索的タスクでは計画を省くこともあります。曖昧なプロンプトが最適な場合もあります。

うまくいったときは理由を観察してください。うまくいかないときは原因を考えてください。やがて、いつ具体化し、いつ開放的にするか、いつ計画し、いつ探索するかが分かるようになります。

関連リソース

参考
https://code.claude.com/docs/en/best-practices