Knowledge Base Builder

ナレッジベースビルダー

ナレッジベースビルダーのスキルは、AI エージェントが効果的に検索し、活用できるナレッジベースの作成、構造化、保守を支援します。プロジェクトドキュメントから暗黙知まで、散在する情報を整理されたアクセス可能なナレッジに変換し、AI のパフォーマンスとチームの生産性を高めます。

このスキルでは、ナレッジの抽出、整理、構造化、保守について説明します。さまざまなナレッジ形式（ドキュメント、コードコメント、意思決定ログ、スキーマ）を理解し、適切な保存先（Markdown ファイル、ナレッジグラフ、データベース）の選択を支援するとともに、ナレッジを最新かつ有用な状態に保ちます。

新しいプロジェクトの開始、複雑なシステムへの AI の導入、組織内のナレッジの保存、またはより適切なコンテキストを通じた AI エージェントの有効性の向上に、このスキルを活用してください。

主なワークフロー

ワークフロー 1：ゼロからナレッジベースを構築する

1. ナレッジベースの目的を定義します：
   • 誰が使いますか？（AI エージェント、開発者、またはその両方）
   • どのような問題を解決しますか？
   • スコープと境界は何ですか？
2. ナレッジソースを特定します：
   • 既存のドキュメント
   • コードリポジトリ
   • チーム内の会話
   • 意思決定記録
   • 暗黙知
3. 関連情報を抽出します：
   • 主要な概念と関係性
   • アーキテクチャ上の意思決定
   • ドメイン用語
   • 一般的なパターン
   • トラブルシューティングの知識
4. ナレッジを構造化します：
   • 整理方法（階層型、グラフ型、ハイブリッド型）を選びます
   • カテゴリ／分類体系を定義します
   • 関係性を確立します
   • メタデータスキーマを作成します
5. 利用しやすい形式に整えます：
   • ドキュメントには Markdown
   • 関係性にはナレッジグラフ
   • 構造にはスキーマファイル
   • 実装にはコードコメント
6. ナレッジベースに情報を登録します：
   • 初期コンテンツを作成します
   • 関連する概念をリンクします
   • 例を追加します
   • 参照情報を含めます
7. アクセス性を検証します：
   • AI は情報を見つけられますか？
   • コンテキストは十分ですか？
   • 関係性は明確ですか？
8. 保守プロセスを確立します

ワークフロー 2：コードベースからナレッジを抽出する

1. コードベースの構造を分析します：
   • アーキテクチャパターン
   • モジュール構成
   • 主要な抽象化
   • データフロー
2. 抽出可能なナレッジを特定します：
   • 設計上の意思決定
   • API コントラクト
   • データモデル
   • ビジネスロジック
   • エッジケース
3. ドキュメントを生成します：
   • アーキテクチャの概要
   • コンポーネントの説明
   • API リファレンス
   • データ辞書
   • インテグレーションガイド
4. ナレッジグラフを作成します：
   • エンティティ（モジュール、サービス、モデル）
   • 関係性（依存する、実装する、拡張する）
   • 観察事項（目的、制約、パターン）
5. コードにリンクします：
   • 参照用のファイルパス
   • 関数シグネチャ
   • 設定ファイルの場所
6. 同期を維持します：
   • コードの変更時に更新します
   • コードと合わせてナレッジをバージョン管理します
   • 可能な場合は自動化します

ワークフロー 3：プロジェクトのナレッジを整理する

1. 既存のナレッジを監査します：
   • どのようなドキュメントがありますか？
   • 何が不足していますか？
   • 何が古くなっていますか？
   • 何が散在していますか？
2. 構造を定義します：
   • ドキュメントの階層
   • ファイルの整理方法
   • 命名規則
   • 相互参照の方法
3. 中核となるドキュメントを作成します：
   • README.md（概要、利用開始方法）
   • ARCHITECTURE.md（システム設計）
   • DECISIONS.md（ADR）
   • PIPELINE_STATUS.md（プロジェクトの状態）
   • CONTRIBUTING.md（開発ガイド）
4. 規約を確立します：
   • ドキュメントのテンプレート
   • メタデータの標準
   • 更新手順
   • レビュープロセス
5. コンテンツを追加します：
   • 既存のドキュメントを移行します
   • 新しいコンテンツで不足を補います
   • 関連するドキュメントをリンクします
   • ナビゲーションを追加します
