ClaudeCodeとObsidianで設計・作業メモを残す

こんにちは、虎の穴ラボのYFです。
今回は、以前からAIエージェントとの相性がよいと話題のObsidianを導入してClaude Codeに記録を残させる仕組みを作ってみました。

調査やコーディングにAIエージェントを使っていて、作業記録をうまく残せていないなと感じている方の参考になればと思います。

作業記録を残すことのメリット

開発の作業では、現行仕様・コードの調査結果、比較した複数の設計案、設計方針の判断理由など、最終的なコードが完成するまでに多くの記録が生まれます。
AIエージェントを用いる時、これらの前提を教えていない状態では適切な出力にならなかったり、同じ調査を何度も行ったりしてしまいます。

しかしながら、毎回複数の資料の場所を教えたりプロンプトに入力するのは手間がかかり、正直面倒な作業です。
そこで、AIに作業をさせる -> 記録を残させる -> 記録を読み込ませる という一連のサイクルを構築することで、効率化・正確性の向上が見込めます。

Obsidianの導入

まずはObsidian本体をインストールします。

obsidian.md

インストール後、Obsidianを起動して空の保管庫を作成します。 Obsidianではこの保管庫のことを「Vault」と呼びます。保管庫に指定したローカルのディレクトリがそのままVaultとなり、Markdownファイルの置き場になります。

次にCLIが使えるか確認します。

obsidian.md

2026/3 にリリースされたバージョン1.12.7 以降からObsidian本体に同梱されています。 obsidianコマンドにはノートの作成・編集から、テンプレート展開、リンクやタグの一覧、検索など幅広いサブコマンドが揃っています。

なお、CLIはObsidianアプリが起動中だけ利用可能です。 アプリとターミナルを起動し、ターミナルからobsidianと入力して実行します。

$ obsidian

         ▗▄▟██
       ▄█████▛ █▄
      ▐█████▛ ▟███
      ▐████▛ ▟████▌
     ▗ ▜███▎▐█████▌
    ▗█▙ ▜██▎▐██████
   ▗███▙ ▜█▙ ▜█████▙
  ▗█████▙ ▄▄▄▄▃▔▀███▙
  ▝██████ ██████▄ ▜█▘
   ▀████▛ ███████▙ ▘
     ▀█▛ ▟████████▌  Obsidian 1.12.7
        ▝▀▀▀▀████▀

  obsidian-storage
  Tab to autocomplete, ↑/↓ for history, Ctrl+C to quit

コマンドからVaultを触れる土台ができました。
実際には人間はUIから操作して、CLIはほとんどAIエージェントが使用することになると思います。
AIに.mdを直接操作させるのではなく、CLIから起動中のObsidianアプリを経由させることで、テンプレート展開やデイリーノートの自動命名といったアプリの機能も利用可能になります。

フォルダ構成

Obsidianは細かく整理せずにどんどんファイルを追加していって後からリンクで繋いでいくといった運用法が可能です。
とはいえ何のフォルダ分けもないと扱いづらいので、最低限の構成を行います。

弊社のタスクはBacklogで管理するため、今回はすべてチケットIDをキーとして整理する方針にしました。

Vault/
├── Daily/
├── template/
├── dev-plan/
│   └── {ticket-id}_{gitブランチ名}/
├── dev-notes/
│   └── {ticket-id}/
└── links/
    └── {ticket-id}.md

それぞれのフォルダ、ファイルの役割は、ざっくりと次のとおりです。

• template: ノートのひな形を置く場所。dev-plan用、dev-note用などのテンプレートをここにまとめる
• dev-plan: 実装前の最終的な設計方針を残す
• dev-notes: 作業中の調査結果や試行錯誤を書き留めるメモ
• links: 1つのチケットに紐づくノートをWikiリンクで束ねる目次ノート

dev-planのフォルダ名には、そのままfeature/ブランチ名として使える命名にしておく取り決めにしました。

一例として、dev-planのテンプレートはこんな感じです。

クリックで表示：dev-plan-template

# dev-plan-template

ID: dev-plan-{{date:YYYYMMDDHHmm}}
tags: #dev-plan <!-- バックログチケットID -->

---

