Claude プロンプトのベストプラクティス｜明確な指示・XML構造化などの技法とClaude Codeでの実践

Claudeのプロンプトのベストプラクティスは、ひとことで言えば「事情を知らない優秀な新人に頼むつもりで、具体的に書く」ことです。Anthropic公式のガイドは、明確で直接的な指示、理由や背景を添える、例を示す、XMLタグで区切る、役割を与える、長い資料は先頭に置く、といった技法を挙げています。

この記事では、前半で公式ガイドの技法をよい例・悪い例つきで紹介し、コピーして使える型を示します。後半では、同じ考え方をClaude Code（CLAUDE.mdやセッションの進め方）にどう落とし込むかを、1年以上の実運用にもとづいて解説します（公式ガイドは2026年10月23日に確認）。

Claudeへのプロンプト設計：公式ガイドが挙げる基本技法（一覧）

Claude（Claude Code含む）に安定して意図通りの出力を出させるには、モデルへの指示そのものの書き方が土台になります。公式に整理されている主な技法は次の通りです。

• 明確かつ直接的な指示：曖昧な依頼文でなく、目的・制約・期待する出力形式を具体的に書く。
• XMLタグによる構造化：指示・参考情報・出力形式などを<instructions><context>のようなタグで区切り、モデルに読み取らせる範囲を明確にする。
• few-shot例の提示：期待する出力に近い具体例を1〜数個与えることで、フォーマットやトーンのブレを抑える。
• 役割（ロール）設定：「あなたは〇〇の専門家として振る舞ってください」のように前提となる立場を与え、回答の視点を固定する。
• 長文コンテキストの引用抽出：大量の資料を渡す際は、まず該当箇所を引用させてから回答させることで参照精度を上げる。
• 思考の誘導（thinking）：結論を急がせず、途中の検討過程を出力させてから最終回答に至らせる。
• エージェント的振る舞いの制御：サブエージェントへの分割やツール呼び出しの並列化など、複数ステップを伴うタスクでの指示設計。

これらはClaudeというモデル自体に向けた、いわば「プロンプトの書き方」です。次の節で、主なものを例つきで見ていきます。

意図どおりの出力になったかを確かめる仕組みは、Claude Code 検証ループで解説しています。

関連記事Claude CodeでSEOを始めるには？

基本技法を例で見る：効果が低い書き方・より効果的な書き方

上の一覧のうち、まず身につけたい6つを、公式ガイドの説明と例で見ていきます（英語の例文は公式ガイドに載っているもの、日本語の例はこの記事で作ったものです）。

1. 明確かつ直接的に書く

公式ガイドは、Claudeを「優秀だが、あなたの職場の決まりや進め方を知らない新入社員」と考えるよう勧めています。目安として紹介されているのが「黄金律」です。事情をほとんど知らない同僚にそのプロンプトを見せて、迷わず作業できるかを確かめます。同僚が迷うなら、Claudeも迷います。

効果が低い例	より効果的な例
Create an analytics dashboard	Create an analytics dashboard. Include as many relevant features and interactions as possible. Go beyond the basics to create a fully-featured implementation.
この議事録を要約して	この議事録を、欠席した部長が3分で読める長さに要約してください。「決まったこと」「宿題と担当者」「次回までの期限」の3つの見出しに分け、それぞれ箇条書きで書いてください。

手順の順番や抜け漏れが大事なときは、指示を番号付きのステップにして渡します。期待以上の仕上がりがほしいときも、察してもらうのを待たず、はっきり頼みます。

2. 理由や背景を添える

「何をしてほしいか」だけでなく「なぜそうしてほしいか」を書くと、Claudeは目的を理解して、書かれていない場面にも当てはめて動けます。

効果が低い例	より効果的な例
NEVER use ellipses	Your response will be read aloud by a text-to-speech engine, so never use ellipses since the text-to-speech engine will not know how to pronounce them.
専門用語は使わないで	この文章は、ITに詳しくない店舗スタッフ向けの社内報に載せます。専門用語は使わず、使う場合は初出でかっこ書きの説明を付けてください。

3. 例を示す（few-shot）

公式ガイドは、例を「出力の形式・トーン・構造をそろえる、最も確実な方法の1つ」としています。例を作るときのポイントは3つです。

• 実際の用途に近いこと：本番で扱う内容に近い例にする
• ばらつきがあること：似た例ばかりだと、意図しない共通点まで真似される。例外的なケースも混ぜる
• 指示と区別できること：例は <example> タグで囲む（複数あるときは全体を <examples> で囲む）

数の目安は3〜5個です。

4. XMLタグで区切る

指示・背景・例・資料が1つのプロンプトに混ざると、どこまでが指示でどこからが資料かが曖昧になります。<instructions>・<context>・<input> のようなタグで種類ごとに囲むと、読み違いを減らせます。タグ名は決まったものがあるわけではありません。内容が分かる名前を付け、プロンプトの中で同じ名前を使い続けます。入れ子にしてもかまいません。

5. 役割を与える

