Claude Code ベストプラクティスガイド

TL;DR

Anthropic は、エンジニアにエージェントコーディングのための Claude への生のアクセスを提供する、低レベルで特定の意見を持たないコマンドラインツールである Claude Code のベストプラクティスガイドを公開しました。このガイドでは、環境の設定方法、ツールの拡張方法、実証済みのワークフローを採用して生産性と安全性を高める方法について説明しています。

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

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

CLAUDE.md は Claude のプロンプトコンテキストに自動的に読み込まれます。これを使用して、一般的なコマンド、ユーティリティ関数、コードスタイルのガイドライン、テスト手順、リポジトリのエチケット、環境設定、およびプロジェクト固有の癖を文書化します。ファイルはリポジトリのルート、モノレポの場合は親ディレクトリまたは子ディレクトリ、またはグローバルデフォルトの場合は ~/.claude/ に配置します。/init コマンドでスターターファイルを生成できます。

1b. CLAUDE.md の内容を調整する

CLAUDE.md を頻繁に使用するプロンプトのように扱います。つまり、文言を繰り返し改善し、簡潔に保ち、重要な指示（例：「IMPORTANT」や「YOU MUST」）を強調します。# キーを使用して Claude にドキュメントを自動追加させ、より高い遵守率を得るために、ファイルを Anthropic の Prompt Improver にかけることを検討してください。

1c. 許可ツールリストを厳選する

Claude Code は、システムを変更するアクションに対して控えめに許可を求めます。以下の方法でツールをホワイトリストに登録できます。

  • セッション中に 常に許可 を選択する。
  • /permissions コマンドを実行する（例: Edit、Bash(git commit:*)）。
  • .claude/settings.json または ~/.claude.json を編集する（前者はソース管理にチェックイン）。
  • 一回限りのセッションには --allowedTools CLI フラグを使用する。

1d. GitHub CLI（gh）をインストールする

gh がインストールされていれば、Claude はイシューを作成し、PR を開き、コメントを直接読むことができます。gh がない場合、Claude は GitHub API または MCP サーバーにフォールバックします。

2. Claude により多くのツールを提供する

2a. bash ユーティリティを活用する

Claude はシェル環境を継承します。カスタムスクリプトを公開するには、ツール名と使用方法を説明し、Claude に --help を実行するよう依頼し、CLAUDE.md にツールを文書化します。

2b. MCP サーバーに接続する

Claude Code は MCP クライアントとサーバーの両方として機能します。プロジェクトレベルの設定、グローバル設定、またはチェックインされた .mcp.json にツールを登録します。--mcp-debug を使用して設定のトラブルシューティングを行います。

2c. カスタムスラッシュコマンドを定義する

