ナレッジの書き方と設計
ナレッジの書き方と設計
専門家（オーナー）がエージェントに教えるナレッジを、検索されやすく・回答に使われやすく・長くメンテしやすい 形で書くためのガイドです。画面操作の詳細は「ナレッジエディターの使い方」「ナレッジ一覧とインポート」を参照してください。
基本方針
| 方針 | 説明 |
|---|---|
| 1 ナレッジ = 1 テーマ | 1 ページに複数の独立したトピックを詰め込まない。別テーマは別ナレッジに分ける |
| 見出しで区切る | セクション（## 見出し）単位で内容を整理する。長い段落は分割する |
| 事実と手順を分ける | 「とは何か」と「どう操作するか」を同じ見出しに混ぜない |
| 陳腐化を想定する | 日付・バージョン・「現在」「最新」など時間依存の表現は、更新しやすい箇所にまとめる |
iknow.dev の運用サイクルは 一覧で全体把握 → エディターで内容確認 → チャットで届ける です。最初から読みやすい構造にしておくと、後のメンテナンスが楽になります。チャットで効かないときの切り分けは No.5.9 を参照。
No（章・節・項番号）の付け方
ナレッジ一覧の 既定の並び順 は No 昇順です（例: 1 → 1.1 → 1.2 → 2）。
| ルール | 内容 |
|---|---|
| 形式 | ドット区切り数字（例 1.2.3）。最大 5 階層 / 20 文字 |
| 用途 | マニュアル体系・手順書の章立てに向く |
| 省略 | 関連性がタグやリンクで足りるなら No は空でもよい |
例（iknow Navigator）: 大分類 1.x ナビゲーション → 2.x 基礎 → 3.x エージェント一覧・チャット履歴・利用分析・アカウント設定 → … のように、カテゴリ.連番 で体系化する（No.0 目次参照）。
タグと関連ナレッジの使い分け
| タグ | 関連ナレッジ | |
|---|---|---|
| 意味 | カテゴリ（このページはどの分野か） | 特定ページ同士の関係（相互参照・派生・詳細版） |
| 例 | マイページ, チャット, MCP |
「はじめかた」と「エージェント一覧」（No.3.1） |
| 付け方 | エディターのタグ行、または一覧の一括タグ設定 | エディターの「関連ナレッジ」ボタン、または MCP からリンク |
| 検索 | 一覧のタグ絞り込み（AND 条件） | エディター右ドロワー・MCP get-knowledge の links |
タグで「A と B が関連」と表現しようとしないでください。特定のナレッジ同士 が関連するときは 関連ナレッジリンク を使います。
本文形式：Markdown とテーブル形式 JSON
| 形式 | 向いている内容 | 編集方法 |
|---|---|---|
| Markdown | 説明文、手順、FAQ、概念 | エディターのセクション編集（Editor.js） |
| テーブル形式 JSON | 列が固定された表データ（一覧、早見表、数値データ） | 表形式エディタ |
Markdown の制約
| 制約 | 内容 |
|---|---|
| 本文上限（手動保存・文字数） | 262,144 文字（画面エディター・REST API。超過時はバリデーションエラー） |
| 本文上限（手動保存・トークン） | 80,000 トークン（既定。画面・REST・MCP 共通。超過時はバリデーションエラー） |
| 本文上限（インポート） | 約 80,000 トークン超は別ナレッジへ自動分割（保存エラーにはならない） |
| HTML 禁止 | HTML タグは使えない |
| 見出しチャンク | 内部では見出し単位で約 8,000 トークン前後に分割（検索用）。見出しを小さく区切る と検索精度が上がる |
テーブル形式 JSON の書き方
本文全体を 配列の配列 で書きます。1 行目がヘッダー、2 行目以降がデータです。
[
["項目", "内容"],
["上限", "262,144 文字"]
]
チャット回答向けの拡張記法
エージェントの回答は Markdown です。ナレッジ本文に次の 専用コードブロック を書いておくと、チャットでも同様に描画されます。
| コードブロック | 用途 |
|---|---|
mermaid |
フローチャート、シーケンス図、ER 図 など |
chart |
パイ・棒・折れ線・ドーナツ・レーダーチャート |
gantt |
ガントチャート |
json |
配列の配列ならテーブル表示 |
手順や関係性は 表 + 箇条書き、流れは mermaid、数値比較は chart — 用途に応じて使い分けると回答が読みやすくなります。
新規ナレッジ作成の流れ
- 既存を確認 — 同テーマのナレッジがないか、一覧の検索または MCP の
search-knowledgeで探す（あれば追記・更新の方がよい） - 一覧の「新規」 — 初期本文はエージェントの テンプレート から作られる（「エージェント設計（プロンプト・テンプレート）」参照）
- タイトル・No・タグ — 一覧で見つけやすい名前とカテゴリを付ける
- セクションを書く — 見出し単位で本文を追加
- 関連ナレッジをリンク — 本文中で参照する他ページと相互リンク
インポートとの使い分け
| やりたいこと | おすすめ |
|---|---|
| ゼロから書く | エディターで新規作成 |
| 既存 Markdown / 社内ドキュメントを取り込む | 一覧のインポート（ファイル / GitHub / Qiita / Web URL） |
| IDE 内でコードを見ながら書く | MCP（Cursor / Claude） |
インポート後も、No・タグ・関連ナレッジの整理はエディターまたは MCP で行ってください。