AIエージェント時代のナレッジベース設計

#ナレッジベース #ai #コーディングエージェント #ドキュメント設計 #スケーラビリティ #フラクタル構造

AIエージェント利用を想定したプロダクト開発の組織的ナレッジベース設計

Claude Code、Cursor、Windsurf、Clineなどのコーディングエージェントが普及する中で、「AIと人間が共有するナレッジベース」の設計が重要になってきている。

個人のメモから始まり、チームの開発ドキュメント、さらには組織全体のプロダクト横断知識まで、どう構造化すれば効率的に管理できるのか？

この記事では、フラクタル構造というアプローチで、個人からチーム、組織までスケールするナレッジベースの設計を提案する。

なぜナレッジベース設計が重要なのか

AIエージェントは、与えられた情報の質に大きく依存する。以下のような課題に直面する：

課題1: 領域特化エージェントの失敗パターン

「技術知識エージェント」「ビジネス知識エージェント」のように領域で分けると：

領域の境界が曖昧（「RAG」は技術？ビジネス戦略？）
ユーザーがどのエージェントを呼ぶべきか判断できない
横断的な知識が分断される

教訓: エージェントは**領域特化（何について）**ではなく、**タスク特化（何をするか）**で設計すべき

課題2: ツール依存のナレッジ

.claude/AGENT.md にプロダクト固有の知識を書いてしまうと：

CursorやWindsurfからは見えない
チームメンバーが直接読めない
ツール移行時に知識が失われる

教訓: プロダクト知識はツール非依存な場所に配置すべき

課題3: スケールしない構造

個人のメモは良いが、チームで共有する段階で破綻：

用語の定義が曖昧
プロダクト間の連携知識がバラバラ
更新時にどこを変えるべきか不明

教訓: 最初からスケール可能な構造を意識すべき

フラクタル構造：各レベルで同じパターンを繰り返す

フラクタル構造とは、各レベル（個人、プロダクト、組織）で同じディレクトリ構成を保ちながら、上位レベルを参照できる設計のこと。

レベル0: 個人のナレッジベース

Obsidianなどの個人メモ：

personal-vault/
├── daily/           # 日次ノート
├── sources/         # 外部記事のメモ
├── articles/        # 自分の記事
└── notes/           # 概念ノート（ナレッジの本体）

特徴:

自分だけが使う
自由な構造でOK
AIエージェント（Claude Code + Exploreエージェント）で検索

スケールの限界: 〜300ノートまで

レベル1: プロダクトレベルのナレッジベース

チームで共有するプロダクト固有の知識：

product-a/
├── src/              # ソースコード
├── docs/
│   ├── development/  # 開発者向けドキュメント
│   │   ├── GLOSSARY.md     # 用語集
│   │   ├── PRINCIPLES.md   # 設計原則
│   │   ├── CONVENTIONS.md  # コーディング規約
│   │   └── architecture/   # アーキテクチャ詳細
│   │       ├── auth.md
│   │       ├── api.md
│   │       └── integration/  # 他プロダクトとの統合
│   │           └── product-b.md
│   ├── features/     # 機能別ドキュメント
│   └── troubleshooting/
├── .claude/
│   └── AGENT.md      # Claude Code固有の指示
├── .cursor/
│   └── rules         # Cursor固有のルール
└── .windsurf/
    └── rules.md      # Windsurf固有の設定

重要な設計判断:

プロダクト知識 vs ツール固有指示の分離

場所	内容	対象
`docs/development/`	プロダクト知識（用語、原則、アーキテクチャ）	全ツール + 人間
`.claude/AGENT.md`	Claude Code固有の指示（skillの使い方など）	Claude Codeのみ
`.cursor/rules`	Cursor固有の設定	Cursorのみ

例: .claude/AGENT.md の正しい書き方

❌ 悪い例（プロダクト知識を.claude/に書く）:

# moltbotの用語集
- moltbot integration: Claudeとのメモリ統合機能
- 認証フロー: Slack OAuth → JWT → セッション管理

→ Cursorからは見えない

✅ 良い例（ツール固有指示のみ）:

# Claude Code 使用ガイド

## プロダクト固有の知識

`docs/development/` を参照してください。

特に以下のファイルは必読：
- `docs/development/GLOSSARY.md` - 用語集
- `docs/development/PRINCIPLES.md` - 設計原則

タスク開始時に、まずExploreエージェントで関連ドキュメントを探してください。

docs/development/ の構成

GLOSSARY.md（用語集）:

# 用語集

