Gemini CLIの会話履歴と実装計画をCustom commandsで個人ナレッジベース化する

目次

1.はじめに
2.各Custom command説明前の前提
3.各Custom commandについて
4.おわりに

1.はじめに

以下2つのブログで hooks を使った AI との会話履歴、Plan Mode で生成した実装計画ファイルを指定箇所に蓄積する仕組みを紹介しました。

• Gemini CLIのhooksで会話履歴をObsidianの保管庫に自動保存してみた
• Gemini CLIのhooksでPlan Mode実装計画をObsidianの保管庫にコピーしてみた

これらの方法で情報を蓄積できる仕組みを作ったならば有効活用を試みたいです。
そこで Custom commands を使った個人ナレッジベース化を考えたので紹介します。

※ Custom commands（複数形）は仕組みの総称とし、個別のコマンドは Custom command と記載しております。

環境情報

• macOS：Tahoe 26.3.1
• Node.js のバージョン（ node --version ）：24.11.1
• Gemini CLI のバージョン（ gemini --version ）：0.38.2

2.各Custom command説明前の前提

ディレクトリ構成について

gemini-cli/ は会話履歴ファイルの自動作成先ディレクトリ、gemini-cli-plans/ は実装計画ファイルのコピー先ディレクトリです。
いずれも上記ブログで紹介した仕組みで自動生成され、残りのディレクトリ・ファイルは新規作成します。

Documents/obsidian_保管庫/
├── _handover.md                        # wiki-sync の進捗管理ファイル
├── .gemini/
│   └── commands/                       # Custom commands 定義ファイル置き場
│       ├── wiki-sync.toml              # 会話履歴をwiki化するコマンド
│       ├── wiki-categorize-others.toml # その他/のナレッジを昇格させるコマンド
│       ├── wiki-search.toml            # wikiを横断検索するコマンド
│       ├── find-past-plans.toml        # 過去の実装計画を検索するコマンド
│       ├── archive-history.toml        # 会話履歴をアーカイブするコマンド
│       └── unarchive-history.toml      # アーカイブを元に戻すコマンド
├── gemini-cli/                         # 会話履歴ファイルの自動作成先（日付/時刻_セッションID先頭8文字.md）
│   ├── 20260406/
│   │   └── 185645_a4c0af78.md
│   ├── 20260407/
│   │   └── 154427_156adae4.md
│   ├── 20260408/
│   │   └── 175012_26d0e4cc.md
│   ├── 20260410/
│   │   └── 155550_68f434a5.md
│   ├── 20260413/
│   │   └── 161453_b08b5697.md
│   └── 20260414/
│       ├── 103226_a7def48b.md
│       └── 144856_3ec7d567.md
├── gemini-cli-plans/                   # 実装計画ファイルのコピー先（プロジェクト名/日付/時刻_作業名.md）
│   ├── aws-infra/
│   │   ├── 20260407/
│   │   │   └── ...
│   │   │   └── ...
│   │   └── 20260410/
│   │       └── ...
│   └── terraform-newrelic-integration/
│       └── 20260414/
│           └── ...
└── wiki/                               # Custom commands で蓄積するナレッジ置き場
    ├── aws/                            # 事前作成済み
    ├── gemini-cli/                     # 事前作成済み
    ├── google-cloud/                   # 事前作成済み
    ├── terraform/                      # 事前作成済み
    └── その他/                          # 分類できないナレッジ置き場

_handover.md は Custom command の wiki-sync で使用する管理ファイルです。
.gemini/commands/ 配下の .toml ファイルが Custom commands の定義ファイルになります。
各コマンドの中身は後続で説明します。

wiki/ ディレクトリには Custom commands 経由でナレッジを蓄積していきます。
配下のサブディレクトリはナレッジのカテゴリに相当します。
蓄積される内容がある程度予測できるものはあらかじめ作成しておきます。

筆者の場合、aws/・gemini-cli/・google-cloud/ ・terraform/ ・その他/ を事前に用意し、ナレッジの分類としてサブディレクトリの名前に当てはまる内容のものはそこへ、該当しないものはまとめて その他/ へ振り分けられます。

その他/ に同じトピックのナレッジが溜まった場合、Custom command の wiki-categorize-others で専用のサブディレクトリを作成し、そこへ昇格させます。
最初から完璧なカテゴリ設計は目指さず、運用しながら育てていくイメージです。

以上が Custom commands を使うにあたっての前提です。
続いて本題である各 Custom command の中身を紹介します。

3.各Custom commandについて