6. AI と連携します：
   • コンテキストに追加します
   • ナレッジグラフのエントリを作成します
   • 検索できるようにします
   • アクセス性をテストします

ワークフロー 4：ナレッジグラフの構築

1. 特定する：エンティティ
   • 重要な概念は何ですか？
   • 何を記憶しておく必要がありますか？
   • どのようなものに関連性がありますか？
2. 定義する：エンティティの種類
   • プロジェクト（リポジトリ、サービス、アプリ）
   • コンポーネント（モジュール、機能、関数）
   • 人物（チームメンバー、関係者）
   • 意思決定（アーキテクチャ上の選択）
   • プロセス（ワークフロー、手順）
   • リソース（ドキュメント、ツール、依存関係）
3. 抽出する：観察事項
   • 各エンティティに関する事実
   • プロパティと属性
   • コンテキストと目的
   • ステータスと状態
4. マッピングする：関係性
   • エンティティ間のつながり
   • 関係の種類
   • 方向性
   • 強さ／重要度
5. ナレッジグラフに保存する：
   • Memory MCP を使用する
   • エンティティを作成する
   • 関係を作成する
   • 観察事項を追加する
6. クエリを実行して検証する：
   • エンティティを見つけられますか？
   • 関係性に一貫性はありますか？
   • 情報は完全ですか？
7. 時間の経過とともに保守する：
   • 新しいエンティティを追加する
   • 観察事項を更新する
   • 新しい関係を追加する
   • 古くなった情報を整理する

ワークフロー 5：ナレッジベースの保守

1. ナレッジの健全性を監視する：
   • 使用頻度
   • 古くなったコンテンツ
   • 網羅性の不足
   • ユーザーからのフィードバック
2. 定期的に更新する：
   • コードの変更を反映する
   • 新しい意思決定を記録する
   • 新しいパターンを追加する
   • 非推奨の情報を削除する
3. 定期的にレビューする：
   • 四半期ごとのナレッジ監査
   • 正確性を検証する
   • 完全性を確認する
   • 明確さを高める
4. 利用しやすさを最適化する：
   • 検索性を向上させる
   • 不足しているリンクを追加する
   • 重複を統合する
   • 例を充実させる
5. フィードバックを収集する：
   • 分かりにくい点は何ですか？
   • 不足しているものは何ですか？
   • 最も役立つものは何ですか？
6. 構成を反復改善する：
   • 必要に応じて再編成する
   • 新しいカテゴリを追加する
   • ナビゲーションを改善する
   • メタデータを調整する

クイックリファレンス

操作	コマンド／トリガー
新しいナレッジベースを構築する	"Build knowledge base for [project]"
コードベースから抽出する	"Extract knowledge from codebase"
プロジェクトのドキュメントを整理する	"Organize project knowledge"
ナレッジグラフを作成する	"Create knowledge graph for [domain]"
ナレッジベースを更新する	"Update knowledge base with [new info]"
ナレッジを監査する	"Audit knowledge base health"
ドキュメントを構成する	"Structure documentation for [project]"

ベストプラクティス

• 目的から始める：ナレッジベースで何を実現するかを定義します

  • AI がコードベースを理解できるようにする
  • 新しい開発者のオンボーディングを支援する
  • アーキテクチャ上の意思決定を保持する
  • ドメイン知識を文書化する

• 見つけやすい構成にする：情報を見つけやすくします

  • 明確な階層
  • 一貫した命名
  • 網羅的な索引
  • 豊富な相互リンク
  • メタデータのタグ付け

• AI と人間の両方に向けて書く：どちらも利用します

  • 明確で簡潔な表現
  • 構造化された形式（表、リスト）
  • 明示的な関係性
  • コンテキスト情報
  • コード例

• 最新の状態を保つ：古いナレッジは、ナレッジがない状態よりも有害です

  • コードの変更に合わせて更新する
  • 定期的にレビューする
  • 古くなった情報を削除する
  • コードと一緒にバージョン管理する

• アクセスしやすくする：ナレッジにアクセスできるようにします

  • README からリンクする
  • コードコメントで参照する
  • AI のコンテキストに追加する
  • ナレッジグラフに作成する

