AI時代のドキュメント規約 — 先頭にパスを書くだけ

正典ファイル1枚でAIに文脈を渡すという運用を紹介しましたが、今回はもっと小さな規約の話です。すべてのMarkdownドキュメントの1行目に、そのファイル自身のパスを書くというだけのルールですが、AIと一緒に何十本もの文書を扱う運用では、これが地味に効いています。

ファイルを渡しても、AIは「どこにあるか」を知らない

AIチャットに文書の中身を貼り付けたり、ファイルを読み込ませたりすると、AIはその内容は理解できますが、そのファイルがリポジトリのどこに置かれているかまでは、明示しない限り分かりません。1回のセッション内なら操作履歴から推測できることもありますが、セッションが変わったり、別のAIツールに引き継いだりすると、この文脈は毎回消えてしまいます。

これは些細な問題に見えて、「このファイルをこのパスに書き込んで」「あの文書の隣にある画像を使って」といった指示のたびに、パスを説明し直すコストとして積み重なっていきます。

規約はシンプル — 1行目に相対パスを書くだけ

Geoエコシステムの運用で採用している規約は、次のとおりです。

> パス: 次期アプリ/blogアイデア/02_blog_head.md

このように、ドキュメントの1行目に「> パス: 〈リポジトリルートからの相対パス〉」という1行を書くだけです。リポジトリルートは各リポの直下（GeoConverterPro・GeoMediaHubなど）を基点にします。パス行の下に、通常どおり見出し（H1）以降の本文を続けます。

実際の運用ドキュメントの冒頭は、たとえばこのようになっています。

> パス: 0-doc/media-registry.md

# media-registry — 宣伝部（GeoMediaHub）メディア運用の正典

ファイルを開いた瞬間に、その1行を見るだけで「これはGeoMediaHubリポの0-doc配下にあるファイルだ」と分かります。人間にとっても、AIにとっても同じです。

対象は「ドキュメント」に限定する

この規約を全ファイルに機械的に適用しているわけではありません。対象と対象外は明確に分けています。

ブログ記事を対象外にしているのは、「パスを書く効果がない」からではなく、記事の本文としての体裁を優先しているためです。パス管理が必要な内部ドキュメントと、読者に届く完成品としてのブログ記事とでは、求められる形が違います。

導入コストはほぼゼロ、効果は積み重なる

この規約の良いところは、導入コストがほぼゼロであることです。

• 新規作成時：最初の1行に書くだけ
• 既存ドキュメントの編集時：編集のついでに付け足すだけ
• ツール側の対応：不要（ただのテキストの1行なので、既存のMarkdownパーサやビューアに影響しない）

一方で効果は、ドキュメントの本数が増えるほど、AIとのセッションが増えるほど積み重なっていきます。「このファイルどこだっけ」という往復のやり取りが1回減るだけでも、地味に作業テンポが良くなります。

「小さな規約」がAI協働の摩擦を減らす

この規約自体は目新しいものではなく、C言語のヘッダファイルにファイル名コメントを書く慣習や、企業文書のヘッダーに文書番号を振る慣習と発想は同じです。ただ、AIと一緒にドキュメントを大量に生成・編集する運用では、この種の「小さな規約」の価値が相対的に上がっている、というのが実感です。人間だけで文書を管理していた頃は気にならなかった摩擦が、AIとのやり取りが増えることで急に目立つようになる、というのは日本語フォルダ名のNFD正規化の罠にも通じる話です。

まとめ

• 運用ドキュメントの1行目に「> パス: 〈相対パス〉」を書く規約を採用している
• 対象はドキュメント（.md）のみで、ブログ記事やデータファイルは体裁を優先して対象外にしている
• 導入コストはほぼゼロで、AIとのセッションが増えるほど「場所の説明コスト」の削減効果が積み重なる
• AIと大量の文書をやり取りする運用では、こうした小さな規約の価値が相対的に上がる

関連記事

• 正典ファイル1枚でAIに文脈を渡す — レジストリ方式のドキュメント運用（GeoPrism JP）
• 日本語フォルダ名の罠 — NFD正規化でツールがパスを見失う（GeoPrism JP）
• 進捗.mdで制作ログを残す — AI協働時代の作業記録術（連載㉒・GeoConverterPro）
• 共同開発リポと個人リポを分ける — 次期アプリ用リポジトリ新設の判断（GeoDiveExa）

開発者より: アプリ・Kindle本・オープンソースの一覧は GitHub: amru195704 にまとめています。

お願い
本記事の情報は参考目的で掲載しており、正確性・完全性を保証するものではありません。誤記・不正確な情報がございましたら、コメント欄よりご指摘いただければ、確認のうえ修正いたします。

アプリを入手（App Store）：GeoConverterPro（座標変換）　｜　GeoPrism JP（測地系の可視化・学習）