システムプロンプトで役割を設定すると、用途に合わせて振る舞いと口調が絞り込まれます。公式ガイドは「1文でも違いが出る」としています（例：You are a helpful coding assistant specializing in Python.）。チャットで使う場合は、依頼の冒頭に「あなたは中小企業の経理を10年担当してきた実務者です」のように書きます。

6. 長い資料は先頭に置き、先に引用させる

長い資料（目安として2万トークン以上）を渡すときは、次の3つが勧められています。

• 資料を先頭に、質問や指示は末尾に置く：公式ガイドは、特に複数の資料を使う複雑な依頼で、質問を末尾に置くと応答の質が最大30%向上することがある、としています。
• 資料ごとにタグで囲む：資料を <document> で囲み、その中に <source>（出どころ）と <document_content>（本文）を入れる。
• 先に関係する箇所を引用させる：作業の前に、資料から関係する部分を <quotes> タグに書き出させる。関係のない部分に引きずられにくくなる。

出典：Anthropic公式ドキュメント「プロンプティングのベストプラクティス」（2026年10月23日確認）

出力の形式を思いどおりにする：公式ガイドの4つのコツ

Anthropic公式の「プロンプティングのベストプラクティス」は、出力の形式（Markdownの多用、箇条書きばかりになる等）を整える方法として、次の4つを挙げています。

コツ	書き方の例
「しないこと」ではなく「すること」を伝える	×「Markdownを使わないで」→ ○「応答は滑らかにつながる散文の段落で書いてください」
XMLタグで出力の入れ物を指定する	「散文の部分は <smoothly_flowing_prose_paragraphs> タグの中に書いてください」
プロンプト自体の書き方を、欲しい出力に合わせる	箇条書きだらけのプロンプトは、箇条書きの応答を招きやすい。散文で答えてほしいなら、プロンプトも散文で書く
形式の好みは具体的に書く	「報告書や技術解説などの長文は、完結した文と段落で書く」のように、どの場面でどう書くかを明示する

最新モデルで変わった点：プリフィルの廃止と「考えすぎ」への対処

プリフィル（応答の書き出しを指定する手法）は使えない

以前は、アシスタントの応答の冒頭を先に与えて（プリフィル）、JSONで答えさせたり前置きを省かせたりする手法がよく使われました。公式ドキュメントによると、Claude 4.6系以降のモデルではプリフィルはサポートされず、プリフィルを含むリクエストは400エラーになります。代わりに次の方法を使います。

プリフィルでやっていたこと	現在の方法
JSONやYAMLなど決まった形式で出力させる	構造化出力（Structured Outputs）でスキーマを指定する
「Here is the summary:」などの前置きを省かせる	システムプロンプトで「前置きなしで直接答えてください」と指示する

考えすぎ・調べすぎを抑える

公式ガイドによると、Claude Opus 4.6以降のモデルは、特に effort を高く設定したとき、以前より多くの事前調査を行います。公式ガイドの対処は次のとおりです。

• 「デフォルトで〇〇ツールを使う」のような包括的な指示を、「問題の理解に役立つ場合に〇〇ツールを使う」のように的を絞った指示に置き換える
• 以前のモデル向けに入れていた「迷ったら〇〇を使う」のような強い指示を削る（今のモデルでは使いすぎの原因になる）
• それでも過剰なら effort を下げる
• 方針を決めたら、新しい情報が出ない限り何度も考え直さないよう指示する

コーディングエージェント向けの注意：ハードコーディングとハルシネーションを防ぐ指示

Claude Codeのようにエージェントとしてコードを書かせる場合、公式ガイドは次の2つの失敗を防ぐ指示を紹介しています。

起こりがちな失敗	プロンプトに入れる指示の要点
テストを通すことだけに集中し、特定の入力でしか動かない値を埋め込む（ハードコーディング）・回避用のスクリプトを作る	標準のツールで汎用的な解法を書くこと、テストケースだけでなく全ての有効な入力で正しく動く実装にすること、値をハードコードしないこと
開いていないファイルの中身を推測で答える	ユーザーが特定のファイルに触れたら、答える前に必ずそのファイルを読むこと。調べる前にコードについて断言しないこと

出典：Anthropic公式ドキュメント「プロンプティングのベストプラクティス」（2026年10月23日確認）

コピーして使えるプロンプトの型

ここまでの技法を1つにまとめた型です（この記事で作った見本です）。資料を先頭に置き、役割・背景・指示・出力の形をタグで分けています。かっこの部分を書き換えて使えます。

<role>
あなたは、社内向けの文章をわかりやすく直す編集者です。
</role>

<documents>
  <document index="1">
    <source>（資料の名前）</source>
    <document_content>
（ここに資料の本文を貼る）
    </document_content>
  </document>
</documents>

<context>
この文章は、来週の全社会議で配る資料に載せます。読むのは、この件を初めて知る他部署の人です。
</context>

<instructions>
1. まず、資料の中から要点に当たる文を <quotes> タグに書き出してください。
2. その引用をもとに、400字以内の要約を書いてください。
3. 専門用語は、初めて出るところでかっこ書きの説明を付けてください。
</instructions>

<output_format>
見出しは付けず、3つの段落で書いてください。箇条書きは使いません。
</output_format>