• 複数の形式を使う：ナレッジの種類に応じて適切な形式を使います

  • 散文形式のドキュメントには Markdown
  • 関係性にはナレッジグラフ
  • 構造にはスキーマファイル
  • 実装の詳細にはコードコメント
  • アーキテクチャには図

• コンテキストを保持する：「何を」だけでなく「なぜ」も文書化します

  • なぜこのアーキテクチャなのか？
  • なぜ別のアプローチを採用しなかったのか？
  • どのような制約が意思決定に影響したのか？
  • どのようなトレードオフを選択したのか？

• 積極的にリンクする：関連する概念をつなげます

  • ドキュメント同士を相互参照する
  • コードとドキュメントをリンクする
  • 関連する意思決定をつなげる
  • 外部リソースを参照する

ナレッジベースの構成

推奨されるファイル構成

/docs
  /README.md                 # Project overview
  /ARCHITECTURE.md           # System design
  /DECISIONS.md              # ADRs (Architecture Decision Records)
  /PIPELINE_STATUS.md        # Current project state
  /CONTRIBUTING.md           # Development guide
  /API.md                    # API reference
  /DATABASE.md               # Schema documentation
  /DEPLOYMENT.md             # Deployment guide
  /TROUBLESHOOTING.md        # Common issues
  /guides/                   # How-to guides
    /getting-started.md
    /development-workflow.md
    /testing.md
  /reference/                # Technical reference
    /components.md
    /utilities.md
    /configurations.md
  /decisions/                # Detailed ADRs
    /001-framework-choice.md
    /002-state-management.md

ドキュメントのテンプレート

ARCHITECTURE.md テンプレート

# Architecture

## Overview
[High-level system description]

## System Components
- **Component 1**: [Purpose and responsibility]
- **Component 2**: [Purpose and responsibility]

## Data Flow
[How data moves through the system]

## Key Design Decisions
1. **[Decision]**: [Rationale]
2. **[Decision]**: [Rationale]

## Technology Stack
- Frontend: [Technologies]
- Backend: [Technologies]
- Database: [Technologies]
- Infrastructure: [Technologies]

## Integration Points
- [External service 1]: [How we integrate]
- [External service 2]: [How we integrate]

## Security Considerations
[Security architecture and patterns]

## Scalability & Performance
[How system scales, performance characteristics]

DECISIONS.md テンプレート（ADR ログ）

# Architecture Decision Records

## ADR-001: [Decision Title]
**Date**: YYYY-MM-DD
**Status**: Accepted | Proposed | Deprecated