## moltbot integration
- **定義**: Claudeとのメモリ統合機能
- **実装場所**: `src/integrations/moltbot/`
- **関連ドキュメント**: `docs/features/moltbot-integration.md`
- **エイリアス**: NI

## 認証フロー
- **定義**: Slack OAuth → JWT発行 → セッション管理の3段階プロセス
- **実装場所**: `src/auth/flow.ts`
- **関連ドキュメント**: `docs/development/architecture/auth.md`
- **重要**: 「ログイン」は認証フローの1段階目のみを指す

PRINCIPLES.md（設計原則）:

# 設計原則

すべてのコーディングエージェントは、以下の原則を遵守してください。

## API設計
1. すべてのAPIはRESTfulであること
2. エンドポイント命名: `/api/{version}/{resource}`
3. エラーレスポンスは必ず日本語メッセージを含める

## 状態管理
- Zustandを使用（ReduxやContextAPIは禁止）
- グローバルステートは `src/stores/` 配下に配置

## アンチパターン
以下は絶対に避けること：
- ❌ 認証トークンをlocalStorageに保存
- ❌ エラーメッセージに内部実装の詳細を含める

CONVENTIONS.md（コーディング規約）:

# コーディング規約

## 命名規則
- 関数名: camelCase
- コンポーネント: PascalCase
- 定数: UPPER_SNAKE_CASE

## コード例

正しい認証フローの実装：
```typescript
// ✅ 正しい実装
const authFlow = new AuthenticationFlow({
  slackClient: slackOAuthClient,
  jwtSecret: process.env.JWT_SECRET
});

// ❌ 間違った実装
const token = localStorage.getItem('token'); // これは禁止


**architecture/integration/product-b.md**（他プロダクトとの統合）:
```markdown
# Product B (Knowledge API) との統合

## 概要
Product AはProduct Bを使用してナレッジデータを取得・保存します。

## エンドポイント
- **ベースURL**: `https://api.yourorg.com/knowledge/v1`
- **認証**: OAuth 2.0

## API呼び出し例
```typescript
import { KnowledgeClient } from '@yourorg/knowledge-api-client';

const client = new KnowledgeClient({
  auth: authService,
});

const results = await client.search({
  query: 'RAG implementation',
});


### レベル2: 組織レベルのナレッジベース

複数のプロダクトが存在する場合、**組織共通の知識**を一元管理する：

organization-knowledge/
├── docs/
│ ├── development/
│ │ ├── GLOSSARY.md # 組織共通用語
│ │ ├── PRINCIPLES.md # 組織共通の設計原則
│ │ └── architecture/
│ │ ├── auth-standard.md # 認証の組織標準
│ │ ├── integration-patterns.md # プロダクト間連携パターン
│ │ └── error-codes.md # 共通エラーコード
│ └── products/
│ └── integration-map.md # プロダクト間の依存関係マップ


**organization-knowledge/docs/development/GLOSSARY.md**:
```markdown
# 組織共通用語集

すべてのプロダクトで共通して使用される用語を定義します。

## 認証・認可

### OAuth フロー
- **定義**: 組織標準のOAuth 2.0実装パターン
- **実装**: すべてのプロダクトは `@yourorg/auth-lib` を使用すること
- **詳細**: `architecture/auth-standard.md` を参照

### API Gateway
- **定義**: Kong APIゲートウェイを使用した統一エンドポイント
- **URL**: `https://api.yourorg.com`
- **責務**: 認証、レート制限、ルーティング

## プロダクト間連携

### Event Bus
- **定義**: RabbitMQベースの非同期メッセージング
- **実装**: `@yourorg/event-bus`
- **パターン**: `architecture/integration-patterns.md` を参照

### Service Mesh
- **定義**: Istioベースのサービス間通信
- **用途**: プロダクト間の同期通信

organization-knowledge/docs/products/integration-map.md:

# プロダクト間統合マップ

## プロダクト一覧

| プロダクト | 責務 | 依存先 |
|-----------|------|--------|
| Product A (moltbot) | ナレッジボット | Product B (Knowledge API) |
| Product B (Knowledge API) | ナレッジ管理 | Product C (User Service) |
| Product C (User Service) | ユーザー管理 | - |

## 統合パターン

### Product A → Product B
- **連携方法**: REST API
- **認証**: OAuth 2.0 (組織標準)
- **データ形式**: JSON
- **詳細**: 各プロダクトの `docs/development/architecture/integration/` を参照

### Product B → Product C
- **連携方法**: Event Bus (非同期)
- **イベント**: `user.created`, `user.updated`
- **スキーマ**: `@yourorg/event-schemas`

上位参照の仕組み：UPSTREAM.md

