FND-001: 意図的アーキテクチャ: ZeroClaw マイクロカーネルへの移行

v0.7.0 から · 種別: アーキテクチャ · 改訂: 10

正式なリファレンス · チーム承認済み · 改訂 10 元のRFCに関する議論とドラフト履歴: #5574

これを読む前にチームへの注意。

このドキュメントは、場当たり的に成長してきたコードベースから、意図を持って構築されるコードベースへと移行するための手助けとして書かれました。ここで紹介する概念のいくつかが初めて目にするものであっても、問題ありません。それは、このドキュメントが役割を果たしている証拠です。あなたがこれから一緒に働くシニアエンジニアは皆、理解できないほど大きくなったコードベースで、苦労しながらこれらの教訓を学んできました。私たちには、そのパターンを早い段階で認識し、それが苦痛になる前に軌道修正できるという、めったにない機会があります。これは良いことです。じっくり時間をかけて取り組んでください。

目次

1. 開発哲学: ビジョンファースト
2. ビジョン: ZeroClawとは
3. 正直な評価：現在の状況
4. ターゲットアーキテクチャ
   • 4.4.1 バージョニングポリシー
   • 4.4.2 リリースアーティファクト
5. 採用すべき標準
6. フェーズ別ロードマップ: v0.7.0 → v1.0.0
7. コードと複雑性メトリクス
8. コントリビューターへの影響

改訂履歴

この正規ドキュメントの改訂番号は、承認済みのリポジトリ履歴に従っています。リンク先の RFC issue では、設定規律に関する編集もドラフト Rev. 4 として記載されていますが、この基盤ドキュメントが #5911 で承認された時点では、そのテキストは含まれていません。現在の設定の正本と環境変数による上書き動作については、設定ライフサイクル および 環境変数 に記載されています。

1. 開発哲学：ビジョンファースト

ソフトウェアにおける私たちのあらゆる意思決定、つまり何を作るか、どう作るか、何を省くかは、意図の階層から下へと流れていくべきものです。

Vision
  └── Architecture
        └── Design
              └── Implementation
                    └── Testing
                          └── Documentation
                                └── Release

これはウォーターフォールプロセスではありません。これは意思決定の階層構造です。つまり、関数を作成する際には、その関数が存在する理由を明確に追跡できる必要があります。この関数はこの設計上の決定に基づいて存在し、その決定はこのアーキテクチャ上の選択に基づいており、その選択はこのビジョンに基づいています。もしそのような経路をたどることができない場合、そのコードは存在すべきではないでしょう。

各レイヤーの実際の意味:

トップをスキップすることの問題

ZeroClaw は、OpenClaw の TypeScript コードベースを基に AI ツールによってブートストラップされました。AI によるコード生成は実装レイヤーで行われます。これは、機能を実行する関数、構造体、モジュールを記述します。しかし、ビジョンの設定やアーキテクチャの決定、設計契約の定義は行いません。

結果として得られるのは、機能的には目を見張るものがあるものの、アーキテクチャ的には偶発的なコードベースです。コードは今日必要なことをこなしますが、設計されたものではありません。積み重なっただけです。このパターンには業界で名前が付いています。すなわち**大きな泥団子（Big Ball of Mud）**です。これはソフトウェアにおいて最も一般的なアーキテクチャですが、それは誰かが選んだからではなく、階層の頂点を飛ばしたときに行き着く先だからです。

このRFCは、それを修正するための私たちのチャンスです。うまく機能しているものを捨てるのではなく、Strangler Fig Pattern と呼ばれる手法を用いて、その周りに意図的なアーキテクチャを成長させていきます。古い構造の端に新しい構造を構築し、時間をかけて内側へ移行していき、最終的に古い構造がなくなるようにします。「ビッグバン」式の書き直しはありません。動作しているコードを捨てることもありません。着実で意図的な改善があるだけです。

2. ビジョン：ZeroClawとは

アーキテクチャについて話す前に、私たちが構築するものを正確に定義する必要があります。これがビジョンレイヤーです。その後に続くすべてのものはこれに従属します。

ZeroClaw は、10 ドルの組み込みボードからクラウドサーバーまで、あらゆるハードウェア上で誰もが実行できるパーソナル AI アシスタントランタイムであり、設定の手間ゼロ、外部サービス要件ゼロ、そして機能やセキュリティを一切妥協することなく動作します。

これを具体的なコミットメントに分解します：

ゼロオーバーヘッド。 コアエージェントはミリ秒単位で起動し、ブラウザのタブ1つより少ないメモリしか使用しません。これはマーケティング上の謳い文句ではなく、アーキテクチャ上の制約です。私たちが下すすべての決定は、この制約に照らして検証されなければなりません。

外部依存ゼロ。 ZeroClaw をダウンロードし、LLM プロバイダを設定したユーザーは、他に何もインストールすることなく、動作する実用的な AI アシスタントを利用できます。チャネル、ダッシュボード、連携機能は、必要なときに追加するものであって、動作させる前に必要となるものではありません。

妥協なし。 Lean（軽量）は弱さを意味しません。ZeroClawには、堅牢なセキュリティモデル、本格的な観測性、そして真の拡張性が不可欠です。「小さなバイナリ」と「完全な機能」の間の緊張関係は、コンポジションによって解決されます。小さなコアを、あなたが選択したコンポーネントで拡張します。

あらゆるスキルレベルに対応。 10ドルのRaspberry Piを使う学生も、本番環境にデプロイするチームも、どちらもZeroClawが自分たちのために設計されたと感じられるべきです。これは、デフォルトの体験はシンプルでなければならず、高度な体験はパワフルでなければならないことを意味します。2つの異なる製品ではありません。

ユーザー所有。 あなたのデータ、あなたのハードウェア、あなたの設定。ZeroClawはアカウントを必要とせず、外部への通信を行わず、特定のプラットフォームに縛り付けません。

3. 正直な評価：現在の状況

このセクションは誰かの作品を批判するものではありません。これは診断であり、名前を付けないものは修正できません。

3.1 構造的な問題

現在、ZeroClawのコードベース全体は1つのRustクレートに収められています。これは、

• Telegram チャンネルとコアエージェントループは、Telegram を使用しているかどうかにかかわらず、同じソースツリーからコンパイルされます。
• Webダッシュボード（完全なReactアプリケーション）は、rust-embedを使用してバイナリに埋め込まれており、CLIのみを使用するユーザーであっても、すべてのバイナリにWeb UIが含まれます。
• ゲートウェイ HTTP サーバーには WhatsApp、Linq、Nextcloud Talk、Gmail 用の Webhook ハンドラーが含まれており、特定のチャネル統合が Web サーバーに組み込まれていることを意味します
• 70以上のすべてのツールは、ユーザーが実際に呼び出すかどうかに関係なく、バイナリにコンパイルされます。
• コードを除外するための唯一の仕組みは、Cargo の機能フラグです。これには、ユーザーが Rust の開発環境を持っており、ソースから再コンパイルする必要があります。

