Claude Media
Claude CodeでObsidianプラグインを開発する手順
Claude Codeチュートリアル

Claude CodeでObsidianプラグインを開発する手順

ObsidianのサンプルプラグインをClaude Codeで拡張し、manifest更新・ホットリロード・審査提出まで進める手順と、レビューガイドラインが定める落とし穴をまとめます。

読了目安 約8分

Obsidianプラグイン開発でClaude Codeが担う役割

Obsidianプラグインとは、TypeScript製のPluginクラスを継承してObsidianに機能を追加するコードです。ビルドや読み込みの手順自体はObsidianのツールチェーンが担い、Claude CodeはTypeScriptコードの生成・レビュー・ガイドライン違反のチェックを担当します。役割は素直な分業で、Obsidian側に「Claude Code専用の開発モード」のようなものは用意されていません。

この記事では、サンプルプラグインをcloneしてからmanifestを更新し、審査に提出するところまでを、Claude Codeを使う場面ごとに区切って説明します。手順そのものはObsidianのチュートリアルと同じで、そこにClaude Codeの使いどころを足す構成です。

開発を始める前に、次の3つを用意します。

  • Git
  • ローカルのNode.js開発環境
  • Claude Code(コードエディタとしてVS Code等を併用してもよい)

Step 1: サンプルプラグインを取得してビルドする

サンプルプラグインはobsidianmd/obsidian-sample-pluginとしてGitHubに公開されています。テンプレートリポジトリなので、自分のGitHubアカウント上に複製してから使うことも可能です。

開発用Vaultの.obsidian/pluginsディレクトリにcloneし、依存関係をインストールします。

cd path/to/vault/.obsidian/plugins
git clone https://github.com/obsidianmd/obsidian-sample-plugin.git
cd obsidian-sample-plugin
npm install
npm run dev

npm run devはターミナルで動き続け、ソースコードを変更するたびにmain.jsを自動で再コンパイルします。ここまでは通常のTypeScript開発と同じで、Claude Codeを起動する必要はまだありません。

Obsidian側では「設定」→「コミュニティプラグイン」から「コミュニティプラグインを有効化」を選び、インストール済みプラグイン一覧でSample Pluginのトグルをオンにします。これでプラグインが読み込まれます。

Step 2: Claude CodeにObsidian APIの作法を教える

Obsidian APIには、レビューで頻出する指摘としてまとめられた作法があります。これをClaude Codeに知らせずに編集を任せると、サンプルプラグインのまま残りがちなアンチパターンを踏襲してしまいます。プロジェクト直下のCLAUDE.mdに、少なくとも次の3点を書いておくと効果的です。

  • グローバルなappではなくthis.appを使う(appはデバッグ用途で将来削除される可能性がある)
  • innerHTML・outerHTML・insertAdjacentHTMLでユーザー入力からDOMを組み立てない(スクリプト注入のリスクがある)。代わりにcreateEl()・createDiv()・createSpan()を使う
  • registerEvent()やaddCommand()で登録したリスナーは、プラグインのアンロード時に自動で解放される。手動で管理するリソースだけonunload()で明示的に解放する

CLAUDE.mdとAGENTS.mdを併用しているプロジェクトでは、AGENTS.mdとCLAUDE.mdで設定を統合する運用パターンのようにファイルを一本化しておくと、Obsidian API向けの作法を二重管理せずに済みます。

CLAUDE.mdに書いた作法を編集のたびに確認させたい場合は、Claude CodeのPostToolUse hookでtsc --noEmitを自動実行し、型エラーを即座に検知する構成も選べます。設定手順はPostToolUse hookでツール実行後の後処理を自動化するにまとめています。

Step 3: manifest.jsonを更新してプラグインを識別可能にする

manifest.jsonはプラグインの識別情報を持つファイルです。リファレンスでは、プラグイン固有のプロパティとして次の3つが必須とされています。

プロパティ必須内容
id必須必須内容小文字とハイフンのみ。末尾をpluginにできず、obsidianという文字列も含められない
description必須必須内容プラグインの説明文
isDesktopOnly必須必須内容NodeJSやElectron APIを使うなどデスクトップ専用の場合はtrue

共通プロパティとしてauthor・minAppVersion・name・version(x.y.z形式のセマンティックバージョニング)も必須です。authorUrlとfundingUrlは任意項目です。ローカル開発ではidをプラグインのフォルダ名と一致させておくと、onExternalSettingsChangeなどの一部メソッドが正しく呼び出されます。

nameにも制約があります。英数字(Basic Latin)を基本とし、ハイフン・プラス記号・括弧以外の記号や絵文字は使えません。「Live Preview」のようなObsidianのコア機能名は単体では使えず、「Obsidian」「Plugin」という単語やその変形も含められません。

Claude Codeにこの節を渡し、「manifest.jsonのidを一意な識別子に変更し、プラグインフォルダ名も揃える」ように指示すれば、チュートリアルのStep 4に相当する作業を任せられます。main.ts側のクラス名(MyPluginなど)をプラグイン名に合わせてリネームする作業も同時に頼むと手戻りが減ります。

