Claudeの過剰実装を防ぐプロンプトの書き方

このTipsでできること

Claudeにコード修正を頼むと、頼んでいない機能や抽象化まで追加されることがあります。バグ修正のついでに周辺コードまで整理されたり、一度しか使わない処理にヘルパー関数が生えたりする現象です。

この過剰実装(overengineering)を抑える指示文は、Anthropicのプロンプトエンジニアリングガイドに載っています。ここでは、その指示文を4区分で使い分ける方法に加えて、モデルごとの癖の違いと、Claude Codeのどこに置けば効くかを扱います。

Claude Opus 4.5/4.6が過剰実装する理由

Claude Opus 4.5とClaude Opus 4.6には過剰実装の傾向があります。余分なファイルを作る、不要な抽象化を追加する、頼まれていない柔軟性を組み込む、という3つの形で現れます。避けたいときは、具体的な指示を加えて解決策を最小限に保つよう促します。

この傾向は、そのモデルで測定された結果として扱うのが安全です。プロンプトエンジニアリングガイドの一般原則も、特定のモデル名を挙げた技術は別のモデルに当てる前に自分の評価で確かめ直すよう求めています。後続のモデルに4区分の指示を使うときも、まず自分の依頼で効果を確かめてください。

欠陥というより、「指示されていない改善」を先取りする振る舞いです。「バグを直して」のような曖昧な依頼には、Claudeが範囲を自分で補う余地が生まれます。同僚に渡しても迷わず実行できる依頼になっているかを確かめれば、曖昧さの残る箇所を洗い出せます。効果は、同じ依頼を指示あり・なしで走らせて差分を比べると分かります。

過剰実装を防ぐプロンプトの4区分

ガイドのサンプルプロンプトは、4つの観点で「やらないこと」を列挙する構成です。日本語に置き換えると次のようになります。

過剰なエンジニアリングを避けてください。要求されたこと、または明確に必要なことだけを
変更します。シンプルで対象を絞った解決策を保ちます。
 
- スコープ: 頼まれていない機能追加やコードのリファクタリング、「改善」を行わない。
バグ修正のために周辺コードを整理する必要はない。単純な機能に余分な設定可能性を
持たせない。
 
- ドキュメント: 変更していないコードにdocstring・コメント・型注釈を追加しない。
ロジックが自明でない箇所にだけコメントを足す。
 
- 防御的コーディング: 起こり得ないシナリオのためにエラーハンドリング・フォールバック・
検証を追加しない。内部コードとフレームワークの保証を信頼する。検証はシステム境界
(ユーザー入力・外部API)だけに絞る。
 
- 抽象化: 一度しか使わない処理のためにヘルパーやユーティリティ、抽象化を作らない。
仮定の将来要件に向けて設計しない。いま必要な最小限の複雑さが正しい複雑さ。

4つの区分は独立した禁止事項ではなく、どれも「今その場にない要求を先取りしない」という同じ原則の言い換えです。恒常的に効かせる先には4つまとめて置き、単発の依頼では実際に問題になった区分だけを足すのが基本になります。

差分の症状から足す区分を決める

どの区分を足すかは、差分に現れた症状で決まります。4区分すべてを毎回書くより、直近の差分で実際に問題になった区分だけを足すほうが、指示文そのものの過剰実装を避けられます。

モデルごとに過剰さの出方が違う

4区分は、もともとOpus 4.5/4.6向けに書かれた指示です。後続のモデルでは出方そのものが変わっており、足すべき指示も変わります。

Sonnet 5.5は「頼んでいない追加」を足す

Sonnet 5.5のガイドによると、リポジトリの慣習に合うテスト・ドキュメント・小さな補助ファイルを、頼まなくても足す傾向があります。effortを問わず起こり、高いほど強まります。要求した変更そのものは依頼の範囲に収まるため、差分の中心は小さいのに周辺ファイルだけ増えるという形で現れます。

ガイドが示す対策は、システムプロンプトに次の段落を足すことです。日本語に置き換えると次のようになります。

ユーザーが求めた作業が完了して確認も済んだら、そこで止めて報告してください。
求められていない機能・テスト・ファイル・ドキュメント・リファクタは追加しません。
追加が役立ちそうなら、実行せず最後に提案として伝えてください。

ガイドは、この段落を別の段落(求められたことがすべて終わるまで作業を続ける指示)と組にして示したうえで、範囲を絞りたいだけなら「止めて報告する」段落だけを足せば足りると説明しています。xhighとmaxのeffortでは、この段落によって追加が減り、変更全体も小さくなります。

xhighとmaxでは、完了後に自分でレビューや検証の周回を始めたり、気づいた関連修正を足したりする傾向もあります。日常的な作業はhigh以下で回すのがガイドの勧めで、それ以上でレビュー用のサブエージェントまで抑えたいときは、別の一段落が用意されています。

Sonnet 5とOpus 5の違い

Sonnet 5は、指示を広く一般化しません。複数ファイルにわたる長いタスクの全体に4区分を効かせたいなら、「この指示は最初の1ファイルだけでなく作業全体に適用して」のように適用範囲を明示したほうが確実です。

Opus 5は、指示がなくても自分の作業を検証します。「最後に検証ステップを入れて」「サブエージェントで検証して」のような検証指示を残すと、自己検証と重なってトークンと待ち時間が増えます。ガイドは、Opus 5へ移行するときは書き直さずに削除するよう勧めています。

Opus 5はタスクの範囲を自分の判断で広げることもあります。狙った範囲に留めたい依頼には、次のような一文が効きます。

求められた範囲で仕上げる。読み方によって結果が大きく変わる場合だけ確認を挟み、
通常の判断は自分で下す。

過剰実装(不要なコードを増やす)と過剰検証(不要な確認を増やす)は別の現象です。モデルを切り替えるときは、どちらの指示が残っているかを分けて見直します。

effortを下げるという第二の手段

スコープを絞る指示を入れても過剰な探索が収まらない場合は、effortを下げる方法があります。Opus 4.6はeffortが高い設定だと事前の探索を多めに行い、これが過剰な調査や不要な変更につながることがあります。ガイドが挙げる対処は3つです。

Claude Codeでeffortを変える方法は何通りかあります。環境変数CLAUDE_CODE_EFFORT_LEVEL、起動時の--effort、セッション中の/effortが明示的な指定で、保存済みの設定より先に効きます。このうち環境変数は、--effortと/effortを上書きします。

指定がなければモデルの既定値になります。公式のモデル設定ページによると、既定値は多くのモデルでhighです。例外はOpus 5.5とSonnet 5.5がmedium、Opus 4.7がxhighで、今のレベルを確かめてから指示を足す順序になります。

effortの基本的な使い分けはClaude effortとは — low〜maxの使い分け方、Claude Codeでの設定方法はClaude Code effortレベルの使い方と設定で扱っています。

一時ファイル・テスト対策・サブエージェント過多を防ぐ追加パターン

4区分だけでは防げない、隣接した挙動が3つあります。

1つは、反復作業中に一時ファイルやスクリプトを作り、スクラッチパッドとして使う挙動です。結果の改善に役立つ場合もありますが、正味の新規ファイル作成を抑えたいなら次の一文を足します。

作業のために一時的な新規ファイル・スクリプト・ヘルパーファイルを作成した場合、
タスクの最後にそれらを削除してクリーンアップしてください。

この一文は4区分と対象が別なので、並べて使っても衝突しません。

もう1つは、テストを通すことだけを目的にした実装です。テストケースにだけ合わせたハードコードや、複雑なリファクタリングの代わりにヘルパースクリプトで回避する挙動が該当します。標準的なツールで汎用的な解決策を書くこと、テストが誤っている場合や課題が実現不能な場合は回避せず報告することを指示文に明記します。テストは解決策を検証する手段であり、解決策そのものを定義するものではない、と書くのが要点です。

3つ目は、サブエージェントの過剰起動です。Opus 4.6は、直接grepすれば済む場面でもコード探索用のサブエージェントを起動しがちです。Opus 5も、それ以前のモデルより気軽に委任します。

指示文で委任してよい場面を明示するほか、Claude Code 2.1.217以降なら環境変数で上限を設けられます。CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSは同時に走らせられる数を制限し、既定は20です。CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHはサブエージェントの入れ子の深さを制限し、既定は3です(v2.1.219以降。v2.1.217〜218では1)。

破壊的な操作の確認は別の指示で扱う

4区分は、変更の範囲を絞るための指示です。取り消しにくい操作を実行前に確認させる指示は、目的が異なる別の項目です。ガイドには、共有システムに影響する操作や他者に見える操作の前にユーザーへ確認を求める文言が載っています。

確認の対象に挙がっているのは、ファイルやブランチの削除、git push --force、git reset --hard、公開済みコミットの改変、コードのpushやPRへのコメントです。過剰実装対策(コードを増やさない)と安全確認(取り消しにくい操作の前に止まる)は別の懸念なので、1つの文にまとめず並列の指示として書きます。どちらが効いていないかを切り分けやすくなります。

置き場所で効き方が変わる

4区分を恒常的に効かせたいとき、Claude Codeには置き場所が3つあります。強制力の有無が最も大きな違いです。

v2.1.289のCLIでは、--effortと--append-system-promptが次のように表示されます。

claude --version
2.1.289 (Claude Code)
 
claude --help | grep -A1 -E "^  --(effort|append-system-prompt) "
  --append-system-prompt <prompt>       Append a system prompt to the default
                                        system prompt
--
  --effort <level>                      Effort level for the current session
                                        (low, medium, high, xhigh, max)

4区分は、どのタスクでも共通して必要な指示なので、CLAUDE.mdをSkillsに移行してコストを削減する方法で扱っている「CLAUDE.mdに残す指示」の基準にも当てはまります。

複数のコーディングツールを併用しているチームでは、ツールごとに別々に書くと同期が崩れます。AGENTS.mdとCLAUDE.mdで設定を統合する運用パターンのように設定ファイルを一元化すると、1か所の更新で全ツールに反映できます。

プロンプトを送るたびに指示を差し込みたいなら、UserPromptSubmit hookでプロンプト送信前に介入するの仕組みがあります。公式のhooksページによると、UserPromptSubmitのhookが出力した文字列は、Claudeが読めるコンテキストとして追加されます。

まとめ

4区分は、Opus 4.5/4.6の「頼まれていない改善」を抑えるための指示です。Sonnet 5.5には「止めて報告する」段落、Opus 5には検証指示の削除と範囲の明示、と使うモデルで足す指示が変わります。

CLAUDE.mdに置いた指示は助言に留まります。取り消しにくい操作のように外せない制約は、hookで止めると決めておくと、指示文の効き具合に左右されません。