生成AIのドキュメントが「読みにくい」理由と、エンジニアが取るべき対策

深夜のコードレビュー、あるいは設計会議の直前。GitHubのプルリクエスト（PR）を開いた瞬間に感じる、あの独特の「重苦しさ」を皆さんは経験したことがないだろうか。情報量は膨大なのに、肝心の「なぜその設計に至ったのか」という核心が霧の中に消えているような感覚だ。最近、Claude CodeのようなAIエージェントが生成したDesign DocやPRを読み込む際、私はまさにこの「情報の過剰摂取による疲労」に苛まれている。内容が間違っているわけではない。むしろ、論理的には正しく、網羅性も高い。しかし、読み手である我々エンジニアの脳は、その文章を処理する過程で、まるでデッドロックに陥ったかのような停滞感を覚えるのだ。

この疲労感の正体は、生成AIが持つ「網羅性への過剰な執着」にあると私は断言する。AIは人間のように「ここは重要だから強調し、ここは自明だから省略する」というコンテキストの取捨選択を自律的に行わない。結果として、決定的な判断と些末な前提条件が同じ熱量で並べられ、読み手は自ら重要度を仕分けするという、本来AIが肩代わりすべきコストを支払わされている。さらに、結論を最後に持ってくるという「起承転結」の構成が、読み手のワーキングメモリを圧迫する。結論から言えば、AIは「ドキュメントを書く」ことには長けているが、「意思決定を伝える」ことにはまだ未熟なのだ。我々エンジニアが直面しているのは、AIが吐き出す「正しいが役に立たない」情報の洪水であり、このままでは開発現場の生産性は、AIによってむしろ低下するという皮肉な事態を招きかねない。

では、この「AI特有の冗長性」をどう克服すべきか。依田氏の検証が示す通り、解決策は「AIに何をさせるか」ではなく「AIに何をさせないか」を定義するプロンプトエンジニアリングの転換にある。実際にECサイトのクーポン適用ロジックという具体的な要件を用いて比較した結果、BeforeとAfterではドキュメントの質が劇的に変化した。Beforeの構成では、Design Docが284行・8521文字にまで膨れ上がったのに対し、ガイドラインを設けたAfterでは41行・1239文字へと圧縮された。この差は、単なる要約ではない。情報の密度が最適化された結果である。

具体的には、以下の表に示すような「制約」をSkill（プロンプト）に組み込むことが極めて有効だ。特に「代替案の比較を表形式にする」という指示は、文章による両論併記という無限ループを断ち切るための強力な武器となる。また、「結論を冒頭に書く」「自明な定型セクションを省略する」といったルールは、読み手の認知負荷を劇的に下げる。これは、コードにおけるリファクタリングと同じだ。冗長なコードが保守性を下げるように、冗長なドキュメントは意思決定のスピードを鈍らせる。我々エンジニアは、AIに対して「網羅せよ」と命じるのではなく、「レビュアーが意思決定を理解するために必要な最小限の情報を抽出せよ」という、より高度な抽象化を求めるべきなのだ。

この検証から得られる教訓は、AIを「優秀なライター」として扱うのではなく、「文脈を理解しないが高速な処理装置」として制御する視点を持つことだ。GitHub Copilotの学習データ利用問題など、AIとの付き合い方が問われる昨今、我々が真に習得すべきは、AIを使いこなすための「言語化能力」そのものなのかもしれない。

最後に、我々エンジニア自身への問いを投げかけたい。AIが生成したドキュメントを「読みたくない」と感じる時、それは本当にAIの性能不足なのだろうか。あるいは、我々自身が「ドキュメントに何を求めているのか」を言語化できていないことの裏返しではないだろうか。AIは、我々が曖昧にしか定義していない「良いドキュメント」の基準を、残酷なまでに忠実に、そして過剰に具現化して見せているに過ぎない。もしAIの出力が冗長で疲れるのであれば、それは我々がこれまで書いてきたドキュメントもまた、同じように冗長で、読み手にとってのノイズを含んでいた可能性を示唆している。

明日から取るべき実践的な処方箋は明確だ。まず、自身のプロジェクトで利用しているAIエージェントのSkillやプロンプトを見直し、「Non-goals（やらないこと）」を明記すること。そして、ドキュメントを「記録」ではなく「意思決定の伝達手段」と再定義することだ。AIに書かせる前に、自分自身で「何が結論で、何が判断の根拠か」を整理するプロセスを挟むだけで、AIの出力は劇的に洗練される。AIは思考の代行者ではなく、思考の増幅器である。我々が思考を放棄すれば、AIはただのノイズ製造機と化す。AI時代において、エンジニアの価値は「コードを書くこと」から「AIを制御し、文脈を設計すること」へとシフトしている。この変化を恐れるのではなく、AIという強力なツールを使いこなし、より本質的な設計判断に集中できる環境を自ら構築できるか。その問いに対する答えが、これからのエンジニアとしてのキャリアを左右するだろう。