**Context**:
[What is the issue we're trying to solve?]

**Decision**:
[What we decided to do]

**Consequences**:
- Positive: [Benefits]
- Negative: [Trade-offs]
- Neutral: [Other impacts]

**Alternatives Considered**:
1. [Alternative 1]: [Why rejected]
2. [Alternative 2]: [Why rejected]

---

## ADR-002: [Next Decision]
[...]

コンポーネントドキュメントのテンプレート

# [Component Name]

## Purpose
[What this component does and why it exists]

## Location
`/path/to/component`

## Dependencies
- [Dependency 1]: [Why needed]
- [Dependency 2]: [Why needed]

## API
### Functions
- `functionName(params)`: [Description]

### Types
\`\`\`typescript
interface ComponentProps {
  // ...
}
\`\`\`

## Usage
\`\`\`typescript
// Example usage
\`\`\`

## Related Components
- [Component A]: [Relationship]
- [Component B]: [Relationship]

## Known Issues
- [Issue 1]: [Workaround]

ナレッジグラフのパターン

ソフトウェアプロジェクトのエンティティタイプ

Project
  - name
  - description
  - status (active, maintenance, deprecated)
  - tech_stack

Component
  - name
  - type (service, module, function)
  - location (file path)
  - purpose
  - status

Person
  - name
  - role
  - expertise_areas
  - current_focus

Decision
  - title
  - date
  - status
  - context
  - choice
  - rationale

Process
  - name
  - type (workflow, procedure, standard)
  - steps
  - triggers
  - outputs

Dependency
  - name
  - version
  - purpose
  - critical (boolean)

関係タイプ

Project --depends_on--> Dependency
Project --contains--> Component
Component --uses--> Component
Component --implements--> Decision
Person --owns--> Component
Person --made--> Decision
Decision --supersedes--> Decision
Component --documented_in--> Document
Process --governs--> Component

ナレッジグラフの作成例

// Create entities
await memory.create_entities({
  entities: [
    {
      name: "id8labs-app",
      entityType: "Project",
      observations: [
        "Next.js 14+ application",
        "Uses Supabase for backend",
        "Deployed on Vercel",
        "Monorepo structure"
      ]
    },
    {
      name: "authentication-module",
      entityType: "Component",
      observations: [
        "Located in /src/features/auth",
        "Handles user authentication via Supabase Auth",
        "Supports magic link and OAuth",
        "Implements RLS policies"
      ]
    }
  ]
});

// Create relationships
await memory.create_relations({
  relations: [
    {
      from: "id8labs-app",
      to: "authentication-module",
      relationType: "contains"
    },
    {
      from: "authentication-module",
      to: "Supabase Auth",
      relationType: "uses"
    }
  ]
});

ナレッジの抽出手法

コードから

• 関数／クラスのドキュメント：目的、パラメーター、戻り値
• モジュールの構成：構造と関係
• デザインパターン：実装方法
• エラー処理：既知の障害モード
• パフォーマンスに関する考慮事項：最適化に関するメモ

会話から

• 決定事項：選択内容とその根拠
• 解決した問題：問題と解決策
• 学んだ教訓：うまくいったこと、いかなかったこと
• 未解決の質問：解決していない問題
• アクションアイテム：タスクと担当者

外部ソースから

• API ドキュメント：統合ガイド
• 研究論文：技術的なアプローチ
• Stack Overflow：一般的な解決策
• ブログ記事：ベストプラクティス
• カンファレンストーク：業界のパターン

ナレッジの品質チェックリスト

質の高いナレッジベースのエントリには、次の項目が求められます。

• 明確で内容が伝わるタイトルを付ける
• 「何を」だけでなく「なぜ」を説明する
• 具体例を含める
• 関連する概念へのリンクを付ける
• 作成日／更新日を明記する
• 状態（現行、非推奨）を示す
• 一貫した書式を使用する
• 検索で見つけられるようにする
• 十分なコンテキストを提供する
• 元の情報源を参照する

メンテナンススケジュール

毎日

• 決定事項が発生したら、その都度記録する
• 進捗に合わせてPIPELINE_STATUS.mdを更新する
• 複雑なロジックにはコードコメントを追加する

毎週

• 未解決の質問を確認して更新する
• 古くなった情報がないか確認する
• エンドポイントに変更があった場合はAPIドキュメントを更新する
• 変更内容に合わせてナレッジグラフを同期する

毎月

• ナレッジベースの完全性を監査する
• 不明瞭なドキュメントを見直して改善する
• アーキテクチャ図を更新する
• 不要になったコンテンツを整理する

四半期ごと

• ナレッジベースを大規模に見直す
• 必要に応じて構成を再編成する
• ユーザーからのフィードバックを集める
• 改善を計画する

ツールとテクノロジー

保存方法

ツール	最適な用途	形式
Markdownファイル	人が読みやすいドキュメント	リポジトリ内の.mdファイル
Memory MCP	AIが参照できる関係性	ナレッジグラフ
コードコメント	実装のコンテキスト	JSDoc、インラインコメント
OpenAPI/GraphQL	APIコントラクト	YAML/JSONスキーマ
Mermaid	視覚的な図	図をコードで記述
Notion	共同作業用ドキュメント	リッチテキスト、データベース

生成ツール

• TypeDoc：TypeScriptからドキュメントを生成
• JSDoc：JavaScriptからドキュメントを生成
• Swagger/OpenAPI：APIドキュメントを生成
• Mermaid：図を生成
• Supabase CLI：データベースの型を生成

よくある落とし穴

• 過剰なドキュメント化：自明なことまで記述しない
• ドキュメント不足：知識が共有されていると思い込まない
• 古いドキュメント：ドキュメントがないよりも悪い
• 情報の分散：関連するナレッジを集約する
• コンテキストの欠如：必ず「なぜ」を説明する
• 整理不足：見つけやすい状態にする
• メンテナンス不足：ナレッジベースは劣化する
• 形式が1種類だけ：ニーズに応じて適切な形式を使う