ObsidianでAI開発のドキュメントを管理する｜複数repoの設計

AIと複数のアプリを開発していると、コードを書く時間より「どの文書が最新なのか」を確認する時間が増えてきます。README、会話ログ、設計メモ、タスク、AI向け指示が別々に増え、同じ内容が少しずつ違う状態になりました。

そこで、Obsidianをすべての正本にするのではなく、Obsidianはプロジェクト横断のハブ、各repoは実装の正本と役割を分けました。

AIとWordPressテーマを自作したときは1つのrepoだけ見れば足りました。その後、Webサービスやモバイルアプリが増えたことで、AIが最初に読む入口と、ログを確定ルールへ昇格する流れが必要になりました。

1か所へ集めるだけでは解決しなかった

最初は「情報をObsidianへ集めれば、AIも人も迷わない」と考えていました。でも、実装仕様まで複製すると別の問題が起きます。

• コードを変更してもObsidian側の仕様が更新されない
• 同じルールが複数repoとObsidianに重複する
• 作業ログに書いた仮説を、AIが確定事項として読む
• 別プロジェクトの似た名前のメモを参照する
• READMEが長くなり、現在の方針へたどり着けない

情報の置き場所を1つにするより、情報の種類ごとに正本を1つ決める方が重要でした。

repoとObsidianの役割を分ける

私が使っている判定基準はシンプルです。

情報	正本	理由
API仕様、DB構造、実行コマンド	repo	コードと同じ変更単位でレビューできる
テスト条件、デプロイ手順	repo	実行するAIが必ず参照する
プロジェクト横断ルール	Obsidian	特定repoだけに属さない
意思決定と理由	Obsidian	会話や経緯を横断して残せる
日次ログ、ブレスト	Obsidian	未確定の材料として蓄積できる
AI向けローカル指示	repo	作業開始時に確実に読ませやすい

AIの入口を1つにする

フォルダを整理しても、AIが毎回すべてのログを読むと時間がかかり、過去の案へ引っ張られます。そこで、参照順を固定しました。

1. プロジェクト索引で、対象repoと現在の状態を特定する
2. AI向けガイドで、読む順番と禁止事項を確認する
3. 現行ルールで、いま守る内容を確認する
4. 決定事項で、理由と未決事項を確認する
5. 必要な根拠があるときだけ、サマリーやログへ降りる
6. 実装前にrepoのコードとローカル指示を最終確認する

ポイントは、ログを検索対象にはしても、最初の入口にはしないことです。最新の方針と過去の検討を分けるだけで、AIが撤回済みの案を採用しにくくなります。

文書ごとの責務を小さくする

プロジェクトごとに、次の4種類へ役割を分けています。ファイル名は環境に合わせて変えても、責務を混ぜないことが大切です。

文書	置く内容	置かない内容
README	概要、状態、ナビ	長い設計議論
AIガイド	参照順、開始時チェック、禁止事項	実装仕様の複製
ルール	現在有効な確定事項	過去の経緯
決定事項	決定、理由、参照ログ、未決	日々の細かな作業記録

未確定の情報しかないプロジェクトには、空のルール文書を作らないようにしました。空ファイルがあると、「確認済みだがルールなし」なのか「まだ調べていない」のか区別できないためです。

ログを確定ルールへ昇格する

Obsidianの価値は、きれいな文書を最初から書くことではありません。雑なログを残し、あとから再利用できる形へ昇格できることです。

日次ログ・議論
  ↓
定期サマリー
  ↓
決定事項（決定・理由・参照元）
  ↓
現行ルール
  ↓
repoへ反映する作業指示
  ↓
repoのコード・docs・AI向け指示

この流れにすると、会話ログを消さずに残しながら、AIが普段読む文書は短く保てます。方針が変わったときは、決定事項に撤回や変更理由を残し、現行ルールだけを更新します。

repo側にも入口の写しを置く

Obsidian側に正しいルールがあっても、AIがそのvaultを毎回読めるとは限りません。別PC、別ツール、CI環境では、Obsidianの場所を知らないこともあります。

そのため、新しいrepoで作業を始めるときは、repo内のAI向け指示へ次の内容を置きます。

• 横断ハブの参照先
• 文書の優先順位
• 作業開始時のgit確認
• 破壊的操作や本番反映の禁止事項
• そのrepo固有のテスト・デプロイ手順

横断ルールの正本はObsidianでも、実行に必要な最小限の写しはrepoへ持たせます。AIにWordPress運用を手伝わせる作業のように本番操作を含む場合は、接続先や反映手順をrepo側で確実に読ませます。内容が競合した場合は、実装に近いrepo側を優先し、ハブの古さをあとで修正します。

最小構成から始める

最初から大きなvaultを作る必要はありません。3つのrepoを超え、同じ判断や指示を何度も説明するようになったら、次の構成で十分です。

knowledge-hub/
  project-index.md
  shared-rules/
  projects/
    project-a/
      ai-guide.md
      rules.md
      decisions.md
      logs/

project-a-repo/
  AGENTS.md
  README.md
  docs/
  src/

まず索引、共通ルール、各プロジェクトの決定事項だけを作り、ログが増えたらサマリーを追加します。分類そのものを目的にせず、AIが正しいrepoと現在方針へ早く到達できるかで判断します。

まとめ：知識の保管場所と実行の正本を分ける

Obsidianへ情報を集めるだけでは、AI開発の迷いはなくなりません。コードと一緒に変わる情報はrepoへ、複数プロジェクトをまたぐ判断と経緯はObsidianへ置くことで、更新責任が明確になります。

この運用で管理している個人開発プロダクトは、pgsideworksにまとめています。