Claude Codeがあなたの設計を無視する理由：descriptionフィールドの罠と回避策

生成AIエージェントを活用したコンテンツ制作において、多くの開発者が直面する問題があります。綿密に設計したワークフローが、なぜかAIに無視されてしまうのです。

今回取り上げるのは、Claude Codeを使ったZenn記事執筆プロジェクトでの実例です。企画、査読、執筆、レビュー、最終チェックという専任チームを想定したエージェントパイプラインを構築したにもかかわらず、Claude Codeはそれを完全にスキップして記事を生成しました。この「なぜ?」を追求した結果、AIエージェント設計における重要な知見が得られました。

Claude Codeには、多くの開発者が見落としがちな重大な仕様があります。**オーケストレーター（LLM）がエージェントを呼び出す際、descriptionフィールドの内容しか参照しない**のです。

これが意味するのは:

この仕様は、Claude Codeがマルチエージェントシステムとして設計されている以上、パフォーマンスとコスト最適化のための合理的な選択です。全てのエージェントの詳細仕様を毎回読み込んでいては、トークン消費量が爆発的に増加するためです。

この仕様は、他のAIツールやフレームワークとは大きく異なります。

LangChainやAutoGPTとの比較

ChatGPT（GPTs）との比較

ChatGPTのカスタムGPTsでは、Instructions全体が常にコンテキストとして機能します。つまり、詳細な手順書を書けば書くほど精度が上がる設計です。Claude Codeはこれとは真逆のアーキテクチャを採用しています。

なぜこの仕様が重要なのか

この発見は、AIエージェント設計における**パラダイムシフト**を意味します。

**メリット**:

1. **高速な判断**: descriptionのみを読むため、エージェント選択が極めて高速

2. **コスト効率**: トークン消費を最小限に抑えられる

3. **スケーラビリティ**: 数十〜数百のエージェントを定義しても、オーケストレーターの負荷が増えにくい

**注意点とトレードオフ**:

1. **設計の制約**: 複雑なワークフローを表現しにくい

2. **学習曲線**: 従来のエージェント設計経験が逆に障害になる可能性

3. **デバッグの難しさ**: なぜ特定のエージェントが選ばれたか（または選ばれなかったか）の理由が見えにくい

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

Claude Codeのこのアーキテクチャは:

**向いている場面**:

**向いていない場面**:

業界への影響

この設計思想は、今後のAIエージェントフレームワーク設計に大きな影響を与えるでしょう。「全てのコンテキストを常に参照する」重厚長大なアプローチから、「必要最小限の情報で判断する」軽量アプローチへのシフトが加速する可能性があります。

1. descriptionファーストで設計する

エージェントを作成する際、まずdescriptionを書きましょう。本文ではなく、この1〜2文にすべてを凝縮します。

description: "企画書を受け取り、SEO最適化されたブログ記事の本文を執筆する。出力はMarkdown形式。"

**ポイント**:

2. エージェントの粒度を見直す

複雑なパイプラインを構築する代わりに、各エージェントを**完全に独立した機能単位**として設計します。

3. 検証パターンを確立する

実際にClaude Codeがあなたの意図通りにエージェントを選択しているか、定期的にテストします。

# テストコマンド例
claude-code "記事を執筆して" --verbose

verboseモードで、どのエージェントが選ばれたかをログで確認し、期待と一致しているか検証しましょう。期待外のエージェントが選ばれた場合は、descriptionの表現を調整します。

Claude Codeの「descriptionしか読まない」仕様は、一見すると制約に見えますが、実はこれこそが設計思想の核心です。制約を理解し、その制約の中で最大の効果を引き出す設計こそが、真のエンジニアリングです。

従来のエージェント設計の常識を一度リセットし、Claude Code独自のアーキテクチャに最適化した設計を行うことで、高速でコスト効率の高いAIワークフローを実現できます。

この情報は @いち さんの投稿を参考にしています。