ユーザーにとっての影響: 掲げられている目標は、$10 のハードウェア向けの軽量なバイナリです。しかし、そのバイナリには 27 種類のメッセージングチャネル、70 以上のツール、完全な Web サーバー、React アプリケーション、そして Jira、Notion、Google Workspace、LinkedIn などとの統合のためのコードが含まれており、その大半はどのユーザーも決して触れることはありません。

コントリビューターへの影響: ファイルが9,500行にも及ぶ場合、その内容を理解することはできません。すべての機能が1つのクレートに含まれていると、何らかの変更を加えるたびにすべてが壊れるリスクがあります。

3.2 証拠

これらは現在のコードベースからの測定された事実であり、推定値ではありません：

9,500行のファイルはモジュールではありません。.rs 拡張子を持っているだけの巨大な塊です。

3.3 すでに良い点

この診断が、本当に良く設計されているものを隠してはなりません：

• トレイトレイヤーは優れています。 Provider、Channel、Tool、Memory、Observer、RuntimeAdapter、Peripheral はクリーンで文書化された Rust のトレイトです。これらは適切な分離点です。問題は、これらがクレートの境界に対応していないため、コンパイラがレイヤーリングを強制できないことです。
• WASM プラグインシステムは部分的に構築されています。 PluginHost、WasmTool、WasmChannel、PluginManifest、および Ed25519 署名検証はすべて src/plugins/ に存在します。実行ブリッジはスタブですが、構造は正しいです。
• 観測性システムは成熟しています。 OpenTelemetry、Prometheus、DORA メトリクスはすべて、クリーンな Observer トレイトに対して実装されています。これは本番環境での使用に耐えうる品質のものです。
• セキュリティモデルは考え抜かれている。 ペアリングコード、自律レベル、サンドボックス化、ポリシーの適用は、明確な設計意図を示している。

ZeroClawを再構築するのではなく、その既存の優れたアイデアに成長できる構造を提供しています。

4. ターゲットアーキテクチャ

4.1 マイクロカーネルモデル

マイクロカーネルアーキテクチャは、最小限で安定したコアと、それを拡張するオプションのサブシステムを分離します。オペレーティングシステムにおける典型的な例は、メモリとスケジューリングのみを処理し、それ以外のすべて、つまりファイルシステム、デバイスドライバ、ネットワークスタックを、明確に定義されたインターフェースを通じて通信する別々のプロセスとして実行するカーネルです。

AIエージェントのランタイムにおいて、このマッピングはOSの类比が混同している2つの明確な内部レイヤーを示しています：

この区別は重要です。基盤は、任意の ZeroClaw バイナリが機能するために存在しなければならない最小限のものです。ランタイムは、それがエージェントとして機能するために存在しなければならない最小限のものです。それ以外のすべては構成されています。

この2層の分割は、Phase 1のワークスペース分解（PR #5559）中に特定され、クレート名に反映されています：zeroclaw-runtime（クレート）は agent-runtime（フィーチャ）によって制御されます。このRFCの以前の改訂では、「カーネル」という用語が、現在正しく「ランタイム層」と呼ばれているものを指すために広く使われていました。今回の改訂では、この用語を全体で修正しています。

4.2 依存性ルール

この設計において最も重要なアーキテクチャ上のルール、すなわち破られると構造全体が崩壊するルールは、次のとおりです。

依存関係は内向きです。ランタイムはプラグインについて何も知りません。プラグインはAPIを知っています。すべてを知るものは何もありません。

    zeroclaw-api          ← defines all traits (Provider, Channel, Tool, ...)
         ▲                  no implementations, no heavy dependencies
         │ depends on
  foundation crates       ← zeroclaw-config, zeroclaw-providers, zeroclaw-memory,
         ▲                  zeroclaw-infra, zeroclaw-tool-call-parser
         │ depends on        all depend on zeroclaw-api; no cross-dependencies
    zeroclaw-runtime      ← implements the agent loop (agent-runtime feature)
         ▲                  depends on zeroclaw-api + foundation crates
         │ depends on        knows nothing about specific channels or tools
  plugin crates           ← zeroclaw-channel-discord, zeroclaw-tools-web, ...
         ▲                  depend on zeroclaw-api (not the runtime)
         │ depends on
  zeroclaw binary         ← thin wiring layer
                             reads config, registers plugins, starts runtime

zeroclaw-runtime が TelegramChannel をインポートした場合、アーキテクチャが違反されています。クレートの境界が設定されると、コンパイラがこの制約を強制します。

4.3 コンポーネントマップ

┌─────────────────────────────────────────────────────────────────────┐
│                    zeroclaw (binary crate)                          │
│  Reads config → registers only configured components → starts       │
│                                                                     │
│   ┌──────────────────────────────────────────────────────────────┐  │
│   │              zeroclaw-runtime  (agent-runtime feature)       │  │
│   │                                                              │  │
│   │  Agent Loop · CLI Channel · Security Policy                  │  │
│   │  Plugin Host · Local IPC API                                 │  │
│   │  Core Tools: shell, file, git, memory recall/store           │  │
│   │                                                              │  │
│   │  ┌──────────────────────────────────────────────────────┐    │  │
│   │  │   Foundation  (--no-default-features)                │    │  │
│   │  │                                                      │    │  │
│   │  │  zeroclaw-api · zeroclaw-config · zeroclaw-infra     │    │  │
│   │  │  zeroclaw-providers · zeroclaw-memory                │    │  │
│   │  │  zeroclaw-tool-call-parser                           │    │  │
│   │  │                                                      │    │  │
│   │  │  Vision target: <5 MB RAM at runtime                 │    │  │
│   │  └──────────────────────────────────────────────────────┘    │  │
│   └──────────────────────────────────────────────────────────────┘  │
│                              ▲                                      │
│                   zeroclaw-api (traits only)                        │
│                              ▲                                      │
│   ┌──────────────┐  ┌────────┴────────┐  ┌─────────────────────┐    │
│   │  zeroclaw-gw │  │  Channel plugins│  │   Tool plugins      │    │
│   │  (opt-in     │  │                 │  │                     │    │
│   │   binary)    │  │  channel-discord│  │  tools-web          │    │
│   │              │  │  channel-slack  │  │  tools-integrations │    │
│   │  HTTP/WS/SSE │  │  channel-tg     │  │  tools-hardware     │    │
│   │  Web UI      │  │  channel-email  │  │  tools-mcp          │    │
│   │  REST API    │  │  ...            │  │  ...                │    │
│   └──────┬───────┘  └─────────────────┘  └─────────────────────┘    │
│          │                                                          │
│          ▼                                                          │
│   ┌─────────────────┐                                               │
│   │ zeroclaw-desktop│   ← Tauri app (already exists in apps/tauri)  │
│   │ System tray app │     bundles zeroclaw-gw as a sidecar          │
│   │ Native GUI      │                                               │
│   └─────────────────┘                                               │
└─────────────────────────────────────────────────────────────────────┘

4.4 配布モデル

