claude code obsidian 連携｜2026年版ガイド

Claude CodeとObsidianを連携させる完全ガイド

Claude CodeとObsidianを組み合わせると、AIによるコーディング支援とナレッジベース管理が一体化し、開発生産性が大きく向上します。当社でもClaude Codeを実務の中心に据えており、Obsidianのvaultをコンテキストとして渡す運用が、調査・設計・実装のサイクルを大幅に短縮することを実感しています。本記事では「どう連携するのか」「何が嬉しいのか」「具体的な設定・運用手順」まで、実務経験をもとに網羅的に解説します。

なぜClaude CodeとObsidianを連携するのか

Claude Codeはターミナルから直接操作できるAIコーディングエージェントです。単にコードを書くだけでなく、プロジェクト全体のファイルを読み込み、設計意図を理解したうえで実装・リファクタリング・デバッグを自律的に行います。一方Obsidianは、Markdownファイルを双方向リンクで結びつけるナレッジベースツールです。仕様書・議事録・技術メモ・ADR（アーキテクチャ決定記録）といったドキュメントを一元管理する用途で広く使われています。

この2つを連携させる根本的な理由は、Claude Codeはファイルシステム上のMarkdownを「そのままコンテキスト」として扱えるからです。Obsidianのvaultは通常のMarkdownファイルの集合体であり、特別なエクスポートや変換なしにClaude Codeが直接参照できます。つまりObsidianで書き溜めた仕様・要件・設計ノートを、Claude Codeが実装の根拠として利用できます。

連携によって解決される具体的な課題

• コンテキスト切り替えのコスト削減：ブラウザやドキュメントツールとエディタを行き来せず、Claude Codeのセッション内で仕様を参照しながら実装できる
• ドキュメントと実装の乖離防止：実装変更時にObsidianのノートも同時に更新させることで、仕様書と実装が常に同期する
• 長大なコンテキスト活用：Claude 3.xシリーズの大きなコンテキストウィンドウを活かし、複数ノートを一度に渡して横断的な推論をさせられる
• プロジェクト固有の知識蓄積：チームのベストプラクティス・命名規則・禁止パターンをObsidianにまとめておくだけで、Claude Codeが自動的に遵守する

連携の全体アーキテクチャ

連携の中核はCLAUDE.mdというファイルです。Claude Codeはプロジェクトルートに置かれたCLAUDE.mdを起動時に自動読み込みし、セッション全体の指示書として扱います。ここにObsidianのノートへの参照・要約・直接内容を埋め込むことで、Obsidianの知識をClaude Codeに恒常的に渡せます。

ステップ別：具体的な連携セットアップ手順

ステップ1：ObsidianのVaultとリポジトリの配置関係を決める

まず物理的なディレクトリ構成を決めます。大きく2つのパターンがあります。

パターン	構成例	メリット	デメリット
docs-in-repo型	my-project/ ├─ src/ ├─ docs/（Obsidian vault） └─ CLAUDE.md	Gitで仕様も一元管理。CI/CDと連動しやすい	個人メモがリポジトリに入る可能性。.gitignoreの管理が必要
外部vault参照型	~/obsidian-vault/ ~/my-project/ └─ CLAUDE.md（vaultを参照）	ObsidianのVaultを汚さず、複数プロジェクトで共有できる	絶対パスが環境依存。チームで共有しにくい

実務ではdocs-in-repo型を推奨します。当社でも、プロジェクトのdocs/フォルダをそのままObsidianのvaultとして開くことで、Git履歴でドキュメントの変遷を追えるようにしています。個人的な作業メモはdocs/_scratch/以下に置き、.gitignoreで除外するとよいでしょう。

ステップ2：CLAUDE.mdを作成してObsidianノートを組み込む

プロジェクトルートにCLAUDE.mdを作成します。このファイルがClaude Codeにとっての「永続的なシステムプロンプト」になります。ObsidianのノートをClaude Codeに渡す方法は主に3つです。

方法A：CLAUDE.md内にノート内容を直接コピー（最もシンプル）

小規模なプロジェクトや、特定のノートだけを参照させたい場合に有効です。

# CLAUDE.md

## プロジェクト概要
このプロジェクトはECサイトのバックエンドAPIです。

## アーキテクチャ方針
（docs/architecture/overview.mdより）

- レイヤードアーキテクチャを採用（Domain / Application / Infrastructure）
- DBはPostgreSQL 15。ORMはPrismaを使用
- 認証はJWT。リフレッシュトークンはRedisで管理
- エラーハンドリングはResult型（neverthrow）で統一

## コーディング規約
（docs/guidelines/coding-standards.mdより）

- 関数は原則純粋関数とし、副作用はInfrastructure層に集約
- テストカバレッジ80%以上を維持
- コミットメッセージはConventional Commits準拠

方法B：セッション開始時に@ファイル指定でノートを渡す（動的・柔軟）

Claude Codeのプロンプト内で@ファイルパス記法を使うと、そのファイルをコンテキストに取り込めます。

> @docs/specs/user-authentication.md を読んで、この仕様に基づいて
  src/auth/login.service.ts のリファクタリング案を提示してください

この方法は、タスクごとに関連ノートを指定できるため、コンテキストウィンドウを無駄に消費しません。当社では大規模な機能実装の際に、該当機能の仕様書・設計書・過去の議事録を複数@指定して渡すことが多いです。

方法C：ディレクトリごと渡す（大規模プロジェクト向け）

> @docs/specs/ 以下の仕様書を全て確認したうえで、
  現在の実装との乖離を列挙してください

ディレクトリを指定するとClaude Codeがフォルダ内のファイルを再帰的に読み込みます。ただしトークン上限に注意が必要で、.claudeignoreファイル（.gitignoreと同じ記法）で不要なファイルを除外しておくと安全です。

ステップ3：.claudeignoreで不要ファイルを除外する

ObsidianのVaultには、Claude Codeに読ませる必要のないファイルが多数あります。プロジェクトルートに.claudeignoreを置いて除外設定を行いましょう。

# Obsidian内部ファイル
.obsidian/
.trash/

# 個人作業メモ（Gitにも入れない）
docs/_scratch/
docs/_daily-notes/

