組織知を repo として運用するための Obsidian vault 設計

yoshida
公開日：2026年8月12日
カテゴリー：Tech
タグ：#Obsidian

はじめに

Obsidian は個人の note taking tool として使われることが多いですが、directory structure と運用ルールを整えると、チームの knowledge base としても扱いやすくなります。

この記事では、Obsidian vault を Git repository として管理し、人間と AI agent の両方が読める shared context repo として運用するための設計を紹介します。具体的には、

00_inbox/, 10_projects/, 20_runbooks/, 30_decisions/ のように情報の置き場を分けます
frontmatter で信頼度と公開範囲を明示します
AGENTS.md で AI agent の読み順と安全ルールを固定します

最初から完璧な knowledge management system を作る必要はありません。まずは雑多なメモを inbox に受け止め、必要なものを project context, runbook, decision, reference へ少しずつ昇格させる流れを作ることが重要です。

解決したかった課題

チームの情報は、放っておくといろいろな場所に散らばります。Slack の会話、ticket のコメント、meeting note、個人の local memo、運用時にその場で調べた command などです。

人間だけで読んでいるうちは、それでもなんとかなることがあります。ただ、AI agent に作業を頼むようになると問題がはっきりします。どの note が現在の正しい状態なのか、どの情報は古いのか、どの情報は読ませてよいのかを、毎回説明しなければならないからです。

特に困るのは次のような状態です。

「現在の状態」と「過去の議論」が同じ場所にある
手順書、設計判断、調査メモ、作業ログが混ざっている
private な note と shared knowledge の境界が曖昧
AI agent が最初に読むべき entry point がない
古い情報を間違って current state として扱ってしまう

そこで、Obsidian の柔軟さを残しつつ、repository としての構造を持たせることにしました。

基本設計: vault を knowledge base repo として扱う

設計方針はシンプルです。

未整理の情報は 00_inbox/ に置く
project の現在状態は 10_projects/<project>/context.md に寄せる
繰り返す作業は 20_runbooks/ に置く
方針決定や設計判断は 30_decisions/ に置く
安定した調査結果や外部資料は 40_references/ に置く
AI agent に読ませない情報は 80_private/ に分ける

これにより、「この情報はどこに置くべきか」「どの note を信頼すべきか」「AI agent にどこまで読ませてよいか」を判断しやすくなります。

実際の top-level directory は次のような形です。

Plain text

.
├── index.md
├── AGENTS.md
├── 00_inbox/
│   └── index.md
├── 05_org/
│   ├── index.md
│   ├── ai-agent-context.md
│   ├── glossary.md
│   └── systems.md
├── 10_projects/
│   ├── index.md
│   └── <project>/
│       ├── index.md
│       ├── context.md
│       ├── decisions.md
│       └── sources/
├── 20_runbooks/
│   └── index.md
├── 30_decisions/
│   └── index.md
├── 40_references/
│   └── index.md
├── 80_private/
├── 90_archive/
└── _templates/
    └── inbox-memo.md

index.md は vault 全体の入口です。人間が読むときも AI agent が読むときも、まずここから辿れるようにします。

05_org/ には organization-wide な context を置きます。たとえば glossary, systems inventory, AI agent 向けの共通 context です。project に閉じない前提はここに集めます。

10_projects/ は project ごとの workspace です。project の概要は index.md、現在状態や重要な前提は context.md、project 内で閉じる判断は decisions.md に置きます。

20_runbooks/ は繰り返し実行する手順の置き場です。deploy, backup, restore, incident response のように、何度も使う command や確認手順は project note から分離します。

30_decisions/ は organization-wide な decision record の置き場です。ADR のように、決定内容、背景、代替案、影響を書いておくと、後から「なぜこうなっているのか」を追いやすくなります。

40_references/ は安定した調査結果や外部資料の置き場です。単なる一時メモではなく、後から参照する価値があるものを置きます。

80_private/ は private note の置き場です。ここは AI agent が読まない、要約しない、公開 summary に出さない領域として明確に分けます。

frontmatter で trust と visibility を管理する

Markdown の本文だけでは、その note をどの程度信頼してよいか判断しづらくなります。そこで各 note に frontmatter を持たせます。

たとえば inbox memo は次のような形です。

YAML

---
status: draft
visibility: internal
owner: "@team"
updated: 2026-07-28
tags:
  - inbox/memo
project:
system:
kind: unclear
target_date:
source:
---

特に重要なのは status と visibility です。

status は、その note の信頼度を表します。

draft: 未確認、作業中、またはまだ整理されていない情報
reviewed: team context として確認済みの情報
stale: 古くなっている可能性が高い情報

visibility は、その note をどの範囲で扱ってよいかを表します。

internal: team 内で共有してよい情報
restricted: 扱いに注意が必要な情報
private: AI agent に読ませず、共有 summary にも出さない情報

この policy を決めておくと、AI agent にも同じ判断基準を渡せます。たとえば reviewed は draft より信頼する、stale は確認なしに現在状態として扱わない、visibility: private は読まない、といったルールです。

完璧な metadata を最初から求める必要はありません。ただ、status, visibility, owner, updated だけでも入れておくと、後から整理するときの判断がしやすくなります。

AGENTS.md で AI agent の読み順を固定する

AI agent に repository を読ませる場合、どこから読むかを明示することが重要です。入口が決まっていないと、たまたま見つけた古い note や断片的な meeting memo を current state として扱ってしまうことがあります。

この設計では AGENTS.md に読み順を書いています。

Plain text