再利用可能なプロンプトテンプレートを .claude/commands/*.md に保存します。これらは / メニューに表示され、$ARGUMENTS プレースホルダーを介して引数を受け取ることができます。これらのファイルをコミットしてチーム全体で共有します。

3. 実証済みのワークフロー

3a. 調査 → 計画 → コーディング → コミット

  1. コードを書かずに関連ファイルや URL を読む。
  2. 「考える」階層（think、think hard、think harder、ultrathink）を使って計画し、より多くの計算予算を割り当てます。
  3. 解決策を実装し、Claude に推論の検証を依頼します。
  4. コミットし、必要に応じて PR を生成するか、ドキュメントを更新します。

3b. テスト駆動開発（TDD）

  1. Claude に失敗するテストを書くよう指示します。
  2. テストを実行し、失敗を確認します。
  3. テストをコミットします。
  4. テストがすべて通るまで、Claude にテストを満たすコードを書くよう指示し、反復します。

3c. スクリーンショットによるビジュアル反復

貼り付けたスクリーンショット、ドラッグ＆ドロップ、またはファイルパスでデザインモックを提供します。Claude に UI の実装を依頼し、結果のスクリーンショットを撮って、モックが一致するまで反復します。

3d. 安全な「YOLO」モード

claude --dangerously-skip-permissions を使用して、迅速でリスクの低いタスク（例：lint 修正）の権限チェックをバイパスします。データ損失のリスクを軽減するために、インターネットに接続されていない隔離されたコンテナ内で実行します。

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

Claude をペアプログラマーとして扱います。「ロギングはどのように機能しますか？」や「foo.rs の 134 行目の async move { … } は何をしますか？」といった質問をします。Claude は特別なプロンプトなしでリポジトリを検索して回答します。

3f. Git 操作

Claude は以下を行うことができます：

  • 変更や所有者を調べるために git 履歴を検索する。
  • 差分に基づいてコミットメッセージの下書きを作成する。
  • 複雑な git 操作（リバート、リベース、パッチの移植）を実行する。

3g. GitHub 自動化

Claude は「pr」のような省略表現を理解してプルリクエストを作成し、レビューコメントを修正し、問題をトリアージし、自動的にラベル付けすることができます。

3h. Jupyter ノートブックのサポート

Claude は .ipynb ファイルの読み書き、出力画像の解釈、指示に応じたノートブックの見た目の改善ができます。

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

4a. 具体的に指示する

明確で詳細な指示は、最初の試行での Claude の成功率を劇的に向上させます。

4b. 画像を提供する

スクリーンショット、図、デザインモックを貼り付けたりドラッグ＆ドロップしたりします。Claude はそれらを直接処理します。

4c. 対象ファイルを指定する

タブ補完を使用して正確なファイルパスを参照し、Claude が正しいリソースで作業することを確実にします。

4d. URL を提供する

Claude が取得できるように URL を貼り付けます。/permissions でドメインを許可リストに追加すると、繰り返しのプロンプトを回避できます。

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

  • コーディングの前に Claude に計画を立てさせます。
  • Escape を押して中断し、コンテキストを保持します。
  • Escape をダブルタップして、以前のプロンプトを編集します。
  • 元に戻すを使用して、不要な変更を元に戻します。

4f. /clear でコンテキストをクリアする

長いセッション中は、Claude の集中力を維持するために、定期的にコンテキストウィンドウをリセットします。

4g. チェックリストとスクラッチパッドを使用する

大規模で複数ステップのタスクでは、Markdown チェックリストまたは GitHub の issue を共有スクラッチパッドとして維持し、Claude に完了した項目にチェックを入れさせます。

4h. データを効率的に渡す

コピー＆ペースト、パイプ（cat foo.txt | claude）、bash コマンド、MCP ツール、ファイル読み取りを組み合わせて、ログ、CSV、その他のデータを Claude に渡します。

5. 自動化のためのヘッドレスモード

CI、pre-commit フック、その他のスクリプト用に、-p "<プロンプト>" --output-format stream-json で Claude を非対話的に実行します。

5a. イシュートリアージの自動化

公開されている Claude Code リポジトリで示されているように、GitHub Actions を介して Claude をトリガーし、新しいイシューにラベルを付けます。

5b. 主観的 lint

GitHub Action で Claude を使用して、静的リンターを超えたニュアンスのあるコードレビューコメントを提供します。

6. マルチ Claude ワークフロー

6a. 並列検証

1 つの Claude インスタンスをコード生成に使用し、2 つ目をレビューまたはテストに使用して、フィードバックを最初のインスタンスに戻します。

6b. 複数チェックアウト

個別の git チェックアウト（または worktree）を生成し、それぞれで独立した Claude セッションを実行して、並列タスク実行を可能にします。

6c. 軽量な並列処理のための Git worktree

worktree（git worktree add …）を作成し、各ディレクトリで Claude を起動して、履歴を共有しながらタスクを分離します。

6d. ヘッドレスパイプライン

  • ファンアウト: タスクリストを生成し、各項目に対して --allowedTools を指定して Claude を呼び出します。
  • パイプライン処理: Claude の JSON 出力を後続のコマンドにパイプして、さらに処理を進めます。

「Claude Code は意図的に低レベルで特定の意見を持たず、特定のワークフローを強制せずに、ほぼ生のモデルアクセスを提供します。」 — Anthropic

結論: CLAUDE.md の設定、ツール権限の厳選、MCP やカスタムスラッシュコマンドによる Claude の拡張、そして計画先行のコーディングやテスト駆動開発などの実証済みのワークフローを採用することで、エンジニアは Claude Code を安全で柔軟、かつ生産性の高いエージェントコーディングアシスタントとして活用できます。

Sources