連載：AIに仕事を奪われる不安から始めるハーネス作成入門
第10回 ← 前回（9回）: RAG / Knowledge MCPがSE経験者に向いている理由

設計メモをKnowledge MCPへ登録する前提のMarkdownテンプレート

AIエージェント、RAG、ローカルLLM——学ぶべき技術が次々と登場し、「どこから手をつければいいのか」と迷っている方は少なくないでしょう。前回までの連載でハーネスの基本構造やプロンプト設計を扱ってきましたが、開発を進めるほど「あのとき決めた設計方針、どこに書いたっけ？」という場面が増えてきます。

今回は、設計メモを Knowledge MCP（知識管理サーバー）に登録することを前提としたMarkdownテンプレートを紹介します。「整理する型」を持つことで、学習の不安を軽減し、知識を再利用可能な資産に変えていきましょう。

📖 連載目次

回	タイトル	状態
1〜4	基礎編（不安の言語化〜ハーネスの概念）	✅
5〜9	実践編（プロンプト設計〜MCP連携）	✅
10	設計メモをKnowledge MCPへ登録する前提のMarkdownテンプレート	📖
11	ローカルLLMを使うべき場面と外部LLMに任せる場面	─
12	モデルルーターの疑似コードでLLM切替を設計する	─
13〜24	運用設計・テスト・発展編	─

1. なぜ設計メモを「登録」するのか

AIハーネス開発では、判断の連続です。「なぜこのプロンプト構成にしたのか」「どの条件でフォールバックするか」——こうした設計意図は、コードのコメントだけでは追いきれません。

設計メモを書くだけでなく、検索・再利用可能な形で保存することが重要です。Knowledge MCPは、テキストをベクトル化して意味検索できるナレッジベースを提供します。「あの設計判断の根拠は？」と聞けば、関連するメモが返ってくる環境を作れるのです。

2. Knowledge MCPとは

Knowledge MCPは、MCPプロトコルに準拠したナレッジ管理サーバーです。主な機能は以下の通りです。

機能	説明
`knowledge_upsert`	テキストを登録・更新する
`search_knowledge`	意味検索でナレッジを検索する
`knowledge_list`	登録済みナレッジの一覧を取得する
`knowledge_delete`	不要なナレッジを削除する

ポイントは、登録するテキストに構造を持たせることです。自由記述のメモをそのまま放り込むより、テンプレートに沿って書いた方が、後から検索したときのヒット精度が上がります。

3. テンプレート設計の考え方

テンプレートを設計するうえで、3つの方針を置きました。

YAMLフロントマターでメタ情報を機械可読にする
決まったセクション構成で検索ヒット率を上げる
最小限のフィールドで記入負荷を下げる

「テンプレートが重いと書かなくなる」——これは多くの開発者が経験する落とし穴です。必須フィールドは5つに絞り、残りはオプションとしました。

4. Markdownテンプレート全文

以下が、Knowledge MCPへの登録を前提としたテンプレートです。

---
title: "設計メモのタイトル"
category: "architecture | prompt | model | integration | operation"
status: "draft | review | approved | archived"
created: "2025-01-01"
updated: "2025-01-01"
tags:
  - タグ1
  - タグ2
---

## 背景・動機

この設計判断が必要になった背景を書きます。
「なぜこの問題に取り組むのか」を1〜3文で。

## 検討した選択肢

| 選択肢 | メリット | デメリット | 備考 |
|:---|:---|:---|:---|
| 案A | - | - | - |
| 案B | - | - | - |

## 決定事項

選んだ方針と、その理由を記述します。

## 影響範囲

- 影響するコンポーネント:
- 影響するプロンプト:
- 注意点:

## 次のアクション

- [ ] TODO項目1
- [ ] TODO項目2

5. 各フィールドの解説

YAMLフロントマター

フィールド	必須	説明
`title`	✅	検索時の表示名。具体的に書く
`category`	✅	5種類から選択。検索フィルタに使う
`status`	✅	メモのライフサイクルを管理
`created`	✅	作成日（ISO 8601形式）
`updated`	✅	最終更新日
`tags`	─	自由記述のタグ。3個以内を推奨

本文セクション

背景・動機: Knowledge MCPの意味検索で最もヒットしやすい部分です。「なぜ」を明確に書きましょう。
検討した選択肢: 後から「なぜ案Bを選ばなかったのか」を振り返れます。
決定事項: 結論を1〜2文で。長い議論の要約です。
影響範囲: 変更がどこに波及するかを記録します。
次のアクション: 設計メモから実装タスクへの橋渡しです。

6. Knowledge MCPへの登録手順

作成したMarkdownを knowledge_upsert で登録します。

# 擬似コード: Knowledge MCPへの登録例
import json

def register_design_memo(filepath: str, namespace: str = "design_memos"):
    """設計メモをKnowledge MCPに登録する"""
    with open(filepath, "r", encoding="utf-8") as f:
        content = f.read()
    
    # MCPツール呼び出し（実際のMCPクライアントに合わせて調整）
    result = mcp_client.call(
        server="pgvector-knowledge",
        tool="knowledge_upsert",
        arguments={
            "content": content,
            "namespace": namespace,
            "metadata": {
                "source": filepath,
                "type": "design_memo"
            }
        }
    )
    return result

登録したメモは search_knowledge で意味検索できます。

# 検索例
results = mcp_client.call(
    server="pgvector-knowledge",
    tool="search_knowledge",
    arguments={
        "query": "プロンプトのフォールバック設計",
        "namespace": "design_memos",
        "top_k": 5
    }
)

7. categoryフィールドの使い分け

5つのカテゴリは、AIハーネス開発の主要な設計領域に対応しています。

category	対象	例
`architecture`	全体構成・レイヤー設計	ハーネスのモジュール構成
`prompt`	プロンプト設計・テンプレート	システムプロンプトの方針
`model`	モデル選択・パラメータ	ローカルLLM vs API判断
`integration`	外部連携・MCP接続	ツール呼び出し設計
`operation`	運用・ログ・監視	エラーハンドリング方針

迷ったときは、その設計判断が一番影響するレイヤーで選んでください。完璧な分類よりも、書くことの方が大切です。

8. 実際の記入例

具体的にどう書くか、一例を示します。

---
title: "プロンプトのフォールバック戦略"
category: "prompt"
status: "approved"
created: "2025-06-01"
updated: "2025-06-03"
tags:
  - フォールバック
  - エラーハンドリング
---

## 背景・動機

LLMが期待するJSON形式で応答しないケースが発生した。
リトライ戦略を設計する必要がある。

## 検討した選択肢

| 選択肢 | メリット | デメリット | 備考 |
|:---|:---|:---|:---|
| 即時リトライ | 実装が簡単 | 同じエラーを繰り返す可能性 | - |
| プロンプト修正リトライ | 成功率が上がる | 実装コスト高 | 採用 |
| フォールバックモデル | 別モデルで補完 | コスト増 | 将来検討 |

## 決定事項

プロンプト修正リトライを採用。エラー内容をプロンプトに追記して再試行する。

## 影響範囲

- 影響するコンポーネント: LLMClient, PromptBuilder
- 影響するプロンプト: system_prompt_v2
- 注意点: リトライ上限は3回に設定

## 次のアクション

- [ ] PromptBuilderにリトライロジックを追加
- [ ] リトライ回数のログ出力を実装

9. 活用シーンと応用

このテンプレートは、個人開発だけでなくチーム開発でも活用できます。

個人開発: 1ヶ月後の自分が「なぜこう設計したか」を思い出せる
チーム共有: 新メンバーが設計経緯を検索できる
AIとの協働: エージェントが search_knowledge で過去の設計判断を参照して、一貫性のある提案をしてくれる

特に3つ目が、AIハーネス開発ならではの価値です。設計メモを登録しておくと、AIエージェント自身が過去の方針を踏まえた提案を出せるようになります。

10. よくある質問

Q: 全部の設計判断をメモにすべき？
A: いいえ。「後から理由を聞かれそうな判断」だけで十分です。判断基準は「1週間後に忘れていそうか」です。

Q: statusはどう運用する？
A: draftで書き始め、実装に反映したらapprovedへ。方針が変わったらarchivedにして新しいメモを作ります。

Q: Markdownファイルはどこに置く？
A: プロジェクトの docs/design/ ディレクトリを推奨します。Gitで履歴管理もできます。

11. まとめ

今回のポイントを整理します。

設計メモは「書く」だけでなく「検索可能にする」ことで価値が倍増する
YAMLフロントマター + 固定セクション構成のテンプレートで、記入負荷と検索精度のバランスを取る
Knowledge MCPの knowledge_upsert で登録し、search_knowledge で活用する
カテゴリは5種類。迷ったら「一番影響するレイヤー」で選ぶ
全部をメモにする必要はない。「1週間後に忘れそうな判断」が目安

学ぶべき技術が多いと感じるときこそ、まず手元の判断を整理する型を持つことが、次のステップへの土台になります。

🔜 次回予告

第11回：ローカルLLMを使うべき場面と外部LLMに任せる場面

設計メモを整理する型を手に入れたところで、次回はAIハーネス開発で避けて通れない「モデル選択」の判断基準に踏み込みます。ローカルLLM（Ollama等）とAPI LLM（OpenAI、Claude等）——コスト・レイテンシ・プライバシー・精度の4軸で比較し、プロジェクトの状況に合わせた選択ができるようになる判断基準表を提示します。

「全部APIでいいのでは？」「ローカルは設定が大変そう」——そんな疑問に、具体的なユースケースとともに答えます。

連載: AIに仕事を奪われる不安から始めるハーネス作成入門
著者: @singula00991 ｜週2回更新
次回（第11回）: ローカルLLMを使うべき場面と外部LLMに任せる場面