このアーキテクチャにより、エンドユーザーがRustツールチェーンを必要としない、クリーンな配布ストーリーが可能になります。

zeroclaw plugin install コマンド（既存の PluginHost をバックエンドとして使用）がパッケージマネージャーとなります。zeroclaw onboard ウィザードはこれを統合し、非技術者ユーザーが cargo を直接見る必要がなくなります。

4.4.1 バージョニングポリシー

ZeroClawが単一のクレートからマルチクレートワークスペースへ移行する際、2つの懸念事項を最初から明確に分離しておく必要があります。

• 製品バージョン: zeroclaw --version が報告するもので、GitHub Releases、変更履歴、パッケージマネージャー（Homebrew、apt、cargo-binstall）が追跡するものです。これは運用担当者やユーザーが基準とするバージョンです。
• コンポーネントの安定性: 特定のコンポーネントがどれだけ成熟し、信頼できるかを示します。単一のバージョン番号だけでは、このシグナルを伝えることはできません。

これらは直交しています。これらを混同すると、誤解を招くセマンティックバージョニングのノイズが生じ、バージョン番号への信頼が損なわれます。このポリシーは両方を定義しています。

クレートのバージョン管理: 意図的な例外を伴う統一

すべてのアプリケーションクレート、カーネル、ゲートウェイ、ツールプラグインクレート、チャネルプラグインクレート、および CLI は、Cargo ワークスペースのパッケージ継承を使用します。ルートの Cargo.toml にある単一のバージョンが、信頼できる製品バージョンとなります。これが正しいモデルである理由は次のとおりです:

• ユーザー、オペレーター、パッケージャーは1つのバージョンのみを扱います。
• release-plz を使ったリリース自動化は簡単です。PR 1つ、バージョンアップ 1回、CHANGELOG エントリ 1つで完了します。
• これは、ZeroClawがライブラリエコシステムではなくプロダクトとしてのアイデンティティを反映していることを示しています。
• WITインターフェースのバージョンは、Rustクレートのバージョンではなく、実際のプラグインABIコントラクトです（§5.2を参照）

2 つの crate クラスは、意図的にワークスペース継承の対象外とされ、それぞれ独自のリリースサイクルで独立したバージョンを維持しています：

製品バージョンにおける「破壊的変更」の意味

アプリケーションのクレートは統一されたバージョンを共有しているため、チームは単一クレートの内部実装における破壊的変更とは区別して、製品レベルでの破壊的変更の定義を必要としています。以下のいずれの境界も越えないプラグインクレート内の破壊的変更は、製品レベルの破壊的変更には該当せず、MAJOR バージョンの引き上げを必要としません。

安定性ティア

プロダクトバージョンは 「これはどのリリースか？」 に答えます。安定性ティアは 「このコンポーネントにどれだけ依存できるか？」 に答えます。すべてのコンポーネント、カーネル、ゲートウェイ、プラグインクレート、WIT インターフェースは、3 つのティアのいずれかを持ちます。コンポーネントローカルな AGENTS.md ファイルとプラグインレジストリマニフェストが、対象とする所有権モデルです。その移行が完了するまでは、正規の現行割り当ては Coding agent guidelines にあります。

安定性レベルは、チームの意図的な決定を通じて昇格され、降格されることはありません。昇格は変更ログに記録され、アーキテクチャコンポーネントの場合はADRにも記録されます。コンポーネントは、昇格が検討される前に少なくとも1つの完全なリリースサイクルの間、現在のレベルを維持する必要があります。

リリース自動化

リリースには release-plz を使用します。master への push 時にリリース PR を作成し、ワークスペースのバージョンを引き上げ、Conventional Commits のタイトルから変更履歴を生成します。release-plz はワークスペースの継承を標準で認識し、クレートの公開順序を自動的に処理します。独立してバージョン管理される zeroclaw-api クレートは、同じツールのクレートごとの設定を使用して個別に管理されます。

4.4.2 リリースアーティファクト

マイクロカーネルへの移行は、「どの機能がコンパイルされるか」という問いの根本的な性質を変更します。現在、この問いに対する答えは1つです。つまり、cargo build に渡した機能フラグすべてです。移行後、この問いは2つの独立した関心事項に分かれます。

• カーネルバイナリに含まれるもの: コンパイル時に固定され、プラットフォームごとに決定され、GitHub Releases に公開されます
• 利用可能な機能: zeroclaw plugin install でインストールされたプラグインによって実行時に決定されます

これらはもう同じ質問ではなく、現在の Cargo.toml の [features] セクションはその観点から解釈されなければなりません。

現在のコンパイル時機能フラグの行く末

現在の Cargo.toml には20以上の機能フラグがあり、アーキテクチャの成熟に伴って以下の3つのカテゴリに分類されます：

plugins-wasm は常時有効ですが、単一のフラグではありません。3つのフラグからなる分類体系です。ホスト側の機構は無条件で有効になりますが、実行バックエンドはビルド時に決定されるプラットフォームレベルの選択です。バックエンドのサブフラグを指定しない plugins-wasm では、使用可能なプラグインランタイムは生成されません。なぜなら、wasmtime がコンポーネントを実行するにはコンパイラーまたはインタープリターのいずれかが必要だからです。

すべてのリリースターゲットはちょうど1つのバックエンドを有効にします: サポートされている場合は cranelift、サポートされていない場合は pulley。常時有効の意図は維持されます: すべてのバイナリはプラグインホストを備え、そのプラットフォームでプラグインを実行できます。

v0.8.0 リリース前にチームによる明示的な判断が必要な2つのフラグがあり、これらは一方的に解決するのではなく、ここで提示しています。

• observability-prometheus: 現在は default に含まれています。Prometheus メトリクスはバイナリサイズに無視できないオーバーヘッドを追加します。問題は、本番環境のランタイムが observability をデフォルトで有効にして出荷すべきか、それともオペレーターがオプトインすべきかという点です。推奨事項: 標準リリースでは default に含めたままにします。サイズの制約が非常に厳しいターゲットを扱うオペレーターは --no-default-features を指定してビルドできます。
• observability-otel: OTLPエクスポートはより大きな依存関係フットプリント（opentelemetry + reqwest ブロッキングクライアント）を伴います。推奨事項: default には含めず、オプトインのままにします。トレースエクスポートが必要な本番環境では明示的に有効化します。

ci-all メタフィーチャは、チャンネルやツールのフラグが廃止されるにつれて大幅に簡素化されます。v1.0.0 では、残りのプラットフォームおよびインフラストラクチャのフラグのみをカバーします。

正規リリースカーネルバイナリ

各プラットフォームターゲットに対してGitHub Releasesに公開されるバイナリは、以下のプロファイルでビルドされています：

「すべてをビルドした」バイナリはもう存在しません。この概念は、zeroclaw plugin install --profile full に置き換えられました。これは、軽量なカーネルバイナリをインストールした後に、フルプラグインカタログをダウンロードします。

リリース成果物マトリックス

各GitHubリリースでは、以下のアーティファクトが公開されます：