Step 4: 開発ループを回す

コードを変更したら、プラグインを再読み込みしないと変更が反映されません。リロードには2つの方法があります。

  1. 手動リロード: コミュニティプラグイン一覧でトグルをオフ→オンにする
  2. 自動リロード: コミュニティプラグインHot-Reloadを導入し、ソースコードの変更を検知して自動的にリロードする

npm run devはエディタ上のソースではなくmain.jsというビルド成果物を書き換えます。このmain.jsはClaude Codeが直接編集したファイルではなく、ビルドプロセスが生成した派生ファイルです。Claude Codeのセッション中にこの種の外部プロセスによる書き換えを把握しておきたい場合は、FileChanged hookでディスク上の変更を検知する構成が使えます。仕組みはFileChanged hookでディスク上のファイル変更を検知するで解説しています。

デバッグには開発者ツールのConsoleタブを使います。Windows/LinuxはCtrl+Shift+I、macOSはCmd-Option-Iで開けます。onload()とonunload()にconsole.logを仕込んでおくと、リロードのタイミングを目視で確認できます。

Claude Codeにレビューさせたいチェック項目

Obsidianのガイドラインには「レビューでよく出る指摘」が一覧になっています。サンプルプラグインを改造したコードをClaude Codeにレビューさせる際は、次の観点を明示的に伝えると効果的です。

観点避けるべき実装推奨される実装
ファイル編集避けるべき実装Vault.modifyで開いていないファイルを直接書き換える推奨される実装Vault.processで原子的に書き換える
フロントマター編集避けるべき実装YAMLを自前でパースして書き戻す推奨される実装FileManager.processFrontMatterを使う
ファイル検索避けるべき実装vault.getFiles().find()で全ファイルを走査する推奨される実装Vault.getFileByPath()で直接取得する
アクティブビュー取得避けるべき実装workspace.activeLeafを直接参照する推奨される実装getActiveViewOfType()を使う
コマンド避けるべき実装デフォルトのホットキーを設定する推奨される実装ホットキーは未設定のままユーザーに委ねる
スタイリング避けるべき実装el.style.colorのようにインラインで指定する推奨される実装CSSクラスと[[CSS variables]]で指定する

モバイル対応が必要な場合は追加の制約があります。Node.jsとElectronのAPIはモバイル版Obsidianで使えないため、isDesktopOnlyをtrueにしない限り、これらのAPIを呼ぶコードはモバイル環境でクラッシュの原因になります。正規表現の後読み(lookbehind)もiOS 16.4未満では未対応なので、Platform.isIosAppで分岐するか、対応バージョンを絞り込む実装が必要です。

公開までの流れ

開発が一段落したら、Obsidian Community directoryへの提出に進みます。提出前にリポジトリのルートへ次の3ファイルを揃えます。

  • README.md(プラグインの説明と使い方)
  • LICENSE
  • manifest.json

manifest.jsonのversionをセマンティックバージョニング(例: 1.0.0)に更新し、そのバージョンをタグ名とするGitHub Releaseを作成します。Releaseにはmain.js・manifest.json・任意でstyles.cssをバイナリ添付ファイルとしてアップロードします。community.obsidian.mdでObsidianアカウントにログインし、GitHubアカウントを連携してから登録すると、自動レビューが走り、修正が必要な箇所があれば画面上に表示されます。指摘に対応したら、バージョンを上げた新しいGitHub Releaseを公開する流れです。

よくあるつまずき

  • idにobsidianという文字列を含めてしまう: 審査で弾かれる制約です。プラグイン名にもObsidianやその変形(Obsi-など)を含められません
  • manifest.jsonを書き換えてもObsidianを再起動していない: マニフェストの変更はプラグインのリロードだけでは反映されないことがあり、Obsidian自体の再起動が必要な場合があります
  • 開発中のonunload()でリーフをdetachしてしまう: ユーザーがプラグインを更新した際、開いていたリーフが元の位置に復元されなくなります
  • モバイル版でクラッシュする: Node.js/Electron APIを使うコードパスがデスクトップ専用のはずが、isDesktopOnlyの設定漏れでモバイルにも配布されているケースです

まとめ

Claude CodeでObsidianプラグインを作る流れは、サンプルプラグインをビルドする工程自体は変わらず、TypeScriptコードの生成とガイドライン準拠のレビューをClaude Codeに任せる分業です。this.appの使用・DOM構築時のXSS対策・リソースの解放・Vault APIの選び方といったガイドラインの指摘事項を先にCLAUDE.mdへ書いておけば、レビューの手戻りを減らせます。VaultをMCP経由でClaudeに読み書きさせたいだけであれば、プラグインを自作せずに済む方法としてObsidianのMCPサーバーでClaudeにVaultを読み書きさせるという選択肢もあります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →