Claude Codeのカスタムサブエージェント開発で学んだ「公式ドキュメント優先」の教訓

「3時間かけて作った機能が、実は標準機能で実現できた」——開発者なら誰もが経験するこの痛みが、Claude Codeの世界でも起きています。@NakuReiさんの投稿は、カスタムサブエージェントを開発した後に「context: fork」という既存機能で十分だったと気づいた経験を共有したものです。

この話は単なる失敗談ではありません。生成AIツールが急速に進化する今、私たちは「AIに聞けば何でも解決する」という思考パターンに陥りがちです。しかし、ツールの全体像を理解せずに開発を進めると、かえって非効率になるという重要な教訓がここにあります。

カスタムサブエージェントとは

Claude Codeのカスタムサブエージェントは、特定タスクに特化した独立実行環境です。主な特徴は以下の通りです：

context: forkの実力

一方、「context: fork」は既存のスキル（Claude Codeにおける再利用可能な機能単位）に付与できるオプションです。これを使うと：

今回のケースでは、3時間かけて構築したカスタムサブエージェントの目的が「コンテキストの分離」だった場合、既存スキルに`context: fork`を付けるだけで同じ効果が得られたということです。

「AIに聞く」vs「ドキュメントを読む」の使い分け

ChatGPTやClaude、GitHub Copilotなど、AIアシスタントの能力は目覚ましく向上しています。しかし、これらのツールには明確な限界があります：

**AIアシスタントの弱点：**

**公式ドキュメントの強み：**

今回のケースは、AIに「コンテキストを分離したい」と相談した結果、「カスタムサブエージェントを作りましょう」という提案を受けた可能性が高いでしょう。AIは質問に対して「できること」を答えますが、「最も簡単な方法」を常に提示するわけではありません。

カスタムサブエージェント開発が正解になるケース

誤解してほしくないのは、カスタムサブエージェント自体は非常に強力な機能だということです。以下のような場合は、`context: fork`では不十分で、カスタム開発が必要になります：

1. **複雑なワークフローの実装**: 複数ステップの処理を自動化したい場合

2. **独自のプロンプト戦略**: 特定ドメインの専門知識を深く組み込みたい場合

3. **外部ツール連携**: APIやデータベースとの統合が必要な場合

4. **再利用性の高いエージェント**: チーム全体で使う標準化されたエージェントを作りたい場合

「コンテキスト分離」だけが目的なら`context: fork`で十分ですが、それ以上の価値を提供したいならカスタム開発は正当化されます。

技術選定における「調査コスト」の考え方

開発者は常に「実装時間」と「調査時間」のトレードオフに直面します。今回の3時間は「無駄」だったのでしょうか？

**短期的視点**: 確かに、15分のドキュメント読解で済んだ作業に3時間かけたのは非効率です。

**長期的視点**: カスタムサブエージェントの仕組みを深く理解できたことで、将来本当に必要になったときの実装速度は格段に上がります。

ただし、プロジェクトのタイムラインや学習目的によって、この判断は変わります。実務では「動くものを最速で作る」ことが求められる場面も多く、そこでは公式ドキュメントの優先読解が鉄則です。

1. 「公式ドキュメント15分ルール」を導入する

新機能を使う前に、必ず15分間は公式ドキュメントを読む習慣をつけましょう。具体的には：

Claude Codeの場合、公式ドキュメントで「Skills」「Context Management」「Subagents」のセクションを読むだけで、今回のような重複作業を避けられます。

2. AIアシスタントに「既存機能での実現方法」を明示的に聞く

単に「○○を実現したい」と聞くのではなく、以下のように質問を工夫します：

**改善前**: 「コンテキストを分離する方法を教えて」

**改善後**: 「Claude Codeでコンテキストを分離したいのですが、カスタムサブエージェントを作る以外に、既存機能で実現できる方法はありますか？標準機能を優先的に教えてください」

この質問方法なら、AIは既存機能を優先的に提案してくれます。

3. 「機能比較マトリクス」を自分で作る

新しいツールを学ぶときは、類似機能の比較表を作成しましょう：

| 機能 | 実装時間 | 柔軟性 | 保守性 | 適用場面 |

|------|----------|--------|--------|----------|

| context: fork | 0分 | 低 | 高 | シンプルな分離 |

| カスタムサブエージェント | 180分 | 高 | 中 | 複雑なワークフロー |

こうした表を作ることで、技術選定の判断基準が明確になり、将来の意思決定が速くなります。

AIツールの進化は素晴らしいものですが、それらを使いこなすための「メタ知識」——どの情報源をいつ参照すべきか——がますます重要になっています。

これら3つの情報源を適切に組み合わせることで、@NakuReiさんのような「1敗」を減らせます。失敗は学びの源ですが、避けられる失敗は避けたほうが効率的です。

次に新しいAIツールに触れるときは、まず公式ドキュメントを開いてみてください。その15分が、3時間を節約するかもしれません。

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