概要

このガイドは、Anthropicが開発したエージェント型コーディングのためのコマンドラインツール「Claude Code」のベストプラクティスをまとめたものです。Claude Codeは「意図的にローレベルで、特定のワークフローを強制しない、モデルへの直接的なアクセスを提供する」設計になっています。

1. セットアップのカスタマイズ

CLAUDE.mdファイルの作成

CLAUDE.mdは、会話開始時にClaudeが自動的にコンテキストに取り込む特別なファイルです。以下の内容を記載することを推奨します：

• よく使うbashコマンド
• コアファイルとユーティリティ関数
• コードスタイルガイドライン
• テスト手順
• リポジトリのエチケット（ブランチ命名規則、マージ vs リベースの方針）
• 開発環境のセットアップ
• プロジェクト固有の予期しない動作や警告
• Claudeに覚えておいてほしいその他の情報

CLAUDE.mdの構成例：

# Bashコマンド
- npm run build: プロジェクトをビルド
- npm run typecheck: 型チェッカーを実行

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

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

ファイルの配置オプション：

• リポジトリのルート（CLAUDE.mdとしてgitで共有、またはCLAUDE.local.mdとしてローカル専用）
• 親ディレクトリ（モノレポで、ルートのCLAUDE.mdとサブディレクトリ版の両方が適用される場合に便利）
• 子ディレクトリ（Claudeがそれらのファイルで作業する際にオンデマンドで取り込む）
• ホームフォルダ（~/.claude/CLAUDE.md、すべてのセッションで適用）

/initコマンドで自動的にスターター用のCLAUDE.mdファイルを生成できます。

CLAUDE.mdファイルのチューニング

CLAUDE.mdの内容はClaudeのプロンプトの一部になるため、洗練が重要です。「効果を検証せずに大量のコンテンツを追加する」ことは避けてください。何が最適な指示遵守を生み出すかを実験で確認しましょう。#キーを使うと、Claudeが自動的に指示をCLAUDE.mdファイルに組み込めます。一部のチームではファイルをプロンプト改善ツールに通したり、「IMPORTANT」や「YOU MUST」などの強調キーワードを使用して遵守を強化しています。

許可ツールのキュレーション

Claude Codeはデフォルトで、システムを変更するアクション（ファイル書き込み、多くのbashコマンド、MCPツール）に対して許可を要求します。4つの管理方法があります：

1. セッション中に「Always allow（常に許可）」を選択
2. /permissionsコマンドでツールを追加・削除（例：Editでファイル編集、Bash(git commit:*)でコミット、mcp__puppeteer__puppeteer_navigateで特定のMCPツール）
3. .claude/settings.jsonまたは~/.claude.jsonを手動編集（前者はチーム共有に推奨）
4. --allowedTools CLIフラグでセッション固有の許可を設定

GitHub CLIのインストール

ClaudeはGitHubとのやり取り（Issue作成、プルリクエストのオープン、コメントの読み取り）にgh CLIコマンドを理解します。インストールされていない場合でも、GitHub APIまたはMCPサーバーが利用可能であれば使用できます。

2. Claudeにさらなるツールを

Claude Codeはbash環境へのアクセスを継承し、利用可能なすべてのツールに即座にアクセスできます。ただし、カスタムbashツールには明示的な指示が必要です。頻繁に使用するツールについては、CLAUDE.mdに記載するか、Claudeに--helpを実行してドキュメントを取得するよう指示してください。

MCPでClaudeを使用

Claude CodeはMCPサーバーとクライアントの両方として機能します。MCPサーバーは3つの方法で設定できます：

1. プロジェクト設定 - そのディレクトリでのみ利用可能
2. グローバル設定 - すべてのプロジェクトで利用可能
3. チェックインされた.mcp.json - コードベースで作業するすべてのチームメンバーと共有

開発中の設定問題の特定には--mcp-debugフラグが役立ちます。

カスタムスラッシュコマンドの使用

.claude/commands/フォルダにMarkdownファイルとしてプロンプトテンプレートを保存すると、/メニューから利用可能なスラッシュコマンドを作成できます。これらはgitにチェックインしてチームでアクセスできます。$ARGUMENTSキーワードでコマンド呼び出しからパラメータを渡すことができます。

GitHubのIssue修正コマンドの例：

GitHubのIssueを分析して修正してください: $ARGUMENTS

以下の手順に従ってください：

1. `gh issue view`でIssueの詳細を取得
2. Issueに記載された問題を理解
3. 関連するファイルをコードベースで検索
4. Issueを修正するために必要な変更を実装
5. 修正を検証するテストを作成・実行
6. コードがリントと型チェックに合格することを確認
7. 説明的なコミットメッセージを作成
8. プッシュしてPRを作成