毎回この形にする必要はありません。短い質問なら、「誰が・何のために読むのか」と「どんな形で答えてほしいか」の2点を足すだけでも結果が変わります。思ったとおりにならないときに、足りない要素（背景・例・出力の形）を1つずつ足していくのが現実的です。

実運用で技法をどう活かすか：CLAUDE.mdの設計に落とし込む

上記の技法は、単発の質問だけでなくCLAUDE.mdのようなプロジェクト設定ファイルの書き方にもそのまま応用できます。2025年からClaude Codeを実務で使い続ける中で、CLAUDE.mdの記述を運用しながら少しずつ見直してきました。曖昧な依頼文だと意図しない挙動が起きやすく、逆に「明確かつ直接的な指示」を心がけて条件や禁止事項を具体的に書き出すほど、モデルの挙動が安定する傾向を実感しています。また、重要な変更を伴う操作の前に必ず確認を挟むルールを明文化したことで、意図しないファイル操作を防ぐ運用も定着しました。こうした「ルールを書いて→実運用で挙動を観察して→書き方を調整する」というサイクル自体が、プロンプト設計の技法をツール運用に応用する具体的なプロセスです。公式ドキュメントが示す技法を出発点に、自分たちの開発フローに合わせて磨き込んでいく――このアプローチが、Claude Codeを使いこなす上での実践的な一歩になります。

ここからは、Claude Codeでの実践に移ります。Claude Codeは、ターミナル・IDE・デスクトップアプリ・ブラウザの各環境で動作するAIコーディングエージェントだ（Anthropic公式 Overview）。プロンプトの技法を活かすには、ツールの動作原理とともに、その限界と設計上の制約を把握しておく必要があります。

Claude Code ベストプラクティスを理解する前提：アーキテクチャと動作原理

Claude Codeはファイルシステムへの読み書き・コマンド実行・Git操作といったシステムレベルの操作を自律的に行うエージェントです。公式の Overview によれば、ターミナルCLI・VS Code拡張・デスクトップアプリ・ブラウザのいずれの環境でも利用でき、ほとんどの環境はClaudeサブスクリプションまたはAnthropic Consoleアカウントを必要とします。ターミナルCLIとVS CodeではサードパーティAPIプロバイダーにも対応しています。

見落とされがちな制約が、コンテキストウィンドウの有限性とセッション単位の状態管理です。エージェントが「何を知っているか」を設計するコンテキスト管理は、出力品質・API利用コスト・処理速度のすべてに直結します。この制約を出発点に置かずにツールを使い始めると、初期の混乱が長引きます。

インストール方法についてはClaude Codeのインストール方法を、料金体系の概要はClaude Codeの料金・プラン解説をそれぞれ参照してください。以下では、公式ドキュメント（code.claude.com/docs/en/common-workflows・features-overview）をもとに実装担当者向けの設計指針を整理します。

Claude Code ベストプラクティス第1層：CLAUDE.mdによる永続コンテキスト設計

Claude Codeがセッション開始時に自動で読み込む設定ファイルがCLAUDE.mdです。公式の Extend Claude Code ドキュメントでは、CLAUDE.mdは「Claude がすべてのセッションで参照する永続コンテキストを追加する」機能として位置付けられています。記述品質がエージェントの行動品質を直接規定するという点で、他のどの設定よりも優先して整備すべき項目です。

配置階層と読み込み優先度

公式ドキュメント（Extend Claude Code）によれば、CLAUDE.mdはリポジトリルート・サブディレクトリ・ホームディレクトリ（~/.claude/CLAUDE.md）の複数階層に配置できます。見つかったCLAUDE.mdは上書きし合うのではなく、すべて連結して読み込まれます（起動した場所より上の階層のものは起動時に、サブディレクトリのものはその中のファイルを扱ったときに読み込まれる）。公式は1ファイル200行未満を目安にしています。そのため、モノレポ構成では各パッケージ配下に専用CLAUDE.mdを置き、共通規約はルートに集約する設計が安定しています。大規模コードベースにおける具体的なCLAUDE.md活用については、公式の Monorepos and large repos ガイドも参照してください。

チーム開発では、ルートのCLAUDE.mdをGit管理下に置いてコードレビューの対象にする運用が推奨されます。個人の作業習慣に依存する設定（ローカルのエディタ設定や個人的なエイリアスなど）は~/.claude/CLAUDE.mdに分離し、リポジトリには含めない切り分けが有効です。

記述すべき内容と記述すべきでない内容

効果的なCLAUDE.mdに含めるべき情報は、（1）コードスタイル・命名規約、（2）テストフレームワークと実行コマンド、（3）プロジェクト固有のアーキテクチャ上の制約、（4）頻繁に参照するファイルパスのエイリアス、の4種類に絞られます。一方、APIキーや認証情報の直書きは絶対に避ける。CLAUDE.mdはGit管理される性質上、誤ってリモートにpushされるリスクが常にあります。

記述量が増えすぎた場合は、公式ドキュメント（Extend Claude Code）が言及する Skills 機能を活用し、知識やワークフローを別ファイルに分割することが選択肢となります。「完璧なものを書いてから使う」より「使いながら育てる」アプローチが持続可能です。