各 Custom Command について、作成背景・実行時の動き・.toml ファイルの内容を紹介します。
wiki-sync・wiki-categorize-others・wiki-search・find-past-plans については実行例のキャプチャも合わせて掲載しています。

wiki-sync.toml

作成背景

そのままの会話履歴ファイルの中身を追っていると、結局何が結論なのかが分かりにくく、また、議論が途中で終わり結論が出ていない会話履歴も存在します。
生の会話形式で蓄積し続けているとナレッジとして活用しにくいという課題感がありました。

Custom command実行時の動きについて

未処理の会話履歴ファイルをチェックし、会話形式でなく知見・結論を体系的にまとめた Wiki ファイルを生成します。
コマンドを実行するたび全ファイルを再チェックするのは避けたいので、進捗管理ファイルとして _handover.md を用意。
このファイルに最終処理日時と最終処理ファイルを記録させます。
これにより、コマンドの次回実行時は最終処理ファイルより新しくできた会話履歴ファイルを対象に Wiki ファイルを生成します。

技術的な知見を含まない会話履歴、Wiki 化作業そのものの会話履歴は Wiki 化対象から省く形にしています。
Custom command による処理完了後、 Wiki 化・スキップ（Wiki 化から省いた会話履歴）したファイル数を報告させ、wiki/その他/ に同じトピックが10件以上溜まっている場合、 wiki-categorize-others コマンドの実行を提案させる形にしています。

_handover.md について

wiki-sync の進捗管理ファイルです。
どのファイルまで処理済みかを記録し、次回実行時の起点とします。
初回実行前は以下の内容で作成しておきます。

# 申し送りファイル
## 最終処理日時
（初期化 - 未処理）
## 最終処理ファイル
なし

2回目以降は wiki-sync 実行のたびに自動で上書き更新されます。

wiki-sync.tomlファイルの内容

description = "会話履歴をWiki化し申し送りファイルを更新する"

prompt = """
# Wiki同期タスク
以下の申し送りファイルの内容を確認し、未処理ファイルをWiki化してください。

## 申し送りファイルの現在の内容
!{cat $GEMINI_PROJECT_DIR/_handover.md}

## 未処理ファイルの特定方法
申し送りファイルの「最終処理ファイル」より辞書順で後のファイルが処理対象です。
ファイル名は日時を含むため、辞書順ソート＝日時順になります。
「最終処理ファイル」が「なし」の場合は全ファイルが処理対象です。

!{find $GEMINI_PROJECT_DIR/gemini-cli -name "*.md" | sed "s|$GEMINI_PROJECT_DIR/||" | sort}

## 保管庫パス
$GEMINI_PROJECT_DIR

## Wikiカテゴリ（どれか一つに分類）
以下のwiki/配下に存在するフォルダを分類先として使用すること。

!{ls -d $GEMINI_PROJECT_DIR/wiki/*/ | sed "s|$GEMINI_PROJECT_DIR/||" | sort}

## Wiki化のルール
- ファイル名：以下のルールでスネークケースで命名すること
  - サービス名・技術用語は英語
  - それ以外の説明部分は日本語OK
  - 例: rds_パラメータグループの設定方法.md
  - 例: cloud_run_デプロイ手順.md
  - 例: gemini_cli_hookの設定方法.md
- 会話形式ではなく知見・結論を体系的にまとめる
- GFM形式で記述する
- ファイルの先頭に以下のタグを設定すること
  1. 保存先フォルダ名（必須）
  2. ファイルの内容のメインとなるサービスや機能名（0〜2個、無理につけない）

例：wiki/gemini-cli/配下でhooksに関する内容の場合
---
tags:
  - gemini-cli
  - hooks
---

## スキップのルール
以下に該当する会話履歴はWiki化せずスキップすること。
- 天気・日常会話など技術的な知見を含まないもの
- Wiki化作業そのものの会話（本タスクの実行履歴）
- 雑談・挨拶のみで完結しているもの

## _handover.md の更新ルール
全ファイルの処理が完了したら上書き更新すること（追記不可）。
最終処理日時は以下コマンドの実行結果で更新すること。

!{date "+%Y-%m-%d %H:%M"}

_handover.mdの内容は以下のフォーマットのみとすること。
---
# 申し送りファイル

## 最終処理日時
yyyy-mm-dd hh:mm

## 最終処理ファイル
gemini-cli/yyyymmdd/hhmmss_xxxxxxxx.md
---

## 処理完了後の報告
_handover.md の更新が完了したら、作業完了をユーザーに報告すること。
報告内容にはWiki化したファイル数・スキップしたファイル数を含めること。
あわせてwiki/その他/配下を確認し、同じトピックのファイルが10件以上ある場合は
完了報告の中で /wiki-categorize-others の実行を提案すること。
"""

