Claudeの過剰実装を防ぐプロンプトの書き方
Claude Opus 4.5/4.6の過剰実装を抑えるプロンプトを、スコープ・ドキュメント・防御的コーディング・抽象化の4区分で使い分ける方法をまとめます。
このTipsでできること
Claudeにコード修正を頼むと、頼んでいない機能や抽象化まで追加されることがあります。バグ修正のついでに周辺コードまで整理されたり、一度しか使わない処理にヘルパー関数が生えたりする現象です。この過剰実装(overengineering)を抑えるための指示文は、Anthropicのプロンプトエンジニアリングガイドに掲載されています。このTipsでは、その指示文をスコープ・ドキュメント・防御的コーディング・抽象化の4区分で使い分ける方法と、モデルやeffort設定による効き方の違いをまとめます。
Claude Opus 4.5/4.6が過剰実装する理由
Claude Opus 4.5とClaude Opus 4.6には過剰実装の傾向があります。余分なファイルを作る、不要な抽象化を追加する、頼まれていない柔軟性を組み込む、という3つの形で現れます。この挙動を避けたいときは、具体的な指示を加えてソリューションを最小限に保つよう促します。
こうしたモデル別の傾向は、そのモデルで測定された結果として扱うのが安全です。プロンプトエンジニアリングガイドの一般原則も、特定のモデル名を挙げた技術は「そのモデルで測定されたものとして扱い、別のモデルに当てる前に自分の評価で確かめ直す」ことを求めています。Opus 5.5やSonnet 5のような後続モデルにこの4区分の指示を使うときも、まず自分の依頼で効果を確かめてください。
裏を返せば、この傾向はモデルの欠陥ではなく「指示されていない改善」を先取りする振る舞いです。プロンプトでスコープを明示すれば、同じモデルでも出力は変わります。効果を確かめるには、同じ依頼に4区分の指示を付けた場合と付けない場合の差分を比べてみると分かりやすいです。
この背景には、繰り返し出てくる「指示は具体的であるほど良い結果につながる」という原則があります。「バグを直して」のような曖昧な依頼には、Claudeが自分の判断で範囲を補う余地が生まれます。同僚に渡しても迷わず実行できるかを確認する黄金律を、過剰実装を防ぐ指示にも当てはめれば、曖昧さが残っている箇所を洗い出せます。
過剰実装を防ぐプロンプトの4区分
プロンプトエンジニアリングガイドが示すサンプルプロンプトは、4つの観点で「やらないこと」を列挙する構成です。日本語に置き換えると次のようになります。
過剰なエンジニアリングを避けてください。要求されたこと、または明確に必要なことだけを
変更します。シンプルで対象を絞った解決策を保ちます。
- スコープ: 頼まれていない機能追加やコードのリファクタリング、「改善」を行わない。
バグ修正のために周辺コードを整理する必要はない。単純な機能に余分な設定可能性を
持たせない。
- ドキュメント: 変更していないコードにdocstring・コメント・型注釈を追加しない。
ロジックが自明でない箇所にだけコメントを足す。
- 防御的コーディング: 起こり得ないシナリオのためにエラーハンドリング・フォールバック・
検証を追加しない。内部コードとフレームワークの保証を信頼する。検証はシステム境界
(ユーザー入力・外部API)だけに絞る。
- 抽象化: 一度しか使わない処理のためにヘルパーやユーティリティ、抽象化を作らない。
仮定の将来要件に向けて設計しない。いま必要な最小限の複雑さが正しい複雑さ。4つの区分は独立した禁止事項ではなく、どれも「今その場にない要求を先取りしない」という同じ原則の言い換えです。CLAUDE.mdやシステムプロンプトのように恒常的に効かせる先には4つまとめて置き、単発の依頼では実際に問題になった区分だけを足す、という使い分けが基本になります。
4区分の使い分け早見表
過剰実装の症状によって、どの区分が効くかが変わります。「ログインエラーを直して」と頼んだのに同じファイル内の無関係な関数までリファクタリングされるならスコープ、変更した行の隣にある既存コードにまでコメントが増えてレビュー担当者が本題以外の行も読む必要が出るならドキュメント、呼び出し元が保証している値にまで検証コードが積まれて内部関数の引数チェックが肥大化するなら防御的コーディング、1箇所でしか呼ばれない処理にヘルパー関数や設定オプションが生えるなら抽象化の区分が効きます。
| 区分 | 止める行動 | 症状が出やすい場面 |
|---|---|---|
| スコープ | 止める行動頼まれていない機能追加・リファクタ | 症状が出やすい場面「バグを直して」で周辺コードまで書き換える |
| ドキュメント | 止める行動未変更コードへのコメント・docstring追加 | 症状が出やすい場面差分レビューが本題以外の行で肥大化する |
| 防御的コーディング | 止める行動起こり得ない例外へのtry/catch・フォールバック | 症状が出やすい場面内部関数にまで入力検証を積む |
| 抽象化 | 止める行動1回しか使わない処理のヘルパー化 | 症状が出やすい場面「将来のため」の共通化・設定項目が増える |
差分レビューで気になった行がどの区分に当たるかを確認すれば、次の指示に足す文言が自然に決まります。4区分すべてを毎回まとめて書くより、直近の差分で実際に問題になった区分だけを足していくほうが、指示文そのものの過剰実装を避けられます。
effortを下げるという第二の手段
スコープを絞る指示を入れても過剰な探索が収まらない場合は、effortパラメータを下げる方法もあります。Claude Opus 4.6はeffortが高い設定だと事前の探索を多めに行う傾向があり、これが過剰な調査や不要な変更につながることがあります。「常にgrepで調査してから答えて」のような一律の指示を、「grepは問題の理解を深める場面でだけ使って」のように条件を絞った指示に置き換えれば、過剰な振る舞いを抑えられます。以前のモデル向けに書いた「疑わしいときはツールを使って」という指示をそのまま引き継ぐと、いまのモデルでは過剰に発火しやすくなります。
effortの基本的な使い分けはClaude effortとは — low〜maxの使い分け方、Claude Codeでの設定方法はClaude Code effortレベルの使い方と設定で扱っています。
Claude Sonnet 5では効き方が違う
同じ4区分の指示でも、モデルごとの出発点は違います。Claude Sonnet 5はlow・mediumのeffortで、要求されたことにスコープを絞って動く挙動がもともと強く出ています。指示を字義通りに解釈し、要求していないことを推論で補いません。過剰実装を防ぐ4区分の指示は、Opus系のモデルほど強く効かせる必要がない場面もあると言えそうです。ただしSonnet 5は指示を広く一般化しません。複数ファイルにわたる長いタスクの全体にこの4区分を効かせたいなら、「この指示は最初の1ファイルだけでなく作業全体に適用して」のように適用範囲を明示したほうが確実です。
逆にClaude Opus 5では、過剰実装とは別の傾向として過剰検証が起こります。Opus 5は指示なしでも自分の作業を検証するため、「最後に検証ステップを入れて」「サブエージェントで検証して」のような検証指示を残したまま使うと、その指示と元々の自己検証が重なってトークンと待ち時間が余分にかかります。Opus 5へ移行するときは、こうした検証指示を書き直さずに削除するのが公式ガイドの推奨です。Opus 5はタスクの範囲を自分の判断で広げる傾向もあり、狙った範囲に留めたい依頼には「求められた範囲で仕上げる。読み方によって結果が大きく変わる場合だけ確認を挟み、通常の判断は自分で下す」のように範囲を明示する指示が効きます。過剰実装(不要なコードを増やす)と過剰検証(不要な確認を増やす)は別の現象です。モデルを切り替える際は、どちらの指示が残っているかを分けて見直す必要があります。
一時ファイル・テスト対策・サブエージェント過多を防ぐ追加パターン
過剰実装の4区分だけでは防げない、隣接した挙動が3つあります。
1つは、反復作業中に一時ファイルやスクリプトを作り「作業用のスクラッチパッド」として使う挙動です。結果の改善に役立つ場合もありますが、ネットの新規ファイル作成を抑えたいなら次の一文を追加します。
作業のために一時的な新規ファイル・スクリプト・ヘルパーファイルを作成した場合、
タスクの最後にそれらを削除してクリーンアップしてください。この一文は過剰実装を防ぐ4区分の指示とは対象が別なので、両方を並べて使っても衝突しません。
もう1つは、テストを通すことだけを目的にした実装です。テストケースにだけ合わせたハードコードや、複雑なリファクタリングの代わりにヘルパースクリプトで回避する挙動が該当します。標準的なツールで汎用的な解決策を書くこと、テストが通らない場合や誤っている場合は作業を回避せず報告することを明示する指示文で防げます。テストは解決策を検証する手段であり、解決策そのものを定義するものではないと明記するのが要点です。
3つ目は、サブエージェントの過剰起動です。Claude Opus 4.6は直接grepすれば済む場面でもコード探索用のサブエージェントを起動する傾向が強く、Claude Opus 5もそれ以前のモデルより気軽にサブエージェントへ委任します。どの場面で委任してよいかを指示文で明示するか、Claude Code 2.1.217以降で使えるCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSなどの環境変数で起動数に上限を設ける対応が有効です。
破壊的な操作の確認は別の指示で扱う
過剰実装を防ぐ4区分の指示は、変更の範囲を絞るためのものです。ファイルの削除やブランチの強制上書きのように取り消しにくい操作を実行前に確認させる指示は、目的が異なる別の項目です。共有システムに影響する操作や、他者に見える形で公開される操作(コードのpush、PRへのコメント、外部サービスへの送信など)を実行する前にユーザーへ確認を求めるよう促す文言を使います。
取り消しにくい操作の例は、ファイルやブランチの削除、git push --force、公開済みコミットの改変です。過剰実装対策(コードを増やさない)と安全確認(取り消しにくい操作の前に止まる)は別の懸念なので、1つの文にまとめず並列の指示として書くと、どちらが効いていないかを切り分けやすくなります。
CLAUDE.mdやhookに置いて恒常化する
過剰実装を防ぐ4区分の指示は、その場限りのプロンプトに書くよりプロジェクト全体で恒常的に効かせたい内容です。どのタスクでも共通して必要な事実に当たるので、CLAUDE.mdをSkillsに移行してコストを削減する方法で扱っている「CLAUDE.mdに残す指示」の基準にも当てはまります。
複数のコーディングツールを併用しているチームでは、この指示をツールごとに別々に書くと同期が崩れます。AGENTS.mdとCLAUDE.mdで設定を統合する運用パターンのように設定ファイルを一元化しておくと、過剰実装を防ぐ指示も1か所の更新で全ツールに反映できます。
送信前に指示の有無を機械的に確認したいなら、UserPromptSubmit hookでプロンプト送信前に介入するの仕組みで、4区分の指示が欠けているプロンプトにフックで注意を挟む運用も組めます。
まとめ
過剰実装を防ぐ4区分の指示は、Claude Opus 4.5/4.6で報告されている「頼まれていない改善」を抑えるために示された具体策です。効かない場合はeffortを下げる、モデルごとの出発点の違いを踏まえる、一時ファイルやテスト対策コードには別の指示を足す、という3つの補助策を組み合わせると、コード差分を意図した範囲に留めやすくなります。安全確認の指示は目的が別なので混ぜず、CLAUDE.mdやSkillに恒常ルールとして分けて置いておくと、タスクの種類が変わっても取りこぼしにくくなります。