wasm32-wasip2 プラグインのビルドは別の CI ジョブで実行され、独自のサイクルでプラグインレジストリに公開されます。プラグインのリリースにカーネルのリリースは必要ありません。

4.5 ギャウェイ分離

現在のゲートウェイは、分離すべき2つのものを混同しています：

Current (wrong):
  zeroclaw binary
    └── gateway
          ├── Web UI server (serves React app)
          ├── REST/WS/SSE API
          ├── WhatsApp webhook handler  ← this is a channel, not a web server
          ├── Linq webhook handler      ← this is a channel, not a web server
          ├── Nextcloud webhook handler ← this is a channel, not a web server
          └── Gmail push handler        ← this is a channel, not a web server

Target (correct):
  zeroclaw-kernel
    └── Local IPC API (Unix socket / 127.x HTTP)

  zeroclaw-gw (separate binary, optional)
    └── Connects to kernel IPC API
    └── Web UI server
    └── REST/WS/SSE API
    └── Generic webhook proxy → routes to channel plugins

  channel-whatsapp.wasm
    └── Registers its own webhook route with the gateway
    └── Handles WhatsApp-specific message parsing

なぜこれが重要なのか: ゲートウェイが別プロセスである場合、それがクラッシュ、再起動、または不在になってもエージェントに影響を与えません。カーネルは動作し続けます。これはエッジハードウェアのユースケースにおいて特に重要です。カーネルを実行している Raspberry Pi は、その Web UI を VPS から配信させることができ、カーネルはチャネルプラグインを介してアウトバウンドで接続します。インバウンドのファイアウォールルールは不要です。

5. 採用すべき基準

標準は、多くの賢明な人々が長年にわたって合意したものです。これらを採用することで、私たちはその長年の知恵を無料で得ることができ、ソフトウェアがエコシステムと自然に統合されるようになります。以下は、ZeroClaw に直接適用される標準の一覧です。

5.1 観測性: OpenTelemetry

概要: OpenTelemetry (OTel) は、ソフトウェアシステムからトレース、メトリクス、ログを収集するための業界標準です。これは Cloud Native Computing Foundation によって管理され、主要なクラウドプロバイダーや監視ツールによってサポートされています。

ZeroClawにとっての重要性: 私たちはすでに Observer トレイトに対して OtelObserver を実装しています。Prometheusメトリクスおよび DORA メトリクスも備えています。問題は、これらがまだコードベース全体で標準化されていないことです。一部のモジュールは tracing::info! でログを記録し、別のモジュールは ObserverEvent を発行しており、その2つが連携していません。

私たちが行うべきこと:

• すべてのコンポーネントに対して、OpenTelemetry を唯一の観測インターフェースとして採用する
• すべてのプラグインが実行時にOTelスパンを出力するようにし、ユーザーが「Discordでメッセージを受信」から「エージェントがシェルツールを呼び出す」を経て「レスポンスを送信」までの完全なトレースを確認できるようにします。
• カーネル ↔ ゲートウェイ ↔ プラグインの境界間でトレースIDを伝播するために、W3C Trace Context（traceparent/tracestate ヘッダー）を採用する
• ZEROCLAW_LOG_FORMAT=json が設定されている場合、構造化ログの出力は JSON 形式である必要があります（すでに tracing クレートを使用しており、JSON サブスクライバーを追加するだけです）。

標準: OpenTelemetry仕様 · W3C Trace Context (REC) · RFC 5424 (Syslog、システムログ統合用)

5.2 プラグインインターフェース: WASI と WIT

概要: WASI（WebAssembly System Interface）は、WebAssemblyモジュールがホストシステムとやり取りするために使用する標準APIです。WIT（WebAssembly Interface Types）は、WASMコンポーネントがエクスポートおよびインポートする内容を記述するためのインターフェース定義言語です。WASMプラグイン向けの.protoファイルのようなものだと考えてください。

ZeroClawにとっての重要性: 現在の WasmTool および WasmChannel ブリッジには、プラグインの WASM バイナリがエクスポートすべき内容に関する正式な契約がありません。そのため、プラグイン作者は推測に頼らざるを得ません。WIT ファイルはこの契約を正確に定義し、あらゆる言語でプラグイン作者向けの自動コード生成を可能にします。

私たちが行うべきこと:

• Tool、Channel、Memory プラグインタイプ用の WIT インターフェースファイルを定義する（ワークスペースのルートに wit/ ディレクトリ）
• wit-bindgen を使用して、それらの WIT ファイルから Rust のホスト側のバインディングを生成します。
• WITインターフェースを公式プラグインSDKとして文書化する
• プラグイン作者は WIT インターフェースに対して Rust（または Go、C、Python）を記述し、cargo build --target wasm32-wasip2 を実行します。その結果は ~/.zeroclaw/plugins/ に配置されます。

標準: WASI 0.2 · W3C WebAssembly コンポーネントモデル · WIT IDL

5.3 ローカル API: OpenAPI 3.1

概要: OpenAPI は HTTP API を記述するための標準仕様です。バージョン 3.1 は JSON Schema Draft 2020-12 に準拠しています。

ZeroClawにとっての重要性: カーネルのローカルIPC API（ゲートウェイやその他のコンポーネントが接続するソケット）には、安定した文書化された契約が必要です。正式な仕様がない場合、ゲートウェイとカーネルは時間とともに静かに乖離していきます。

私たちが行うべきこと:

• 実装前に、カーネルのローカル IPC API の OpenAPI 3.1 仕様を作成する
• utoipa または aide を使用して、仕様書から Rust のサーバースタブを生成します。
• 仕様を docs/reference/api/kernel-ipc-api.yaml として公開する
• ゲートウェイの外部APIにもOpenAPI仕様が必要です。

標準: OpenAPI 3.1 · JSON Schema Draft 2020-12

5.4 セキュリティ: OWASP ASVS

概要: OWASPアプリケーションセキュリティ検証基準（OWASP Application Security Verification Standard）は、リスクレベル（L1：基本、L2：標準、L3：高度）ごとに整理されたセキュリティ要件のチェックリストです。

ZeroClaw にとって重要な理由: ゲートウェイは外部サービスからの Webhook を処理し、信頼できないユーザー入力を処理し、シークレットを管理します。ペアリングシステム、WebAuthn サポート、レート制限はすべて存在しますが、それらが完全または正確であることを検証するためのフレームワークがありません。

私たちが行うべきこと:

• ゲートウェイとセキュリティモジュールに対して ASVS レベル 2 をターゲットにする
• レベル2のチェックリストを確認し、どの要件を満たしているか、部分的に満たしているか、そしてどの範囲外かを文書化してください。
• セキュリティ関連の課題やPRの基準としてこれを使用してください。

基準: OWASP ASVS 4.0 · OWASP Top 10

5.5 品質モデル: ISO/IEC 25010

概要: ISO/IEC 25010は、ソフトウェア製品の品質に関するモデルを定義しており、8つの主要な特性（機能適合性、パフォーマンス効率性、互換性、ユーザビリティ、信頼性、セキュリティ、保守性、移植性）を含みます。