実行例

Wiki 化・スキップしたファイル数と Wiki 化したファイル名が出力されます。
wiki/その他/ の状況に応じ wiki-categorize-others の実行要否の提案も行われています。

wiki-categorize-others.toml

作成背景

wiki フォルダ配下にはあらかじめ使用頻度の高いカテゴリ用のフォルダを用意していますが、それ以外のナレッジは全てその他フォルダに格納されることとなります。
案件を重ねていけば、その他フォルダに同じトピックのファイルが溜まっていくことが予想できるので、その他フォルダから専用フォルダへ昇格させるコマンドを用意しました。

Custom command実行時の動きについて

その他フォルダ配下のファイルをファイル名と内容からトピックごとにグルーピングし、同じトピックが10件以上あるものを昇格候補として特定します。
候補が見つかった場合、新規フォルダ名と対象ファイルの一覧をユーザーに提示し、承認を得てから昇格作業を実行します。
承認後、新規フォルダの作成・ファイルの移動・Frontmatterタグ（Markdownファイル冒頭の --- で囲んだメタデータ内のタグ）の更新まで行い完了報告をします。
昇格候補がない場合はその旨を伝えて終了となります。

wiki-categorize-others.tomlファイルの内容

description = "wiki/その他/のファイルを集計し同じトピックが10件以上あれば独立フォルダに昇格させる"

prompt = """
# Wiki その他カテゴリ化タスク

## Step 1: その他フォルダの確認

以下のwiki/その他/配下のファイルを確認してください。

!{find $GEMINI_PROJECT_DIR/wiki/その他 -name "*.md" | sed "s|$GEMINI_PROJECT_DIR/||" | sort}

## Step 2: グルーピングと判断

ファイル名と内容からトピックをグルーピングしてください。
同じトピックが10件以上あるグループを昇格候補として特定してください。

## Step 3: ユーザーへの提案

昇格候補が見つかった場合、以下の形式でユーザーに提案してください。

---
以下のトピックが10件以上あります。独立フォルダへの昇格を提案します。

【トピック名】新規フォルダ名: wiki/xxx/
- その他/ファイル名1.md
- その他/ファイル名2.md
- その他/ファイル名3.md
...

上記をwiki/xxx/に移動してよいですか？
---

昇格候補がない場合は「現時点で昇格対象のトピックはありません」と伝えて終了してください。

## Step 4: ユーザーとの擦り合わせ

ユーザーからOKまたは要望が来たら内容を確認してください。
フォルダ名に異議があれば修正して再確認すること。

## Step 5: 実行

ユーザーの承認が得られたら以下を実行してください。

1. 新規フォルダを作成する（wiki/xxx/）
2. 対象ファイルを新規フォルダに移動する
3. 移動したファイルのFrontmatterタグを更新する（その他 → 新フォルダ名）
4. 完了報告をする（作成フォルダ名・移動ファイル数）

## 注意事項
- ユーザーの明示的な承認なしに実行しないこと
- 複数のトピックが昇格候補の場合は一つずつ確認すること
"""

実行例

wiki/その他/ 配下のファイルをトピックごとにグルーピングします。
OCI（Oracle Cloud Infrastructure）に関連するファイルが10件以上見つかったため、wiki/oci/ への昇格を提案・実行しています。

wiki-search.toml

作成背景

過去の AI とのやり取りで解決したことが、時間を経るとどう解決したか具体的な内容を思い出せないという場面がありました。
会話履歴を wiki-sync コマンドで体系化しているなら、それを情報源に調査し、どのような課題に対してどのような手を打ったかを振り返れるよう、このコマンドを用意しました。

Custom command実行時の動きについて

まず知りたいことを一問一答で確認します。
一度に全て聞かず段階的に進めることでユーザーから出来るだけ情報を引き出します。
ヒアリング完了後、Wiki から関連しそうな情報をファイル名から目星をつけ、その内容を確認します。
情報が見つかれば該当ファイル名を明示しつつ質問に沿って整理した回答をします。
情報がなかった場合、推測や一般知識での補完は行わず、該当する情報がなかった旨を返します。

wiki-search.tomlファイルの内容

description = "Wikiを情報源に質問に答える"

prompt = """
# Wiki検索タスク

あなたはユーザーの個人Wikiを参照する検索アシスタントです。

## 手順

### Step 1: ヒアリング
以下を順番に聞いてください。一度に全部聞かず、一問一答で進めること。

1. 何について調べたいですか？（例：AWSやTerraform、Gemini CLIなど）
2. 具体的にどんなことが知りたいですか？（例：設定方法、エラーの原因、概念の理解など）

### Step 2: Wiki検索
ヒアリング完了後、以下のWikiファイル一覧からテーマに関連しそうなファイルを特定してください。
ファイル名で目星をつけたら必ず中身を読んで内容を確認すること。

利用可能なWikiファイル一覧：
!{find $GEMINI_PROJECT_DIR/wiki -name "*.md" | sed "s|$GEMINI_PROJECT_DIR/||" | sort}

### Step 3: 回答

**情報があった場合：**
- 該当するWikiファイル名を明示する
- Wikiの内容をもとに回答する
- Wikiの内容をそのまま転記せず、質問に沿って整理して答える

**情報がなかった場合：**
- 「Wikiに該当する情報はありません」と明示する
- 推測や一般知識での補完は行わない
- 必要であれば `/wiki-sync` で最新の会話履歴をWiki化することを提案する
"""

実行例

何について、どんなことを知りたいか一問一答で確認します。
「Gemini CLI の Auto Memory の発動条件」について質問しており、Wiki 内の該当ファイルを参照した上で整理した回答をしています。

find-past-plans.toml

作成背景

Plan Mode では AI と設計を詰めた後、実装計画ファイルが作成されます。
業務において似た作業が発生した際に過去の実装計画を見つけることができれば、それを元に AI へ的確なコンテキストを渡せるため、このコマンドを用意しました。

Custom command実行時の動きについて

蓄積した実装計画ファイルから探したい作業内容を含むものを一問一答で確認します。
ヒアリング完了後、gemini-cli-plans フォルダ配下の実装計画ファイルを横断調査します。
ファイルパスに含まれるプロジェクト名と作業名を手がかりに関連するファイルを読み込み、対象が見つかった場合、該当ファイルを明示した上で作業の概要と参考になるポイントを整理し回答します。
対象が見つからなかった場合、推測や一般知識での補完は行わず見つからなかった旨を返します。

find-past-plans.tomlファイルの内容

description = "過去の実装計画から前例を探す"

prompt = """
# 前例検索タスク

あなたはユーザーの過去の実装計画を参照する検索アシスタントです。
以下の手順でユーザーから情報を引き出し、実装計画を横断して前例を探してください。

## Step 1: ヒアリング
以下を順番に聞いてください。一度に全部聞かず、一問一答で進めること。

1. どんな作業・対応の前例を探していますか？（例：CloudWatchの拡張、Terraformモジュールの改修など）
2. その対応でどんなことを参考にしたいですか？（例：実装パターン、設計の判断理由、注意点など）

## Step 2: 実装計画を横断検索

ヒアリング完了後、以下の実装計画ファイルを確認してください。

利用可能な実装計画一覧：
!{find $GEMINI_PROJECT_DIR/gemini-cli-plans -name "*.md" | sed "s|$GEMINI_PROJECT_DIR/||" | sort}

構造は gemini-cli-plans/プロジェクト名/日付/時刻_作業名.md の形式です。
プロジェクト名と作業名が前例探しの重要なヒントになります。
関連しそうなファイルを読んで前例を探してください。

## Step 3: 回答

**前例が見つかった場合：**
- 該当する実装計画のファイルパスを明示する
- どんな作業だったかを簡潔に説明する
- ユーザーが参考にしたい点（実装パターン・設計の判断理由・注意点）を整理して答える
- 今回の作業の参考になりそうな点を具体的に示す

**前例が見つからなかった場合：**
- 「過去の実装計画に該当する前例はありません」と明示する
- 推測や一般知識での補完は行わない
"""

実行例

どんな作業の実装計画を探しているか、何を参考にしたいか一問一答で確認します。
「AWS 環境での NACL 追加（三層構造）」の前例を検索し、該当する実装計画ファイルを特定した上で実装パターン・設計の判断理由・注意点を整理した回答をしています。

archive-history.toml / unarchive-history.toml

作成背景・Custom command実行時の動きについて

wiki-sync で体系化済みの会話履歴ファイルを後から見返すことは基本的にないため、月次単位でアーカイブするコマンドを用意しました。
archive-history では現在の日付から先月分の会話履歴フォルダを対象として圧縮内容をユーザーに提示します。
承認後、圧縮・元フォルダの削除を行い完了報告をします。
アーカイブしたファイルを参照したくなった場合に備え、unarchive-history で zip を展開し元の構造に戻せるようにもしています。

archive-history.tomlの内容

