AIツールの実力は、ドキュメントの質次第です

現在、あらゆるエンジニアリングチームが何らかの形でAIツールを利用しています。コードを自動補完するコードアシスタント、コードベースを検索・修正できるエージェント、システムやプロセスに関する質問に答える社内ツールなどです。これらのツールは、関連する知識に即座にアクセスできるようにすることで、エンジニアリングを加速させることが期待されています。

しかし、ほとんどのチームにおける現実は、これらのツールは一般的なコーディングタスクには便利であるものの、チーム独自のシステムに特化したことになると驚くほど役に立たないということです。コードアシスタントはPythonの関数を書くことはできても、チームのコーディング規約を知りません。エージェントはコードベースを検索できても、決済サービスがなぜそのような構造になっているのかを説明することはできません。社内チャットボットは、必要な知識が検索可能なドキュメントではなく、人々の頭の中やSlackのスレッドに存在するため、会社固有のシステムについてハルシネーション（嘘の回答）を起こします。

これはAIモデルの限界ではありません。AIがアクセスできるコンテキストの限界なのです。

コンテキストの問題

AIツールはコンテキストから推論します。現在のファイルとそのインポートを確認できるコードアシスタントは、それなりの補完を行います。さらにプロジェクトのアーキテクチャドキュメント、コーディング規約、決定の履歴まで確認できるコードアシスタントは、チームが選択したパターンとその理由を理解しているため、劇的に優れた補完を行います。

同じことが、エンジニアリングワークフローにおけるすべてのAIツールに当てはまります。社内エージェントに「請求システムはどのように返金を処理しているか？」と尋ねた場合、エージェントが検索できる場所にその答えが存在して初めて、有用な回答を得ることができます。もしその答えが8ヶ月前のSlackのスレッド、文字起こしされていない会議の録音、あるいはシニアエンジニアの記憶の中にしかない場合、エージェントは何も手がかりがなく、わからないと認めるか、さらに悪いことには、間違っているもっともらしい回答をでっち上げることになります。

AIツールの出力の質は、そのツールが利用できるドキュメント化されたコンテキストの質によって制限されます。包括的で最新のドキュメントを用意しているチームは、そうでないチームよりも、AIへの投資から大幅に多くの価値を引き出すことができます。

AIインフラとしてのドキュメンテーション

これは、従来の議論よりもエンジニアリングリーダーにとって説得力のある形で、ドキュメンテーションの問題を再定義します。

ドキュメントはもはや人間だけのものではありません。それは、あなたのスタックにあるすべてのAIツールのトレーニンググラウンドなのです。アーキテクチャの決定、システムの挙動、障害履歴、チームの規約を取り込む「自己執筆型ドキュメント」は、人間とAIエージェントの双方がクエリを投げられるナレッジベースを構築します。

あなたのエンジニアリングWikiが、GitHubのアクティビティ、Slackの会話、会議の文字起こしから自動で執筆されるとき、作成されたドキュメントは二重の役割を果たします。新入社員のためのオンボーディングリソースであり、AIツールのためのコンテキストレイヤーでもあります。新しいエンジニアが決済サービスを理解するのに役立つ同じドキュメントが、AIエージェントがそれについて正確に質問に答えるのにも役立つのです。

MCP（Model Context Protocol）を通じて、ドキュメント化されたエンジニアリングの知識は、カスタムインテグレーションなしで任意のAIエージェントからアクセス可能になります。ドキュメントは、互換性のある任意のツールが読み取れる共有コンテキストレイヤーとして機能します。つまり、ドキュメンテーションへの投資が、ワークフローにおけるすべてのAIツールの価値を何倍にも高めるのです。

フィードバックループ

ここには、説明しておく価値のある好循環が存在します。優れたドキュメンテーションは、AIツールをより便利にします。より便利なAIツールは、エンジニアリングを高速化します。高速なエンジニアリングは、自己執筆型ドキュメントシステムが取り込むアクティビティをさらに生み出します。取り込まれるアクティビティが増えることで、ドキュメントはより豊かになります。より豊かなドキュメントは、AIツールをさらに便利にします。

このサイクルに早く入ったチームには、複利的な強みが生まれます。ドキュメントが改善されるにつれてAIツールが向上し、エンジニアリングアクティビティがより多くのドキュメント化されたコンテキストを生成するにつれて、ドキュメントが自動的に改善されていきます。ドキュメント化を行わないチームは、一般的な能力はあるものの、自分たちのコードベースに対しては具体的に役に立たないAIツールから抜け出せなくなります。

よくある質問

どのようなAIツールがドキュメンテーションから最も恩恵を受けますか？ 会社固有のシステムに関する質問に答える社内エージェントは、その価値が完全に会社固有のコンテキストに依存しているため、最大の改善が見られます。コードアシスタントは、規約遵守やアーキテクチャを意識した提案において、有意義な改善が見られます。コードを修正するコーディングエージェントは、既存の構造の背後にある理由を理解することで恩恵を受けます。

これはMCPとどのように連携しますか？ MCPは、AIエージェントがあなたの指示に従ってナレッジベースから読み取ることを可能にするオープンプロトコルです。ドキュメント化されたエンジニアリングの知識は、その知識がツールのトレーニングデータに吸収されることなく、MCP互換のツールのコンテキストレイヤーになります。ドキュメントはあなたのもののままであり、AIはそこから読み取ります。

すでにナレッジベースを持っています。なぜAIツールにうまく機能しないのでしょうか？ ほとんどのナレッジベースは古く、不完全であるか、検索が困難な方法で整理されています。AIツールには、最新で包括的、かつ意味的に検索可能なドキュメントが必要です。自動的に更新され、意味で検索可能な自己執筆型ドキュメントは、これら3つの問題すべてに対処します。

関連の読み物：なぜエンジニアリングドキュメントが重要なのか、自己執筆型ドキュメントの解説、記憶こそが障壁である。関連ページ：自己執筆型ドキュメント、MCP、エンジニアリングチーム向け。