ZeroClawにとっての重要性: 「これはマージに十分か？」と問われた場合、現在の回答は主観的なものです。ISO 25010 は、その議論のための用語を提供します。ビジョンのコミットメントは直接的にマッピングされます。「ゼロオーバーヘッド」→パフォーマンス効率、「任意のハードウェア」→ポータビリティ、「ゼロコンプロミス」→セキュリティ＋信頼性。

私たちが行うべきこと:

• 重要な変更については、8つの品質特性をレンズとしてPRレビューに活用してください。
• アーキテクチャ変更に関するPRテンプレートには、品質への影響に関する簡潔な記述を含めてください（例：「この変更は、ゲートウェイとチャネル実装間の結合を減らすことで保守性を向上させ、パフォーマンス効率には影響を与えません」）。

規格: ISO/IEC 25010:2023

5.6 すでに採用済み: これらは維持してください

これらはすでに配置されており、維持される必要があります：

6. フェーズ別ロードマップ: v0.7.0 → v1.0.0

各フェーズは、Vision → Architecture → Design → Implementation → Testing → Documentation → Release の階層に従います。設計がレビューされ、合意されるまで、どのフェーズも実装を開始しません。

全体の移行戦略はStrangler Fig Patternを採用しています。既存のコードの周辺から新しいアーキテクチャを構築し、徐々に内部へと移行を進めていきます。最終的には古い構造が完全に置き換えられます。このアプローチでは、「システム全体を停止して書き直す」ことは行いません。アプリケーションは常にリリース可能な状態を維持されます。

フェーズ 1 · v0.7.0: “The Seams”

テーマ: 動作を変更せずにアーキテクチャを可視化する。まず線を描く。

このフェーズの目的: レイヤーが実際の境界として存在するようになるまでは、レイヤードアーキテクチャへ移行できません。現時点では、トレイトが論理的な継ぎ目を定義しているものの、コンパイラはそれを強制しません。すべてが1つのクレートに含まれているため、何でも何でもインポートできてしまいます。このフェーズでは、その継ぎ目を実体化させます。

ビジョンの整合性: ユーザーにとって、ビジョンに関連するプロパティは変更されません。これは完全に内部の処理です。この取り組みの価値は、今後のすべての貢献が構造的に位置づけられるようになり、新しい貢献者がコードベースを全体としてではなく、部分的に理解できるようになる点にあります。

フェーズ1の成果物

D1: zeroclaw-api クレートを抽出

新しいクレート crates/zeroclaw-api を作成し、トレイト定義とそのサポート型のみを含めます。実装は含めず、依存関係も最小限にします。このクレートは2秒以内にコンパイルできる必要があります。

このクレートに移動します:

• src/providers/traits.rs → Provider、ChatMessage、ChatResponse、ToolCall、StreamChunk、ProviderCapabilities
• src/channels/traits.rs → Channel、ChannelMessage、SendMessage
• src/tools/traits.rs → Tool、ToolResult、ToolSpec
• src/memory/traits.rs → Memory、MemoryEntry、MemoryCategory
• src/observability/traits.rs → Observer、ObserverEvent、ObserverMetric
• src/runtime/traits.rs → RuntimeAdapter
• src/peripherals/traits.rs → Peripheral

ワークスペース内の他のすべてのクレートは、これらの型が必要になるたびに zeroclaw-api を依存関係として追加します。コンパイラは、実装クレートが API レイヤーを経由せずに他の実装クレートをインポートできないことを強制するようになりました。

D2: zeroclaw-tool-call-parser クレートを抽出する

src/agent/loop_.rs のツール呼び出し解析ロジックは、純粋なテキスト変換として約 1,400 行にわたります。これは LLM から文字列を取得し、構造化されたツール呼び出しのリストを返すものです。エージェントの状態、メモリ、プロバイダー、チャネルには依存しません。JSON、XML、GLM スタイル、MiniMax、Perl スタイル、マークダウン フェンスなど、12 種類以上の異なる LLM 出力形式を処理します。

このロジックは：

1. 自己完結型: 独自のクレートに最適
2. プロジェクトの中で最もファズテストに適したコード：プロパティベーステストはここに置きます
3. Rustエコシステムへの真の貢献：これほど包括的に対応しているクレートは他にありません

crates/zeroclaw-tool-call-parser を、以下の公開 API を持つように作成してください:

#![allow(unused)]
fn main() {
pub fn parse(text: &str, specs: &[ToolSpec]) -> ParseResult

pub struct ParseResult {
    pub calls: Vec<ParsedToolCall>,
    pub remaining_text: Option<String>,
}

pub struct ParsedToolCall {
    pub name: String,
    pub arguments: serde_json::Value,
    pub tool_call_id: Option<String>,
}
}

現在 loop_.rs にある約300個のパーサーテストが、このクレートに移動されます。loop_.rs は約1,400行削減されます。

D3: 可観測性の標準として OpenTelemetry を採用する

すでに実装済みの仕様を正式文書化します。ObserverEvent と ObserverMetric が内部イベントバスであり、OtelObserver が標準的な本番環境用バックエンドであることを文書化します。ZEROCLAW_LOG_FORMAT=json に対して JSON 構造化ログのサブスクライバーを採用します。また、今後のコンポーネント間トレーシングのために W3C Trace Context を導入します。

D4: WIT インターフェイスファイルを記述する

WASM プラグインの実行を実装する前に、契約を定義しましょう。ワークスペースのルートに wit/ ディレクトリを作成し、以下のインターフェース定義を含めてください：

• zeroclaw:tool/tool.wit: Tool プラグインインターフェース
• zeroclaw:channel/channel.wit: Channelプラグインインターフェース

これらが公式プラグインSDKとなります。v0.8.0での実装はこれらのファイルから生成されます。

v0.7.0 の成功指標

• zeroclaw-api は、実装依存関係ゼロで2秒以内にコンパイルされます。
• zeroclaw-tool-call-parser はテストカバレッジが 95% 以上です（ロジックは完全に独立してテスト可能です）。
• loop_.rs は8,000行未満です
• ユーザーに見える動作の変更はありません
• パフォーマンスの低下なし（ベンチマークスイートがパス）

フェーズ2 · v0.8.0:「The Runtime」

テーマ: エージェントランタイムをクリーンで独立してデプロイ可能なユニットとして形式化する。ランタイム以外のすべてをゲストとする。

このフェーズの目的: シーム（接合部）が整った後（v0.7.0）、ランタイムの境界を明示的に引くことができるようになります。このフェーズでは、zeroclaw-runtime を独立したクレートとして抽出し、WASM プラグイン実行ブリッジを完成させ、プラグインレジストリクライアントを接続します。これは、ランタイム外のあらゆるものがランタイムに接続するための仕組みです。