よくある記述ミスとその影響

CLAUDE.mdに曖昧な表現を多用すると、エージェントが解釈を誤る原因になります。例えば「適切なエラーハンドリングをする」という指示より「すべてのAPI呼び出しでtry-catchを使い、エラーをlogger.errorで記録してから再throwする」という形式が、動作の一貫性を高めます。指示は「人間への説明文」ではなく「エージェントへの仕様書」として書く意識が必要です。

CLAUDE.mdを「育てる」運用サイクル

Claude Codeのセッション中に「この規約をCLAUDE.mdに追記して」と指示し、エージェント自身に蓄積させるサイクルが実用的かつ継続しやすいです。スプリントの終わりにCLAUDE.mdをレビューし、不要になった規約を削除して鮮度を保つことも重要な運用タスクです。スラッシュコマンドの活用方法についてはClaude Codeのスラッシュコマンド一覧も参照してください。

Claude Code ベストプラクティス第2層：プロンプト設計と思考フロー制御

Claude Codeの出力品質を左右する最大の変数は、指示の構造にあります。公式の Common workflows ドキュメントが示す基本的な考え方は、「まず探索・理解、次に計画、それから実装」というフローです。このフローを内面化しているかどうかで、同じツールを使っても生産性に大きな差が出ます。

探索フェーズ：コードを書く前に徹底的に読ませる

公式の Common workflows では、新しいコードベースを理解するステップとして「プロジェクトルートに移動 → claude を起動 → コードベースの概要を問う → 特定コンポーネントを掘り下げる」という順序が示されています。具体的なプロンプト例として同ドキュメントは次を挙げています。

• give me an overview of this codebase
• explain the main architecture patterns used here
• what are the key data models?
• how is authentication handled?

新機能実装やリファクタリング前に「このファイル群を読んで、アーキテクチャを要約してください。コードは一切書かないでください」と指示することで、モデルが誤った前提に基づいてコードを書き始めるという最も多発するミスを防げます。

計画フェーズ：実装前にTODOリストを承認する

探索完了後、「実装計画をステップ形式で列挙してください。私が承認するまでコードは書かないでください」と指示します。これにより、エンジニアはモデルが意図を正しく解釈しているかを確認する検査ポイントを設けられます。承認前のコード出力を防ぐ明示的な制約句は、長いセッションで特に効果的です。

公式の Common workflows では「Plan before editing」というセクションで、ディスクへの変更が発生する前に計画を確認するというアプローチが推奨されています。計画フェーズの出力をplan.mdとして保存しておくと、セッションが途切れた後の再開時に「plan.mdに従って実装を続けてください」と指示できます。

実装フェーズ：スコープを意図的に細分化する

一度の指示で大きすぎるタスクを渡すと、コンテキストウィンドウの消費が急増し、後半のコード品質が劣化する傾向があります。「1ファイルずつ実装し、各ファイルで私の確認を待ってください」のように粒度を明示することで、コスト制御と品質保証を両立できます。変更の独立性が高い単位で区切るのが原則です。

検証フェーズ：実装直後の自己レビューを組み込む

実装完了後に「あなた自身の実装をコードレビューしてください。潜在的なバグとエッジケースをリストアップしてください」と指示するパターンが実務で評価されています。モデルが生成直後の文脈を保持しているうちに自己検証させることで、別セッションでレビューするより精度の高い指摘が得られる場合があります。ただし自己レビューには盲点があり、人間によるレビューを代替するものではない点は明記しておきます。

サブエージェントへの調査委任

公式の Common workflows では「Delegate research to subagents」として、メインのコンテキストをクリーンに保つためにサブエージェントへ調査を委任するアプローチが紹介されています。公式の Extend Claude Code ドキュメントによれば、サブエージェントは独立したコンテキストの中で自律的に動作し、結果サマリーをメインセッションに返す仕組みです。長い調査タスクをメインセッションで抱え込まないことがコンテキスト節約の基本戦略となります。

Claude Code ベストプラクティス第3層：セッション管理と並列処理によるスケーリング

単一のClaude Codeセッションは線形に実行されるが、複数セッションを並列で走らせることで大規模なリファクタリングや機能開発を加速できます。公式の Common workflows には「Resume previous conversations」「Run parallel sessions with worktrees」「Pipe Claude into scripts」の3項目が明示されており、これらが公式推奨のセッション管理パターンです。

セッションの継続と再開：公式が示す2つのオプション

公式の Common workflows では、前回の作業を複数のセッションにまたがって継続できると明記されています。セッション再開には、最新セッションを再開する方法と過去のセッションを選択して再開する方法があります。長時間作業の中断・再開が多いプロジェクトでは、引き継ぎ情報をCLAUDE.mdや計画ファイルに記録しておくことが有効です。再開時にコンテキストウィンドウの残量を意識することも重要になります。

Git Worktreeを活用した並列セッションの設計

