AIに「大規模設計をさせない」ためのCLAUDE.md設計 — 過剰設計を止める実運用ルール

AIエージェントの開発をご検討中ですか？ AIエージェント開発サービスを見る →

AIが勝手に「大規模設計」を始める問題

社内のちょっとしたCRUDツールや小規模なバッチ処理スクリプトを作りたいだけなのに、Claude CodeなどのAIコーディングエージェントが、勝手にマイクロサービスアーキテクチャやメッセージキュー、過剰な抽象基底クラスを組み込もうとして頭を抱えた経験はないでしょうか。これは、現在の開発現場で急速に顕在化している「AIによる過剰設計（Over-engineering）」問題です。

チャットで「もっとシンプルに書いて」と都度指示をすれば、一時的には改善されます。しかし、セッションが切れたり別のタスクに移ったりすると、AIはすぐにまた「大規模前提」の設計に戻ってしまいます。

本記事では、この「AIの大規模病」を根本から止めるために、プロジェクトのルートに配置する設定ファイル CLAUDE.md を活用した抑止ルールと、実務ですぐに使える設計テンプレートを解説します。

なぜAIはコーディング時に「過剰設計」に走るのか？

そもそも、なぜ優秀なAIエージェントが単純なタスクに対して複雑すぎる設計を提案してしまうのでしょうか。その根本的な理由は主に3つあります。

学習データのバイアス：大企業のエンタープライズOSSが「正解」として刷り込まれている

LLM（大規模言語モデル）の学習データには、世界中の公開リポジトリや技術ドキュメントが大量に含まれています。その中には、大企業が運用するエンタープライズ向けのOSSや、拡張性を極限まで高めた大規模システムアーキテクチャの事例が多く存在します。そのため、AIは統計的に「大規模で拡張性の高い設計こそが正解（ベストプラクティス）である」と誤認しがちです。結果として、数人が使うだけの社内ツールにも、分散キャッシュや複雑なDI（依存性の注入）コンテナを持ち込んでしまいます。

制約がないと「最大値（大は小を兼ねる）」を取りにいくLLMの特性

LLMは、明示的な「制約」を与えられない限り、将来のあらゆる要件変更に耐えられるような「最大値」の設計を取りにいく特性があります。「大は小を兼ねる」という思考回路により、YAGNI（You Aren't Gonna Need It: 今必要ないものは作るな）原則を無視します。将来的に必要になるかもしれないというだけで、不必要なキャッシュ層を作ったり、実装が1つしかないのにインターフェースと抽象基底クラスを分離したりしてしまうのです。

「シンプルにして」という都度プロンプトが現場で形骸化する理由

「AIが複雑なコードを書いたら、その都度チャットで『シンプルにして』と指示すればいい」と考えるかもしれません。しかし、実運用においてこのアプローチはすぐに破綻します。 LLMのコンテキストウィンドウには上限があり、対話が長く続くと過去の「シンプルにして」という指示は押し出されて忘れ去られます。その結果、いつの間にか複雑なアーキテクチャが復活し、コードレビューのたびにエンジニアが修正指示を出すという無駄な往復が発生し、開発現場でのAI活用ルールが形骸化してしまいます。

過剰設計を止めるCLAUDE.mdの設計原則：ポジティブ指示より「禁止事項」

この問題を解決するためには、AIに対するアプローチを変える必要があります。プロジェクトごとに CLAUDE.md を配置し、「〜してほしい」というポジティブ指示よりも、「〜は絶対にするな」という強い制約を設けることが効果的です。

原則1：「小〜中規模・YAGNI最優先」を規模の前提として固定する

まず、プロジェクト自体が大規模開発ではないことを CLAUDE.md に明記し、「シンプルで薄い設計」をデフォルトの振る舞いとして固定化させます。「すべてのプロジェクトの前提として、大規模開発は一切行わない」「YAGNI原則を最優先する」と宣言することで、AIのベースラインを「エンタープライズ」から「小〜中規模」へと強制的に引き下げることができます。

原則2：不要なアーキテクチャ層を「名指し」で列挙する

「シンプルな設計にして」という抽象的な指示は、AIによって解釈がブレます。確実に過剰設計を防ぐには、持ち込まれたくない技術や構成を「名指し」で明確に列挙（禁止カタログ化）します。例えば「マイクロサービス」「メッセージキュー（RabbitMQ, Kafka等）」「Redis等の外部キャッシュ」「過度な抽象基底クラス」など、現在のプロジェクトスコープで不要なものをリストアップして禁止します。

原則3：1イテレーションのスコープ（フェーズ粒度）を制限する

AIに機能全体を一気に設計・実装させると、見えない部分を勝手に推測し、複雑なアーキテクチャを作り上げてしまいます。これを防ぐため、「粒度を大きくさせず細かいフェーズに分ける」というルールを定義します。1回のプロンプトで扱うスコープを限定し、小さくイテレーションを回して人間が確認を挟む前提を作ることで、意図しない大規模化を防ぎます。