ビジョンの整合: ここで合成モデルがユーザーにとって現実のものになります。CLI エージェントだけを必要とするユーザーは、1 つのバイナリをダウンロードして zeroclaw onboard を実行すれば完了です。Rust ツールチェーンもコンパイルも不要です。zeroclaw onboard ウィザードは、プラグインコンポーネントをオンデマンドでダウンロードする機能を備えます。

フェーズ2の成果物

D1: zeroclaw-runtime クレートの形式化

エージェントのオーケストレーションループ、CLIチャンネル、セキュリティポリシー、プラグインホスト、およびIPC APIを crates/zeroclaw-runtime に抽出し、agent-runtime 機能で制御します。このクレートは zeroclaw-api と基盤となるクレートに依存しており、Telegram、Discord、Anthropic、または特定のツール実装に関する知識を持ちません。

ランタイムはクリーンな公開APIをエクスポートします：

#![allow(unused)]
fn main() {
pub struct Runtime { ... }

pub struct Registry {
    pub fn register_channel(&mut self, ch: Arc<dyn Channel>);
    pub fn register_tool(&mut self, t: Box<dyn Tool>);
    pub fn set_provider(&mut self, p: Arc<dyn Provider>);
    pub fn set_memory(&mut self, m: Arc<dyn Memory>);
    pub fn set_observer(&mut self, o: Arc<dyn Observer>);
}

pub async fn run(runtime: Runtime, registry: Registry) -> anyhow::Result<()>;
}

バイナリクレートは、設定を読み取って run を呼び出す薄い配線層になります。

D2: WASM実行ブリッジを完成させる

extism 依存関係は WASM Component Model（.wit ファイル）と互換性がなく、wasmtime の cranelift 機能を必要とするため、ARM32 ターゲットのコンパイルがブロックされます。Extism を削除し、wasmtime の直接利用に置き換えてください。移行期間中は、最終的な廃止 PR まで Extism をオプションとして残しておく必要があります。

WIT インターフェースが v0.7.0 で定義されたら、cranelift（ほとんどのビルドターゲット向け）または pulley（ARM32 向け）へのオプション依存を使って、wasmtime を zeroclaw-plugins に組み込みます。wit-bindgen を使ってホスト側のバインディングを生成します。

完全な WASM 実行ブリッジの実装では、WASM プラグインが呼び出せる WASI ホスト関数（HTTP リクエスト、メモリアクセス、ロギング）を、PluginPermission で既に定義されているパーミッションモデルの範囲内で定義します。可能な限り、WASI Preview 2 API（wasi:io、wasi:http、wasi:filesystem など）を使用して、プラグインに一貫した標準ベースの API を提供する必要があります。

D3: コンポーネントレジストリクライアント

zeroclaw plugin サブコマンドを追加し、シンプルなレジストリクライアントでバックエンド化します：

zeroclaw plugin list              # list installed plugins
zeroclaw plugin search <query>    # search the component registry
zeroclaw plugin install <name>    # download, verify, and install a plugin
zeroclaw plugin remove <name>     # remove an installed plugin
zeroclaw plugin update            # update all installed plugins

レジストリは、既知の URL から提供される JSON インデックスファイルです（例: https://plugins.zeroclaw.com/index.json）。各エントリには、名前、バージョン、ダウンロード URL、SHA-256 チェックサム、パブリッシャーの Ed25519 公開鍵が含まれます。PluginHost の署名検証が、セキュリティモデルをすでに担っています。

D4: zeroclaw onboard をプラグインシステムと統合する

オンボーディングウィザードは、ユーザーが希望するチャンネルやインテグレーションを尋ね、その後、それぞれに対して PluginRegistry::install を呼び出す必要があります。コンパイルは不要です。ユーザーはバイナリをダウンロードして zeroclaw onboard を実行するだけで、2分以内に動作する設定済みエージェントが利用可能になります。

D5: all_tools_with_runtime をコアツールのみに削減

カーネルには、プラグインがインストールされていない状態で有用なエージェントを作成するために必要なツールが正確に含まれています：shell、file_read、file_write、file_edit、git_operations、glob_search、content_search、memory_recall、memory_store、memory_forget、および web_fetch。それ以外のツールは、インストールされたプラグインによって登録されます。

v0.8.0 の成功指標

• zeroclaw-runtime は、チャネルやツールの実装コードなしで独立してコンパイルされます。
• zeroclaw plugin install channel-discord はエンドツーエンドで動作します。
• zeroclaw onboard は、Rust ツールチェーンを必要とせずにプラグインをインストールします。
• ランタイムのバイナリサイズは追跡され、レポートされ、リリースノートに記載されます。目標は、ビジョンターゲット（§7参照）に向かって下向きに進むことです。
• WITインターフェースを使用してRustで書かれたWASMツールプラグインが正しく実行されました。

フェーズ3 · v0.9.0：「The Gateway」

テーマ: ウェブ表面とエージェントのコアを分離する。

このフェーズの目的: ゲートウェイは現在、コードベースの中で最も大きな構造的結合となっています。コンパイル済みの React アプリケーションを埋め込み、チャネル固有の Webhook ロジックを処理し、Web ページを一切配信しない 10 ドルのエッジハードウェア向けのバイナリを含む、すべてのバイナリにコンパイルされます。

ビジョンの整合性: このフェーズは、「外部要件ゼロ」という約束を完全に実現します。Raspberry Pi のユーザーは、Web サーバー、React アプリ、HTTP リスナーを含まないカーネルバイナリを取得します。Web ダッシュボードを必要とするユーザーは、zeroclaw-gw を別途インストールします。

フェーズ3 成果物

D1: カーネルIPC APIを定義する

ゲートウェイを抽出する前に、カーネルがUnixソケットまたはループバックポートで公開するローカルAPIのOpenAPI 3.1仕様を定義してください。このAPIは、ゲートウェイ、Tauriアプリ、および将来のクライアントが接続するものです。これは、カーネルと外部世界間の安定した契約です。

エンドポイントには次のものが含まれます: メッセージの送信、ストリーミングレスポンスの受信、アクティブセッションの一覧表示、インストール済みプラグインの一覧表示、エージェントステータスの取得、メモリの管理、cron ジョブのトリガー。これはまず設計ドキュメントです。実装を 1 行でも書く前に、仕様をレビューして合意しておく必要があります。

D2: カーネルIPCサーバーの実装

IPC サーバーを zeroclaw-kernel に、--features ipc の機能フラグの背後に追加します。対応しているプラットフォームでは、カーネルは ~/.zeroclaw/kernel.sock の Unix ソケットでリッスンします。Windows では名前付きパイプを使用します。zeroclaw gateway コマンド（現在の Web サーバーのエントリポイント）は、このソケットに接続する zeroclaw-gw になります。

D3: zeroclaw-gw を独立したバイナリとして抽出する

src/gateway/ を独自のバイナリを持つ新しい crates/zeroclaw-gw/ クレートに移動します。これは zeroclaw-api に依存し、IPC API 経由でカーネルに接続します。rust-embed 経由で組み込まれた React アプリケーションも、このクレートに完全に移動します。カーネルのバイナリには、Web アセットが一切含まれなくなります。