公式の Common workflows が明示的に推奨するパターンが「Run parallel sessions with worktrees」です。並列実行の最大の課題は、複数エージェントが同一ファイルを同時編集することによるコンフリクトであり、git worktree add で作業ツリーを複数生成し各エージェントを別ディレクトリに閉じ込めることでこのリスクを根本から回避できます。

基本フローは以下の3ステップです。

1. git worktree add ../feature-a origin/main でブランチと作業ツリーを同時生成します。
2. 各worktreeディレクトリでClaude Codeセッションを個別に起動します。
3. 各タスク完了後に通常のPRフローでマージし、worktreeを削除します（git worktree remove）。

並列セッション数を増やすほどAPIコストも増加します。複数エージェントのタスク分割が不適切だと、マージ段階で人手が増える逆効果になるため、タスクの依存関係分析が並列化の前提条件です。使い方の全体像はClaude Codeの使い方ガイドにまとめています。

スクリプトへのパイプ：CI/CD統合

公式の Common workflows では「Pipe Claude into scripts」としてCI/CDやバッチ処理への組み込みが紹介されています。非インタラクティブな実行形式を用いることで、Claude CodeをCIパイプラインの一部として活用できます。ただし自動化の度合いが上がるほど誤操作のスコープも広がるというトレードオフがあります。テスト環境での試験運用を十分に行ってから本番CIに組み込む段階的な導入が安全です。

なお、Agent SDKを利用した高度な自動化については、公式の Agent SDK overview も参照してください。同ドキュメントによれば、PythonおよびTypeScriptでエージェントをプログラム可能であり、ファイル読み込み・コマンド実行・コード編集のビルトインツールが含まれます。PythonパッケージはPython 3.10以上が必要です。

コンテキストのリセットタイミングを意識する

長時間のセッションではコンテキストウィンドウの残量が減るにつれてモデルの応答精度が低下する症状が報告されています。「コンテキストが一定量を超えたら新セッションに切り替え、引き継ぎ情報を記録してから再開する」というルールを設けることで、この劣化を抑制できます。具体的な閾値は利用中のモデルのコンテキストウィンドウサイズによるため、公式ドキュメントで最新の仕様を確認することを推奨します。

Claude Code ベストプラクティス第4層：権限制御・セキュリティ・運用上の限界

Claude Codeはシステムレベルの操作を行うエージェントであるため、権限設計の甘さが直接的なセキュリティインシデントに繋がります。この層は他の3層とは異なり、「できること」よりも「制限すること」が中心になります。

Permissionモデルの設計原則：最小権限から始める

公式の Extend Claude Code ドキュメントでは、ツールの許可・禁止を設定で制御できることが示されています。必要なツールだけをallowルールで許可し、秘密情報のファイルなどはdenyルールで禁止する、最小権限の考え方が基本になります（ルールはdeny・ask・allowの順に評価される）。特に本番環境のクレデンシャルが存在するディレクトリでは、ファイル書き込みツールの範囲を制限することが重要です。

内閣サイバーセキュリティセンター（NISC）が公開した「AIシステムに係る検討」資料（cyber.go.jp）では、AIシステムの操作権限は業務上の必要範囲に限定することの重要性が示されています。エージェント設計においても同様の原則が適用されます。

Hooksによるライフサイクル制御

公式の Extend Claude Code ドキュメントによれば、Hooks はライフサイクルイベントに応じてスクリプト・HTTPリクエスト・プロンプト・サブエージェントを起動できる機能です。特定の操作の前後にチェックを差し込むことで、意図しないファイル変更やコマンド実行を検知・阻止する仕組みを構築できます。完全自動実行を目指す場面では、Hooksによる監視を組み合わせることがセキュリティ上有効です。

human-in-the-loopの設計：完全自動化のトレードオフ

CI/CDパイプラインへの組み込みなど完全自動実行を目指すケースでは、操作の副作用を事前に評価する仕組みが必要になります。デジタル庁の技術検証報告書（digital.go.jp, 2024年5月）においても、生成AIの業務利用でヒューマンチェックポイントの設置が安全性確保の基本要件として位置付けられています。完全自律化は開発効率を上げる一方で、誤操作のスコープも広がるというトレードオフを常に念頭に置くべきです。

ログとトレーサビリティの確保

エージェントが行った操作の監査ログを保持することは、障害発生時の原因特定とコンプライアンス上の要請から重要です。ログ管理の仕組みは導入初期に構築しておき、CIパイプライン側で定期的にアーカイブする運用を組み込むことが望ましいです。具体的なログ保存先・形式については公式ドキュメントの最新版を確認してください。

また、LLMを活用した開発支援ツールのアクセシビリティに関する議論も進んでいます。JST J-STAGEに掲載された「LLM時代における障害者のソフトウェア開発参加の可能性」（jstage.jst.go.jp）では、LLMがソフトウェア開発参加のハードルを下げる可能性とともに、ツール設計における配慮の必要性が論じられています。チームへの導入を検討する際はこうした多様性の観点も参考になります。

Claude Codeが現時点で苦手とする領域

ベストプラクティスを語るうえで、限界と弱点の明示は不可欠です。現時点のClaude Codeが苦手とする領域として以下が挙げられます。

