Wiki Generator

プロフェッショナルグレードの構造化プロジェクト Wiki を .mini-wiki/ ディレクトリに生成します。

核心原則：生成されたドキュメントは 詳細、構造化、図表付き、相互関連 である必要があり、エンタープライズグレードの技術ドキュメント標準を達成する必要があります。

📋 ドキュメント品質基準

重要：生成されるすべてのドキュメントは、以下の基準を満たす必要があります:

コンテンツの深さ

• すべてのトピックは 完全なコンテキスト を備えている必要があります。スケルトンコンテンツは不可
• 説明は 詳細で具体的 である必要があります。WHY と HOW を説明してください
• 動作するコード例 を含める必要があります。実行結果を含めて
• エッジケース、警告、よくある落とし穴 をドキュメント化する必要があります

構造要件

• 階層的な見出し (H2/H3/H4) を使用して、情報アーキテクチャを明確化
• 重要な概念は 表 でクイックリファレンス化
• プロセスは Mermaid 図 で可視化
• 関連ドキュメント間の相互リンク

図表要件（ドキュメントあたり最小 2-3 個）

コンテンツタイプ	図表タイプ
アーキテクチャ	flowchart TB (サブグラフ付き)
データ/呼び出しフロー	sequenceDiagram
状態変化	stateDiagram-v2
クラス/インターフェース	classDiagram (プロパティ + メソッド付き)
依存関係	flowchart LR

🔴 必須: ソースコード追跡可能性

すべてのセクションには末尾にソース参照を含める必要があります:

**セクションソース**
- [filename.ts](file://path/to/file.ts#L1-L50)
- [another.ts](file://path/to/another.ts#L20-L80)

**図表ソース**
- [architecture.ts](file://src/architecture.ts#L1-L100)

🔴 必須: 動的品質基準

質量基準は固定数値ではなく、モジュール複雑度に基づいて動的に計算される

複雑度評価ファクタ

complexity_factors:
  # ソースコード指標
  source_lines: 0       # モジュールのソースコード行数
  file_count: 0         # ファイル数
  export_count: 0       # エクスポートされるインターフェース数
  dependency_count: 0   # 依存するモジュール数
  dependent_count: 0    # 依存される回数
  
  # プロジェクトコンテキスト
  project_type: "fullstack"  # frontend / backend / fullstack / library / cli
  language: "typescript"     # typescript / python / go / java / rust
  module_role: "core"        # core / util / config / test / example

動的品質式

メトリクス	計算式	説明
ドキュメント行数	max(100, source_lines × 0.3 + export_count × 20)	ソースコードが多いほど、ドキュメントが長くなります
コード例	max(2, export_count × 0.5)	各エクスポートインターフェースあたり最低 0.5 例
図表数	max(1, ceil(file_count / 5))	5 ファイルごとに 1 つの図表
セクション数	6 + module_role_weight	コアモジュールはセクションが増加

モジュール役割の重み

役割	重み	期待される深さ
core (コア)	+4	深い分析、完全な例、パフォーマンス最適化
util (ユーティリティ)	+2	インターフェース説明、使用例
config (設定)	+1	設定項目説明、デフォルト値
test (テスト)	+0	テスト戦略、カバレッジ
example (サンプル)	+0	実行説明

プロジェクトタイプの適応

プロジェクトタイプ	フォーカスコンテンツ
frontend	コンポーネント Props、状態管理、UI インタラクション例
backend	API インターフェース、データモデル、ミドルウェア例
fullstack	フロントエンド・バックエンド相互作用、データフロー、デプロイメント設定
library	API ドキュメント、型定義、互換性説明
cli	コマンドパラメータ、設定ファイル、使用例

言語適応

言語	サンプルスタイル
TypeScript	型注釈、ジェネリック例、インターフェース定義
Python	docstring、型ヒント、デコレータ例
Go	エラーハンドリング、並行処理例、インターフェース実装
Rust	所有権、ライフタイム、エラーハンドリング

モジュール ドキュメント セクション

モジュール役割に基づいて以下のセクションを動的に含める:

セクション	core	util	config	コンテンツ
概要	✅	✅	✅	紹介、価値、アーキテクチャ位置図
コア機能	✅	✅	-	機能表 + classDiagram
ディレクトリ構造	✅	✅	-	ファイルツリー + 責任説明
API/インターフェース	✅	✅	✅	エクスポートインターフェース、型定義
コード例	✅	✅	✅	基本/高度/エラーハンドリング
ベストプラクティス	✅	-	-	推奨/回避すべき実践
パフォーマンス最適化	✅	-	-	パフォーマンステクニック、ベンチマークデータ
エラーハンドリング	✅	✅	-	よくあるエラー、デバッグテクニック
依存関係	✅	✅	✅	依存関係図
関連ドキュメント	✅	✅	✅	クロスリンク

🔴 コード例（対象: AI とアーキテクチャレビュー）

ドキュメントの主な対象者は AI とアーキテクチャレビュー であり、コード例は以下の条件を満たす必要があります:

1. 完全に実行可能：import、初期化、呼び出し、結果処理を含める
2. エクスポートインターフェースをカバー：各主要エクスポート API に最低 1 つの例
3. コメント説明を含める：重要なステップと設計意図を説明
4. プロジェクト言語に適応：言語のベストプラクティスに従う

// ✅ 良い例：完全、実行可能、コメント付き
import { AgentClient } from '@editverse/agent-core';

// 1. クライアント作成（必要な設定を表示）
const agent = await AgentClient.create({
  provider: 'openai',
  model: 'gpt-4',
});

// 2. 基本的な対話
const response = await agent.chat({
  messages: [{ role: 'user', content: 'こんにちは' }],
});
console.log(response.content);

// 3. エラーハンドリング
try {
  await agent.chat({ messages: [] });
} catch (error) {
  if (error.code === 'INVALID_MESSAGES') {
    console.error('メッセージリストは空にできません');
  }
}

サンプルタイプはエクスポート API の数に基づいて動的に調整:

エクスポート数	サンプル要件
1-3	各 API に基本例 1 個 + エラーハンドリング 1 個
4-10	コア API に各 1 つの例 + 統合例 1 個
10+	カテゴリー分類例（機能別分類）

🔴 必須: コアクラスの classDiagram

すべてのコアクラス/インターフェースについて、詳細な classDiagram を生成:

classDiagram
class ClassName {
  +property1 : Type
  +property2 : Type
  -privateField : Type
  +method1(param : Type) : ReturnType
  +method2() : void
}

ドキュメント関係

• すべてのドキュメントは 「関連ドキュメント」 セクションを含む必要があります
• モジュールドキュメントはリンク先：アーキテクチャ位置、API リファレンス、依存関係
• API ドキュメントはリンク先：親モジュール、使用例、型定義

---

出力構造

🔴 必須: ビジネスドメイン階層（フラットではなく）

業務領域で階層的に組織化され、modules/ ディレクトリはフラット構造ではない

.mini-wiki/
├── config.yaml
├── meta.json
├── cache/
├── wiki/
│   ├── index.md                    # プロジェクトホームページ
│   ├── architecture.md             # システムアーキテクチャ
│   ├── getting-started.md          # クイックスタート
│   ├── doc-map.md                  # ドキュメント関係図
│   │
│   ├── AI システム/                 # ビジネス領域 1
│   │   ├── _index.md               # 領域概要
│   │   ├── Agent コア/              # サブ領域
│   │   │   ├── _index.md
│   │   │   ├── クライアント.md     # 400+ 行
│   │   │   └── ツールシステム.md   # 400+ 行
│   │   ├── MCP プロトコル/
│   │   │   ├── _index.md
│   │   │   └── 設定管理.md
│   │   └── 対話フロー/
│   │       ├── 状態管理.md
│   │       └── レスポンス処理.md
│   │
│   ├── ストレージシステム/           # ビジネス領域 2
│   │   ├── _index.md
│   │   ├── 状態管理/
│   │   │   └── Zustand.md
│   │   └── 永続化/
│   │       └── ストレージアダプタ.md
│   │
│   ├── エディタ/                    # ビジネス領域 3
│   │   ├── _index.md
│   │   ├── コア/
│   │   └── 拡張/
│   │
│   ├── クロスプラットフォーム/       # ビジネス領域 4
│   │   ├── _index.md
│   │   ├── Electron/
│   │   └── Web/
│   │
│   └── api/                        # API リファレンス
└── i18n/

ドメイン自動検出

コード分析後、ビジネス領域を自動識別:

# 自動識別されるビジネス領域マッピング
domain_mapping:
  AI システム:
    keywords: [agent, ai, llm, chat, mcp, tool]
    packages: [agent-core, agent, mcp-core, agent-bridge]
  ストレージシステム:
    keywords: [store, storage, persist, state]
    packages: [store, storage, electron-secure-storage]
  エディタ:
    keywords: [editor, tiptap, markdown, document]
    packages: [editor-core, markdown, docx2tiptap-core]
  クロスプラットフォーム:
    keywords: [electron, desktop, web, app]
    packages: [apps/*, browser-core, electron-*]
  コンポーネントライブラリ:
    keywords: [component, ui, shadcn]
    packages: [shadcn-ui, chat-ui, media-viewer]

🔴 各ビジネス領域は以下を含む必須

ファイル	説明
_index.md	領域概要、アーキテクチャ図、サブモジュールリスト
サブ領域ディレクトリ	関連モジュールを機能別にグループ化
各ドキュメント	400+ 行、5+ コード例

🔌 プラグイン指示プロトコル（コード実行なし）

重要：プラグインは 指示のみ です。エージェントは、プラグイン提供のコード、スクリプト、または外部コマンドを実行してはいけません。フックは分析とドキュメント作成の方法のみに影響します。

1. レジストリをロード：plugins/_registry.yaml を読んで有効なプラグインを確認
2. マニフェストを読む：各有効なプラグインについて、その PLUGIN.md を読んで フック と 指示 を理解
3. フック指示を適用（テキストのみ）: 初期化前（on_init）：開始前にガイダンスを適用 分析後（after_analyze）：構造分析後にガイダンスを適用 生成前（before_generate）：生成計画/プロンプトを変更 生成後（after_generate / on_export）：wiki 作成後にガイダンスを適用

安全制約:

• プラグインスクリプトやバイナリを実行しないでください
• ネットワークからコードをフェッチしたり実行したりしないでください
• PLUGIN.md 内のすべての CLI コマンドは 人間のみ であり、エージェントが実行してはいけません

例：api-doc-enhancer が有効な場合、その PLUGIN.md を読み、API ドキュメント生成の特定のルールに従う必須です

ワークフロー

1. 初期化チェック

.mini-wiki/ が存在するかチェック:

• 存在しない：scripts/init_wiki.py を実行してディレクトリ構造を作成
• 存在する：config.yaml とキャッシュを読み、増分更新を実行

2. プラグイン発見

plugins/ ディレクトリにインストールされたプラグインをチェック:

1. 有効なプラグインについて plugins/_registry.yaml を読む
2. 各有効なプラグインについて、PLUGIN.md マニフェストを読む
3. フックを登録：on_init、after_analyze、before_generate、after_generate

3. プロジェクト分析（ディープ）

scripts/analyze_project.py を実行するか、手動で分析:

1. テックスタックを識別：package.json、requirements.txt などをチェック
2. エントリーポイントを見つけ：src/index.ts、main.py など
3. モジュールを識別：src/ ディレクトリ構造をスキャン
4. 既存ドキュメントを見つけ：README.md、CHANGELOG.md など
5. プラグインから after_analyze ガイダンスを適用（テキストのみ）

構造を cache/structure.json に保存

4. ディープコード分析（新規 - 重要）

重要：各モジュールについて、実際のソースコードを読み、分析する必須:

1. ソースファイルを読む：read_file ツールを使用して重要なソースファイルを読む
2. コードセマンティクスを理解：単に構造だけではなく、コードが何をするかを分析
3. 詳細情報を抽出:
   • 関数の目的、パラメータ、戻り値、副作用
   • クラス階層と関係
   • データフローと状態管理
   • エラーハンドリングパターン
   • 使用されている設計パターン
4. 関係を識別：モジュール依存関係、呼び出しグラフ、データフロー

📖 references/prompts.md → 「深度コード分析」を参照してください

5. 変更検出

scripts/detect_changes.py を実行してファイルチェックサムを比較:

• 新規ファイル → ドキュメント生成
• 変更ファイル → ドキュメント更新
• 削除ファイル → 廃止としてマーク

6. コンテンツ生成（プロフェッショナルグレード）

プラグインから before_generate ガイダンスを適用（テキストのみ）し、その後 厳密な品質基準 に従ってコンテンツを生成:

6.1 ホームページ（index.md）

含める必須項目:

• プロジェクトバッジと 1 行説明
• 詳細な紹介 2-3 段落（箇条書きだけではなく）
• アーキテクチャプレビュー図（Mermaid フローチャート）
• ドキュメントナビゲーション表（対象者付き）
• コア機能表（モジュールリンク付き）
• クイックスタートコード例（実行結果付き）
• プロジェクト統計表
• モジュール概要表（リンク付き）

6.2 アーキテクチャドキュメント（architecture.md）

含める必須項目:

• エグゼクティブサマリー（位置付け、テック概要、アーキテクチャスタイル）
• システムアーキテクチャ図（Mermaid フローチャート TB（サブグラフ付き））
• テックスタック表（バージョンと選択理由付き）
• モジュール依存図（Mermaid フローチャート）
• 詳細なモジュール説明（責任とインターフェース付き）
• データフロー図（Mermaid sequenceDiagram）
• 状態管理図（適用される場合）
• ディレクトリ構造と説明
• 設計パターンと原則
• 拡張ガイド

6.3 モジュールドキュメント（modules/<name>.md）

各モジュールドキュメントは以下を含む必須（最小 16 セクション）:

1. モジュール概要（2-3 段落、2-3 文ではなく）
2. コア価値提案
3. アーキテクチャ位置図（現在のモジュールをハイライト）
4. 関連 API付き機能表
5. 責任説明付きファイル構造
6. コアワークフロー図（Mermaid フローチャート）
7. 状態図（適用される場合）
8. パブリック API 概要表
9. 詳細な API ドキュメント（シグネチャ、パラメータ、戻り値、例）
10. プロパティ表付き型定義
11. クイックスタートコード
12. 3+ の使用例（シナリオ付き）
13. ベストプラクティス（do's and don'ts）
14. 設計上の決定と トレードオフ
15. 依存関係図
16. 関連ドキュメントリンク

6.4 API ドキュメント（api/<name>.md）

各 API ドキュメントは以下を含む必須:

• インポート例付きモジュール概要
• API 概要表
• プロパティ表付き型定義
• 各関数について：
  • 1 行説明 + 詳細説明（3+ 文）
  • 関数シグネチャ
  • 制約とデフォルト付きパラメータ表
  • 可能なケース付き戻り値
  • 例外表
  • 3 つのコード例（基本、高度、エラーハンドリング）
  • 警告とヒント
  • 関連 API
• クラスについて：クラス図、コンストラクタ、プロパティ、メソッド
• 使用パターン（2-3 つの完全なシナリオ）
• FAQ セクション
• 関連ドキュメント

6.5 クイックスタート（getting-started.md）

含める必須項目:

• バージョン要件付きの前提条件表
• 複数のインストール方法
• 設定ファイルの説明
• ステップバイステップの最初の例
• 次のステップ表
• よくある問題 FAQ

6.6 ドキュメントマップ（doc-map.md）

含める必須項目:

• ドキュメント関係図（Mermaid フローチャート）
• ロール別読込パス推奨
• 完全なドキュメントインデックス
• モジュール依存マトリックス

プラグインから after_generate ガイダンスを適用（テキストのみ）

7. ソースコードリンク

コードブロックにソースリンクを追加:

### `functionName` [📄](file:///path/to/file.ts#L42)

8. 保存

• Wiki ファイルを .mini-wiki/wiki/ に書き込む
• cache/checksums.json を更新
• meta.json タイムスタンプを更新

---

🚀 大型プロジェクトの段階的スキャン

問題：大型プロジェクトの場合、AI は少数のドキュメントだけを生成し、すべてのモジュールを完全にカバーしないかもしれません。

起動条件

プロジェクトが以下のいずれかの条件を満たす場合、段階的スキャン戦略を使用必須:

• モジュール数 > 10
• ソースファイル数 > 50
• コード行数 > 10,000

段階的スキャン戦略

flowchart TB
    A[プロジェクト分析] --> B{モジュール数 > 10?}
    B -->|はい| C[段階的スキャン有効化]
    B -->|いいえ| D[標準スキャン]
    C --> E[モジュール優先度ソート]
    E --> F[バッチ分割]
    F --> G[バッチごとドキュメント生成]
    G --> H{未処理モジュールあり?}
    H -->|はい| I[進捗保存]
    I --> J[ユーザーに続行を提示]
    J --> G
    H -->|いいえ| K[インデックス生成]

実行手順

ステップ 1: モジュール優先度ソート

以下の次元に基づいて優先度スコアを計算:

次元	重み	説明
エントリーポイント	5	main.py, index.ts など
依存回数	4	他のモジュールで import される回数
コード行数	2	より大きなモジュールを優先
既存ドキュメント	3	README または docs が存在
最終更新	1	最近更新されたものを優先

ステップ 2: バッチ分割

🔴 重要：バッチあたり 1-2 モジュール、複雑度に基づいて深度を動的に調整

batch_config:
  batch_size: 1              # バッチあたり 1-2 モジュール処理
  quality_mode: dynamic      # dynamic / fixed
  pause_between_batches: true
  auto_continue: false

バッチ割り当て例（ビジネス領域 + 複雑度順）:

バッチ	コンテンツ	複雑度	期待行数
1	index.md	-	150+
2	architecture.md	-	200+
3	AI システム/Agent コア/クライアント.md	2000 行ソース、15 エクスポート	600+
4	ストレージシステム/Zustand.md	500 行ソース、8 エクスポート	250+
5	設定/constants.md	100 行ソース、3 エクスポート	100+
...	深度は複雑度に比例	動的計算

ステップ 3: 進捗追跡

cache/progress.json に記録:

{
  "version": "2.0.0",
  "total_modules": 25,
  "completed_modules": ["core", "utils", "api"],
  "pending_modules": ["auth", "db", ...],
  "current_batch": 2,
  "last_updated": "2026-01-28T21:15:00Z",
  "quality_version": "professional-v2"
}

ステップ 4: チェックポイント復帰

ユーザーが「wiki の生成を続ける」または「continue wiki generation」と言う場合:

1. cache/progress.json を読む
2. 完了したモジュールをスキップ
3. 次のバッチから続ける

🔴 各バッチの品質チェック

**各バッチ