D4: チャネル webhook ハンドラーをゲートウェイから移行する

現在 gateway/mod.rs にある WhatsApp、Linq、Nextcloud Talk、Gmail の webhook ハンドラーを、それぞれのチャネルプラグインに移動します。ゲートウェイは汎用的な webhook 登録 API を提供します。チャネルプラグインは読み込まれると、Webhook パスプレフィックスとハンドラー関数を登録します。ゲートウェイは受信した webhook を登録済みのハンドラーにルーティングします。ゲートウェイは WhatsApp を認識しなくなります。

D5: Tauri サイドカーの関係を形式化する

apps/tauri/ を更新して、zeroclaw-gw を Tauri のサイドカーバイナリとしてバンドルします。Tauri アプリは「フル体験」版の配布物となり、カーネルとゲートウェイを自動的に起動し、Web UI を開きます。Tauri アプリをダウンロードしたユーザーは、ターミナルを操作することなくすべてを動作させることができます。

v0.9.0 の成功指標

• カーネルバイナリ（リリース版）には、Web アセットや HTTP サーバーのコードは含まれていません。
• zeroclaw-gw が起動し、IPC を介してカーネルに接続して Web ダッシュボードを提供します
• zeroclaw-gw を削除しても、カーネルやチャネルプラグインには影響しません。
• WhatsApp、Linq、Nextcloud Talk、Gmail のチャネルコードはプラグインクレートに移動しました
• Tauri デスクトップアプリは、両方のバイナリを正しくバンドルして起動します。

フェーズ4 · v1.0.0:「プラットフォーム」

テーマ: ZeroClawはモノリシックなアプリケーションではなく、コンポーザブルなプラットフォームへと進化します。

このフェーズの理由: カーネルが安定し、ゲートウェイが分離され、プラグインシステムが動作しているため、v1.0.0 はアーキテクチャがプロダクトとなるリリースです。外部開発者はプラグインを作成・公開できます。ユーザーは、自分好みの ZeroClaw を組み立てることができます。バイナリは、ビジョンが約束する軽量なプロファイルを真に実現します。

フェーズ4の成果物

D1: 残りのすべてのチャネルをプラグインに移行する

27以上のチャンネル実装それぞれが、スタンドアロンのWASMプラグインクレートになります。これらは署名付きリリースでコンポーネントレジストリに公開されます。カーネルバイナリには、CLIを除いて、チャンネル実装は含まれていません。

D2: ロングテールツールをプラグインに移行する

70以上のツールのうち約60個が、ドメインごとにグループ化されたプラグインクレートへ移行します。具体的には、zeroclaw-tools-web（ブラウザ、検索、スクリーンショット、PDF）、zeroclaw-tools-integrations（Jira、Notion、Google Workspace、MS365、LinkedIn）、zeroclaw-tools-hardware（ボード情報、GPIO）、zeroclaw-tools-cloud（クラウド運用、セキュリティ運用）です。カーネルには、v0.8.0で特定された10〜12個のコアツールのみが保持されます。

D3: プラグインSDKおよび開発者向けドキュメント

プラグイン開発ガイドを公開します。開発者は午後の間に新しいツールプラグインを作成できるはずです：

1. 依存関係として zeroclaw-plugin-sdk を追加する
2. WITで生成されたトレイトを実装する
3. cargo build --target wasm32-wasip2
4. zeroclaw plugin install ./my-plugin/

SDKは、ホスト関数のバインディング、マニフェスト形式、および権限モデルを処理します。

D4: カーネルIPC APIをv1.0で安定化

カーネルのIPC APIにはバージョンプレフィックス（/v1/）と安定性の保証が付与されます。v1.xにおける破壊的変更はこのAPIに対して許可されません。これは、サードパーティのクライアントやゲートウェイが依存する契約です。

D5: バージョニングポリシーと安定性ティアの定義を docs/book/src/maintainers/stability-tiers.md に抽出する

このRFCの§4.4.1で定義されているバージョニングポリシーと安定性ティアの表は、docs/book/src/maintainers/stability-tiers.md に恒久的なコントリビュータ参照ドキュメントとして格納されます。このドキュメントは、コントリビュータが新しいプラグインクレートのティアを割り当てる際に日常的に参照するもので、メンテナがリリースの決定を行う際にも参照されます。RFC自体は、これらの決定がなされた理由の歴史的記録であり、抽出されたドキュメントはコントリビュータが参照する内容です。

v1.0.0 の成功指標

• ランタイムのバイナリサイズはビジョンターゲットに対して追跡されます（§7参照）。v1.0.0のワークストリームとして、各クレートに対する専用の最適化パスが期待されています。
• サードパーティのデベロッパーは、公開されているドキュメントのみを使用して動作するプラグインを公開できます。
• 27以上のチャンネル実装がレジストリでダウンロード可能なプラグインとして提供されています。
• zeroclaw onboard コマンドは、Rust ツールチェーンがインストールされていない Raspberry Pi Zero 2W 上で、2分以内に完全なセットアップを完了します。
• すべてのプラグインカタログは、zeroclaw plugin install --profile full でインストール可能です。

7. コードと複雑性メトリクス

これらは現在のコードベースの直接コード分析に基づく見積もりです。これらは正確な予測ではなく、規模感を把握するために提供されています。

ランタイムから移動するコードの行数

ファイルレベルの複雑さの削減

バイナリサイズ: 測定された進捗とビジョンの目標

プロジェクトのビジョンはランタイムの観点で表現されています。$10のハードウェアで**<5 MB RAM**を実現します。ディスク上のバイナリサイズとランタイムのメモリフットプリント（RSS）は関連していますが、同一ではありません。デマンドページングにより、実行されたコードパスのみが常駐します。両方とも追跡されます。

2パスモデル: アーキテクチャの分解（フェーズ1〜3）とバイナリサイズの最適化は、それぞれ独立した作業ストリームです。依存関係を所有するクレートに分離することで、最適化が可能になります。クレートごとに効率を最大化することは、構造に関する作業そのものの成果物ではなく、期待される2回目のパスです。

6.6 MB のフェーズ 1 基盤ビルドは、8.8 MB のモノリスからの実質的な進歩を示しており、分解が機能していることを証明しています。ビジョンの目標値に到達するには、構造的な分解が完了した後、各クレートを対象とした専用の依存関係監査と最適化のパスが必要です。具体的には、各クレートの Cargo.toml を確認して不要な依存関係や機能過多な依存関係を洗い出し、LTO と strip のプロファイルを検証し、実際に必要な tokio/serde の機能フラグを監査します。

重要な構造的な変化：バイナリサイズは「ビルド時にコンパイルされる機能」の関数から、「ユーザーが制御するランタイム時にインストールされるプラグイン」の関数へと変化します。この変化がフェーズ1〜3のアーキテクチャ上の目標です。サイズに関する数値は、その次のフェーズの最適化目標となります。

コンパイル時間の改善