description = "会話履歴を月次単位で圧縮・アーカイブする"

prompt = """
# 会話履歴アーカイブタスク

あなたは会話履歴の整理を手伝うアシスタントです。
以下の手順でユーザーと擦り合わせてからアーカイブを実行してください。

## Step 1: 現状確認と提案

まず現在の日付と会話履歴フォルダの状況を確認してください。

現在の日付：
!{date "+%Y-%m-%d"}

会話履歴フォルダの一覧：
!{ls $GEMINI_PROJECT_DIR/gemini-cli/}

上記をもとに、以下の形式でユーザーに提案してください。

---
今は〇月なので、先月分（〇月）の会話履歴が圧縮対象になります。

例：対象フォルダ：
- gemini-cli/202604/xxxxxxxx.md
- gemini-cli/202604/xxxxxxxx.md
- ...（対象ファイル数と合計サイズも表示）

これらを `gemini-cli/archive_202604.zip` に圧縮しましょうか？
他にご要望があればお知らせください。
---

## Step 2: ユーザーとの擦り合わせ

ユーザーからOKまたは要望が来たら内容を確認してください。
要望がある場合は内容を復唱して再確認すること。

## Step 3: アーカイブ実行

ユーザーの承認が得られたら以下を実行してください。

1. 対象月のファイルをzipに圧縮する
   - 圧縮先：$GEMINI_PROJECT_DIR/gemini-cli/archive_202604.zip（月に合わせて変更、重複回避のため `archive_` を付与）
   - 圧縮元：Step 1で確認した各フォルダ
2. 圧縮の成功を確認したら、**Step 1で特定したフォルダのみ**を個別に削除する
   - 警告：`rm -rf gemini-cli/202604*` のような曖昧なワイルドカードは絶対に使用しないこと。
3. 完了報告をする（圧縮ファイル名・削除したフォルダ名・ファイル数）

## 注意事項
- 圧縮の成功を確認してから元フォルダを削除すること
- フォルダ削除時にzipファイルを巻き込まないよう、対象をディレクトリに限定し、パスを個別に指定すること
- 当月分は圧縮しないこと
- ユーザーの明示的な承認なしに実行しないこと
"""

unarchive-history.tomlの内容

description = "アーカイブ済みの会話履歴を解凍する"

prompt = """
# 会話履歴解凍タスク

あなたは会話履歴の整理を手伝うアシスタントです。
以下の手順でユーザーと擦り合わせてから解凍を実行してください。

## Step 1: 現状確認と提案

まずアーカイブ済みのzipファイルを確認してください。

アーカイブ済みファイル一覧：
!{ls $GEMINI_PROJECT_DIR/gemini-cli/archive_*.zip 2>/dev/null || echo "アーカイブファイルが見つかりません"}

上記をもとに、以下の形式でユーザーに提案してください。

---
現在以下のアーカイブファイルがあります。

例：
- gemini-cli/archive_202604.zip
- gemini-cli/archive_202603.zip
- ...

どの月のアーカイブを解凍しますか？
---

アーカイブファイルが存在しない場合は「解凍できるアーカイブファイルが見つかりません」と伝えて終了してください。

## Step 2: ユーザーとの擦り合わせ

ユーザーから解凍したい月が指定されたら以下を確認して復唱してください。

例：
- 解凍対象：gemini-cli/archive_202604.zip
- 解凍先：gemini-cli/202604/

内容を復唱してユーザーの承認を得てから実行してください。

## Step 3: 解凍実行

ユーザーの承認が得られたら以下を実行してください。

1. 指定されたzipファイルを解凍する
   - 解凍先：$GEMINI_PROJECT_DIR/gemini-cli/（元のフォルダ構造に戻す）
2. 解凍が成功したらzipファイルを削除する
3. 完了報告をする（解凍したファイル数・解凍先フォルダ名）

## 注意事項
- 解凍の成功を確認してからzipファイルを削除すること
- ユーザーの明示的な承認なしに実行しないこと
- 既に同名フォルダが存在する場合はユーザーに確認すること
"""

4.おわりに

Custom commands を使った会話履歴や実装計画ファイルの個人ナレッジベース化を紹介しました。
会話履歴をそのまま残しておくだけでは資産になりにくいですが、wiki-sync で体系化し、wiki-search で参照できる形にすることで、過去の知見を次の作業に活かせるようになります。
実装計画についても find-past-plans を使えば前例を見つけ出し、AI への的確なコンテキスト提供に活かせます。
情報を蓄積する仕組みを作ったら、それを活用する仕組みも整えることで、AI との作業の質がより高まるかと思います。