https://www.anthropic.com/engineering/claude-code-best-practices

1. セットアップをカスタマイズする

Claude Codeは自動でコンテキストをプロンプトに取り込むが、時間・トークンを消費する。環境を設定することでこれを効率化できる・

1.a. CLAUDE.md ファイルを作成する

CLAUDE.mdは、会話開始時に自動でコンテキストに取り込まれる特別なファイル。以下などのような項目をドキュメント化しておくことで

• よく使う bash コマンド
• コアとなるファイルやユーティリティ関数
• コードスタイルガイドライン
• テストの実行方法
• リポジトリのエチケット（ブランチ命名規則、merge vs rebase など）
• 開発環境のセットアップ手順（例: pyenv の利用方法、動作するコンパイラ）
• プロジェクト固有の注意事項や警告
• そのほか Claude に覚えさせたい情報

CLAUDE.md のフォーマットは特に指定はないが、簡潔で読みやすい記述が推奨される。

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

# コードスタイル
- ES モジュール（import/export）を使い、CommonJS（require）は避ける
- 可能な限り分割代入でインポート（例: import { foo } from 'bar'）

# ワークフロー
- 一連の変更が終わったら必ず型チェックを実行する
- パフォーマンスのため、テストは単体テスト単位で実行する

CLAUDE.mdのは位置場所は以下がある

• リポジトリのルート
  • CLAUDE.mdとして配置し、そこでClaude Codeを実行。最も一般的な使い方。
  • git 管理に含めることを推奨。チームでセッションをまたいで共有できる。
  • CLAUDE.local.md として配置、.gitignore に追加すれば、個人のプロジェクト固有設定として利用可。（注記: ただし非推奨、らしい）
• Claude Code実行ディレクトリの親ディレクトリ
  • モノレポで推奨
  • ルートとサブフォルダ両方に CLAUDE.md を置くと、両方が自動で取り込まれる。
• Claude Code 実行ディレクトリの子ディレクトリ
  • 作業対象ファイルがサブフォルダにある場合、そのサブフォルダ内の CLAUDE.mdがあれば取り込まれる。
• ホームフォルダ
  • ~/.claude/CLAUDE.md として置くと、すべてのセッションに適用される

/init コマンドを実行すると、CLAUDE.mdが自動で作成される。

1.b. CLAUDE.md ファイルを調整する

CLAUDE.md の内容は、プロンプトの一部に含まれるため、

• よく使うプロンプトと同じように、ブラッシュアップが必要
• 情報を詰め込みすぎると指示の精度が落ちることがある

これらを踏まえて、時間をかけて実験しながら、最も効果的なバランスを検討する必要がある。

CLAUDE.mdは、手動で追記することもできるが、コード中で # キーを押して Claude に指示を与えることで反映させることもできる。コーディング中にコマンド、ファイル、スタイルガイドラインなどをドキュメント化するために #を多用しつつ CLAUDE.md をgit管理することで、チームでメリットを共有できる。

Anthropic 社内では以下もやっているらしい

• prompt improver を使ってCLAUDE.mdを改善
• "IMPORTANT"や"YOU MUST"といった強調語句を追加することで指示追従性を高める

1.c. Claude の許可ツール一覧を管理する

デフォルトでは、ファイル書き込みや bash コマンド、MCP ツールなど、システムを変更する可能性のある操作はすべて許可を求める保守的な設定になっている。

安全だとわかっているツールや簡単にロールバックできる操作（例: ファイル編集、git commit）などを、許可リストに追加できる。

許可リストを管理する方法は以下の4つ。

• セッション中に表示される許可プロンプトで "Always allow" を選択
• セッション開始後に /permissions コマンドで、許可する操作を追加・削除
  • 例
    • Editを追加して、ファイル編集を許可
    • Bash(git commit:*) を追加して、git commitを許可
    • mcp__puppeteer__puppeteer_navigate を追加して、Puppeteerのナビゲーション操作を許可
• .claude/settings.json または ~/.claude.json を手動で編集
  • （前者をソース管理してチーム共有を推奨）
• CLI で --allowedToolsをつけると、そのセッション固有で許可される

1.d. GitHub を使う場合は gh CLI をインストールする

Claudeは gh CLI を利用して、

• Issue 作成
• プルリクエスト操作
• コメントの読み取り

などのGitHub 操作が可能。

gh がインストールされていない場合でも、GitHub API や MCP サーバー（インストールされている場合）経由で同様の操作が可能。

2. Claude により多くのツールを与える

Claude は、シェル環境へのアクセスを通じて、あらゆるツールを利用できる。また、MCP や REST API 経由で、より複雑なツールも利用可能。

