AIが書いたドキュメントは「実パス直書き」で腐る — 参照構造を変えたら不整合検出が45%減った

AIエージェントの開発をご検討中ですか？ AIエージェント開発サービスを見る →

AI駆動開発において、Claude CodeやCursorなどにドキュメントを生成・更新させる運用は今や一般的です。しかし、「AIがもっともらしい嘘のファイルパスを書く」「ファイルの移動で大量のリンク切れが発生する」といったドキュメントの「腐敗」に悩まされていませんか。

結論からお伝えすると、AIが書いたドキュメントの不整合が減らない根本原因は「実パスの直書き」にあります。これを防ぐには、プロンプトを工夫するのではなく、ドキュメントの参照構造そのものを変え、CI（継続的インテグレーション）による機械検査を導入する必要があります。

本記事では、私たちの開発現場で実際に起きた54件の不整合データを分析し、実パス直書きを3箇所に絞り込む参照アーキテクチャの導入により、不整合を45%削減した実例を公開します。

1. レビューを5回ループさせても不整合が消えない — 検出54件の現実

「合格するまで直して」プロンプトの限界

AIに仕様書をメンテナンスさせる際、多くの開発チームが「ズレがないかレビューし、合格するまで修正を繰り返して」といったプロンプトを使用しています。私たちも当初はこの方法に頼っていました。

しかし、このアプローチには明確な限界があります。AIが自律的に修正ループを回しても、ある箇所を直せば別の箇所が壊れる、いわゆる「モグラ叩き」状態に陥るのです。結果として、最終的には人間が目視でドキュメントの整合性を確認しなければならず、AIの本来のスピード感を活かせない状況が続いていました。

不整合54件の内訳：なぜAIはリンクを壊し続けるのか

現状を打破するため、私たちはリポジトリ内のドキュメントで発生した不整合54件を抽出・分析しました。その結果、AIがドキュメントを壊し続ける理由が明確になりました。

不整合の内訳を見ると、単なる文脈の誤解や記述漏れよりも、「他のドキュメントへのリンク切れ」や「存在しないファイルへの参照」が圧倒的多数を占めていました。AIはプロジェクトの全体構造を常に完璧に把握しているわけではなく、コンテキストウィンドウの制限やファイル構成の変更によって、容易に幻覚（ハルシネーション）を引き起こし、無効なパスを生成してしまうのです。

2. 根本原因は「実パス直書き」による密結合だった

45%を占めた「他文書の実パス直書き」問題

54件の不整合をさらに詳細に分類すると、全体の45%（約24件）が「ドキュメントが他のドキュメントの実パス（例：../docs/api/user-service.md）を直書きしている」ことに起因していました。

Markdownファイル間で相対パスや絶対パスをハードコードする従来の手法（Docs as Codeの標準的な記法）は、人間が手動で管理する分には機能します。しかし、AIが高速かつ大量にファイルを生成・リファクタリングする現代の開発スタイルでは、このパスの直書きが致命的な弱点となります。

ファイル移動やリファクタリングで連鎖崩壊するドキュメント網

実パスを直書きしていると、ドキュメント同士が「密結合」な状態になります。例えば、ディレクトリ構造を見直して user-service.md を別のフォルダに移動した瞬間、それを参照していたすべてのドキュメントのリンクが破壊されます。AIは移動されたファイルの新しいパスを全ての参照元に正確に反映させることが苦手なため、リファクタリングのたびに連鎖的な崩壊が発生していました。

これはプロンプトの改善で解決する問題ではなく、ドキュメントの「参照アーキテクチャ」という構造的欠陥そのものだったのです。

3. 解決策：実パス直書きを「3箇所」に限定する参照アーキテクチャ

実パスを許す3箇所の境界線（README / CLAUDE.md / ビルドスクリプト）

この密結合を解消するため、私たちは「ドキュメント内に他のドキュメントの実パスを直書きしてはいけない」という強力なルールを設けました。具体的には、実パスの直書きを許容する場所を以下の3箇所のみに限定しました。

README.md: プロジェクトのエントリポイントとしての役割上、主要なドキュメント群へのリンク（実パス）を記載する。
CLAUDE.md（またはAIへの指示書）: AIがリポジトリの構造を理解するためのSSoT（Single Source of Truth）表として実パスを定義する。
ビルドスクリプト / CI設定ファイル: ドキュメントをビルド・検査するためのスクリプト群。

これ以外の一般の仕様書や設計ドキュメントでは、いかなる場合も実パスによるリンクを禁止しました。

文書間は論理参照 `[[ドキュメント名]]`、コードからは「節番号」で結合を疎にする

実パスを禁止した代わりに、ドキュメント間の参照には論理参照（Wikiリンク形式の [[ドキュメント名]]）を採用しました。例えば、「ユーザー認証仕様」を参照したい場合、[ユーザー認証仕様](../auth/user-auth.md) と書くのではなく、[[UserAuthSpec]] のように識別子のみを記述します。

