ファイル名の連番をやめた理由 — ドキュメント設計における「黙って別の文書を指す」事故

1. 導入：連番ファイル名が生む「サイレントな参照事故」

結論から言うと、ドキュメントのファイル名に連番（例：01_xxx.md）を付ける運用は、いますぐやめるべきです。

設計文書や仕様書をフォルダ内で整理する際、表示順を整える目的でファイル名の先頭に連番を振る運用は、多くのプロジェクトで採用されています。たしかに、人間がディレクトリを眺める分には、順序が明確で分かりやすいというメリットがあります。

しかし、プロダクトが成長し、ドキュメントの再編成や追加・削除が必要になったとき、この連番管理が深刻な問題を引き起こします。番号を振り直すたびに、古いファイルパスを参照していたリンクが静かに壊れていくからです。

特に現代の開発環境では、Claude Codeのような自走型AIコーディングエージェントが、リポジトリ内のMarkdownドキュメント（Docs as Code）を直接読み書きして実装を進めるスタイルが定着しつつあります。もしAIが参照しているドキュメントのリンク先が、「エラーを出さずに、黙って別の文書を指す」状態になっていたらどうなるでしょうか。AIは誤った仕様を真実だと信じ込み、誤った実装を生成し続けてしまいます。

本記事では、連番ファイル名が引き起こす「サイレントな参照事故」のメカニズムを明らかにし、このトラブルを未然に防ぐための「ベース名参照への移行」と「CIを用いた自動検査（リント機構）」の手順を具体的に解説します。ドキュメントの参照ズレによるバグや、AIのハルシネーション（幻覚）に悩まされている方の参考になれば幸いです。

2. 事故の再現：なぜ「黙って別の文書を指す」のか

実際にどのような事故が起きるのか、具体例を交えて説明します。

複数のドキュメント間でリンクを張る際、例えば docs/06-api-design.md の第1節（§1）を参照するために、ソースコードのコメントや他の仕様書内で以下のように略記や相対パスが指定されることがあります。