• 複雑なUI状態のデバッグ：ビジュアルな確認が必要な領域は、テキストベースのフィードバックだけでは精度が出にくいです。スクリーンショットを渡すワークアラウンドはあるが、根本的な制約は残ります。
• 巨大モノレポの全体最適化：コンテキストウィンドウの制約から、大規模コードベース全体を一度に把握させることは現実的ではありません。スコープを分割して渡す設計が必要になります。公式の Monorepos and large repos ガイドに詳細な対処法があります。
• 非決定論的なテストの修正：環境依存のフレイキーなテストは、エージェントが誤った原因推定に基づいて修正を繰り返すループに陥りやすいです。人間が原因を特定してから修正を依頼する手順が安全です。
• 長期にわたる文脈依存タスク：数日・数週間にわたる開発作業ではセッション分断による文脈喪失が蓄積します。CLAUDE.mdへの引き継ぎ情報の記録が欠かせません。

設定パターンと用途別の比較表

Claude Codeの運用環境を整備する際、設定の選択肢は複数あります。以下に代表的な設定パターンと用途を整理します。Claude CodeとCursorやCodexとの機能比較についてはClaude Code vs Cursor比較およびClaude Code vs Codex比較も参照してください。

設定項目	個人開発向け	チーム開発向け	CI/CD統合向け
CLAUDE.md配置	ルートのみ・シンプル構成	ルート＋パッケージ別・Git管理	CI用専用設定として管理
権限スコープ	比較的広め（生産性優先）	中程度（PR単位で制限）	最小限（読み取り中心）
セッション並列数	1〜2	worktree単位で3〜5	ジョブ単位で独立管理
ログ管理	デフォルトのまま運用	共有ストレージに集約	監査要件に合わせてアーカイブ
human-in-the-loop	任意のタイミングで介入	PRレビュー時に必須チェック	デプロイゲートで承認必須
コスト管理	APIトークン上限を個人で設定	プロジェクト別予算アラート	ジョブごとのトークン上限設定
CLAUDE.md更新頻度	気づいたときに随時更新	スプリント末にレビュー・更新	リリースサイクルに合わせて更新

権限スコープは、プロジェクトの .claude/settings.json に許可と拒否のルールとして書いておくと、チームで同じ設定を共有できます。書いたルールは、Claude Codeで /permissions を開くと一覧で確かめられます。下の画面は、テストの実行と差分の表示だけを許可（Allow）し、.env と secrets フォルダの読み取り、git push を拒否（Deny）したプロジェクトで開いたところです。

実装チームが陥りやすい失敗パターンと対処法

Claude Code導入初期に多発する問題を類型化し、対処法を示します。以下は公式ドキュメントの推奨事項（Common workflows・Extend Claude Code）と実践コミュニティの知見から整理しました。

失敗1：CLAUDE.mdを書かずに運用を始める

空のCLAUDE.mdまたはCLAUDE.mdなしで運用を開始すると、毎セッションでプロジェクト固有の背景説明を繰り返す羽目になります。最低限、テスト実行コマンドとコードスタイルガイドへのポインタを記述するだけで、セッション開始の品質が安定します。

失敗2：「全部やって」という一括指示

「この機能を全部実装して」という指示は、エージェントに過剰な推測を強います。公式の Common workflows が示す探索→計画→実装フローを徹底することで、実装の手戻りを大幅に削減できます。Claude Codeの基本的な使い方についてはClaude Code入門ガイドを参照してください。

失敗3：エラーメッセージなしのデバッグ依頼

「動かないので直して」という指示では、エージェントが推測で試行錯誤を繰り返し、コンテキストを無駄に消費するリスクがあります。エラーメッセージ・スタックトレース・再現手順を必ずセットで渡すことが基本です。再現環境の情報（OSバージョン、ランタイムバージョンなど）も含めると精度が上がります。

失敗4：権限スコープを「とりあえず広く」設定する

開発効率を優先するあまり、ファイルシステム全体への書き込みを許可したまま運用するケースが散見されます。前述のNISC資料（cyber.go.jp）でも指摘されているように、AIシステムの操作権限は必要範囲に限定することが基本原則です。権限設定の見直しを後回しにすると、組織のセキュリティポリシーとの整合性確保が困難になります。

失敗5：コンテキストの枯渇に気づかずに使い続ける

コンテキストウィンドウが埋まっていくとモデルの応答が短くなり、指示への準拠性が低下するサインが現れます。この状態を放置してセッションを続けると、後半の出力が大幅に品質劣化することがあります。コンテキスト消費量をモニタリングし、適切なタイミングで新セッションに切り替える習慣が重要です。

実際に踏んだ「効くベストプラクティス」の優先順位（一次情報）

監修者・河合継はClaude Codeを1年以上、実務で運用してきました。数あるベストプラクティスの中で、実際にいちばん効いた順に挙げると次のようになります。