現在、このコードベースで cargo build --release を実行すると、すべてのチャンネル、すべてのツール、すべてのプロバイダー、および埋め込みされた React アプリが単一のコンパイル単位でコンパイルされます。クレートの分解とは：

• カーネルは独立してコンパイルされ、そのコンパイル結果はキャッシュされます。
• channel-discord への変更はカーネルを再コンパイルしません
• プラグインの作業に携わる貢献者は、自分のプラグインだけを再コンパイルします。
• CIは、ジョブ間でクレートのコンパイルを並列化できます。

インクリメンタルビルドの推定ウォールクロック時間の改善：カーネルに触れない変更で60〜75%の削減。

8. 貢献者にとっての意味

新しいコントリビューターの方へ

大規模なコードベースに初めて貢献する人々から最もよく寄せられる不満は、「どこから始めればよいのかわからない」というものです。現在のアーキテクチャでは、「Discord のメッセージはどこに送られるのか？」という問いに答えるために、channels/discord.rs → channels/mod.rs → gateway/mod.rs → agent/loop_.rs → その他数十のファイルを追跡する必要があります。

マイクロカーネルアーキテクチャでは、その答えは「channel-discord プラグインを介して、カーネルの Channel 受信者に送られる」です。新しいコントリビューターは、1つのプラグインクレートを読むだけで Discord チャンネルを完全に理解できます。また、チャンネルやツールのコードをスコープに含めることなく、zeroclaw-kernel を読むだけで、エージェントのループ全体を理解することができます。

新しいコントリビューター向けの良い指針: 変更内容を、複数のコンポーネントに言及することなく1文で説明できるなら、適切な粒度で作業できています。「Discordチャンネルのスレッド返信の処理におけるバグを修正する」は1つのコンポーネントです。「エージェントループをリファクタリングし、Discordチャンネルを更新し、さらにメモリバックエンドを修正する」は3つのコンポーネントであり、3つのPRに分けるべきです。

メンテナ向け

すべてのバグレポートには明確な対応先があります。「エージェントがツールを誤って呼び出している」→ zeroclaw-tool-call-parser または zeroclaw-runtime。「Discord 連携が壊れている」→ channel-discord プラグイン。「Web ダッシュボードが読み込まれない」→ zeroclaw-gw。現在、これらのバグは 50,000 行以上のどこにでも存在する可能性があります。

リリースプロセスについて

プラグインモデルにより、チャンネルやツールは独立したリリースサイクルを持つことができます。Telegram チャンネルのバグ修正に新しいカーネルのリリースは必要ありません。カーネルの安定性は、他のすべてのものが構築する基盤となります。プラグインの迅速な反復は、カーネルの安定性を脅かすリスクがありません。

コミュニティ向け

公開されたWITインターフェースとプラグインSDKにより、誰でもZeroClawをフォークせずに拡張できます。特定の統合が必要な企業は、公開インターフェースに対してプラグインを作成できます。これがエコシステムを構築する方法です。

付録 A: 用語集

この文書で使用されている用語で、なじみの薄いもの：

Big Ball of Mud（大きな泥団子）: コードベースが構造的な計画なしに無秩序に成長していくアーキテクチャ（あるいはアーキテクチャの欠如）。この名称は、Brian Foote と Joseph Yoder による1997年の論文に由来します。これはソフトウェアにおいて最も一般的なアーキテクチャですが、誰かが選んだからではなく、何もしなければ自然とそうなってしまうからです。

コンウェイの法則:「システムを設計するあらゆる組織は、その組織のコミュニケーション構造を写し取った構造を持つ設計を生み出す。」(Mel Conway, 1968) コントリビューターが互いに会話せず孤立したサイロの中で作業すれば、コードはそれを反映します。コントリビューターがそれぞれの作業の間に明確なインターフェイスを設けて協力すれば、コードはそれもまた反映します。

依存性逆転の原則: 上位モジュールは下位モジュールに依存すべきではありません。どちらも抽象に依存すべきです。これが、zeroclaw-runtime が channel-discord（特定の実装）ではなく zeroclaw-api（抽象）に依存している理由です。

マイクロカーネル: コアシステムが必要最小限の機能のみを含み、その他すべての機能は、明確に定義されたインターフェースを通じてコアと通信する個別のコンポーネントによって提供されるアーキテクチャ。

ストラングラーフィグパターン: 既存システムの一部を、古いコンポーネントと並行して新しいコンポーネントを構築することで段階的に置き換えていく移行戦略です。既存の木の周囲に成長し、最終的に元の木を完全に置き換えてしまう絞め殺しイチジク（strangler fig）にちなんで名付けられました。重要な特性は、移行中も常にシステムが稼働しており、常にデプロイ可能であることです。

技術的負債: ソフトウェア設計で近道をしたことによって蓄積されるコスト。金銭的な負債と同様に、少額であれば生産的に働くこともあります（今すぐ出荷できる）。しかし大きくなると深刻な足かせになります（新機能の代わりに、利息の支払い、つまりバグ修正や回避策にすべての時間を費やすことになる）。

WIT (WebAssembly Interface Types): WASMコンポーネントがエクスポートおよびインポートする内容を記述するためのインターフェース定義言語です。これは契約のようなものと考えてください。「Toolプラグインは、JSONを受け取りJSONを返すexecuteという関数をエクスポートしなければならない」というものです。WITはその契約を正確かつ機械可読なものにします。

付録B: 参考文献

これらはチームにとって有益なリソースです。必須の読み物ではありませんが、それぞれがこの提案に直接影響を与えています。

• 「A Philosophy of Software Design」: John Ousterhout 著。ソフトウェアの複雑さを管理することについて書かれた最高の短編書籍。彼の「ディープモジュール」（シンプルなインターフェース、強力な実装）という概念は、まさにマイクロカーネルモデルが目指すものです。

• 「クリーンアーキテクチャ」: Robert C. Martin著。本ドキュメントのセクション4.2で説明している依存関係のルールは、この書籍に由来します。

• 「Release It!」: Michael Nygard著。本番環境で安定して稼働し続けるソフトウェアを構築するための実践的なパターン。ここで取り上げているゲートウェイ分離パターンとサーキットブレーカーパターンは、本書から引用しています。

• The Rust API Guidelines: 慣用的なRustライブラリを設計するための公式ガイドです。私たちのトレイトインターフェースはこれらの規約に従うべきです。

• WebAssembly コンポーネントモデル: この RFC で提案されているプラグインシステムの技術的基盤です。

• OpenTelemetry 仕様: 私たちが採用するオブザーバビリティ標準の完全な仕様です。

この提案は、v0.6.8 における ZeroClaw コードベースの詳細な分析に基づいて作成されました。引用されているコードメトリクスは、ソースファイルの直接測定に基づいています。アーキテクチャの推奨事項は、ZeroClaw プロジェクトの特定の制約と目標に適用されたシステムソフトウェア設計における確立されたパターンを反映しています。

フィードバック、修正、対案を歓迎します。最良のアーキテクチャは、誰か一人が決めたものではなく、チームが理解し信頼できるものです。