GitHub関連のすべてのタスクにはGitHub CLI (`gh`) を使用してください。

.claude/commands/fix-github-issue.mdに保存すると、/project:fix-github-issueコマンドとして利用可能になります（Issue #1234の場合は/project:fix-github-issue 1234と呼び出し）。個人用コマンドは~/.claude/commands/に配置すると、すべてのセッションで利用可能になります。

3. 一般的なワークフローを試す

探索、計画、コード、コミット

この汎用的な4ステップアプローチ：

1. 関連するファイル、画像、URLを読むようClaudeに依頼（まだコードは書かない）。一般的なポインタまたは具体的なファイル名を使用。この段階では、詳細の確認や特定の質問の調査にサブエージェントの使用が有効で、特に会話の初期にコンテキストの可用性を保持するのに役立ちます。
2. コーディング前に計画を立てるようClaudeに依頼。「think」を使うと拡張思考モードがトリガーされ、追加の計算時間が割り当てられます。システムはこれらのフレーズを思考予算レベルにマッピングします：「think」 < 「think hard」 < 「think harder」 < 「ultrathink」。それぞれ段階的により多くの思考リソースを割り当てます。実装が逸脱した場合にリセットできるよう、計画をドキュメントまたはGitHub Issueに作成してください。
3. 解決策を実装するようClaudeに依頼。各部分の実装時に解決策の妥当性を明示的に検証するよう要求します。
4. 結果をコミットしてプルリクエストを作成するようClaudeに依頼。必要に応じてREADMEや変更履歴を更新します。

ステップ1-2は重要です。これらがないと、Claudeはコーディングに飛びつく傾向があります。調査と計画は、より深い思考を必要とする問題に対してパフォーマンスを大幅に向上させます。

テストを書く、コミット；コード、イテレート、コミット

このテスト駆動開発ワークフローは、容易に検証可能な変更を実現します：

1. 期待される入出力ペアに基づいてテストを作成。存在しない機能のモック実装を避けるため、テスト駆動開発であることを明示的に伝えます
2. テストを実行してfailすることを確認。実装コードは書かない
3. 満足したらテストをコミット
4. テストに合格するコードを作成。テストを変更しないよう指示します。すべて合格するまで続け、通常数回のイテレーションが必要です。サブエージェントで実装がテストに過剰適合していないか検証できます
5. 満足したらコードをコミット

Claudeは明確なイテレーションターゲット（ビジュアルモック、テストケース、その他の出力）があると最高のパフォーマンスを発揮します。期待される出力があれば、変更、評価、段階的な改善が可能になります。

コードを書く、結果をスクリーンショット、イテレート

以下を通じてビジュアルターゲットを提供：

1. ブラウザのスクリーンショット機能（Puppeteer MCPサーバー、iOSシミュレーターMCPサーバー、または手動でのコピー＆ペースト経由）
2. ビジュアルモック（ファイルパスまたはドラッグ＆ドロップで画像を提供）
3. 結果がモックと一致するまで実装とイテレーション
4. 満足したらコミット

人間と同様に、Claudeの出力はイテレーションを通じて大幅に改善されます。最初のバージョンは良いかもしれませんが、2〜3回のイテレーション後には通常はるかに良くなります。

安全なYOLOモード

claude --dangerously-skip-permissionsは許可チェックをバイパスし、Claudeが中断なく作業できるようにします。リントエラーの修正やボイラープレートの生成などのワークフローに最適です。これにはデータ損失やシステム破損を含む重大なリスクがあります。リスクを最小限にするには、インターネットアクセスなしのコンテナを使用してください。Docker Dev Containerのリファレンス実装がClaude Codeリポジトリにあります。

コードベースQ&A

チームメイトとペアプログラミングするように質問して、新しいコードベースへのオンボーディングにClaude Codeを使用：

• ロギングはどのように機能しますか？
• 新しいAPIエンドポイントを作成するにはどうすればよいですか？
• foo.rsの134行目のasync move { ... }は何をしていますか？
• CustomerOnboardingFlowImplはどのようなエッジケースを処理しますか？
• 333行目でbar()ではなくfoo()を呼び出しているのはなぜですか？
• baz.pyの334行目に相当するJavaコードは何ですか？

Claudeはエージェント的にコードベースを検索して回答を見つけます。特別なプロンプトは不要です。Anthropicでは、これがコアオンボーディングワークフローになり、ランプアップ時間を大幅に短縮し、他のエンジニアの負荷を軽減しています。

Claudeをgit操作に使用

Claudeは多くのgit操作を効果的に処理します。Anthropicのエンジニアは90%以上のgit操作にClaudeを使用しています：