各レベルが上位レベルを明示的に参照するために、UPSTREAM.md を配置する。

product-a/docs/UPSTREAM.md:

# 上位ナレッジへの参照

このプロダクトは、以下の上位ナレッジベースを参照します。

## 組織レベル

**場所**: `.knowledge/org/` (git submodule)

**必読ドキュメント**:
- `.knowledge/org/docs/development/GLOSSARY.md` - 組織共通用語
- `.knowledge/org/docs/development/PRINCIPLES.md` - 組織の設計原則
- `.knowledge/org/docs/products/integration-map.md` - プロダクト間の関係

## 用語の優先順位

同じ用語が複数のレベルで定義されている場合：

1. **プロダクト固有定義** (`docs/development/GLOSSARY.md`) - 最優先
2. **組織共通定義** (`.knowledge/org/docs/development/GLOSSARY.md`)

例：
- 「認証フロー」
  - 組織レベル: OAuth 2.0の一般的なフロー
  - Product A: Slack OAuth → JWT発行 → セッション管理（Product A固有）
  - → Product Aでは、Product A固有の定義を使用

## コーディングエージェント向け指示

タスク開始時の手順：
1. このファイル（UPSTREAM.md）を読む
2. `.knowledge/org/` の関連ドキュメントを確認
3. プロダクト固有の `docs/development/` を読む
4. 不明な用語は、プロダクト固有 → 組織共通の順で検索

product-a/docs/development/GLOSSARY.md（用語の上書き例）:

# Product A 用語集

**重要**: 組織共通用語は `.knowledge/org/docs/development/GLOSSARY.md` を参照してください。
このファイルにはProduct A固有の用語のみを記載します。

## Product A 固有用語

### moltbot
- **定義**: Slack上で動作するナレッジボット（Product A固有）
- **実装場所**: `src/bot/`
- **依存プロダクト**: Product B (Knowledge API)
- **統合詳細**: `architecture/integration/product-b.md` を参照

## 組織共通用語の上書き

以下の用語は組織共通定義とは異なる意味で使用します：

### 認証フロー（Product A固有定義）
- **組織共通**: 一般的なOAuth 2.0フロー（`.knowledge/org/docs/development/GLOSSARY.md` を参照）
- **Product A**: Slack OAuth → JWT発行 → セッション管理の3段階
- **理由**: Slackボットであるため、Slack固有の認証が必要
- **実装**: 組織標準の `@yourorg/auth-lib` をラップした `src/auth/slack-flow.ts`

全体構造：フラクタルパターン

最終的な全体構造：

organization-knowledge/          # 組織レベル（Level 0）
├── docs/
│   ├── development/
│   │   ├── GLOSSARY.md
│   │   ├── PRINCIPLES.md
│   │   └── architecture/
│   │       └── integration-patterns.md
│   └── products/
│       └── integration-map.md
│
product-a/                        # プロダクトA（Level 1）
├── docs/
│   ├── development/
│   │   ├── GLOSSARY.md          # プロダクトA固有用語
│   │   ├── PRINCIPLES.md        # プロダクトA固有原則
│   │   └── architecture/
│   │       ├── auth.md
│   │       └── integration/
│   │           └── product-b.md
│   └── UPSTREAM.md              # 上位ナレッジへの参照
├── .claude/AGENT.md             # Claude Code固有指示
├── .cursor/rules                # Cursor固有設定
└── .knowledge/
    └── org/                     # git submodule
│
product-b/                        # プロダクトB（Level 1）
├── docs/
│   ├── development/
│   │   ├── GLOSSARY.md
│   │   └── architecture/
│   └── UPSTREAM.md
└── .knowledge/org/
│
monorepo-example/                 # モノレポの場合
├── packages/
│   ├── service-x/               # サービスX（Level 2）
│   │   ├── docs/development/
│   │   └── UPSTREAM.md          # packages共通 + org を参照
│   └── service-y/
├── docs/development/            # モノレポ共通知識
└── .knowledge/org/

組織ナレッジの配信方法

組織レベルのナレッジを各プロダクトに配信する方法：

方法1: git submodule（推奨：変更頻度が高い場合）

# 組織ナレッジをsubmoduleとして追加
cd product-a
git submodule add https://github.com/yourorg/organization-knowledge.git .knowledge/org
git submodule update --init --recursive

# 更新
git submodule update --remote .knowledge/org

利点:

バージョン管理が厳密（各プロダクトが特定のコミットを参照）
ローカルで編集・テスト可能
CI/CDで自動更新可能

欠点:

submoduleの更新を忘れがち
チーム全員がsubmoduleに慣れる必要がある

方法2: npm package（推奨：安定している場合）

# 組織ナレッジをnpmパッケージ化
cd organization-knowledge
npm init -y

// organization-knowledge/package.json
{
  "name": "@yourorg/knowledge",
  "version": "1.2.3",
  "files": ["docs/**/*"],
  "publishConfig": {
    "registry": "https://npm.pkg.github.com"
  }
}

# 各プロダクトでインストール
cd product-a
npm install @yourorg/knowledge
ln -s node_modules/@yourorg/knowledge .knowledge/org

利点:

npm/pnpmの標準ワークフロー
バージョン管理が明確（semver）
CI/CDと統合しやすい

欠点:

パッケージ公開の手間
ローカル編集がやりにくい

方法3: ハイブリッド

# 開発環境：submoduleで直接編集
git submodule add ... .knowledge/org

# CI/CD：npmパッケージから取得
npm install @yourorg/knowledge
ln -s node_modules/@yourorg/knowledge .knowledge/org

コーディングエージェント向けの指示

各ツールの設定ファイルから、共通ナレッジベースを参照させる：

Claude Code (.claude/AGENT.md)

# Claude Code 使用ガイド

## プロダクト固有の知識

**重要**: このプロジェクトは階層的なナレッジベースを使用しています。

### ナレッジベースの構造

1. **組織レベル**: `.knowledge/org/docs/`
   - 全プロダクト共通の用語・原則・パターン

2. **プロダクトレベル**: `docs/development/`
   - Product A固有の用語・アーキテクチャ

### タスク開始時の手順

1. `docs/UPSTREAM.md` を読んで、上位ナレッジの場所を確認
2. Exploreエージェントで関連ドキュメントを検索：
   - まず `docs/development/` から検索
   - 見つからなければ `.knowledge/org/docs/` も検索
3. 用語の定義を確認する際の優先順位：
   - Product A固有定義（`docs/development/GLOSSARY.md`）
   - 組織共通定義（`.knowledge/org/docs/development/GLOSSARY.md`）

タスク実行時はコンテキストを効率的に活用し、Exploreエージェントで必要な情報を段階的に検索していく。

### 検索のベストプラクティス

**Example: 「認証フロー」について調べる**

ステップ1: プロダクト固有を検索

Explore agent: "docs/development/ 配下で '認証フロー' を検索"

ステップ2: 見つからなければ組織共通を検索

Explore agent: ".knowledge/org/docs/ 配下で '認証フロー' を検索"


**Example: プロダクト間統合を実装**

ステップ1: 統合先の情報を確認

Read: "docs/development/architecture/integration/product-b.md"

ステップ2: 組織標準パターンを確認

Read: ".knowledge/org/docs/development/architecture/integration-patterns.md"

ステップ3: 実装

Cursor (.cursor/rules)

## プロダクト固有の知識

`docs/development/` ディレクトリを参照してください。
特に GLOSSARY.md, PRINCIPLES.md, CONVENTIONS.md は必読。

組織共通の知識は `.knowledge/org/docs/development/` を参照。

## 検索時の優先順位
1. プロダクト固有（`docs/development/`）
2. 組織共通（`.knowledge/org/docs/development/`）

Windsurf (.windsurf/rules.md)

## プロダクト固有の知識

`docs/development/` ディレクトリを参照してください。
実装前に必ず用語集と設計原則を確認すること。

組織レベルの参照情報は `docs/UPSTREAM.md` を参照。

RAGとの関係

RAG（Retrieval-Augmented Generation）は、このナレッジベース構造と相性が良い。

RAGが必要になるタイミング

[[RAGのアーキテクチャとデータ登録・ユースケース]]で述べた基準を適用：

規模	推奨アプローチ
個人レベル（〜300ノート）	Exploreエージェント + 全文読み込み
プロダクトレベル（〜300ファイル）	Exploreエージェント + 全文読み込み
組織レベル（300ファイル以上）	RAG導入を検討
複数プロダクト横断（1000ファイル以上）	RAG必須

RAG導入時の設計

フラクタル構造を保ったまま、RAGを追加：

organization-knowledge/
├── docs/                    # 従来通りのMarkdown
│   └── development/
└── vector-db/              # RAG用のベクトルDB設定
    ├── embeddings/         # 事前生成した埋め込み
    ├── schema.json         # メタデータスキーマ
    └── README.md           # RAGセットアップガイド

各プロダクトで：

// RAGクライアント例
import { OrgKnowledgeRAG } from '@yourorg/knowledge/rag';

