同じ開発ルールが、3か所にありました。repoのREADMEと、AI向けの指示ファイルと、Obsidianのメモです。それぞれ、少しずつ書き方が違います。どれも書いた時点では間違っていませんでした。困ったのは、いまどれが有効なのか分からないことです。更新日も見比べてみたんですが、それだけでは決められませんでした。
AIを使って複数のアプリを開発していると、この「どれが最新か探す時間」がじわじわ効いてきます。ドキュメント管理の問題だと思って、最初は保存場所ばかり考えていました。ただ、実際に大事だったのは場所ではなく、「どれを正本にするか」のほうでした。
そこで行き着いたのが、Obsidianはプロジェクト横断のハブ、各repoは実装の正本という役割分担です。この分け方にしてから、AIが最初に読む入口と、いま有効なルールと、過去の議論が混ざりにくくなりました。コードと一緒に変わる仕様はrepo側にあるので、古いメモをもとに実装してしまう事故も減らせます。
正本の置き場所は情報の種類で決まる
API仕様、DB構造、テスト、デプロイ手順の正本はrepo。Obsidianに置くのは、プロジェクト索引、横断ルール、意思決定、ログ。AIには索引と現行ルールから読ませ、理由が必要になったときだけ過去ログへ戻る。
全部Obsidianへ集めて起きたこと
白状すると、最初は「Obsidianへ集めれば、人もAIも迷わなくなる」と思っていました。実際、便利ではあるんです。会話ログも設計メモもタスクもAI向け指示も、1か所で検索できます。ここまでは期待どおりでした。
ずれが出たのは、repoにある実装仕様までObsidianへコピーしてからです。
- コードを変更しても、Obsidian側の仕様が更新されない
- 同じルールが、複数のrepoとObsidianに重複する
- 作業ログに書いた仮説を、AIが確定事項として読む
- 別プロジェクトの、似た名前のメモを参照してしまう
- READMEが長くなり、いまの方針を見つけにくくなる
どれか1つでも起きると、結局は冒頭の「どれが最新か」に戻ってきます。情報が1か所にあるだけでは、「どこを直せば更新完了か」が決まりません。必要だったのは集約ではなく、情報の種類ごとに正本を1つ決めることでした。
分け方の基準は「コードと一緒に変わるか」
で、残る問題は、その正本をどう決めるかです。私が使っている基準は、拍子抜けするほどシンプルです。
AIが実行に使う情報はrepoへ
AIがその情報を見てコードを書いたり、テストしたり、デプロイしたりするなら、正本はrepoに置きます。複数のプロジェクトにまたがる判断や、コードが消えても残したい経緯は、Obsidianが正本です。
| 情報 | 正本 | 理由 |
|---|---|---|
| API仕様、DB構造、実行コマンド | repo | コードと同じ変更単位でレビューできる |
| テスト条件、デプロイ手順 | repo | 実行するAIが必ず参照する |
| プロジェクト横断ルール | Obsidian | 特定repoだけに属さない |
| 意思決定と理由 | Obsidian | 会話や経緯を横断して残せる |
| 日次ログ、ブレスト | Obsidian | 未確定の材料として蓄積できる |
| AI向けローカル指示 | repo | 作業開始時に確実に読ませやすい |
迷うのは、Obsidianとrepoの両方に同じ内容が必要になる場面です。そこは無理に重複をなくさず、どちらが正本かを明記したうえで、コピーする範囲を必要最小限にとどめます。
AIに読ませる順番は索引が先、ログが最後
役割を分けただけでは、まだ足りませんでした。AIが毎回すべてのログを読みにいくと、過去の案と現在のルールが同じ重さで扱われてしまうからです。なので、読む順番そのものを固定しました。
- プロジェクト索引で、対象repoと現在の状態を特定する
- AI向けガイドで、読む順番と禁止事項を確認する
- 現行ルールで、いま守る内容を確認する
- 決定事項で、理由と未決事項を確認する
- 根拠が必要なときだけ、サマリーやログまでさかのぼる
- 実装前に、repoのコードとローカル指示を最終確認する
ログを読ませないわけではありません。最初からは読ませない、というだけです。AIはいま有効な短いルールから作業を始めて、判断の理由が要る場面になったら、そこで初めて過去の議論へ戻ります。
1つの文書に2つの仕事をさせない
参照順を決めると、今度は各文書の中身が問われます。READMEに長い設計議論が混ざっていたら、順番を決めた意味が薄れてしまいます。だから、プロジェクトごとの文書は役割で切っています。ファイル名は環境に合わせて変えて構いません。ただ、いま有効な仕様と過去の長い議論だけは、同じ文書へ入れないようにしています。
| 文書 | 置く内容 | 置かない内容 |
|---|---|---|
| README | 概要、状態、ナビ | 長い設計議論 |
| AIガイド | 参照順、開始時チェック、禁止事項 | 実装仕様の複製 |
| ルール | 現在有効な確定事項 | 過去の経緯 |
| 決定事項 | 決定、理由、参照ログ、未決 | 日々の細かな作業記録 |
こう分けておくと、冒頭のように同じルールがREADMEにもAI向け指示にも書かれている状態が、そもそも作られにくくなります。
未確定の情報しかないプロジェクトには、空のルール文書も作りません。空ファイルが1つあるだけだと、「確認した結果、ルールがなかった」のか「まだ何も調べていない」のか、あとから見分けがつかないからです。
雑なログが現行ルールに育つまで
一方で、Obsidian側の書き方はゆるくしています。日次ログや会話には、未確定の案も、失敗も、判断した理由も、そのまま残します。整えるのはあとです。何度も使うと分かったものだけを、順番にルールへ上げていきます。
日次ログ・議論
↓
定期サマリー
↓
決定事項（決定・理由・参照元）
↓
現行ルール
↓
repoへ反映する作業指示
↓
repoのコード・docs・AI向け指示方針が変わったときも、ログを消して過去を書き換えることはしません。変更した理由を決定事項に残して、直すのは現行ルールだけにします。こうしておくと、AIが普段読む文書は短いまま、判断の出どころはいつでもたどれます。
repo側にも置くObsidianへの入口
ここまで整えても、穴が1つ残ります。Obsidian側にどれだけ正しいルールがあっても、AIがそのvaultを毎回読めるとは限らないんです。別のPCやツール、CI環境では、そもそもObsidianの場所が分かりません。
そこで、repo内のAI向け指示にも、Obsidianへの参照先をセットで置いています。
- 横断ハブの参照先
- 文書の優先順位
- 作業開始時のgit確認
- 破壊的操作や本番反映の禁止事項
- そのrepo固有のテスト・デプロイ手順
たとえばWordPress運営をAIに手伝ってもらったときは、接続先と反映手順をrepo側に置きました。もしハブとrepoの内容が食い違ったら、実装に近いrepoを優先します。ハブ側の古い記述は、あとから直せば済みます。
始めるなら索引と共通ルールから
「そこまでの仕組みが必要なのか」と思われたかもしれません。最初から全部は必要ありません。いきなり大きなvaultを作らなくても、複数の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/まずは索引で対象repoを示し、共通ルールへ複数プロジェクトで使う方針を置き、決定事項に理由を残します。サマリーは、ログが増えて探しにくくなってから足せば十分です。判断の軸は分類の細かさではなく、AIがいまの方針と実装の正本へ迷わずたどり着けるかどうかに置いています。
この仕組みで管理している個人開発プロダクトは、pgsideworksにまとめています。
最初に困っていたのは、3か所に散らばったルールを前に、更新日を見比べていた時間でした。いまは同じ場面が来ても、見比べる必要がありません。実装に使う情報ならrepoが正本、横断の判断と経緯ならObsidianが正本と、先に決まっているからです。文書を増やすより先に決めるのは、この1行です。私のハブづくりは、そこから始まりました。