• git履歴の検索：リリースの変更、機能の所有者、APIデザインの根拠に関する質問に回答（Claudeに履歴をレビューするよう明示的にプロンプトすることが有効）
• コミットメッセージの作成：差分と最近の履歴を自動的に調べる
• 複雑なgit操作の処理：ファイルのリバート、リベースの競合解決、パッチの比較・適用

ClaudeをGitHub操作に使用

Claude CodeはGitHubとのやり取りを管理：

• プルリクエストの作成（「pr」の短縮形を理解し、差分とコンテキストに基づいて適切なメッセージを生成）
• ワンショットでのコードレビュー解決の実装（PRのコメントを修正し、オプションで具体的な指示を追加してPRブランチにプッシュ）
• 失敗したビルドまたはリンター警告の修正
• オープンなGitHub Issueをループしてカテゴライズとトリアージ

これにより、ghの構文を覚える必要がなくなり、ルーティンタスクを自動化できます。

Jupyterノートブックでの作業

研究者やデータサイエンティストは、Jupyterノートブックの読み書きにClaude Codeを使用しています。Claudeは画像を含む出力を解釈し、高速なデータ探索とやり取りを提供します。必須のプロンプトはありませんが、推奨ワークフロー：Claude Codeと.ipynbファイルをVS Codeで並べて開いておく。Claudeにノートブックやデータの可視化を「見栄え良く」するよう依頼すると、人間の閲覧体験の最適化に役立ちます。

4. ワークフローの最適化

指示を具体的に

Claudeの成功率は「より具体的な指示で大幅に向上し、特に最初の試行で顕著」です。事前の明確な指示により、軌道修正が減少します。

比較例：

Claudeは意図を推測できますが、心を読めません。具体性がアラインメントを向上させます。

Claudeに画像を渡す

Claudeは以下を通じて画像やダイアグラムに優れています：

• スクリーンショットを貼り付け（macOSではcmd+ctrl+shift+4でクリップボードにスクリーンショット、ctrl+vで貼り付け。cmd+vではないことに注意）
• 画像をプロンプトに直接ドラッグ＆ドロップ
• 画像のファイルパスを提供

UI開発の参照ポイントとしてのデザインモックや、分析とデバッグのためのビジュアルチャートに特に有用です。ビジュアルが提供されない場合、視覚的な魅力の重要性を強調することが助けになります。

見てほしいファイルを言及

リポジトリ全体のファイルやフォルダを参照するためにタブ補完を使用し、Claudeが正しいリソースを見つけたり更新したりするのを助けます。

ClaudeにURLを渡す

Claudeが取得して読み取るように、プロンプトと一緒に特定のURLを貼り付けます。/permissionsを使用してドメインを許可リストに追加（例：docs.foo.com）すると、繰り返しの許可プロンプトを回避できます。

早期かつ頻繁に軌道修正

自動承認モード（shift+tabで切り替え）は自律的な作業を可能にしますが、通常はアクティブなコラボレーションとガイダンスでより良い結果が得られます。4つの軌道修正ツール：

1. コーディング前に計画を立てるようClaudeに依頼し、実装開始前に承認を確認
2. Escapeキーを押してClaudeを中断（思考中、ツール呼び出し中、ファイル編集中のいずれでも）。コンテキストは保持され、リダイレクトが可能
3. Escapeダブルタップで履歴を遡り、以前のプロンプトを編集し、異なる方向を繰り返し探索
4. Claudeに変更を元に戻すよう依頼。多くの場合、オプション#2と組み合わせて異なるアプローチを試す

Claudeが時折最初の試行で問題を完璧に解決することがありますが、修正ツールを使用することで一般的により良い解決策をより速く得られます。

/clearでコンテキストを集中

長いセッション中、無関係な会話、ファイルの内容、コマンドでコンテキストが埋まり、パフォーマンスが低下しClaudeの注意が散漫になる可能性があります。タスク間で頻繁に/clearを使用してコンテキストをリセットしてください。

複雑なワークフローにはチェックリストとスクラッチパッドを使用

複数のステップがある大きなタスクや、網羅的なソリューションが必要なタスク（コード移行、多数のリント修正、複雑なビルドスクリプト）では、Markdownファイルのチェックリストまたは作業用スクラッチパッドとしてのGitHub Issueでパフォーマンスを向上させます。

リント修正のアプローチ例：

1. Claudeにリントコマンドを実行させ、すべての結果エラー（ファイル名と行番号）をMarkdownチェックリストに書き込む
2. Claudeに各問題を順番に対処させ、修正・検証してから次に進むようチェックオフ

Claudeにデータを渡す

いくつかのデータ提供方法があります：

