
企画や設計のメモはObsidianにたまっているのに、コーディングエージェントはコードのリポジトリしか見ていませんよね。この記事では、ObsidianとClaude Codeを連携させて、保管庫(vault)のノートをClaude CodeやCodexのようなコーディングエージェントが読み書きできるようにする設定を、順番にまとめました。
ノートを指示書として使う方法や、Issueに分解する方法は以前の記事で扱いました。今回はその手前の接続と設定だけを扱います。フォルダをどうつなぐか、ルールファイルに何を書くか、ノートが壊れないように何を仕掛けておくか、そしてObsidianが公式に出しているスキルとCLIをどう使うかです。
Obsidianの保管庫とコードのリポジトリをつなぐ方法#
保管庫は、結局のところMarkdownファイルが入ったフォルダです。そのため、エージェントから見れば「そのフォルダにアクセスできるか」さえ解決すれば十分です。Dylan BoudroさんのObsidian + Claude Code統合ガイドは接続方法をいくつかに分けて紹介していて、コーディングで使いやすいのは次の3つです。
| 方法 | やり方 | 向いている場合 |
|---|---|---|
| 保管庫を作業フォルダに | 保管庫のルートでエージェントを実行します | ノート整理、企画、スペック作成が中心のとき |
| シンボリックリンク | 保管庫の中にコードのリポジトリへのリンクを作ります | 1つの保管庫で複数のプロジェクトを見るとき |
| リポジトリごとに保管庫 | リポジトリそのものを保管庫として開きます | ドキュメントをコードと一緒にバージョン管理するとき |
シンボリックリンクはコマンド1行で済みます。保管庫のフォルダの中で実行します。
# 保管庫の中に my-app という名前でコードのリポジトリをつなぎます
ln -s ~/projects/my-app my-app同じガイドには注意点も書かれています。シンボリックリンクはObsidianのモバイル版で問題を起こすことがあり、リポジトリごとに保管庫を置く場合は .obsidian/ フォルダを .gitignore に入れるように、とのことです。
Claude Codeを使うなら、方法がもう1つあります。コードのリポジトリで実行しながら、--add-dir オプションで保管庫のフォルダを追加で開く方法です。作業フォルダはコードのリポジトリのままで、ノートも一緒に読ませられます。
# コードのリポジトリで実行しながら、保管庫のフォルダも一緒に開きます
claude --add-dir ~/vaultただし、この方法で開けるのはファイルへのアクセスだけです。Claude Codeのメモリのドキュメントによると、--add-dir で追加したフォルダの指示ファイルは既定では読み込まれません。CLAUDE.md は環境変数 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 を設定すれば読み込まれますが、AGENTS.md はそれでも読み込まれません。このあと紹介する保管庫の権限ルールも、この方法では適用されません。ルールと権限まで使うなら、保管庫のルートで実行してください。
保管庫のルートにAGENTS.mdでルールを書く#
つないだだけでは、エージェントは保管庫がどんな場所なのかを知りません。どのフォルダに何があり、何に触れてはいけないのかを伝える必要があります。その役割を担うのが、保管庫のルートに置く指示ファイルです。私は AGENTS.md を1つだけ置いています。Codexが読むファイルで、同じメモリのドキュメントによると、Claude Codeもv2.1.277以降は CLAUDE.md がなければ AGENTS.md を直接読むからです。ファイルが1つなら、エージェントごとに同じ内容をそろえる手間がありません。それより古いClaude Codeを使う場合は、@AGENTS.md の1行だけを書いた CLAUDE.md を隣に置けば使えます。
Kenneth ReitzさんはObsidianの保管庫とClaude Codeを一緒に使うエッセイで、このファイルに保管庫の概要、書き方のルール、やってはいけないことのリストを書くと紹介しています。この構成をコーディング向けに置き換えると、次のような形になります。
# 保管庫の案内
## 構成
- `specs/` 機能ごとのスペックと設計メモ
- `decisions/` 技術的な決定とその理由
- `tasks/` エージェントに任せる作業ノート
- `sources/` 外部資料の原文
## 書き方のルール
- ノート同士は `[[ウィキリンク]]` でつなぐ
- 新しいノートには frontmatter に `type`、`status`、`date` を書く
## やらないこと
- 頼まれていない新しいファイルを作らない
- `sources/` は編集も移動も削除もしない
- 既存のノートを直す前に、変更するファイルの一覧を先に見せるいちばん大事なのはやらないことです。エージェントは、頼んでいない整理まで親切にやってしまうことが多いからです。コードならテストが誤った変更を捕まえてくれますが、ノートにはそういう仕組みがありません。
エージェントがノートに触れる前に用意する安全策#
指示ファイルはお願いにすぎません。Adam Reedさんはノートを失わずにClaude CodeとObsidianを使う方法で、境界を実際に守ってくれるのはClaude Codeの権限設定と本物のバックアップだけだと指摘しています。この記事のうち、コーディング作業にもそのまま使えるのは次のとおりです。
- まずGitのチェックポイントを作ります — エージェントが保管庫に触れる前に、コミットを1つ残します。同期はバックアップではない、という点も合わせて指摘されています。
- フォルダごとに役割を決めます — 原文のフォルダは読み取り専用、既存のノートは編集の前にまず提案、エージェントが自由に書ける出力フォルダは別に用意する、という形です。
- 読むだけの作業から始めます — 最初はプランモードで保管庫を調べさせて、その次にファイルを1つだけ書かせます。
- 終わるたびに変更を確認します —
git status --shortとgit diffで何が変わったかを見ます。
保管庫のルートでClaude Codeを実行するなら、エージェントの編集ツールが原文のフォルダを書き換えないように、権限ルールで止められます。保管庫の .claude/settings.json に拒否(deny)ルールを入れます。
{
"permissions": {
"deny": ["Edit(/sources/**)"]
}
}Claude Codeの権限ドキュメントによると、プロジェクト設定で / から始まるパスはプロジェクトのルートが基準です。また、ルールは拒否、確認、許可の順に評価されるので、拒否ルールに当たったパスを許可ルールで開け直すことはできません。
このルールが止めるのはファイルの編集です。シェルで実行する rm や mv には Bash(rm *) のようなルールを別に入れる必要があり、同じドキュメントにはBashルールはセキュリティの境界ではないと書かれています。だからこそ、1番のGitチェックポイントが最後の安全網になります。
obsidian-skillsでエージェントにObsidianの書き方を教える#
ウィキリンク、コールアウト、プロパティ(properties)のようなObsidian独自の記法は普通のMarkdownと違うので、エージェントに別途教える必要があります。Obsidianが公式に管理しているobsidian-skillsリポジトリが、この部分を補ってくれます。
エージェントスキル(Agent Skills)は、エージェントが必要なときに読み込む指示のまとまりです。リポジトリの説明によると、Agent Skillsの仕様に従っているため、Claude Code、Codex、OpenCodeのようにスキルに対応したエージェントで共通して使えます。
| スキル | 教える内容 |
|---|---|
| obsidian-markdown | ウィキリンク、埋め込み、コールアウト、プロパティなどのObsidian Markdown |
| obsidian-bases | ビュー、フィルター、数式が入るBases(.base)ファイル |
| json-canvas | ノードとエッジでできたJSON Canvas(.canvas)ファイル |
| obsidian-cli | Obsidian CLIで保管庫を扱う方法 |
| obsidian-headless | デスクトップアプリなしでの保管庫の同期と公開 |
| defuddle | Webページから余計な部分を除いたMarkdownの抽出 |
| knap | JSONやCSVのデータでMarkdownテンプレートを埋める方法 |
インストールのコマンドはリポジトリのREADMEに載っています。Claude Codeではプラグインとしてインストールします。
# Claude Code に obsidian-skills のマーケットプレイスを追加してインストールします
claude plugin marketplace add obsidianmd/obsidian-skills
claude plugin install obsidian@obsidian-skillsCodexはREADMEによると、codex plugin marketplace add obsidianmd/obsidian-skills を実行したあと、プラグイン一覧からObsidianをインストールします。手動で入れたい場合は、リポジトリの plugins/obsidian/skills/ フォルダを、Claude Codeなら保管庫ルートの .claude/skills/ に、Codexなら ~/.agents/skills にコピーすれば使えます。
Obsidian CLIで保管庫を検索してノートを読む#
エージェントはファイルを直接開いて読むこともできますが、Obsidian CLIを使えば、Obsidianがすでに作ってある検索、タグ、バックリンクの情報をターミナルのコマンドで取り出せます。先ほどのStarmorphのガイドも、Claude CodeとObsidianをつなぐ方法の中で、CLIをいちばん速くてトークン効率のよい方法に挙げています。
Obsidian CLIを有効にする#
Obsidian CLIの公式ドキュメントによると、Obsidian 1.12のインストーラーが必要で、設定は次のように進めます。
- Obsidianのインストーラーを最新バージョン(1.12.7以上)に上げます。
- Settings → General で Command line interface を有効にします。
- 案内に従ってCLIを登録し、ターミナルを開き直します。
1つ知っておきたい点があります。CLIは起動中のObsidianアプリに接続して動きます。アプリが起動していなければ、最初のコマンドがObsidianを立ち上げます。デスクトップアプリなしで同期が必要な場合については、ドキュメントがObsidian Headlessを別に案内しています。
エージェントがよく使う読み取りコマンド#
パラメーターは 名前=値 の形で書きます。以下のコマンドは、私のブログの保管庫で実行してみたものです。
# 使えるコマンドをすべて表示
obsidian help
# 保管庫からキーワードで検索(結果はノートのパス一覧)
obsidian vault=blog search query="Obsidian" limit=3
# ノートの内容を読む
obsidian vault=blog read path="posts/202610012001.md"
# タグを使用回数の順に表示
obsidian vault=blog tags counts sort=count- 保管庫の指定 —
vault=名前は先頭に書きます。ターミナルの現在のフォルダが保管庫の中なら、その保管庫が使われるので省略できます。 - ファイルの指定 —
file=はウィキリンクのように名前だけで探し、path=は保管庫のルートからの正確なパスを受け取ります。
このほかに backlinks、tasks、property:read などのコマンドもあります。ノートを作ったり追記したりする create や append もありますが、最初は読み取りコマンドだけを使わせるほうが安全です。
「Your Obsidian installer is out of date」という警告が出るとき#
アプリは最新なのにインストーラーが古い場合、コマンドを実行するたびにこの文言が出ます。
Your Obsidian installer is out of date. Please download the latest installer which includes better CLI support: https://obsidian.md/downloadObsidianはアプリが自分で更新されるため、アプリのバージョンとインストーラーのバージョンが別々にあります。obsidian version を実行すると、1.15.1 (installer 1.8.4) のように両方が表示されます。警告が出ても上の読み取りコマンドは動きましたが、公式ドキュメントが求めているとおり、ダウンロードページからインストーラーを新しく入手して入れ直すのが正しい対処です。私も入れ直したあとは 1.15.1 (installer 1.15.1) に変わり、警告は出なくなりました。
つないだあとは、ノートを作業指示書として使う#
ここまで済めば、エージェントは保管庫を読めて、ルールを知っていて、むやみに壊せない状態になります。あとは、ノートに何を書いて任せるかが残っています。
- 1つの作業を1枚のノートに書く形式は、ObsidianのノートをAIエージェントの作業指示書として使うにあります。
- アイデアのノートをPR 1つ分の大きさのIssueに分ける方法は、AIエージェントのワークフロー:アイデアを完了条件付きのIssueに分解するにまとめました。
- ノートを監視してエージェントを自動で動かしたくなったら、先にMarkdownでAIエージェントの作業を自動化するときに押さえることを読んでみてください。自分で作って動かしてみたあとに残した記録です。
フォルダ1つとルールファイル1つから#
一度に全部そろえる必要はありません。今日は保管庫にGitのコミットを1つ残し、保管庫のルートに AGENTS.md を作って、構成とやらないことだけを書いてみてください。その状態でエージェントに読むだけの質問を1つ投げてみると、スキルとCLIのどちらが次に必要なのかが見えてきます。
If you do what you've always done, you'll get what youve always gotten.
— Tony Robbins