2.a. bash ツールと一緒に Claude を使う

Claude はユーザのbash 環境をそのまま継承するため、ユーザが使えるツールをすべて利用できる。

ただし、Claudeは、よく知られた UNIX ツールや gh（GitHub CLI）などの使い方は知っているが、ユーザが自作したカスタムツールに対しては、アクセスはできても使い方などの知識を持たない。よって、以下のようにして使い方を教える必要がある。

1. ツール名と使用例を Claude に教える
2. ツールの --help を実行させてドキュメントを確認させる
3. よく使うツールは CLAUDE.md に記載しておく

2.b. MCP を使って Claude を利用する

Claude Code は MCP（Model Context Protocol）サーバー兼クライアントとして動作する。MCPクライアントとしてMCP サーバーが提供するツールにアクセスする方法は以下の3つ

• プロジェクト設定内（そのディレクトリで Claude Code を実行すると利用可能）
• グローバル設定内（全プロジェクトで利用可能）
• git管理された.mcp.json ファイル内（リポジトリに含めておくと、誰でも同じ設定で使える）
  • 例: Puppeteer や Sentry の MCP サーバーを .mcp.json に追加しておけば、チーム全員で利用可能

MCP 設定に問題がある場合は、claude --mcp-debug をつけて起動すればトラブルシュートに役立つ。

2.c. カスタムスラッシュコマンドを使う

デバッグのループやログ解析など、何度も繰り返し行うワークフローの場合は、.claude/commands フォルダー内に Markdown ファイルとしてプロンプトテンプレートを保存しておくと、Claude のスラッシュコマンドメニューとして登録され、/ を入力すると一覧から呼び出せる。また、これをgit管理に含めればチーム全体で共有できる。

カスタムスラッシュコマンドには、特別なキーワード $ARGUMENTS を使ってコマンド実行時に引数を渡すことが可能。以下はGitHubのIssueを修正してPRを作るコマンドの例。

GitHub issue: $ARGUMENTS を分析して修正してください。

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

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

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

これを .claude/commands/fix-github-issue.md に保存して /project:fix-github-issue 1234のように実行すれば、記載の手順に従ってGitHubのIssue番号1234 の修正〜PRまでを自動で行う。

個人用コマンドの場合は ~/.claude/commands フォルダに置けば、自分の全セッションで使い回せる。

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

Claude Code は特定のワークフローを強制しないため、自由に使える柔軟性がある。この柔軟性により、コミュニティの利用者の間で効果的と確認されたいくつかのパターンがある。

3.a. 探索 → 計画 → コーディング → コミット

多くの問題に適した汎用ワークフロー。

1. Claude に関連ファイル、画像、または URL を読ませる
   • 「ロギングを担当するファイルを読んで」といった大まかな指示でも、「logging.py を読んで」といった具体的なファイル名の指定でも、どちらでもOK
   • ただし、この段階ではコードを書かせないよう明示的に伝えるのがポイント
     • 特に複雑な問題の場合は、サブエージェント（subagents）の使用を検討すべきポイント。
     • 会話やタスクの初期段階では、Claude に「サブエージェントを使う」ことを指示して、詳細の検証や特定の疑問の調査をさせることで、効率低下をほとんど招かずにコンテキストを維持できる。
2. Claude に特定の問題へのアプローチ計画を立てさせる
   • "think" という単語を使う（訳注: 英語のまま使うことが重要）って、Claude の拡張思考モードを有効にすることを推奨。
   • これにより、計算時間（≒思考バジェット）が追加され、選択肢をより丁寧に検討する。
   • システム内では、"think" ＜ "think hard" ＜ "think harder" ＜ "ultrathink" の順で思考バジェット量が増加する。
     • ここで計画内容が妥当であれば、その計画をドキュメントや GitHub Issue として出力させておくと、実装段階（次のステップ3）が上手くいかない場合にリセットポイントとして活用できる。
3. Claudeにコードの実装を行わせる
   *実装中も随時、解決策の妥当性を検証させるとよい。
4. Claude に結果のコミットとプルリクエストの作成を指示する
   • 必要に応じて README や 何を行ったか？の説明を含むCHANGELOG の更新を指示する

ステップ1と2は重要。ここを省くと Claude はすぐにコーディングを開始しがちだが、事前のリサーチと計画があることで、複雑な問題に対するパフォーマンスが大きく向上する。

3.b. テスト作成 → コミット; 実装 → 反復 → コミット