• プロンプトに直接コピー＆ペースト（最も一般的）
• Claude Codeにパイプで渡す（例：cat foo.txt | claude）。ログ、CSV、大量データに特に有用
• bashコマンド、MCPツール、カスタムスラッシュコマンドを通じてClaudeにデータを取得させる
• Claudeにファイルを読ませるまたはURLを取得させる（画像でも動作）

ほとんどのセッションではこれらのアプローチを組み合わせ、ログファイルをパイプで渡しながらClaudeにツールを使用して追加のコンテキストを取得するよう指示します。

5. ヘッドレスモードでインフラを自動化

Claude Codeには、非インタラクティブなコンテキスト（CI、pre-commitフック、ビルドスクリプト、自動化）向けのヘッドレスモードがあります。-pフラグとプロンプトでヘッドレスモードを使用し、--output-format stream-jsonでストリーミングJSON出力を取得できます。注意：ヘッドレスモードはセッション間で永続化されません。各セッションでトリガーしてください。

ClaudeをIssueトリアージに使用

ヘッドレスモードは、新しいIssueが作成された時などのGitHubイベントトリガーの自動化を実現します。公開されているClaude CodeリポジトリはClaudeを使用して着信Issueを検査し、適切なラベルを割り当てています。

Claudeをリンターとして使用

Claudeは従来のリントツールを超えて主観的なコードレビューを提供し、タイポ、古いコメント、誤解を招く関数/変数名などを特定します。

6. マルチClaudeワークフローでレベルアップ

スタンドアロンでの使用を超えて、複数のClaudeインスタンスを並列で実行するアプリケーションがあります。

一人のClaudeにコードを書かせ、別のClaudeに検証させる

効果的なアプローチ：

1. Claudeを使用してコードを書く
2. /clearを実行するか、別のターミナルで2番目のClaudeを開始
3. 2番目のClaudeに1番目のClaudeの作業をレビューさせる
4. 別のClaudeを開始（または再び/clear）し、コードとフィードバックの両方を読ませる
5. このClaudeにフィードバックに基づいてコードを編集させる

テストでも同様のアプローチが有効：一人のClaudeがテストを書き、別のClaudeがテストに合格するコードを書く。インスタンスは別々の作業用スクラッチパッドを通じて通信できます。この分離により、単一のClaudeが処理するよりも良い結果が得られることが多いです。

リポジトリの複数チェックアウトを持つ

各ステップの完了を待つのではなく：

1. 別々のフォルダに3-4つのgitチェックアウトを作成
2. 各フォルダを別々のターミナルタブで開く
3. 異なるタスクで各々にClaudeを開始
4. 循環して進捗を確認し、許可を承認/拒否

Git Worktreesを使用

独立したタスク用の複数チェックアウトに対する軽量な代替手段。Git worktreesは、Git履歴とreflogを共有しながら、分離された作業ディレクトリを持つ別々のディレクトリに複数のブランチをチェックアウトできます。

ワークフロー：

1. worktreeを作成：git worktree add ../project-feature-a feature-a
2. 各worktreeでClaudeを起動：cd ../project-feature-a && claude
3. 必要に応じて追加のworktreeを作成（新しいターミナルタブで繰り返し）

ヒント：

• 一貫した命名規則を使用
• worktreeごとに1つのターミナルタブを維持
• MacのiTerm2ではClaudeが注意を必要とする時の通知を設定可能
• 異なるworktreeには別々のIDEウィンドウを使用
• 完了したらクリーンアップ：git worktree remove ../project-feature-a

カスタムハーネスでヘッドレスモードを使用

2つの主要なヘッドレスモード統合パターン：

ファンアウトは大規模な移行や分析を処理：

1. Claudeにタスクリストを生成するスクリプトを書かせる（例：フレームワーク移行が必要な2kファイル）
2. タスクをループして、ツールアクセス付きでプログラム的に各タスクにClaudeを呼び出す
3. 望ましい結果を得るためにプロンプトを洗練しながらスクリプトを繰り返し実行

パイプラインはClaudeを既存のデータ/処理パイプラインに統合：

1. claude -p "<your prompt>" --json | your_commandを呼び出し、your_commandは次のパイプラインステップ
2. JSON出力は自動処理に役立つ

--verboseフラグはClaudeの呼び出しのデバッグに役立ちます。通常、本番環境ではクリーンな出力のためにオフにします。

結論

これらのプラクティスは、普遍的なルールではなく、出発点として機能します。成功は、個人やチームのニーズに合ったアプローチを実験し見つけることから生まれます。@AnthropicAIにタグ付けしてAnthropicにヒントを提供することで、コミュニティの知識を拡大できます。

出典: Claude Code: Best practices for agentic coding - Anthropic Engineering Blog