ARCHITECTURE (アーキテクチャ設計書 - Agentic 版)

1. システム構成の基本方針

本システムは、自律型 AI エージェント（Antigravity 2.0 等）がプロジェクトディレクトリ内の 「スキル指示書（Markdown）」 を読み込み、ローカルのツール群（MCP）をオーケストレーションしながら、ナレッジベース（Markdown Wiki）を自律的に構築・管理する 完全エージェント主導型アーキテクチャ です。

従来のプログラムによる厳格なパイプライン制御を廃止し、エージェントの推論能力と自律的なファイル操作能力を活かして、ファジーかつ柔軟に相互リンクの修復やナレッジの整理を行います。

2. コードマップ (ディレクトリ構造)

antigravity/
├── raw_sources/              # 生のインプットドキュメント管理階層
│   ├── inbox/                # 新規ソース文書の一時投入口（インボックス）
│   └── (その他カテゴリ等)/   # エージェントが自動整理して配置するディレクトリ
├── wiki/                     # エージェントがスキルを用いて管理するWiki階層
│   ├── index.md              # Wiki全体の動的目次
│   ├── log.md                # エージェントの動作ログ
│   ├── review_queue.md       # エージェントが検出した監査要確認リスト
│   └── entities/             # 抽出された個別エンティティページ (Markdown)
├── .agents/                  # エージェント設定およびスキル定義ディレクトリ
│   ├── AGENTS.md             # エージェントの役割と全体運用ルール
│   └── skills/               # エージェントが実行する個別スキル定義 (Markdown)
│       └── llm_wiki/         # LLM Wiki用スキルディレクトリ
│           ├── wiki-ingest.md # wiki-ingest スキル指示書
│           ├── wiki-query.md  # wiki-query スキル指示書
│           └── wiki-lint.md   # wiki-lint スキル指示書
├── src/                      # エージェントを支援する軽量補助ツール・MCP
│   ├── parser/               # テキスト抽出補助スクリプト (PDF, Excel等)
│   └── mcp_server.py         # ローカル操作用のカスタム MCP サーバー
├── requirements.txt          # 補助ツールの依存ライブラリ
└── .env                      # エージェント環境変数

3. 技術スタック

自律エージェント: Antigravity 2.0 (Gemini 3.5 Flash バックエンド)
スキル定義: Markdown 標準による自然言語指示書
ローカルツールインターフェース: Model Context Protocol (MCP) 規格
- ファイル操作: Workspace 内のファイル読み書き・検索・置換ツール
- 検索エンジン: SQLite FTS5 によるローカル全文検索 MCP
- 外部検索 (Deep Research 用): Tavily / SearXNG MCP サーバー
補助スクリプト: Python 3.10+ (PDF/Excel テキスト抽出用ライブラリ含む)
フロントエンド閲覧: Obsidian (Vault として wiki/ ディレクトリを指定)

4. システム構成図

エージェントとスキル、ローカル環境の接続関係を以下に示します。

graph TD
    %% ユーザーおよびインターフェース
    User[ユーザー]
    Obsidian[Obsidian Vault]

    %% エージェントとスキル
    subgraph Agent_Boundary [エージェント実行環境]
        Agent[Antigravity 2.0 エージェント]
        Skills[.agents/skills/ 指示書]
    end

    %% ローカルツール・データ
    subgraph Local_Workspace [ローカル環境]
        MCP[MCP サーバー / ツール]
        FTS[(SQLite 全文検索)]
        RawDir[(raw_sources/)]
        WikiDir[(wiki/)]
    end

    %% コントロールフロー
    User -->|ドキュメント追加| RawDir
    User -->|対話・指示| Agent
    User -->|閲覧・人間による修正| Obsidian

    Agent -->|1. スキルをロード| Skills
    Agent -->|2. ツール呼び出し| MCP

    MCP -->|テキスト抽出| RawDir
    MCP -->|検索クエリ| FTS
    MCP -->|Markdown更新・リンク生成| WikiDir

    Obsidian -.->|フォルダを参照| WikiDir