Anthropic が特に好むワークフローで、変更は、単体テスト・統合テスト・E2E テストで容易に検証可能。エージェント型コーディングによりテスト駆動開発 (TDD) はさらに強力になる。

1. Claudeに 期待される入出力ペアに基づきテストを書くよう依頼する
   • テスト駆動開発であることを明示的に指示することで、まだ存在しない機能についてモック実装を避けることが可能。
2. Claude にテストを実行させ、失敗することを確認させる
   • この段階では実装コードを書かないよう明示的に伝えると効果的。
3. テストに満足したら Claude にテストをコミットさせる
4. Claude にテストを通過するコードを書かせる
   • テストを変更しないよう指示し、すべてのテストが通過するまで続行させる。
   • 通常、Claude はコードを書き、テストを実行し、コードを調整し、再度テストを実行するという手順を数回繰り返す。
     • この段階では、独立したサブエージェントに実装がテストへ過剰適合していないか検証させると役立つ。
5. 変更に満足したら Claude にコードをコミットさせる

Claude は、視覚モック・テストケース・その他の出力など、何を反復するか？のターゲットが明確であれば、最高のパフォーマンスを発揮する。テストという期待出力を与えることで、Claude は変更を加え、結果を評価し、成功するまで漸進的に改善できる。

3.c. コードを書く → スクリーンショット取得 → 反復

テスト駆動ワークフローと似ているが、Claude に視覚的ターゲットを提供できる。

1. ブラウザのスクリーンショットを取得する手段を Claude に与える
   • Puppeteer MCP サーバー
   • iOS シミュレータ MCP サーバー
   • 手動でスクリーンショットをコピペ。
2. 視覚モックを Claude に提供する
   • 画像をコピー＆ペースト。
   • 画像をドラッグ＆ドロップ。
   • 画像ファイルのパスを渡す。
3. デザインをコードで実装するよう Claude に依頼
   • 結果のスクリーンショットを取得し、モックと一致するまで反復する。
4. 満足したら Claude にコミットを依頼する。

人間と同様、Claude の出力も反復により大きく向上する。最初のバージョンが良かったとしても、通常は2～3回の反復で、さらに良い結果が得られる。最良の成果を得るには、Claude に結果を確認するためのツールを与えることを推奨。

3.d. Safe YOLO モード

Claude を監督せずに、claude --dangerously-skip-permissions を使用してすべての許可チェックをバイパスし、完了まで中断なく作業させることができる。これは lint エラー修正やボイラープレートコード生成のようなワークフローに適している。

Claude に任意のコマンドを実行させることはリスクが高く、データ損失、システム破損、さらにはデータ流出（例: プロンプトインジェクション攻撃）を招く可能性がある。これらのリスクを最小化するためには、 --dangerously-skip-permissionsをインターネットアクセスのないコンテナ内で使用することを推奨。Docker Dev Containers を用いた 参考実装 を参考に。

3.e. コードベース Q&A

新しいコードベースにオンボーディングする場合は、Claude Code をコードベースの学習と探索に利用できる。ペアプログラミングで他のエンジニアに尋ねるのと同様の質問を Claude に投げかけれる。Claude はコードベースをエージェント的に検索し、次のような一般的な質問に回答できる:

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

Anthropic ではこの方法が主要なオンボーディングワークフローとなっており、立ち上がり時間を大幅に短縮、他のエンジニアの負荷を軽減している。特別なプロンプトは不要で、ただ質問すれば、Claude がコードを探索して回答を得ることができる。

3.f. git との連携に Claude を活用する

Claude は多くの git 操作を効果的に行うことが可能。Anthropic の多くのエンジニアは git 操作の 90% 以上を Claude に任せている。

• git 履歴の検索
  • 例:「v1.2.3 に含まれた変更は？」「この機能のオーナーは誰？」「この API はなぜこう設計された？」
  • 上記のような質問への回答には、明示的に git 履歴を調べるよう指示すると効果的。
• コミットメッセージの作成
  • Claude は変更内容と最近の履歴を自動で参照し、関連コンテキストを考慮したメッセージを生成可能。
• 複雑な git 操作の処理
  • ファイルの revert、rebase コンフリクト解消、パッチ比較や graft など。

3.g. GitHub との連携に Claude を活用する

Claude Code は多くの GitHub 操作を行うことができる。

• Pull Request 作成
  • Claude は短縮形 "pr" を理解し、差分と関連コンテキストを元に、適切なコミットメッセージを生成できる。
• 簡単なコードレビューコメントのワンショット修正
  • PR に付いたコメントを修正し、完了後に PR ブランチへ push するよう指示できる（必要に応じ追加指示も可）。