<!-- 他のドキュメントからの参照例 -->
詳細は [API設計（06）の第1節](docs/06-api-design.md#1) を参照してください。

<!-- あるいは、人間向けの短いメモ書き -->
※ docs/06 §1 の仕様に準拠する

ここで、プロジェクトの要件が変わり、API設計の前に「認証フローの設計書」を差し込む必要が生じたとしましょう。ドキュメントの順序を整理するため、新しく 06-auth-flow.md というファイルを配置し、元々あった 06-api-design.md を 07-api-design.md へとリネーム（番号を1つ後ろにずらす）しました。

この瞬間、恐ろしい事故が発生します。

以前書かれた docs/06 §1 という参照や、単純な 06 から始まるファイル名へのパス指定は、エラーになることなく、新しく配置された 06-auth-flow.md の第1節を指すように変わってしまうのです。

ファイル名や番号に基づく参照は、対象が移動したことによって「存在しない場所（404）」を指すのではなく、「たまたまそこに新しく置かれた別のドキュメント」を指すようになります。これが、ドキュメント参照が「黙って別の文書を指す」サイレント事故の正体です。

3. なぜ気づけないか：リンク切れ検査をすり抜ける理由

「ファイルのパスやアンカーが変わったのなら、リンク切れ検知ツールで気づけるのではないか？」と思われるかもしれません。

一般的な Docs as Code の運用では、markdown-link-check などのCIツールを導入し、プルリクエストの段階でリンク切れ（HTTP 404 やファイルの未存在）を自動検知する仕組みを構築しています。

しかし、このサイレント事故はCIのリンクチェッカーを完全にすり抜けます。

なぜなら、リンク先のファイル（新しく配置された 06-auth-flow.md）は実在しており、多くの場合、そのファイルの中にも §1 や #1 などの適当な見出し（アンカー）が存在するからです。チェッカーから見れば「ファイルもアンカーも存在するため、正常なリンクである」と判定されてしまいます。

人間の目視レビューでも気づくのは困難です。リンク先のドキュメントをクリックしたとき、そこには体裁の整った仕様書が表示されます。忙しいレビューの最中に、「リンク先が本来意図していた文書と違う」という文脈の違和感に気づくのは至難の業です。

実際に、私たちのプロジェクトのリポジトリでドキュメントの不整合について検証・実測を行いました。その結果、検出された文書不整合のうち、実に約45%が「実パスの直書きが移動（連番のズレ等）によって壊れた」ものであることが判明しました。

つまり、ドキュメントのバグの約半分は、リンク切れツールでは検知できない「サイレントフォールト」だったのです。

4. 対策：連番を捨て、ベース名参照へ移行する

この問題の根本原因は、「連番」という本来は物理的な配置順序（プレゼンテーション層）にすぎないものを、文書を特定するための論理的ID（識別子）として参照してしまっていることにあります。

恒久的な解決策は、ファイル名から連番を完全に排除し、ベース名（論理識別子）での参照に移行することです。具体的な移行ステップを解説します。

連番プレフィックスの廃止

まず、ドキュメントのファイル名から 01_ や 06- といった連番プレフィックスを削除します。 先ほどの例であれば、06-api-design.md は単に api-design.md と変更します。

実際の私たちのプロジェクトでも、この方針に従ってリファクタリングを実施しました。 （コミット例: e8b3fe1 — 文書の名前から番号を外し、参照が番号のズレで壊れないように修正）

名前から番号を外すことで、ファイルがディレクトリ内でどのように並び替えられても、ファイルそのものの名前（識別子）が変わることはなくなり、移動に強い構造になります。

参照ルールの統一

次に、ドキュメント間のリンクは、相対パスや絶対パスの直書きではなく、ファイル名（ベース名）のみで解決する仕組みを導入します。

例えば、Obsidianや一部のMarkdownパーサーで広く使われているWikiリンク記法（[[api-design]]）などのベース名参照ルールを採用します。これにより、「どのフォルダに置かれているか」というパス情報に依存せず、「api-design という名前のドキュメント」を直接指し示すことが可能になります。

フォルダ間の大掛かりな再編成を行っても、ベース名が変わらなければ参照は一切壊れません。

コードからの参照方法

ソースコード内のコメントから設計書を参照する場合も、実パスを書くのは避けるべきです。ファイルパスが変わった際に、コード内のコメントまで追従して修正するのは非現実的だからです。

代わりに、「対象ドキュメントの特定の節名」や「システム内で一意なシンボル名」を使ってアンカーを打つようにします。

// ❌ 悪い例: 実パスと行番号や連番に依存している
// 詳細は docs/06-api-design.md の §1 を参照

// ⭕ 良い例: ベース名と論理的なアンカー名に依存している
// 詳細は設計書 [[api-design]] の「認証トークンの有効期限仕様」を参照

これにより、ドキュメント側でファイル名や見出しの階層が多少変わっても、検索（grep）によって容易に追跡可能になり、参照がサイレントに壊れるのを防ぐことができます。

5. 運用：CIによる実パス直書き防止ガードレール

ルールを定めてドキュメントを修正しても、人間の注意力やAIの推論に頼っていては、いずれ同じ事故が再発します。

特に、Claude Code などの AIコーディングエージェントは、リポジトリ内の既存の文脈から学習し、良かれと思って実パスや相対パスを直書きしてしまう傾向があります。

私たちが実際に遭遇したケースとして、AIに対して次のようなプロンプト（要約）を与えたことがありました。

「最終的な設計書のフォルダとファイルはどういう構造になりますか？最適にするためにかなり変更してもOK」

この指示を受けたAIは、ドキュメント構成を最適化する過程で、新旧のパスを混同して出力し、別のドキュメント内に誤った相対パスのリンクを埋め込んでしまいました。AIは「ファイルが存在するかどうか」までは推論できても、「移動後の正しいパスがどれか」を厳密にトラッキングしきれないことがあるのです。

そのため、人間の目やAIの出力に依存しない強制的なガードレールが必要です。

具体的には、CI環境（GitHub Actionsなど）に検査スクリプトを組み込みます。 ドキュメント内やソースコードのコメント内に、docs/ から始まる相対パスや実パスの直書き（例：[API設計](../docs/06-api-design.md)）を正規表現で検知し、発見した場合は即座にLinterとしてFail（エラー）させる自動化を行います。

# 例: パス直書きを検知する簡易的なスクリプトのイメージ
if grep -rE "\]\(\.?\.?/docs/" ./src ./docs; then
  echo "Error: ドキュメントへの実パス直書きが検出されました。ベース名参照を使用してください。"
  exit 1
fi

これにより、「404にならない誤参照」を生む余地そのものを物理的に排除し、AIが誤ったパスを記述してもPRのマージをブロックすることができます。

6. まとめ：リファクタリング耐性のあるドキュメント設計を

ドキュメントの連番管理は、一見すると整理されているように見えますが、変更が加わった瞬間に「静かな参照破壊」を引き起こす時限爆弾となります。

特にAIを用いた開発時代において、ドキュメントの「機械可読性」と「リファクタリング耐性」は、開発速度とプロダクト品質を直接左右する重要なインフラです。AIが誤った仕様書を参照してしまえば、生み出されるコードもまた誤ったものになります。

ファイル名の連番管理をやめ、ベース名参照へと移行し、CIによる厳密なガードレールを導入することで、初めて私たちは「安心してコードとドキュメントを共にリファクタリングできる環境」を手に入れることができます。

壊れないドキュメント基盤の設計や、AIエージェントに最適化された Docs as Code の導入については、ぜひグランドリームにご相談ください。確かな知見と実測データに基づき、持続可能な開発体制の構築をサポートいたします。