CLAUDE.mdは「育てる」ものではなく「設計する」もの——コンテキストドリブン開発の落とし穴

井本賢氏が投稿した興味深い失敗談が、AIコーディング支援ツールのユーザーに重要な示唆を与えています。半年かけて育て上げたCLAUDE.mdを新しいリポジトリにコピーしたところ、AIが全く正しく動作しなかったというのです。

この事例は、生成AI時代の開発において避けて通れない本質的な問題を浮き彫りにしています。それは「AIの設定ファイルは、プロジェクトのコンテキストに深く依存している」という事実です。

井本氏のケースでは、以下のような問題が発生しました：

これは単なる「コピペミス」ではありません。CLAUDE.mdのようなAI設定ファイルが、実は**プロジェクトの暗黙知を大量に含んでいる**ことを示しています。

GitHub CopilotやCursorとの比較

この問題は、実はClaude Codeに限った話ではありません。GitHub CopilotやCursorでも、プロジェクト固有の設定やコメントを積み重ねると同様の問題が発生します。ただし、重要な違いがあります：

**Claude Codeの特徴**：

**GitHub Copilot/Cursorの特徴**：

メリットと注意点の両面分析

**CLAUDE.mdアプローチのメリット**：

1. **ルールの明示性**：チーム内で共有しやすく、レビュー可能

2. **バージョン管理の容易さ**：Gitで変更履歴を追跡できる

3. **学習曲線の短縮**：新メンバーがプロジェクトの規約を理解しやすい

**注意すべき落とし穴**：

1. **コンテキスト依存性の不可視化**：ファイル単体では「何に依存しているか」が明示されない

2. **過剰な最適化のリスク**：特定プロジェクトに最適化しすぎると汎用性を失う

3. **メンテナンスコスト**：プロジェクトが進化するとCLAUDE.mdも更新が必要

どんな人・場面に向いているか

**CLAUDE.mdを「育てる」アプローチが有効な場面**：

**「テンプレート化」アプローチが有効な場面**：

重要なのは、**「育てる」と「設計する」を意識的に使い分ける**ことです。

1. CLAUDE.mdを「レイヤー化」する

CLAUDE.mdを以下のように分割することを推奨します：

# CLAUDE.md（プロジェクト固有）

## プロジェクト構造
- src/components/ にReactコンポーネントを配置
- tests/ にテストファイルを配置

## このプロジェクト固有のルール
（ここに現在のプロジェクトに特化した内容を記述）

---

以下の汎用ルールも参照：
- [汎用コーディング規約](../templates/coding-standards.md)
- [TypeScript規約](../templates/typescript-rules.md)

2. 「依存関係チェックリスト」を作成する

新しいリポジトリにCLAUDE.mdをコピーする前に、以下を確認するチェックリストを作りましょう：

3. 「汎用テンプレート」と「プロジェクト固有設定」を分離する

組織レベルで以下のような構造を維持することをお勧めします：

organization-templates/
├── claude-base.md          # 全プロジェクト共通
├── claude-frontend.md      # フロントエンド共通
└── claude-backend.md       # バックエンド共通

project-a/
└── .claude/
    ├── CLAUDE.md           # プロジェクトA固有
    └── includes/
        └── base.md -> ../../organization-templates/claude-base.md

こうすることで、「何が汎用で何が固有か」が明確になり、新プロジェクト立ち上げ時の混乱を防げます。

井本氏の失敗談は、AI時代の開発における新しい課題を明らかにしています。それは「AIへのインストラクションも、ソフトウェアアーキテクチャの一部として設計すべき」ということです。

CLAUDE.mdは単なる設定ファイルではなく、**プロジェクトのコンテキストを記述したドキュメント**です。だからこそ、コピー&ペーストではなく、各プロジェクトに合わせた適切な「設計」が必要なのです。

この情報は @井本 賢 | WebRTC×音声AI / LLMO さんの投稿を参考にしています。