5. エージェントの動作モデル（コアロジック）

5.1. スキルベースのコンテキスト交渉

指示の読み込み:

エージェントは、ユーザーから「Wikiへの取り込み(Ingest)」「監査(Lint)」「質問(Query)」の指示を受けると、対応する .agents/skills/ 内の Markdown 指示書をメモリ（Context Window）にロードします。

目的（purpose.md）の参照:

エージェントは、Wiki の目的（schema/purpose.md 等）を併せてロードし、Wiki をどのような方向性で要約・整理すべきか、記述の粒度やフォーカスを自律的に決定します。

長文脈 In-Context Learning:

エージェントは、ロードした Wiki 階層全体（wiki/）とスキル指示書をインプットとして、高度なコンテキスト理解を行い、矛盾検出や類似ページの紐付けを一度の推論プロセス（Gemini の長文脈能力を活用）で実行します。

5.2. MCP ツールのオーケストレーション

エージェントは、ドキュメントの更新や検索を行う際、Pydantic などで定義された API ではなく、MCP ツール（例: read_file, write_file, grep_search 等）を自律的に判断して段階的に呼び出します。
エージェント自身が実行結果（エラーやパース結果）を評価し、エラーが発生した場合は自動でリカバリ処理（別のツールを呼び出す、ファイルを修正するなど）を試行します。

6. ワークフロー（エージェントの実行手順）

Ingest (取り込み) の実行手順

ユーザーがエージェントに「新しいファイルを raw_sources/inbox/ から取り込んで」と指示する。
エージェントは .agents/skills/llm_wiki/wiki-ingest.md を読み込む。
エージェントは raw_sources/inbox/ から対象ファイルを raw_sources/ 配下の適切なディレクトリ（インボックス外）へ移動する。
エージェントは raw_sources/ へ移動した対象ドキュメントを読み出し、テキストを抽出する。
エージェントは、Wiki ディレクトリを検索し、既存の関連エンティティページがあるか調査する。
エージェントは、対象ファイルのメタデータ（対象ファイル名、取り込み日時、最終更新日時、サマリー、キーワード）を抽出し、対応する .metadata.json ファイルを raw_sources/（対象ファイルと同ディレクトリ）に生成・保存する。
エージェントは、抽出したエンティティ情報に基づいて新規 Markdown ページの作成または既存ページの更新（部分マージ）を自律的に実行する。
エージェントは、更新したページ内で他ページに言及している語句を検出し、自動で [[wikilink]] 形式に置換・相互参照を完了する。
処理結果を wiki/log.md に追記する。

7. セキュリティ設計

SECURITY.md に基づき、エージェントの挙動を以下のように制限します。

Workspace 内の制限: エージェントに提供する MCP ツールは、プロジェクトディレクトリ配下のみを操作可能とする。
データ/命令の分離: wiki-ingest.md スキルにおいて、入力ソースドキュメントのテキストは「データ」としてのみ処理し、指示（Command）として解釈させないメタプロンプトを施すことで、間接的プロンプトインジェクションを防御する。

8. 非機能要件への対応方針

拡張容易性 (Flexibility):
- プログラムコードを変更することなく、.agents/skills/ 内の Markdown 指示書を書き換えるだけで、Wiki の命名規則や要約フォーマット、リンク抽出ルールなどの仕様変更が即座に反映されます。
ポータビリティ:
- データベースや複雑なバックエンドサーバーを持たないため、エージェント環境（Antigravity 2.0 等）と MCP サーバーがあれば、どのようなローカル環境でも即座に展開・再現が可能です。
冪等性 (Idempotency):
- エージェントは、Ingest 時に既存の Wiki ページをスキャンし、ハッシュ値や同一タイトルの有無を判断した上で更新を行うため、二重取り込みによる不要な重複ファイルの発生を自律的に防止します。

Keyboard shortcuts