• 失敗したビルドやリンター警告の修正
• Open Issue の分類・トリアージ
  • Openな GitHub Issue をループで処理するよう依頼できる。

これにより gh コマンドの構文を覚える必要がなくなり、日常的なタスクが自動化される。

3.h. Jupyter Notebook で Claude を活用する

Anthropic の研究者やデータサイエンティストは、Jupyter Notebook の読み書きにもClaude Code を使用している。Claude は画像を含む出力を解釈でき、データの探索と対話を迅速化する。特に必須のプロンプトやワークフローはないが、Claude Code と .ipynb ファイルを VS Code内で並べて開くワークフローを推奨。

同僚に見せる前に Notebook を整理したり視覚的に改善したい場合は、「Notebook やデータ可視化を『見栄え良く』してほしい」と具体的に伝えると、人間の閲覧体験に最適化するように働きかけられる

4. ワークフローを最適化する

以下は、すべてのワークフローに共通して有効。

4.a. 指示を具体的にする

Claude Code の成功率は、特に最初の試行で、指示が具体的であるほど大きく向上する。最初に明確な指示を出すことで、後からの起動修正は少なくて済む。

Claude は意図を推測できるが、心を読むことまではできない。具体性は期待に対する整合性を高める。

4.b. Claude に画像を渡す

Claude は画像や図を扱うのが得意。

• スクリーンショットを貼り付ける
  • macOS では cmd+ctrl+shift+4 → ctrl+v。通常のctrl+vとは異なり、リモートでは動作しない点に注意。
• 画像をプロンプト入力欄へドラッグ＆ドロップ
• 画像ファイルのパスを指定

これは、UI 開発のデザインモックや、解析・デバッグ用のビジュアルチャートを扱う際に特に役立つ。視覚要素を追加しない場合でも、見た目の重要度を Claude に明示すると結果が向上する。

4.c. Claude に見てほしいファイルを指定する

リポジトリ内のファイルやフォルダをタブ補完で素早く参照し、Claude が適切なリソースを見つけて更新しやすくする。

4.d. Claude に URL を渡す

プロンプトと一緒に具体的な URL を貼り付けると、Claude がそのページを取得して読み込む。同一ドメイン（例: docs.foo.com）に対する許可プロンプトを避けたい場合は、/permissions でドメインを許可リストに追加する。

4.e. 早めかつ頻繁に進路修正する

自動承認モード（shift+tab で切り替え）を使うと Claude は自律的に作業できるが、能動的に協働して方向づけを行ったほうが通常は良い結果になる。タスクを最初に詳しく説明すると効果的だが、途中でいくらでも軌道修正は可能。

進路修正に役立つ 4 つのツール:

• コードを書く前に Claude にプランを作成させる
  • ユーザがプランを確認するまでコードを書かないよう明示的に伝える。
• Escape キーで Claude を中断
  • 思考・ツール呼び出し・ファイル編集のいずれの段階でも停止できる。
  • コンテキストを保持したまま指示を拡張・変更可能。
• Escape を素早く 2 回押して履歴を遡る
  • 以前のプロンプトを編集して別ルートを試すことができる。
  • 結果に満足するまで繰り返し可能。
• Claude に変更を元に戻すよう依頼
  • 手順 2 と組み合わせて別アプローチを試す際に有用。

Claude Code が最初の試行で完璧に解決することもあるが、これらのツールを活用すると通常より速くより良い解決策に到達できる。

4.f. /clear でコンテキストを整理する

長いセッションでは、不要な会話・ファイル内容・コマンドがコンテキストウィンドウに溜まり、パフォーマンスが低下したり Claude の注意が散漫になることがある。タスク間で /clear を頻繁に実行してリセットすること。

4.g. 複雑な作業にはチェックリストとスクラッチパッドを使う

コード移行、大量の lint エラー修正、複雑なビルドスクリプト実行など、手順が多く抜け漏れが許されない大規模タスクでは、Markdown ファイル（または GitHub Issue）をチェックリスト兼作業用スクラッチパッドとして Claude に使用させるとパフォーマンスが向上する。

例として、大量の lint エラーを修正する場合:

1. Claude に lint コマンドを実行させる
   - 生成されたエラー（ファイル名と行番号を含む）を Markdown チェックリストへ書き出す。
2. Claude に各エラーを順番に対処させる
   - 修正と検証を行い、完了したらチェックを付けて次へ進む。

4.h. データを 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 ストリーム形式で出力できる。

ヘッドレスモードは セッション間で状態を保持しない点に注意。利用するたびに毎回トリガーする必要がある。

5.a. Claude を Issue トリアージに使う