const rag = new OrgKnowledgeRAG({
  level: ['org', 'product-a'], // 検索対象レベル
  filters: { products: ['product-a', 'product-b'] } // 関連プロダクトのみ
});

const results = await rag.search('認証フローの実装方法');

重要な設計判断:

AGENT.md、GLOSSARY.md、PRINCIPLES.mdはRAGに入れない
- これらは常にLLMに直接読ませる（重要度が高いため）
architecture/、features/だけをRAG化
- [[チャンキング]]: 見出し単位（## や ###）で分割
- メタデータにファイル名、更新日、プロダクト名を含める
[[ハイブリッド検索]]必須
- プロダクト固有用語はキーワード検索で拾う
- 概念的な検索は[[ベクトルデータベース]]を活用

チーム運用のベストプラクティス

1. 新機能実装時のワークフロー

1. 開発者が docs/development/ に初期ドキュメント作成
   ↓
2. PR時にレビュアーが「GLOSSARY.mdに用語定義が必要か？」チェック
   ↓
3. 必要ならGLOSSARY.mdにも追記
   ↓
4. 組織レベルの用語と重複する場合、UPSTREAM.mdの上書きルールを確認

2. 仕様変更時のワークフロー

1. 関連ドキュメントを更新（docs/development/architecture/）
   ↓
2. Claude Codeに「docs/配下で古い情報がないか確認して」と依頼
   ↓
3. 矛盾があれば統一
   ↓
4. 組織レベルの定義と乖離した場合、GLOSSARY.mdで上書き定義を明記

3. 月次レビュー（推奨）

1. Claude Codeに「GLOSSARY.mdと実際のコードに乖離がないか確認して」
   ↓
2. 乖離があれば修正
   ↓
3. 組織ナレッジ（.knowledge/org/）の更新を確認
   ↓
4. 必要なら git submodule update または npm update

4. 組織ナレッジの更新フロー

1. 組織ナレッジのリポジトリ（organization-knowledge）でPR作成
   ↓
2. 複数プロダクトの代表者がレビュー
   ↓
3. マージ後、npmパッケージ or submoduleタグを更新
   ↓
4. 各プロダクトが新バージョンを取り込む

まとめ：フラクタル構造の5原則

このナレッジベース設計の核心を5つの原則にまとめる：

1. 各レベルで同じ構造を保つ

docs/
├── development/
│   ├── GLOSSARY.md      # 用語集
│   ├── PRINCIPLES.md    # 設計原則
│   ├── CONVENTIONS.md   # コーディング規約
│   └── architecture/    # アーキテクチャ詳細

この構造を、個人レベル、プロダクトレベル、組織レベルで繰り返す。

2. 上位参照は UPSTREAM.md で明示

各レベルが上位を明示的に参照：

プロダクトレベル → 組織レベル
モノレポ内サービス → モノレポ共通 → 組織レベル

3. 用語の上書きルール

下位レベルが上位を上書き可能
上書きする場合は理由を明記
優先順位: プロダクト固有 > 組織共通

4. プロダクト知識とツール固有指示を分離

プロダクト知識 → docs/development/（ツール非依存）
ツール固有指示 → .claude/, .cursor/, .windsurf/（ツール依存）

5. スケールに応じた検索方法

小規模（〜300ファイル）: Exploreエージェント + 全文読み込み
中規模（300〜1000ファイル）: 構造化されたドキュメントナビゲーション
大規模（1000ファイル以上）: セマンティック検索（構造は変えずに検索方法を変更）

おわりに

AIエージェントと人間が共に働く時代において、ナレッジベースは「AIが読むもの」ではなく「AIと人間が共有する知識基盤」である。

フラクタル構造は、個人のメモから始めて、チーム、組織へとスムーズにスケールできる。最初から完璧な構造を目指す必要はない。まずは docs/development/GLOSSARY.md から始めて、必要に応じて拡張していけば良い。

重要なのは、知識を一箇所に集約し、明確なルールで参照できる状態を保つことだ。それができれば、どのコーディングエージェントを使っても、どのチームメンバーが見ても、同じ知識にアクセスできる。

この記事で提案した構造が、あなたのチームのナレッジ管理の参考になれば幸いだ。

抽出された概念

この記事の主要な概念は以下の既存ノートでカバーされています：

階層的ナレッジベース - 個人・プロダクト・組織レベルの階層構造
フラクタル - 各レベルで同じ構造を繰り返す設計パターン
ツール非依存なドキュメント - プロダクト知識とツール固有指示の分離
タスク特化エージェント - 領域特化ではなくタスク特化でエージェントを設計する原則