【コピペで使える】過剰設計抑止用 CLAUDE.md 実装テンプレート

ここでは、過剰設計を抑止するために実務ですぐに使える CLAUDE.md のコードスニペットと、それに付随するチーム運用ルールを紹介します。そのままプロジェクトのルートディレクトリにコピーして活用してください。

規模の前提（Project Scale & Philosophy）

CLAUDE.md の冒頭で、プロジェクトの思想と規模を定義します。

## Project Scale & Philosophy
- **規模の前提**: 本プロジェクトにおいて、大規模開発（エンタープライズ規模）は一切行いません。小〜中規模の要件に特化しています。
- **YAGNI原則の徹底**: 今必要ない機能や拡張性は絶対に実装しないでください。「将来必要になるかもしれない」という推測に基づく設計は禁止します。
- **KISS原則**: アプリケーションや設計は、常にシンプルで薄く、柔軟性が高い状態を維持してください。

禁止構成カタログ（Forbidden Architectures）

次に、名指しで禁止するアーキテクチャや技術スタックを明記します。

## Forbidden Architectures (禁止構成リスト)
以下のアーキテクチャや技術要素の導入は、明示的な指示がない限り禁止します。
- マイクロサービスアーキテクチャ（単一のモノリスとして構築すること）
- メッセージキュー（RabbitMQ, Kafka, SQSなど）や非同期ワーカー
- 外部キャッシュ層（Redis, Memcachedなど）
- 実装クラスが1つしか存在しないインターフェースや抽象基底クラス
- 過剰なデザインパターンの適用（複雑なDIコンテナ、無駄なFactory等）

実装フェーズの粒度定義（Phase & Scope Definition）

一度に大量のコードを書かせないための制約です。

## Phase & Scope Definition
- 一気に大規模なコード生成やリファクタリングを行わないでください。
- 実装は粒度を大きくさせず、細かいフェーズに分けて進行してください。
- 1つのフェーズが終わるごとに、実装の意図を説明し、次のステップへ進む許可を求めてください。

完了報告ルール（「あえて作らなかったもの」の明記）

設定ファイルだけでなく、人間の確認プロセス（運用ルール）も重要です。 AIに対して「タスク完了時に、YAGNI原則に基づき『あえて作らなかったもの』を報告させる」ルールを追加します。

## 完了報告のルール
タスク完了時やPull RequestのDescription作成時には、必ず以下の項目を記載してください。
1. 実装した内容の概要
2. **YAGNIに基づいて「あえて作らなかったもの・削った箇所」**
3. 設計がシンプルで薄く保たれているかの自己評価結果

これにより、AI自身に「シンプルに保てているか」を再チェックさせる仕組みが働き、人間（レビュアー）も過剰設計がないことを容易に確認できるようになります。

チーム導入で見えた定量的・定性的効果（DX改善）

この CLAUDE.md の設計と運用ルールを開発現場に導入したことで、DX（開発者体験）において次のような明確な改善が見られました。

PRレビュー往復回数の削減（手戻りの激減）

もっとも大きな効果は、設計レビューにおける手戻りの激減です。 AIが勝手に複雑なキューイングシステムや不要なインターフェースを生成しなくなるため、「ここの抽象化は過剰だから削って」という人間からの修正指示が劇的に減りました。結果としてレビューの往復回数が減り、開発スピードが大きく向上します。

不要な設定・依存関係が排除され、コードベース認知負荷が半減

「大は小を兼ねる」設計が排除されたことで、不要なライブラリの依存関係や複雑な設定ファイルがプロジェクトから消え去りました。コードベース全体が薄く保たれるため、新しくプロジェクトに参画したメンバーがシステムを理解する際の認知負荷が大幅に下がります。

ジュニアエンジニアがAIの過剰提案に流される事故の防止

経験の浅いジュニアエンジニアは、AIがもっともらしい理由をつけて提案してくる「分散キャッシュ」や「クリーンアーキテクチャ」を、「これがベストプラクティスなんだ」と誤認してそのまま取り込んでしまうことがあります。 CLAUDE.md で強力な制約をかけておくことで、こうしたAIの過剰提案自体を封じ込め、チーム全体のコード品質を安全な水準に保つことができました。

まとめ：AI時代に必要なのは「作らせる力」ではなく「制限する力」

AIコーディングエージェントは非常に強力なツールですが、その生産性を最大化するためには、「何を自動で作らせるか」以上に、「何をさせないか（制約のコントロール）」が重要になります。今回紹介した CLAUDE.md の「規模の前提」と「名指しの禁止リスト」を活用して、AIの暴走をコントロールし、保守しやすいシンプルなコードベースを維持してください。

AIコーディングエージェントの業務導入におけるプロンプト設計、プロジェクトごとのルール整備、DX改善に関するお悩みは、グランドリームにぜひご相談ください。貴社の開発チームに最適なAI活用プロセスをご提案します。