ヘッドレスモードは、リポジトリに新しい Issue が作成された際などの GitHub イベントをトリガーにした自動化を実現できる。たとえばClaude Code のパプリックレポジトリでは、
新規 Issue が登録されると Claude が内容を解析し、適切なラベルを自動付与している。

5.b. Claude をリンターとして使う

Claude Code は、従来のリンティングツールが検出できない領域まで網羅する主観的コードレビュー を提供できる。例えば、このワークフロー では、タイポ、陳腐化したコメント、誤解を招く関数名・変数名などを検出して指摘する。

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

スタンドアロン利用にとどまらず、複数の Claude インスタンスを並列に動かすことで最も強力な活用法が得られる場合がある。

a. 1 つの Claude にコードを書かせ、別の Claude で検証する

1 つの Claude がコードを書き、もう 1 つがレビューやテストを行う、といった複数エンジニアで作業する場合と同様のシンプルかつ効果的な手法。文脈を分離することで功を奏するケースがある。

1. Claude にコードを書かせる
2. /clear を実行するか、別ターミナルで 2 つ目の Claude を起動する
3. 2 つ目の Claude に、1 つ目の成果をレビューさせる
4. さらに別の Claude（または再度 /clear）を起動し、コードとレビュー結果の両方を読む
5. この Claude に、フィードバックを反映してコードを修正させる

これをテストでも同様にできる。1 つ目の Claude にテストを書かせ、2 つ目にコード実装をさせる、という感じに。さらに、各 Claude に別々のスクラッチパッドを与え、「どこへ書き込むか／どこを読むか」を指定して互いに通信させることも可能。

この分離は、単一 Claude で全てを処理するより良い結果 を得られることが多い。

b. リポジトリを複数チェックアウトする

Claude がステップを完了するまで待つ代わりに、Anthropic の多くのエンジニアは次のようなことを行っている:

1. 3～4 個の git チェックアウト を別フォルダに作成
2. ターミナルタブを複数開いて各フォルダをそれぞれ開く
3. 各フォルダで Claude を起動し、タスクを分けて実行
4. タブ間を巡回 し、進捗を確認しつつ許可リクエストを承認／却下

c. git worktree を使う

独立したタスクが複数ある場合 に真価を発揮する、チェックアウトより軽量な代替手段。
git worktree を使うと、同一リポジトリの複数ブランチを別ディレクトリにチェックアウトできる。各 worktree は独立した作業ディレクトリを持ちつつ、Git 履歴と reflog を共有する。

これにより、異なる部分を担当する複数 Claude セッションを同時実行できる。たとえば、ある Claude が認証システムをリファクタリングし、別の Claude がまったく無関係なデータ可視化コンポーネントを構築する――といったケース。タスクが重複しないため、各 Claude は互いの変更を待つことなく全速力で作業し、マージコンフリクトにも悩まされることはない。

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

ヒント:

• 命名規則を統一する
• worktree ごとに 1 タブを維持する
• mac の iTerm2 を使う場合は、Claude が入力待ちになったときの 通知設定 を行う
• IDE ウィンドウも worktree ごとに分ける
• 作業後は git worktree remove ../project-feature-a でクリーンアップ

d. ヘッドレスモードをカスタムハーネスで使う

claude -p（ヘッドレスモード）は、Claude Code をプログラムからワークフローへ組み込み、内蔵ツールとシステムプロンプトを活用できる。主な利用パターンは 2つ:

1. Fanning out: 大規模マイグレーションや解析（例: 数百のログ感情分析、数千 CSV 解析）を並列処理する
   1. Claude にタスクリストを生成するスクリプトを書かせる。例: フレームワーク A から B へ移行すべき 2 000 ファイルの一覧。
   2. そのタスクリストをループし、各タスクでプログラム経由で Claude を呼び出す。例: claude -p "foo.py を React から Vue に移行してください。完了したら、成功した場合は文字列 OK を、タスクが失敗した場合は FAIL を返してください。" --allowedTools Edit Bash(git commit:*)
   3. スクリプトを複数回実行し、プロンプトを洗練して望む結果を得る。
2. Pipelining: 既存のデータ／処理パイプラインに Claude を組み込む
   1. claude -p "<あなたのプロンプト>" --json | あなたのコマンド を呼び出し、あなたのコマンド を次の処理ステップにする。
   2. 以上。JSON 出力（任意）は自動処理を容易にする構造化データとして役立つ。

いずれの用途でも、デバッグには --verbose フラグが便利。ただし本番運用ではクリーンな出力を保つため verbose をオフにすることを推奨。