また、ソースコードのコメントからドキュメントを参照する場合は、ファイルパスではなくドキュメント内の「節番号（セクションID）」や不変の識別子を使用します。これにより、ドキュメントのファイル名やディレクトリ構造が変更されても、論理的な参照関係は壊れない「疎結合」なドキュメント網が完成しました。

4. 正本の二重化を防ぐ「SSoT表」の運用ルール

「正本がコードにあるもの」と「正本が文書にあるもの」の完全分離

AIがドキュメントを更新する際にもう一つ起きがちな問題が、「コードとドキュメントの二重管理（正本の喪失）」です。これを防ぐため、プロジェクトのルートに配置する CLAUDE.md 内に「SSoT表」を作成し、何がどこに定義されているか（正本はどれか）をAIに対して明確に指示します。

CLAUDE.md の SSoT表の例：

# ドキュメントの正本（SSoT）管理表

以下の情報の正本はそれぞれのファイルに存在します。情報を更新する際は必ず正本を変更し、他の場所に二重定義してはいけません。

| 情報の種類 | 正本の場所 (実パス) | 備考 |
| :--- | :--- | :--- |
| データベーススキーマ | `src/db/schema.prisma` | ドキュメントにはスキーマを直接書かず、このファイルを参照すること |
| 外部APIの仕様 | `docs/api-specs.md` | API連携の実装時はこのドキュメントを正とすること |
| ビジネスルール（割引計算など）| `docs/domain/business-rules.md` | コード上のマジックナンバーはこの文書の要件に従う |

腐る数値（定数・スキーマ・設定値）をドキュメントに生書きしない

SSoT表の運用で最も重要なのは、「腐る数値」をドキュメントに生書きしないことです。例えば、タイムアウトの秒数や文字数制限などの定数をMarkdown内に直接書き込むと、コード側の変更時に高確率でドキュメントが取り残されます。こうした数値は「正本がコードにあるもの」として扱い、ドキュメント側では「詳細は src/config/constants.ts を参照」とだけ記述するルールを徹底しました。

5. 読み直しをやめ、`check-docs.mjs` でCI機械検査へ

人間もAIも信用しない：リンク切れと参照規則を静的解析する

参照ルールを定めても、人間の目視確認やAIの自己チェックに依存している限り、ミスは必ずすり抜けます。そこで私たちは、ドキュメントの静的解析を行うスクリプト check-docs.mjs を作成し、目視レビューを完全に廃止しました。

このスクリプトは、以下の点を機械的に検証します。

[[ドキュメント名]] という論理参照が、実際に存在するドキュメント（SSoT表などで定義されたエイリアス）と紐づいているか。
許可された3箇所以外のファイルに、不正な実パスの直書き（../ などを含むリンク）が存在しないか。

CIで弾くことで「AIが壊した瞬間に検知できる」開発サイクル

作成した check-docs.mjs は、GitHub ActionsなどのCIパイプラインに組み込みます。PRが作成されたタイミングで自動実行されるため、AI（あるいは人間）がドキュメントの参照構造を壊すような変更を行った場合、即座にCIがエラーを吐いてマージをブロックします。

これにより、「AIにコードとドキュメントを書かせる → PRを作成する → CIが検証する → エラーがあればAIに修正させる」という、人間を介在させない自律的な品質保証ループが実現しました。

6. 導入後の成果：`[[名前]]` 参照の破壊はゼロ、レビュー工数の劇的削減

不整合検出45%減・論理参照破損0件のインパクト

この「参照アーキテクチャの変更」と「CIによる機械検査」を導入した結果、劇的な改善が見られました。ファイル移動やリファクタリングを行っても、[[名前]] による論理参照は1件も壊れることがなくなり、これまで全体の45%を占めていた実パス起因の不整合は完全に消滅しました。

また、不整合の検出自体がCIに任されるようになったため、人間が「リンクが正しいか」「正本とズレていないか」をチェックするレビュー工数はほぼゼロになりました。

AI時代のドキュメント運用の結論と今後の展望

AI駆動開発におけるドキュメント管理の結論は、「プロンプトでAIの振る舞いを制御しようとするのではなく、AIがミスをしても壊れない構造（アーキテクチャ）を作り、機械的に検証する」ことに尽きます。

「実パス直書きの禁止」「論理参照の活用」「SSoT表による正本の分離」、そして「CIによる静的解析」。これらを組み合わせることで、AIの圧倒的なスピードを安全に享受できるドキュメント基盤が構築できます。AIにドキュメントを書かせて運用が辛くなってきたチームは、ぜひ参照構造の再設計に踏み切ってみてください。

CTAエリア AI時代のドキュメント設計・開発体制づくりはグランドリームにご相談ください。（関連サービスURL: /development）