Anthropic のエンジニアリング

Claude Code: エージェンティックコーディングのベストプラクティス

公開日: 2025年4月18日

Claude Code はコマンドライン上でエージェンティックコーディングを行うツールである。本稿では、さまざまなコードベース・言語・環境で Claude Code を用いる際に効果的だった Tips とテクニックをまとめる。

最近、Claude Code をリリースした。研究プロジェクトとして開発されたこのコマンドラインツールにより、Anthropic のエンジニアや研究者は Claude をよりネイティブにコーディングワークフローへ統合できる。

Claude Code は意図的に低レベルかつアンオピニオン。特定のワークフローを強制せず、モデルアクセスをほぼ生の形で提供する。この設計哲学により、柔軟・カスタマイズ可能・スクリプト可能・安全なパワーツールが実現する。一方で、柔軟性ゆえに学習コストが発生するため、エージェンティックツールが初めてのエンジニアは独自のベストプラクティスを獲得するまで時間がかかる。

ここでは Anthropic 社内チームおよび外部エンジニアが多様なコードベース・言語・環境で得た一般的なパターンを紹介する。絶対的なものではない。出発点として捉え、最適な方法を探してほしい。

詳細情報が必要な場合は、claude.ai/code の包括的ドキュメントを参照。

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

Claude Code はコンテキストを自動収集してプロンプトに組み込むエージェント型アシスタントだ。この収集は時間とトークンを消費するが、環境調整で最適化できる。

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

CLAUDE.md は会話開始時に Claude が自動で読み込む特別なファイル。以下の記述場所に適する。

• よく使う bash コマンド
• 主要ファイルとユーティリティ関数
• コードスタイルガイドライン
• テスト実行手順
• リポジトリエチケット（ブランチ命名、merge vs rebase など）
• 開発環境セットアップ（pyenv の使用、対応コンパイラなど）
• プロジェクト固有の挙動や警告
• Claude に記憶させたいその他の情報

フォーマットに制約はないが、簡潔かつ可読性を保つとよい。例:

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

# コードスタイル
- CommonJS（require）ではなく ES Modules（import/export）を使用
- 可能な限り import を分割（例: import { foo } from 'bar'）

# ワークフロー
- 一連の変更が終わったら型チェックを忘れない
- パフォーマンスのため単体テストを推奨。全スイート実行は避ける

CLAUDE.md の配置場所:

• リポジトリルート（claude を実行する場所）。CLAUDE.md を git にコミット（推奨）または CLAUDE.local.md として .gitignore
• 実行ディレクトリの親フォルダ。モノレポで root/foo から claude を実行する場合、root/CLAUDE.md と root/foo/CLAUDE.md が両方読み込まれる
• 実行ディレクトリの子ディレクトリ。必要に応じて子側の CLAUDE.md を動的読み込み
• ホームフォルダ (~/.claude/CLAUDE.md)。すべてのセッションに適用

/init コマンドで Claude は自動的に CLAUDE.md を生成する。

b. CLAUDE.md をチューニングする

CLAUDE.md はプロンプトの一部になるため、頻繁に使うプロンプト同様に改善が必要。内容を足すだけで効果検証を怠るのは誤り。実験し、モデルの従属性が最も高まる構成を探るとよい。

手動追記も可能だが、# キーを押して Claude に指示を与えると、該当 CLAUDE.md へ自動書き込みさせられる。Anthropic ではコマンド・ファイル・スタイルガイドを # で追記し、コミットに含めてチーム全体で共有している。

社内では時折 prompt improver を通し、「IMPORTANT」「YOU MUST」などを追加して遵守率を高めている。

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

デフォルトで Claude Code はシステム変更の恐れがある操作（ファイル書き込み、多くの bash コマンド、MCP ツール等）に対し許可を要求する。安全性を最優先した保守的設計だ。安全と分かっているツールや取り消しが容易な操作（ファイル編集、git commit 等）は許可リストを調整できる。

管理方法は4通り:

• セッション中のプロンプトで 「Always allow」を選択
• /allowed-tools コマンド で許可/削除を実行例: Edit を追加して常時ファイル編集許可、Bash(git commit:*) で git commit 許可、mcp__puppeteer__puppeteer_navigate で Puppeteer MCP ナビゲーション許可
• .claude/settings.json または ~/.claude.json を手動編集（前者をソース管理下に置くとチーム共有可）
• セッション限定で --allowedTools CLI フラグ を使用

d. GitHub 利用時は gh CLI をインストール