# 画像・添付ファイル
docs/attachments/
**/*.png
**/*.jpg
**/*.pdf

# アーカイブ
docs/_archive/

ステップ4：ObsidianのノートをClaude Codeが更新できるようにする

Claude Codeは読むだけでなく、ファイルの書き込みも行えます。実装を変更した際に、対応するObsidianのノートを自動更新させることで、ドキュメントと実装の同期が保てます。

> src/payment/stripe.service.ts のリファクタリングが完了したら、
  @docs/specs/payment-integration.md の「実装メモ」セクションを
  変更内容に合わせて更新してください

CLAUDE.mdに「実装変更時は対応するdocs/specs/以下のドキュメントも更新すること」と明記しておくと、Claude Codeが自律的にドキュメントを更新するようになります。当社ではこの設定を入れてから、「実装したけど仕様書が古いまま」という問題がほぼなくなりました。

Obsidianのノート構成：Claude Codeが読みやすい設計

ObsidianのノートをClaude Codeに渡すとき、ノートの構造が読み取りやすいほど精度が上がります。以下のガイドラインを実務で効果的と感じています。

推奨：ADR（アーキテクチャ決定記録）ノートの書き方

ADRは特にClaude Codeとの相性が良いドキュメントです。「なぜこの設計にしたか」という背景を明示することで、Claude Codeが設計意図に反する変更を避けられます。

# ADR-003: 認証トークンの保存先

## 状態
採択済み（2024-11-15）

## 背景
モバイルアプリとSPA両対応が必要。XSSとCSRFの両リスクに対処する必要がある。

## 決定
- アクセストークン：メモリ上（Reactのstateのみ）
- リフレッシュトークン：HttpOnly Cookie（SameSite=Strict）

## 理由
- LocalStorageはXSSで盗取リスクがあるため不使用
- HttpOnly CookieはJSから読めないためXSS耐性がある

## 影響
- SPA再ロード時はリフレッシュトークンで再取得が必要
- src/auth/token.store.ts がこの方針を実装している

推奨：仕様書ノートの構造

Claude Codeが参照しやすい仕様書ノートは、次の要素を含めると効果的です。

• 対象ファイルパスの明示：「このノートはsrc/xxx.tsに対応する」と書く
• 入出力の型定義：TypeScriptの型やJSONスキーマをそのままMarkdownコードブロックに書く
• 境界条件と禁止事項：「〇〇の場合は例外を投げる」「〇〇は絶対にしない」を明記
• 関連ノートへの内部リンク：Obsidianの[[リンク]]記法はそのまま書いてよい（Claude Codeはリンク先を参照しないが、テキストとして文脈を理解する）

実務で効いているCLAUDE.mdのベストプラクティス

当社での実運用で特に効果があったCLAUDE.mdの設定パターンをまとめます。

1. ドキュメント更新ポリシーを明記する

## ドキュメント管理ルール

- 新機能実装時は docs/specs/ に対応する仕様書を作成すること
- 既存機能の変更時は対応する仕様書を同時に更新すること
- 廃止したAPIは docs/specs/ から削除せず docs/_archive/ に移動し
  廃止日・理由を先頭に記録すること
- ADRに反する実装が必要な場合は、実装前に新しいADRを docs/adr/ に作成すること

2. Obsidianのフォルダ構造をCLAUDE.mdに記載する

## ドキュメント構造（docs/フォルダ = Obsidian vault）

docs/
├─ specs/        # 機能仕様書（実装の正とする）
├─ adr/          # アーキテクチャ決定記録
├─ guidelines/   # コーディング規約・命名規則
├─ runbooks/     # 運用手順書
└─ _archive/     # 廃止ドキュメント（削除禁止）

不明な設計判断がある場合は必ず docs/adr/ を確認すること。

3. よく使うObsidianノートをCLAUDE.mdに要約として埋め込む

毎回@ファイル指定するのが面倒な、プロジェクト全体に適用されるルール（命名規則・エラー処理方針など）は、CLAUDE.mdに要約を直接埋め込む方が効率的です。詳細が必要なときだけ@ファイルで参照させる「二段構え」が実務では最もバランスが良いです。

ObsidianプラグインとClaude Code連携の活用

Templaterプラグインとの組み合わせ

ObsidianのTemplaterプラグインを使うと、Claude Codeへの指示テンプレートをノートとして管理できます。例えば「バグ修正依頼テンプレート」「機能追加依頼テンプレート」を作成しておき、該当ノートをClaude Codeに渡すだけで定型タスクを高品質に実行させられます。

Dataviewプラグインとの組み合わせ

DataviewプラグインでObsidian内の仕様書一覧やTODOを動的に生成している場合、Claude Codeはそのクエリ結果ではなく生のMarkdownを読みます。Dataviewクエリのある部分は、Claude Codeに見せる用の静的なサマリーを別途Frontmatterに書いておくか、定期的にDataviewのスナップショットをエクスポートする仕組みを設けると確実です。

Git連携：obsidian-git プラグイン

obsidian-gitプラグインを使ってVaultをGit管理すると、Claude Codeによるドキュメント更新がコードの変更と同じコミット履歴に残ります。「どの実装変更と同時にドキュメントが更新されたか」が追跡でき、コードレビューの際にドキュメント変更も同時にレビューできます。

よくあるトラブルと対処法

トラブル	原因	対処法
コンテキストが途中で切れる	大量のノートを渡してトークン上限超過	.claudeignoreで不要ファイルを除外。タスクに関係するノートだけ@指定で渡す
Claude Codeが古い仕様で実装する	CLAUDE.mdとノートで情報が矛盾している	CLAUDE.mdに「docs/specs/が最新の仕様。CLAUDE.md内の記述より優先する」と明記
.obsidianフォルダの設定ファイルをClaude Codeが読もうとする	.claudeignoreが未設定	.claudeignoreに.obsidian/を追加
Claude Codeが勝手にObsidianノートを削除・大幅改変する	指示が曖昧でClaude Codeが積極的に動きすぎた	CLAUDE.mdに「docs/以下のファイルは追記・更新のみ。削除・大幅改変は必ず確認を取ること」と明記。Gitでdocs/を管理しておくと復元が容易
Obsidian内部リンク([[リンク]])の解釈が変	Claude Codeはリンク先を自動追跡しない	重要な関連ノートは@指定で明示的に渡す。あるいは仕様を一つのノートに集約する

Claude Code × Obsidianで実現できる開発フロー例

具体的な開発サイクルをイメージしやすくするため、「新機能追加」のフローを示します。

このフローの最大の利点は、ドキュメントと実装が常に同一のGit履歴上で管理される点です。コードレビュー時にPRを見れば、仕様変更・ADR追加・実装変更が一度に確認できます。

まとめ

Claude CodeとObsidianの連携は、追加のツールやAPIキーを必要とせず、ObsidianのVaultをMarkdownファイルの集合として扱うというシンプルな原則で実現します。重要なのは3点です。

1. CLAUDE.mdをプロジェクトの中心に置く：Claude Codeへの永続的な指示書として、Obsidianノートの要約・参照方法・ドキュメント更新ルールを記載する
2. ノートをClaude Codeが読みやすい構造で書く：ADR・仕様書・コーディング規約を明確なMarkdown構造で管理し、対象ファイルパスや境界条件を明示する
3. .claudeignoreで不要なObsidianファイルを除外する：.obsidian/フォルダや個人メモをコンテキストから除くことで、トークン効率と精度を両立する

当社での実運用では、この連携によって「仕様書を確認してからコードを書く」というプロセスがClaude Codeによって自動化され、ドキュメントと実装の乖離が大幅に減りました。開発とナレッジ管理を切り離さず、一つのワークフローとして統合する—その基盤としてClaude Code × Obsidianの組み合わせは実践的な選択肢です。

関連記事

• Claude Codeとは（総合ガイド）
• claude code api 料金
• claude code codex 比較
• claude code cursor 比較
• claude code hooks