1. index.md
2. 05_org/ai-agent-context.md
3. 05_org/glossary.md
4. 05_org/systems.md
5. target project's index.md
6. target project's context.md
7. related runbooks, decisions, and references

この順番にしている理由は、まず vault 全体の地図を読み、次に organization-wide な用語や system context を読み、その後で target project の現在状態に入るためです。

project に関する質問なら、散らばった note よりも 10_projects/<project>/context.md を優先します。運用手順なら 20_runbooks/、判断理由なら 30_decisions/ を参照します。こうしておくと、人間が「どの note を見ればよいか」を迷いにくくなるだけでなく、AI agent の回答も安定します。

AGENTS.md には読み順だけでなく、安全ルールも書きます。たとえば 80_private/ を読まない、visibility: private を要約しない、secret や credential を shared summary に出さない、といったルールです。

inbox を正本にせず canonical note へ promotion する

この運用で一番大事なのは、00_inbox/ を情報の正本にしないことです。

inbox は入口です。Slack から拾ったメモ、作業中に気づいたこと、meeting で出た話、後で整理したい command などを一時的に置きます。ただし、そのまま溜め続けると、結局どれが正しい情報なのか分からなくなります。

そこで inbox の note を定期的にトリアージし、内容に応じて canonical な置き場へ昇格します。これが promotion flow です。

このトリアージは手動でも運用できますが、AI agent の skill として自動化しておくと、分類や promotion の判断を繰り返しやすくなります。

Plain text

00_inbox/<memo>.md
        |
        v
      triage
        |
        +--> 10_projects/<project>/context.md
        |    project の current state, important context, open questions
        |
        +--> 20_runbooks/<procedure>.md
        |    繰り返し使う operational procedure
        |
        +--> 30_decisions/<decision>.md
        |    organization-wide な decision record / ADR
        |
        +--> 10_projects/<project>/decisions.md
        |    project に閉じる decision
        |
        +--> 40_references/<topic>.md
             安定した調査結果、外部資料、仕様メモ

たとえば inbox に「backup の restore 手順」「その方式を採用した理由」「現在 project で未解決の課題」が一緒に書かれていたとします。この場合、全部を一つの note として残すのではなく、手順は 20_runbooks/、判断理由は 30_decisions/ または project decisions.md、現在の課題は project context.md に移します。

promotion では、source memo をそのままコピーするよりも、destination note を canonical に整えることを重視します。inbox は raw input であり、長期的に参照する正本ではありません。

運用上のコツは次の通りです。

Current State は短く保つ
長く残る前提や背景は Important Context に分ける
手順は runbook に逃がす
判断理由は decision record に逃がす
ambiguous, restricted, stale な note は無理に昇格しない
shared note から local-only の inbox note へむやみにリンクしない

この流れがあると、雑多な note を受け止めながら、knowledge base 全体は整理された状態を保ちやすくなります。

project workspace の作り方

project ごとに 10_projects/<slug>/ を作り、最低限 index.md と context.md を用意します。

Plain text

10_projects/<project>/
├── index.md
├── context.md
├── decisions.md
└── sources/

index.md は project の入口です。目的、owner、関連 note、関連 system への link を置きます。

context.md は AI agent にとって特に重要です。project の current state、重要な前提、未解決の question、最近の変更点をここに寄せます。project について相談するときは、まず context.md を読めば現在状態が分かるようにします。

decisions.md は project に閉じる判断の置き場です。一方で、複数 project に効く判断や organization-wide な設計方針は 30_decisions/ に ADR として置きます。

sources/ は raw source を shared repository に残す必要がある場合だけ使います。inbox の raw memo を無条件に残すのではなく、共有する価値があり、private 情報を含まないものだけを移します。

safety: private note と shared knowledge を混ぜない

AI agent に vault を読ませるなら、情報境界は最初に決めるべきです。

この設計では 80_private/ を private note の置き場として扱い、AI agent は読まない前提にしています。また、visibility: private の note も読まない、要約しない、露出しない対象です。

さらに、次のような情報は shared summary に出さないルールにします。

secret
credential
token
customer-sensitive data
private personal information

大事なのは、人間向けの運用ルールと AI agent 向けの運用ルールを分けないことです。同じ AGENTS.md や context note に明文化しておくことで、「便利だからつい読ませてしまう」状態を避けやすくなります。

また、visibility が missing の note は広く扱わない、status が missing の note は draft として扱う、という conservative な default も有効です。metadata が不足している情報を安全側に倒すことで、意図しない共有を減らせます。

まず始めるなら

これから同じような vault を作るなら、最初の step はこれで十分です。

index.md を作り、vault 全体の入口にする。
00_inbox/ を作り、未整理メモをすべて受け止める。
10_projects/<project>/index.md と context.md を作る。
繰り返し使う手順を 20_runbooks/ に分ける。
判断理由を 30_decisions/ に ADR として残す。
frontmatter に status, visibility, owner, updated を入れる。
AGENTS.md に reading order と safety rules を書く。

最初に凝った仕組みを作るよりも、情報の置き場と読み順を固定する方が効果があります。

まとめ

Obsidian vault を Git repository として扱うと、人間向けの knowledge base と AI agent 向けの shared context を同じ場所で運用できます。

重要なのは、未整理情報の入口、現在状態の正本、繰り返す手順、判断理由、参照資料、private 領域を分けることです。

frontmatter で trust と visibility を表現し、AGENTS.md で AI agent の読み順と安全ルールを固定し、inbox から canonical note へ promotion する。この三つを決めるだけで、Obsidian vault は実用的なナレッジベースとして運用できます。