Claude は gh CLI を利用して GitHub の Issue 作成・PR 作成・コメント読み込みなどを行える。gh がない場合でも GitHub API や MCP サーバー経由で操作可能。

2. Claude にツールを追加する

Claude はシェル環境へアクセスできるため、便利なスクリプトや関数を人間同様に用意できる。さらに MCP や REST API を介した高度なツールも利用可能。

a. bash ツールと併用する

Claude Code はユーザの bash 環境を継承する。Unix ユーティリティや gh など一般的なツールは知っているが、カスタムツールは指示が必要:

1. ツール名と使用例を伝える
2. --help を実行してドキュメントを読むよう指示する
3. よく使うツールを CLAUDE.md に記載する

b. MCP と併用する

Claude Code は MCP サーバー兼クライアント。クライアントとして複数の MCP サーバーに接続し、3つの方法でツールを提供できる:

• プロジェクト設定（該当ディレクトリ実行時に有効）
• グローバル設定（全プロジェクトで有効）
• .mcp.json をリポジトリにコミット（リポジトリ利用者全員が利用可能）。例: Puppeteer と Sentry を .mcp.json に追加

MCP 利用時は --mcp-debug フラグで設定問題を特定すると便利。

c. カスタムスラッシュコマンド

デバッグループやログ解析など繰り返す作業は、.claude/commands フォルダに Markdown テンプレートを置き / メニューから呼び出せる。Git にコミットすればチーム全体で共有可能。

テンプレ内に特殊キーワード $ARGUMENTS を含めると実行時引数を渡せる。

例: GitHub Issue を自動取得し修正するコマンド

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

手順:
1. `gh issue view` で詳細取得
2. 問題点を理解
3. 関連ファイル検索
4. 変更実装
5. テスト作成・実行
6. Lint と型チェック
7. 分かりやすいコミットメッセージ作成
8. Push と PR 作成

GitHub 関連作業は `gh` CLI を使用

上記を .claude/commands/fix-github-issue.md に置くと /project:fix-github-issue コマンドになる。/project:fix-github-issue 1234 で Issue #1234 を修正できる。個人用は ~/.claude/commands に配置。

3. よく使われるワークフロー

Claude Code はワークフローを強制しない。柔軟性の中で、効果的と実証されたパターンがコミュニティで確立している。

a. Explore → Plan → Code → Commit

多様な問題に対応する汎用フロー:

1. 関連ファイル・画像・URL を読ませる。「まだコードを書かない」と明示

2. 具体的アプローチ計画を立てさせる。think キーワードで拡張思考モードを発動。think < think hard < think harder < ultrathink の順に思考予算が増える

   • 計画が妥当なら文書または GitHub Issue に記録すると後戻り可能

3. 計画に基づきコード実装。適宜サブエージェントで妥当性確認

4. コミットと PR 作成。README や changelog 更新も指示

手順1・2が鍵。調査・計画なしではいきなりコードを書きがちで、深い思考が必要な問題では性能が落ちる。

b. テスト作成 → コミット → コード → 反復 → コミット

単体・統合・E2E テストで検証しやすい変更向け。TDD をエージェンティックに強化:

1. 期待入出力に基づくテスト生成。TDD と明示し、未実装部分でモック生成を避ける

2. テスト実行し失敗を確認。実装はまだ書かせない

3. テストをコミット

4. テストを通すコードを書く。テスト変更は禁止。数回の反復でテスト合格へ

   • 実装がテストに過適合しないようサブエージェント検証を指示

5. コードをコミット

明確なターゲット（テストなど）があると Claude は反復改善しやすい。

c. コード → スクリーンショット → 反復

UI などビジュアルターゲットを用いたフロー:

1. ブラウザスクリーンショット手段を用意（Puppeteer MCP など）
2. デザインモックの画像を提供
3. モックに合わせて実装 → スクショ → 反復
4. 満足したらコミット

人間同様、2–3回の反復で品質向上。

d. Safe YOLO モード

claude --dangerously-skip-permissions で確認なしに実行。Lint 修正やボイラープレート生成向け。リスクが高いので、ネットワーク遮断したコンテナで実行推奨。参考実装: Docker Dev Containers。

e. コードベース Q&A

新規コードベースの習熟に最適。ペアプログラミング時に同僚へ尋ねるのと同じ質問を Claude に投げる。例:

• ロギングの仕組みは？
• 新しい API エンドポイントの作り方は？
• foo.rs 134 行目の async move { ... } の意味は？
• CustomerOnboardingFlowImpl が扱うエッジケースは？
• 333 行目で bar() ではなく foo() を呼ぶ理由は？
• baz.py 334 行目と同等の Java コードは？

Anthropic ではこの方法がオンボーディングの中核。特別なプロンプトは不要。

f. git 操作に Claude を利用

Anthropic では git 操作の 90% 以上を Claude が担う。

• git 履歴検索「v1.2.3 に入った変更は？」「この機能のオーナーは？」「この API 設計の経緯は？」
• コミットメッセージ作成。差分と履歴を考慮し自動生成
• 複雑な git 操作 ファイルの revert、rebase コンフリクト解決、パッチ比較と graft など

g. GitHub 操作に Claude を利用

• PR 作成「pr」で shorthand 指示。差分からメッセージ生成
• レビューコメントの一括修正
• CI 失敗や Lint 警告の修正
• Issue ラベル付け・トリアージ

gh コマンドの記憶不要でルーチンを自動化。

h. Jupyter ノートブック操作

研究者・データサイエンティストは Claude Code で .ipynb を読み書きし、画像出力も解釈。VS Code でノートブックと並べて開くと効率的。可視性を高めるよう頼むと整形も可能。

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

a. 指示は具体的に

初回成功率が大幅向上。例:

b. 画像を与える

スクリーンショット貼り付け（macOS: cmd+ctrl+shift+4→ctrl+v）、ドラッグ＆ドロップ、ファイルパス指定。UI モックやチャート解析に有効。

c. 対象ファイルを明示

タブ補完で Claude に読ませたいファイルやフォルダを素早く指定。

d. URL を与える

URL を貼り付けて取得・読込。特定ドメインへの許可を /allowed-tools で登録すると再確認を省略できる。

e. 早期かつ頻繁に軌道修正

• 計画作成を依頼し、承認までコード禁止
• Escape で中断し指示追加
• Escape 2 回で履歴を遡りプロンプト編集
• 変更を取り消し別アプローチへ

f. /clear でコンテキスト整理

長時間セッションでは不要情報が増える。タスク間で /clear を使いメモリを空ける。

g. チェックリストとスクラッチパッド

大規模タスクでは Markdown や GitHub Issue にチェックリストを書かせると効率的。例: lint エラー大量修正

h. データを渡す

• コピー＆ペースト
• パイプ (cat foo.txt | claude)
• bash/MCP/コマンドで取得
• ファイル読込や URL 取得を依頼

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

非対話環境（CI、プリコミットフック、ビルドスクリプト等）で -p フラグを使用。--output-format stream-json で JSON ストリーム出力。

a. Issue トリアージ

GitHub イベントでトリガーし、新規 Issue にラベル付け。例: Claude Code リポジトリ。

b. Linter として利用

従来の Linter が検出しない主観的レビュー（タイポ、陳腐化コメント、誤解を招く命名等）を行う。例: コードレビューアクション。

6. マルチ Claude でレベルアップ

a. 片方が実装、片方が検証

1. Claude A でコード作成
2. /clear または別ターミナルで Claude B 起動
3. Claude B がレビュー
4. Claude C が両方を読み修正
   テストも同様に分担可能。

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

1. 3–4 個のチェックアウトを別フォルダに作成
2. 各フォルダでターミナルを開く
3. 各々で Claude を起動し別タスクを割当

c. git worktree を使う

軽量に複数ブランチを別ディレクトリへチェックアウト。独立タスクを同時進行。

git worktree add ../project-feature-a feature-a
cd ../project-feature-a && claude

d. ヘッドレスモード + カスタムハーネス

Fan-out 大規模移行・解析:

1. Claude にタスクリスト生成スクリプトを書かせる
2. ループで claude -p "<タスク>" --allowedTools ... を呼ぶ
3. プロンプトを調整し結果を改善

Pipeline 既存処理に統合:

claude -p "<プロンプト>" --json | your_command

--verbose はデバッグ用。本番では非推奨。

何か Tip があれば @AnthropicAI をタグ付けして共有してほしい。

謝辞

執筆: Boris Cherny。本文は Claude Code ユーザーコミュニティ全体のベストプラクティスに基づく。Daisy Hollman、Ashwin Bhat、Cat Wu、Sid Bidasaria、Cal Rueb、Nodir Turakulov、Barry Zhang、Drew Hodun ほか多数の Anthropic エンジニアの洞察と実務経験に感謝する。