<!-- タイトルはチケットのタイトル -->
## {{title}}

| 項目      | 値                                                                |
| ------- | ---------------------------------------------------------------- |
| チケット    | [{{TICKET_ID}}](https://hogehoge.backlog.jp/view/{{TICKET_ID}}) |
| ブランチ    | `{{branch-name}}`<!-- feature/{{branch-name}} -->                |
| Docブランチ | `{{branch-name}}`<!-- feature/doc/{{branch-name}} -->            |
| 関連プラン   | `~/.claude/plans/{{plan-file}}.md` <!-- プランが存在しない場合は空欄 -->       |
| 作成日     | {{date:YYYY-MM-DD}}                                              |

---

## 第1部：設計

### 1.1 背景・目的

<!--
- このタスクが何を解決するか / なぜ必要か
- 関係者・経緯（誰からの依頼 / どの案件か）
- 達成したいゴール
-->

- {{背景}}
- {{目的}}

### 1.2 要件

#### 機能要件

- {{要件1}}
- {{要件2}}

### 1.3 対応方針設計

<!--
- このセクションは追加する機能に応じて関連する現行ロジックおよび対応方針
    - 現行のフロー
    - 現行のロジックと変更内容の説明
-->

### 1.4 影響範囲

<!--
- 変更を行うファイル名とその変更概要・目的などをリストアップ
-->

#### {{カテゴリA：例 表示側 / フロントエンド}}

| ファイル                | 概要       |
| ------------------- | -------- |
| `{{path/to/file1}}` | {{変更内容}} |
| `{{path/to/file2}}` | {{変更内容}} |

#### {{カテゴリB：例 バックエンド / 依存タスク}}

| ファイル                | 概要       |
| ------------------- | -------- |
| `{{path/to/file3}}` | {{変更内容}} |

### 1.5 実装設計
#### {{処理名}} フロー

<!--
- フローは関連する箇所の現行の処理のフローをMermaidで記述
-->


```mermaid
flowchart TD
    A[起点] --> B[処理1]
    B --> C{分岐条件}
    C -->|YES| D[処理2]
    C -->|NO| E[処理3]
    D --> F[(永続化先)]
    B -.->|エラー時| X[フォールバック]
```

#### {{処理名}} ロジック

<!--
- 変更するファイルの変更箇所を抽出して、現行ロジックとどんな処理をしているかの概要説明
- どの位置でどのような変更をするかを日本語でコードに追記
- 新規ファイルの場合は、ファイル名とどのような実装にするかの説明を記載する
-->

##### {{ファイル名}}

{{説明}}

```{{lang}}

{{code}}

対応箇所の既存コード + 対応の内容を日本語で説明
```

これで、Obsidianの導入とフォルダ構成の準備までが整いました。
次は、この構成にAIが自分で記録を残せるようにするためのSkill作りに入っていきます。

Skillの作成

作業の文脈に応じてAIが自分で記録を残せるよう、Skillを用意します。

ディレクトリ構成は次のようにしました。
helps.md には Obsidian CLI のサブコマンドやパラメータの一覧を置いておき、SKILL.md から参照させます。

.claude/skills/obsidian/
├── SKILL.md   … 記録の作成・整理ルール本体
└── helps.md   … Obsidian CLIのコマンド・パラメータ一覧

ポイントは

1. Vaultへのアクセスは必ずObsidian CLI経由にする
   • せっかくCLIが用意されているので.mdを直接触らせないように
   • コマンドはhelps.mdを置いておいて参照
2. どの作業のときに、どこへ何を残すか
   • 設計方針はdev-plan/、作業メモはdev-notes/、それらを束ねる目次はlinks/、とフォルダ構成、命名ルールの指示
3. リンク
   • dev-notesでは汎用名のファイルをチケットをまたいで使い回すため、ファイル名だけだと同名ファイルと衝突して誤リンクになる

こちらも一例として、SKILL.md はこのようにしました。

クリックで表示：.claude/skills/obsidian/SKILL.md

---
name: obsidian
description: obsidian CLIを使用したドキュメント(設計方針・作業メモ・まとめノート)の作成・整理を行う
argument-hint: "[Vault-name]"
context: fork
disable-model-invocation: false
user-invocable: true
---

## 共通ルール

- Vaultへのアクセスには必ず Obsidian CLI を使用すること。ファイルを直接読み書きしない。
- Obsidian CLI のコマンド・パラメータ一覧は `.claude/skills/obsidian/helps.md` を参照する。
- 引数で Vault-name が指定された場合は、全コマンドに `vault=<name>` を付与する。指定がなければ Obsidian の active vault を対象とする。
  ```bash
  # 引数あり
  obsidian read vault=MyVault path=dev-plan/XXX/design.md
  # 引数なし(active vault)
  obsidian read path=dev-plan/XXX/design.md
  ```
- チケットID（バックログのチケットID）が不明な場合はユーザーに確認する。確認しても不要な場合は省略可。
- 関連資料が存在する場合は参照し、作業の参考とする。
- コードへのリンクはObsidian上では有効ではないため、記録を作成する際は``で囲むこと。
- Wikiリンクは必ずVaultルートからのパス付き＋表示名で記述すること。
  - ファイル名だけの `[[依頼内容]]` は、別チケットの同名ファイル（`依頼内容.md` 等）と衝突し誤リンクになる。
  ```text
  [[dev-notes/{ticket-id}/{ファイル名(拡張子なし)}|{表示名}]]
  # 例: [[dev-notes/TICKET_12345/依頼内容|依頼内容]]
  ```
  - パスはVaultルート相対・拡張子(`.md`)なし。`|` の後ろが表示テキスト。
  - dev-notes は各チケットで汎用名（`依頼内容` `実装内容まとめ` `レビュー結果` 等）を使い回すため、パス付きが必須。
  - dev-plan はファイル名がチケットIDプレフィックスで一意だが、一貫性のため同様にパス付きで記述する。
  - リンク対象のパスは `obsidian files folder=...` の出力をそのまま利用する。

## Vault構成(規約)

```
Vault/
├── template/
│   ├── dev-plan-template       … 設計方針用テンプレート
│   └── dev-note-template       … 作業メモ用テンプレート
├── dev-plan/
│   └── {ticket-id}_feature-name/
│       └── *.md                … 設計方針ノート
├── dev-notes/
│   └── {ticket-id}/
│       └── *.md                … 作業メモ
└── links/
    └── {ticket-id}.md          … チケット単位のまとめノート
```

- `{ticket-id}_feature-name` の `feature-name` は `feature/ブランチ名` として使える命名にする。
- ディレクトリが存在しない場合は作成する。

## トリガー別の手順

### 1. 設計方針の作成（ユーザーから設計方針の作成指示があったとき）

作業完了後に以下手順で記録を作成する。

1. **テンプレート確認**
   ```bash
   obsidian template:read name=dev-plan-template
   ```
   存在しない場合は任意の構成で作成する。

2. **当日のDailyノート確認**
   ```bash
   obsidian daily:read
   ```
   設計に関連するメモがあれば参考にする。

3. **不足情報の確認**
   テンプレートに対して不足する情報があればユーザーに確認する。

4. **ノート作成**
   `dev-plan/{ticket-id}_feature-name/` 配下にノートを作成する。
   ```bash
   obsidian create \
     path=dev-plan/{ticket-id}_feature-name/design.md \
     template=dev-plan-template
   ```

5. **まとめノート更新** → 「3. linksの整理」へ。

### 2. 作業メモの作成（設計・実装・調査の作業を行ったとき / ユーザーから設計・実装・調査指示があったとき）

以下のような事柄を、コード・図・言葉での説明を駆使して記録する。

- 設計・実装時の how-to、ノウハウ、気づき
- 一度でうまくできなかった箇所、リトライした箇所
- コードから読み取れない、実装の意図・思想で補足説明したい箇所
- 調査の目的・経緯・調べた範囲・確認した結果・残課題・参考にした資料/コード

手順:

1. **テンプレート確認**
   ```bash
   obsidian template:read name=dev-note-template
   ```

2. **当日のDailyノート確認**
   ```bash
   obsidian daily:read
   ```

3. **ノート作成**
   `dev-notes/{ticket-id}/` 配下にテンプレートから新規ノートを作成する。
   ```bash
   obsidian create \
     path=dev-notes/{ticket-id}/{タイトル}.md \
     template=dev-note-template
   ```

4. **まとめノート更新** → 「3. linksの整理」へ。

### 3. linksの整理（ファイルの追加・削除を行ったとき）

1. **`links/{ticket-id}.md` の有無を確認**
   ```bash
   obsidian file path=links/{ticket-id}.md
   ```
   存在しない場合は作成する。
   ```bash
   obsidian create path=links/{ticket-id}.md
   ```

2. **関連ファイルへのリンクを整理して記載**
   同じ `{ticket-id}` に紐づく `dev-plan/` および `dev-notes/` 配下のノートを Wiki リンク形式で列挙する。
   ```bash
   obsidian files folder=dev-plan/{ticket-id}_feature-name
   obsidian files folder=dev-notes/{ticket-id}
   ```
   **リンクは「共通ルール」のパス付き形式 `[[Vaultルートからのパス(拡張子なし)|表示名]]` で記述すること**（ファイル名だけの記法は同名ファイルと衝突するため禁止）。`obsidian files` が返したパスをそのまま流用する。
   ```text
   ## 作業メモ (dev-notes)
   - [[dev-notes/{ticket-id}/依頼内容|依頼内容]]
   - [[dev-notes/{ticket-id}/実装内容まとめ|実装内容まとめ]]

   ## 設計方針 (dev-plan)
   - [[dev-plan/{ticket-id}_feature-name/{ticket-id}_feature-name|設計方針]]
   ```
   結果を元に `links/{ticket-id}.md` の内容を更新する（`append` / `prepend` / `create overwrite` を適宜使用）。

記録を促してもらう

作業が一段落したタイミングでClaudeの側から記録をサジェストしてくれるようにしておきます。
Claude Codeには、繰り返したい指示やフィードバックを覚えさせておくメモリ機能があるので、適当なセッションの中で「タスクがひと段落したら、obsidian skillで記録するか聞くように。メモリーで覚えて」のような感じで頼むだけです。

次のような内容がメモリファイルとして保存されます。

---
name: 設計・実装・調査後のobsidian skillサジェスト
description: 設計・実装・調査作業が一段落したタイミングで、条件を満たす場合のみ /obsidian skill の利用をユーザーに提案する
type: feedback
originSessionId: XXXXXXXXXXXXXXXXXXXXXXXXXXX
---
設計方針の検討、機能の実装作業、または調査作業が一段落したターンの終わりに、`/obsidian` skill を使ってドキュメント化（実装ノウハウや調査記録を作業メモとして残すことを含む）することをユーザーにサジェストする。

保存先はVaultではなく、Claude Codeのメモリ領域です。
具体的には、ホーム配下の~/.claude/projects/<プロジェクトのパスをエンコードした名前>/memory/などに置かれますが、Claudeにどこにあるか聞けば、パスを出してくれます。

~/.claude/projects/-Users-xxxx-dev-myproject/memory/
├── MEMORY.md
└── obsidian_skill_suggest.md

MEMORY.mdはセッション開始時に読み込まれるため、次回以降の会話でもこの指示が効くようになります。
これにより、作業のたびに「記録しておきますか？」と一言促してくれるようになり、人間は「よろしく」と頼むだけであとはAIがやってくれるようになります。
(もちろんサジェストされなくても、メモしておくように依頼すればやってくれます)

記録の参照

最後に、サンプルとして作成した記録を参照させてみます。

無事、サンプル用に作った記録を読み込めました。

まとめ

ObsidianのCLIとClaude CodeのSkillを組み合わせて、設計方針や作業メモを残し、参照させることができました。
AIに作業をさせる → 記録を残させる → 記録を読み込ませる、というサイクルが一通り完成です。

ObsidianとAIエージェントを使った作業ログの蓄積については他にも多くの記事がありますが、本記事も仕組みづくりの一助になれば幸いです。

Fantia開発採用情報

虎の穴ラボでは現在、一緒にFantiaを開発していく仲間を積極募集中です！
多くのユーザーに使っていただけるtoCサービスの開発をやってみたい方は、ぜひ弊社の採用情報をご覧ください。
toranoana-lab.co.jp