Claude Codeベストプラクティス — Anthropicが示す自走エージェントの設計原則と運用パターン

Anthropicが公開している「Best practices for Claude Code」が、2026年5月時点で公式ドキュメント(code.claude.com/docs/en/best-practices)に集約されました。旧URLのanthropic.com/engineering/claude-code-best-practicesからは308リダイレクトで誘導されており、Claude Codeを業務で本格運用するチーム向けの一次情報として機能しています。

このドキュメントは、Anthropic社内チームと外部エンジニアの実運用から抽出されたパターンを、検証・計画・コンテキスト管理・自動化・スケールの5領域で整理した内容です。Claude Codeを「コードを書くアシスタント」ではなく「自走するエージェント」として扱うときに、どこに気をつけ、どこに投資するかを示しています。

本記事では、ドキュメントが示す原則を日本語の読者向けに整理しつつ、Claude Media内の関連記事と接続して「自分のチームで何から手を付けるか」を判断できる地図を提示します。Claude Codeの全体像はClaude Code完全ガイド、CLAUDE.mdの設計はCLAUDE.mdに書くべき10パターンを併読してください。

ベストプラクティスの全体像

ドキュメントは5つの大ブロックで構成されています。並びそのものが、Claude Codeを使い始めたチームが順に克服すべきハードルの順番になっています。

最後に「自動化とスケール」(非対話モード・並列セッション・ファンアウト・auto mode)と「ありがちな失敗パターン」の節が続きます。

全体に通底する制約は1つだけです。コンテキスト窓は早く埋まり、埋まるほど性能は劣化する。デバッグ1回・コード探索1回で数万トークンが消えるため、コンテキスト窓こそが「管理すべき最も重要な資源」だと明言されています。逆に言えば、本ドキュメントのほぼすべての項目はコンテキスト窓を守るための処方箋として読めます。

検証可能性を与える — 最も投資効果が高い1点

「これが唯一最大のテコ」と明言されている領域です。Claudeは自分の出力を検証できるときに大きく性能が伸びます。逆に検証手段がないと、人間が唯一のフィードバックループになり、ミスのたびに人間の注意が消費されます。

具体的なBefore/After例として挙げられているのは次のような書き換えです。

UIに関してはClaude in Chrome拡張がブラウザでタブを開き、UIをテストして反復改善できると紹介されています。検証はテストスイートでも、リンターでも、出力をチェックするBashコマンドでも構いません。要は「Claudeが自分で合否を確かめられる仕組みに投資せよ」という主張です。

探索→計画→実装の4フェーズワークフロー

Plan Modeを使って、研究フェーズと実装フェーズを切り離す段取りです。推奨される流れは次の4ステップです。

1. Explore(計画モード):/src/auth配下とセッション・環境変数管理の流れを読ませる
2. Plan(計画モード):変更すべきファイルと手順を計画化、Ctrl+Gでエディタに開いて直接編集できる
3. Implement(通常モード):計画に沿って実装し、テストを走らせて失敗を直す
4. Commit:わかりやすいメッセージでコミットし、PRを作る

ただし計画にもオーバーヘッドがあります。タイポ修正・ログ追加・リネームのように1文で差分を説明できる小作業ではPlan Modeを省くよう推奨されています。判断軸は「複数ファイルを触るか」「アプローチに自信がないか」「対象コードに不慣れか」の3つです。

Plan Modeの実用パターンはPlan Modeの使いどころ完全ガイドで詳しく扱っています。

プロンプトに具体的な文脈を入れる4つの型

Claudeは意図を推測できますが、人の頭の中までは読めません。書き換え型として示されている4つを要点だけ並べると次のとおりです。

• タスクのスコープを切る:どのファイル・どのシナリオ・モックを使うかを指定
• 情報源を指す:ExecutionFactoryのgit historyを読ませる、など
• 既存パターンを参照:HotDogWidget.phpを真似て新ウィジェットを作る、というように
• 症状で記述:バグ修正は「症状・推定場所・直った状態」の3点セットで頼む

逆に「このファイルを改善するなら?」のような曖昧プロンプトは、軌道修正できる前提なら探索フェーズとしては有効と位置付けられています。曖昧さは禁忌ではなく使い分け対象、というのが本ドキュメントの立場です。

リッチデータの渡し方も整理されています。@でファイル参照、画像のペースト/ドラッグ&ドロップ、ドキュメントURL指定(/permissionsで頻出ドメインをallowlist化)、cat error.log \| claudeのパイプ、そして「Claude自身に取りに行かせる」の5系統です。

環境を整える — CLAUDE.md・権限・CLI・MCP・hooks・skills

セッションを跨いで効くチューニングがここに集中しています。それぞれ独立記事相当の話題なので、要点だけ拾います。

CLAUDE.mdは「短く、コード並みに保守する」

/initでプロジェクトのスケルトンを生成し、Bashコマンド・コードスタイル・ワークフロー規約を書き溜めるのが基本です。

強調されているのは入れる/入れないの判断基準です。

「Claudeが何度言っても言うことを聞かない」と感じたら、CLAUDE.mdが長すぎてルールが埋もれている可能性が高い、というのがドキュメントの見立てです。ファイルが長くなったら重要度の低い行を消す、IMPORTANTやYOU MUSTで強調を付ける、@path/to/fileで部分を別ファイルに分割する、の3手が示されています。

配置場所は4種類です。~/.claude/CLAUDE.md(全セッション)、./CLAUDE.md(チーム共有)、./CLAUDE.local.md(個人メモ、.gitignoreに追加)、親ディレクトリ/子ディレクトリ(モノレポでの自動取り込み)。

実戦的な書き方はCLAUDE.mdに書くべき10パターン、CLAUDE.mdとSkillsの使い分けはSkill運用ガイドに整理しています。

権限管理は3段階で選ぶ

毎回の許可ダイアログをどう減らすかは、ある程度使い込んだチームの最大の悩みです。選択肢は次の3つです。

Auto Modeはスコープのエスカレーション、未知のインフラ操作、悪意ある内容駆動の動作をブロックする方針です。非対話モード(-p)では分類器が繰り返しブロックするとabortになる、という運用上の挙動も明記されています。Auto Modeを実戦投入する話はAuto Mode実戦ガイドで詳述しています。

CLIツール・MCP・hooks・skills・subagents・plugins

ここからは「拡張ポイント」の話です。

• CLIツール:gh・aws・gcloud・sentry-cliなどをClaudeに渡すのが最もコンテキスト効率が良い。ghがないとAPI直叩きでレート制限に当たりやすい
• MCPサーバ:claude mcp addでNotion・Figma・データベースを接続する。MCP実用はMCP実用ガイドを参照
• Hooks:.claude/settings.jsonで設定する決定的な自動処理。「eslintを毎回走らせる」「migrationsへの書き込みを禁止」など、CLAUDE.mdの助言型と違い確実に走るのが特徴。詳しくはHooks運用ガイド
• Skills:.claude/skills/<name>/SKILL.mdに書く再利用可能なワークフロー。disable-model-invocation: trueで副作用付きの定型作業を手動起動限定にできる
• Subagents:.claude/agents/<name>.mdで独自の限定権限エージェントを定義。tools: Read, Grep, Glob, Bashのように使えるツールを絞り、model: opusでモデルも個別指定可能。詳細はSubagent運用ガイド
• Plugins:/pluginでmarketplaceから導入。Skills・Hooks・Subagents・MCPサーバを1つにまとめた配布単位

「型付き言語を使うならcode intelligence pluginを入れろ」と具体名で推奨されています。シンボル参照とエラー検出が編集後に自動で走るため、Claudeが自分で間違いに気づける構造になります。これは「検証可能性を与える」原則の延長線上にあります。

効果的に対話する — コンテキスト管理がすべての中心

ドキュメントで最も印象的なのは、対話術をコンテキスト管理の問題に還元している整理です。具体的な処方箋は次の5つに整理できます。

1. コードベース質問はシニアエンジニアに聞くように

新しいリポジトリに入ったとき、Claude Codeに「ロギングはどう動いてる?」「foo.rsの134行目のasync moveは何?」「CustomerOnboardingFlowImplのエッジケースは?」と聞く。新メンバーのオンボーディング時間を短くする使い方として推奨されています。

2. インタビューさせる

大きめの機能は、最初から仕様を書かずにClaudeにAskUserQuestionツールで尋ねさせるのが効きます。推奨されているプロンプトはこの型です。

I want to build [brief description]. Interview me in detail using
the AskUserQuestion tool. Ask about technical implementation, UI/UX,
edge cases, concerns, and tradeoffs. Don't ask obvious questions,
dig into the hard parts I might not have considered. Keep interviewing
until we've covered everything, then write a complete spec to SPEC.md.

仕様化が終わったら新規セッションで実装に入ることで、実装側のコンテキストを綺麗な状態から始められます。これは「探索→計画→実装」フェーズ分離の応用例とも読めます。

3. 早期軌道修正

Escで割り込み、Esc + Escまたは/rewindでチェックポイントに戻り、「Undo that」で変更を取り消し、/clearでリセットする。経験則として示されているのは明快で、同じ問題で2回以上修正したらコンテキストは汚染されている。/clearして、学んだことを織り込んだ良いプロンプトで書き直す方が、長セッションの修正積み上げより速い、という主張です。

4. コンテキストを攻めに管理する

通常時は自動コンパクションが要点を残してくれます。手動の制御も用意されています。

CLAUDE.mdに「コンパクション時は変更ファイル一覧とテストコマンドを必ず残せ」と書くと、要約後にも重要情報が生き残ります。これはCLAUDE.mdとコンテキスト管理を繋いで設計する発想です。

5. 調査はサブエージェントに分離

「認証システムのtoken refreshの扱いと、既存OAuthユーティリティの再利用可能性を調べて」というような調査依頼を、サブエージェントで隔離コンテキストで走らせ、要約だけを本セッションに戻すパターンです。実装後の検証(「サブエージェントでエッジケースをレビューして」)にも同じ仕組みが使えます。並列実行の設計はサブエージェント並列パターンに整理してあります。

加えて、Checkpointing(/rewind)は会話・コード・両方を任意の地点に戻せる仕組みで、各プロンプトの直前で自動スナップショットが取られています。git代替ではないものの、「危険な変更を試してダメなら戻る」という探索的な動き方を許容する設計です。

セッションには/renameで名前が付けられ、claude --continueで直近、claude --resumeで一覧から復帰できます。oauth-migrationのようにブランチ名のように扱うのが推奨パターンです。

自動化とスケール — 並列Claudeの4パターン

ここからは「一人 + 一Claude + 一会話」の前提を崩したときの話です。

非対話モード(claude -p)

CI・pre-commit hook・自動化スクリプトに組み込むときの基本形です。

# 単発クエリ
claude -p "Explain what this project does"
 
# スクリプト用のJSON出力
claude -p "List all API endpoints" --output-format json
 
# リアルタイム処理用のストリーミング
claude -p "Analyze this log file" --output-format stream-json

開発中は--verboseを付けて挙動を観察し、本番では外す、という運用方針も明示されています。

複数Claudeセッションの並列実行

並列の手段が用途別に4つ整理されています。

並列の用途は速度だけではありません。「書き手と査読者」を別Claudeにすることで、コードレビューが自分の書いたコードに引っ張られなくなる、という品質設計が示されています。テスト先行も同じ構造です。Worktreeでの隔離手順はWorktree完全ガイド、複数セッション運用はマルチセッション運用で扱っています。

ファイルにファンアウト

2,000ファイルの移行のような大規模一括処理は、ファイル一覧をClaudeに作らせ、シェルでループする型が紹介されています。

for file in $(cat files.txt); do
  claude -p "Migrate $file from React to Vue. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)"
done