• 最優先はコンテキスト管理。どれだけ良い指示を書いても、肥大化したセッションでは精度もコストも崩れます。話題で区切る・要約する習慣が、他のどの工夫より結果に効きました。
• 次に運用ルールの言語化（CLAUDE.md）。毎回口頭で伝えるより、方針をファイルに残して改善していくほうが、品質が安定し再現します。ただし盛りすぎは逆効果で、棚卸し前提で育てます。
• 最後に権限とレビューの設計。自律的に動くほど、どこまで任せどこで人が確認するかの線引きが効いてきます。華やかな機能より、この「任せ方の設計」が長期の安全運用を決めました。

CLAUDE.mdが20ルールから105ルールまで育った理由（一次情報）

監修者・河合継の運用チームでは、CLAUDE.mdに記す運用ルールが1年間で20個から105個まで増えました。数を追うこと自体が目的ではなく、実際に痛い目を見た失敗のたびに一つずつ言語化してきた結果です。象徴的な事例を挙げます。

• 「作成した」と「確認した」は違う、という教訓。スクリーンショットや録画を取得しただけで中身を見ずに「対応できました」と報告し、実際には失敗していたケースが繰り返されました。これを機に、証拠となる画像・映像は生成した本人が最後まで目視確認してから報告する、という原則を明文化しました。
• Git操作は事故が起きてから厳格化しました。バグを含んだままコミットしてしまう、reset系のコマンドで作業を消してしまう、といった実際の事故を経て、リスクのある操作は全面禁止・y/n確認必須という形に固めていきました。「便利だから」で緩めていたルールは、たいてい後で高くつきます。
• 「同じ失敗を繰り返した回数」を数値で残します。ある画面確認作業で、検証の待ち時間を毎回不足させて失敗する、という同一パターンのミスが半年間で220回以上記録されていました。ここまで繰り返されて初めて、「気をつける」ではなく「最低◯秒待つ」という具体的な数値基準として固定する必要があると学びました。注意喚起の言葉だけでは、AIは同じ失敗を平気で繰り返します。

ルールが増えるほど良い、という単純な話でもありません。棚卸しをせず積み上げるだけでは形骸化するため、定期的に「今も効いているか」を見直す運用も併せて行っています。

Claude Code ベストプラクティスの優先アクション：導入から定着まで

Claude Code ベストプラクティスを体系的に整理すると、実装チームが最初に取り組むべきアクションは明確になります。

1. CLAUDE.mdの雛形を1時間で作成します。完璧を求めず、テストコマンド・スタイルガイドへのポインタ・禁止操作の3点だけでも記述します。完成度より存在することの方が重要です。
2. 公式推奨の探索→計画→実装フローを全員のデフォルトワークフローにします。チーム導入時は、このフローを遵守することをコードレビューチェックリストに追加することで定着を促します。出典は公式の Common workflows です。
3. Git Worktreeを使った並列セッション環境を試験的に1つ構築します。公式の Common workflows で推奨されているこのパターンを、コンフリクトを経験する前に理解しておくことで本番運用でのトラブルを防げます。
4. 権限スコープをレビューし、最小権限設定を明文化します。本番クレデンシャルが存在する環境では、設定ファイルをGitで管理しレビュープロセスに組み込みます。
5. セッションログのアーカイブ運用を早期に整備します。障害発生後に「ログがなかった」という事態を避けるため、ログ管理の仕組みは導入初期に構築しておきます。

2つ目の「探索→計画→実装」は、プランモードで始めると習慣にしやすくなります。下の画面は、claude --permission-mode plan で起動し、「price.js にテストを追加したい。まず中身を調べて、作業の計画を立てて」と頼んだところです。Claude Codeはファイルを読んで計画を示し、実行に進んでよいかを確認しています。この時点では、ファイルはまだ変更されていません。

Claude Codeは頻繁にアップデートされるツールであり、インストール方法ひとつとっても macOS・Linux・WSL向けの curl インストール、Windows PowerShell向けの irm インストール、Homebrew経由など複数の方法が公式に提供されており（Anthropic公式 Overview）、今後も変更される可能性があります。本稿の原則は特定バージョンに依存しない設計思想に基づいているが、具体的なコマンドオプションや設定キー名については常に公式ドキュメントで最新を確認することを推奨します。

Claude CodeのAPI利用コストの最適化についてはClaude Code APIの料金最適化で詳しく解説しています。また、Claude Codeの全体像を改めて俯瞰したい場合はClaude Codeとはも参照してください。

よくある質問

Q. Claudeのプロンプトで最初に意識すべきことは何ですか？
A. 明確で直接的に書くことです。公式ガイドは、Claudeを「優秀だが、あなたの職場の決まりや進め方を知らない新入社員」と考えるよう勧めています。事情を知らない同僚にそのプロンプトを見せて迷わず作業できるか、という「黄金律」で確かめられます。

Q. XMLタグは決まった名前を使う必要がありますか？
A. 決まった名前はありません。instructions・context・input のように内容が分かる名前を付け、プロンプトの中で同じ名前を使い続けます。指示・背景・例・資料が混ざるプロンプトで、読み違いを減らす効果があります。

Q. 長い資料を渡すときは、質問をどこに書けばよいですか？
A. 資料を先頭に置き、質問や指示は末尾に書きます。公式ガイドは、複数の資料を使う複雑な依頼では、質問を末尾に置くと応答の質が最大30%向上することがあるとしています。あわせて、作業の前に関係する箇所を引用させると、関係のない部分に引きずられにくくなります。