--allowedToolsで実行ツールを絞るのが重要で、無人運用時はとくに権限スコープが事故防止になります。最初の2〜3ファイルで挙動を確認してからスケールさせる、という段取りも忘れずに紹介されています。

Auto Modeで自走させる

長時間の無人実行にはclaude --permission-mode auto -p "..."を使います。分類器がスコープ逸脱・未知のインフラ操作・敵対的内容駆動の動作をブロックし、ルーチンワークは通過させる方針です。-pとの組み合わせでは、分類器が繰り返しブロックするとabortされます。

Auto Modeのthreshold・運用観点はAuto Mode実戦ガイドで整理しています。

ありがちな失敗パターン5つ

「これを早く見抜けると時間が浮く」として挙げられている5パターンを、原文の対症療法とともに表に直しました。

実例ベースの失敗回避はClaude Codeでよくある落とし穴と対処も併読してください。

このベストプラクティス集をどう読むか — 編集視点

ドキュメント自体は淡々と原則を列挙していますが、行間を読むといくつかの設計哲学が透けて見えます。

第1に、「最高の単発プロンプト」ではなく「最高のフィードバックループ」を目指すという方向です。検証可能性に投資せよ、計画と実装を分けよ、コンテキストを清潔に保て、というすべての原則は、Claudeに「自分の失敗に気づく機会」を増やすことを狙っています。1ショットで完璧を求めるのではなく、ループを高速に回し続ける設計こそがエージェント運用の本質だ、という立場です。

第2に、「コンテキスト窓は資源、節約は美徳」という思想が一貫しています。CLAUDE.mdは短く、無関係なタスクで/clear、調査はサブエージェントに隔離、長時間タスクは/compactで要約、検証は別セッションで。これらは「無料で使える容量はない」という前提を共有しています。トークン課金との関係でも、長セッションは品質と料金の両面で割高になるという読み方ができます。

第3に、「禁止ではなく分離」で安全性を担保する設計です。権限はallowlist・Auto Mode・Sandboxingの3段階、調査はサブエージェントで隔離、並列はWorktreeで隔離、検証は別セッションで隔離。「危険な操作を止める」より「操作を狭い箱に押し込める」発想が一貫しており、これはClaude Codeの内部設計とも整合しています。

第4に、ドキュメントが「直感を育てろ」で締められている点も興味深いところです。パターンを示しつつ、最後に「これは出発点であって絶対ではない」「コンテキストが価値を持つ場面では蓄積させていい」「探索的なタスクでは曖昧プロンプトが正解になる」と明記されています。型を渡しつつ、型からの逸脱を例外として認めるのは、エンジニア向けのドキュメント設計として誠実な構えです。

自分のチームで何から始めるか

Claude Codeを導入したばかりのチームと、すでに数か月使い込んでいるチームでは、効くテコが違います。利用熟度別に推奨着手順を整理しました。

ドキュメントの構成順(検証→計画→具体プロンプト→環境→対話→自動化)は、ほぼそのまま熟度の階段になっています。Claude Code完全ガイド(Claude Code完全ガイド)やClaude Codeの実戦ワークフローと組み合わせて、自社の現在地を当てはめる起点として使えそうです。

まとめ

• Claude Codeのベストプラクティスはcode.claude.com/docs/en/best-practicesに集約され、anthropic.com/engineering/claude-code-best-practicesからはリダイレクトされている
• 中核原則は5つ:検証可能性を与える、探索→計画→実装、具体的な文脈、環境整備、コンテキスト管理。最大のテコは検証可能性の付与
• CLAUDE.mdは短く保つ、Plan Modeは大きめタスクで使う、/clearは2回失敗したら即発動、検証手段なしでの出荷は避ける、というのが頻出の処方箋
• 並列実行・非対話モード・Auto Modeは、コンテキスト窓を節約しつつ生産性を伸ばす次のステージの手段
• ドキュメントは「直感を育てろ」と結び、原則からの逸脱を例外として認めている。型を持ったうえで型を破れる、という設計