Q. CLAUDE.mdはどこに配置できますか？
A. リポジトリルート・サブディレクトリ・ホームディレクトリ（~/.claude/CLAUDE.md）の複数階層に配置できます。見つかったCLAUDE.mdは、上書きし合うのではなく、すべて連結して読み込まれます（起動した場所より上の階層のものは起動時に、サブディレクトリのものは、その中のファイルを扱ったときに読み込まれます）。

Q. CLAUDE.mdに書くべき内容と書くべきでない内容は何ですか？
A. 含めるべき情報は(1)コードスタイル・命名規約(2)テストフレームワークと実行コマンド(3)プロジェクト固有のアーキテクチャ上の制約(4)頻繁に参照するファイルパスのエイリアス、の4種類に絞られます。一方、APIキーや認証情報の直書きは避けるべきです。

Q. 公式が推奨する基本的なプロンプトフローは何ですか？
A. 「まず探索・理解、次に計画、それから実装」というフローです。探索フェーズではコードベースの概要を問い、計画フェーズでは実装計画を承認してから、実装フェーズでは1ファイルずつ細分化して進めます。

Q. Git Worktreeを使った並列セッションの基本フローはどうなりますか？
A. (1)git worktree add ../feature-a origin/mainでブランチと作業ツリーを同時生成する(2)各worktreeディレクトリでClaude Codeセッションを個別に起動する(3)各タスク完了後に通常のPRフローでマージしworktreeを削除する（git worktree remove）、の3ステップです。

Q. Permissionモデルの設計原則は何ですか？
A. 必要なツールだけをallowルールで許可し、秘密情報のファイルなどはdenyルールで禁止する、最小権限の考え方が基本です。ルールはdeny・ask・allowの順に評価されます。特に本番環境のクレデンシャルが存在するディレクトリでは、ファイル書き込みツールの範囲を制限することが重要です。

Q. Hooksとは何ですか？
A. ライフサイクルイベントに応じてスクリプト・HTTPリクエスト・プロンプト・サブエージェントを起動できる機能です。特定の操作の前後にチェックを差し込むことで、意図しないファイル変更やコマンド実行を検知・阻止する仕組みを構築できます。

Q. Claude Codeが現時点で苦手とする領域は何ですか？
A. 複雑なUI状態のデバッグ、巨大モノレポの全体最適化、非決定論的なテストの修正、長期にわたる文脈依存タスクの4領域が挙げられます。

Q. 導入初期に陥りやすい失敗パターンにはどのようなものがありますか？
A. 「CLAUDE.mdを書かずに運用を始める」「『全部やって』という一括指示」「エラーメッセージなしのデバッグ依頼」「権限スコープをとりあえず広く設定する」「コンテキストの枯渇に気づかずに使い続ける」の5パターンが挙げられます。

---

まとめ

Claude Codeのベストプラクティスは、（1）CLAUDE.mdによる永続コンテキスト設計、（2）探索→計画→実装という段階的プロンプト戦略、（3）セッション継続・Git Worktreeを使った並列化・スクリプトへのパイプという公式推奨セッション管理、（4）最小権限・Hooks・ヒューマンチェックポイントを組み合わせた権限制御、の4層に整理できます。いずれも公式の Common workflows および Extend Claude Code ドキュメントに明示された考え方に基づいています。

ツールの仕様は更新が続くため、本稿の設計原則を土台としつつ、個別のコマンドや設定値については公式ドキュメントを都度参照する運用が長期的に安定した活用につながります。

---

参考文献

• Claude Code公式 Overview（Anthropic）：https://code.claude.com/docs/en/overview
• Claude Code公式 Common workflows（Anthropic）：https://code.claude.com/docs/en/common-workflows
• Claude Code公式 Extend Claude Code（Anthropic）：https://code.claude.com/docs/en/features-overview
• Claude Code公式 Agent SDK overview（Anthropic）：https://code.claude.com/docs/en/agent-sdk/overview
• Claude Code公式 Monorepos and large repos（Anthropic）：https://code.claude.com/docs/en/large-codebases
• 行政における生成AIの適切な利活用に向けた技術検証（デジタル庁, 2024年5月）：https://www.digital.go.jp/assets/contents/node/information/field_ref_resources/19c125e9-35c5-48ba-a63f-f817bce95715/e03a8092/20240510_resources_ai_r5mainresults.pdf
• AIシステムに係る検討資料（内閣サイバーセキュリティセンター NISC）：https://www.cyber.go.jp/pdf/council/cs/cs_expert/05/05document2.pdf
• LLM時代における障害者のソフトウェア開発参加の可能性（JST J-STAGE）：https://www.jstage.jst.go.jp/article/lam/3/0/3_105/_pdf

関連記事

• Claude Codeとは
• Claude Codeでできること・活用事例
• Claude CodeのメモリとCLAUDE.md活用
• Claude Codeの使用量・制限を確認する方法
• Claude Codeの学習リソースまとめ
• Claude Fable 5とは？特徴・料金・Opus 4.8との違い