fable-architecture

Fable アーキテクチャ：マイクロサービス強制エンジン

プロジェクト仕様を着手時（Step One）に評価し、規模、スループット、同時実行性、ドメインの複雑さ、またはワークロードの異質性を理由に、分散マイクロサービスアーキテクチャが必要かどうかを決定的に判断します。該当する場合は、すべての主要なコーディングエージェントと下流のサブエージェントに、分離されたマイクロサービス主導の実行パラダイムに厳密に従うよう強く制約し、中核的な専門性に基づいて厳選した言語とフレームワークの組み合わせを割り当て、標準的なサービス間通信プロトコルを適用します。

---

ミッション

ディレクトリ構成の作成や実装が始まる前にプロジェクト仕様を検査し、規模と負荷、ドメインの分離、またはリソース負荷の高さを理由に分散アーキテクチャが必要かどうかを決定的に評価します。しきい値を超えた場合は、エージェントチームがモノリスを構築できないように強制的に制限し（allowMonolith: false）、厳選したポリグロット言語・フレームワークスタックによる分離されたマイクロサービスを適用し、2種類のトランスポートを必須とします。North-South は REST HTTP/JSON（OpenAPI 3.1）、East-West は gRPC（Protocol Buffers）またはメッセージブローカー（RabbitMQ / Kafka）を使用します。

---

次の場合に有効化

• プロジェクト仕様に高い同時実行性（同時ユーザー／接続数が $\ge 5,000$、または RPS/TPS が $>10,000$）が記載されている。
• 仕様で $\ge 2$ 個の分離された運用ドメイン（Identity/Auth、Billing/Stripe、Transcoding、AI Inference、Analytics、Messaging）が定義されている。
• ワークロードに、CPU バウンドのカーネル（高負荷な数値計算、トランスコーディング、暗号処理）と I/O バウンドのパイプライン（API Gateway、CRUD）が混在している。
• ユーザーがマイクロサービスの評価、分散アーキテクチャの設計、またはポリグロットスタックの割り当てを明示的に求めている。
• Step One のプロンプト評価フックが、アーキテクチャのトリガーしきい値を検出する。

---

次の場合は有効化しない

• プロジェクトが単純なコマンドラインスクリプト、ユーティリティ、または単一ファイルのツール（fable-execute）である。
• プロジェクトが、モノリスの範囲内に収まる規模の、単一ドメインに限定された CRUD プロトタイプまたは静的ブログである。
• タスクが局所的なバグ修正または単一モジュールのリファクタリング（fable-tdd または fable-simplify）のみである。
• 広範な作業がすでに分解されており、標準的な段階的計画（fable-plan）のみが必要である。

---

状況分類

カテゴリ	中核的な専門性	言語	フレームワークの選択肢	主なワークロード	サブエージェントの役割
カテゴリ A	高同時実行 API と分散ネットワーキング	Go（Golang）	Fiber、Gin、Go-Kit	ステートレスなルーティング、毎秒数百万件のメッセージ、エッジプロキシ	distributed-network-engineer
カテゴリ B	I/O 負荷の高い、高速な API ゲートウェイとオーケストレーション	TypeScript	NestJS、Fastify（Node.js）または Elysia（Bun）	パブリック API ゲートウェイ、BFF、CRUD、高速なビジネスロジック	gateway-orchestrator / crud-engineer
カテゴリ C	高性能計算カーネルとシステム	Rust	Axum、Actix-web	高負荷な数値計算、暗号処理、動画トランスコーディング、生のバイナリデータ	systems-kernel-engineer
カテゴリ D	人工知能、データエンジニアリング、ML	Python	FastAPI（PyTorch/TensorFlow と併用）	LLM のルーティング、予測モデリング、埋め込み、ML パイプライン	ai-inference-engineer
カテゴリ E	超高同時実行性、フォールトトレラントなリアルタイムシステム	Elixir	Phoenix（LiveView と併用）	数十万件の永続的な WebSocket、リアルタイムメッセージングのオーケストレーション、ゼロダウンタイム	realtime-systems-engineer

---

プロトコル

ステージ 1：開始時の3ベクトル評価

受け取った仕様を、以下の3つの個別のベクトルで評価します。

1. ベクトル 1：規模と負荷（0～10点）：高い同時実行数（$\ge 5k$）、スループット目標、レイテンシ SLA を検出します。
2. ベクトル 2：ドメインの分離（0～10点）：運用ドメインの境界（auth、billing、gateway、compute、ai、messaging、realtime）を検出します。
3. ベクトル 3：リソース負荷（0～10点）：CPU バウンドと I/O バウンドのボトルネックが混在しているかを検出します。
4. 総合スコアを計算します：$(0.35 \times \text{Scale}) + (0.40 \times \text{Domain}) + (0.25 \times \text{Resource})$。

ステージ 2：判定とモノリスの禁止

• いずれかのベクトルが $\ge 7.0$、または総合スコアが $\ge 6.0$ の場合：
  • verdict: 'microservices' と allowMonolith: false を設定します。
  • モノリシックアプリケーションのスキャフォールディングは厳格に禁止されます。
• それ以外の場合：
  • verdict: 'monolith' と allowMonolith: true を設定します。

ステージ 3：ポリグロットスタックの割り当てと分解

• API Gateway は、カテゴリー B（TypeScript/NestJS）を使用するサービス #1 として必ず構成します。
• 識別された各運用ドメインに、カテゴリー A～E の専用サービススタックを割り当てます。
• Gateway に加えて、少なくとも2つの異なるドメインワーカーサービスを確保します。

ステージ 4：通信標準の契約

• North-South：OpenAPI 3.1 スキーマと TLS 1.3 を使用する REST HTTP/JSON。
• East-West：Protocol Buffers（proto/）を使用する gRPC、またはメッセージブローカー（Kafka/RabbitMQ）。内部 HTTP/JSON は禁止します。

ステージ 5：アーキテクチャマニフェストの出力

• 構造化された TOON マニフェスト microservices_manifest.toon と、対応する docker-compose.yml を生成します。

---

判断ルール

• allowMonolith: false の場合、単一ディレクトリアプリケーションや共有データベースを生成しようとする行為は、直ちに不変条件違反となります。
• すべての内部 East-West RPC サービスインターフェースは、クライアントコードまたはサーバーコードを実装する前に、厳格な .proto IDL で定義する必要があります。
• 高負荷な CPU 計算を Node.js のイベントループ上で実行してはなりません。必ずカテゴリー C（Rust）またはカテゴリー D（Python）に振り分けます。
• 高スループットでステートレスなメッセージストリームは、カテゴリー A（Go）の分散ネットワークサービスに振り分けます。
• サブサービスで数十万件の永続的な WebSocket 接続の管理、リアルタイムメッセージングのオーケストレーション、またはゼロダウンタイムのフォールトトレランスが必要な場合は、カテゴリー E：Elixir（Phoenix/LiveView）を自動選択します。
• 外部クライアントが内部 East-West gRPC サービスを直接呼び出すことは禁止します。すべてのクライアントトラフィックは API Gateway 経由で受け付けます。

---

不変条件

• いずれかのベクトルが $\ge 7.0$、または総合スコアが $\ge 6.0$ の場合、モノリスのスキャフォールディングは禁止されます。
• マイクロサービスが必須の場合、型付けされていない HTTP/JSON による内部サービス間通信を厳格に禁止します。
• 各マイクロサービスは専用のプライベートデータ永続化レイヤーを所有します。サービス境界を越えたリレーショナルテーブルの共有は禁止です。
• 製品のスキャフォールディングを開始する前に、アーキテクチャマニフェストを有効な TOON 形式でシリアル化します。

---

障害の分類

不適切なモノリスのスキャフォールディング

規模やドメインのしきい値を超えているにもかかわらず、エージェントがモノリシックなコントローラーを備えた単一リポジトリを構築しようとします。対処法：強制的に遮断し、ディレクトリ構造を拒否して、fable-architecture による再分解を実行します。

East-West トランスポートのダウングレード

内部サービスが gRPC ではなく、プレーンな HTTP/JSON REST で通信します。対処法：proto/ に .proto IDL コントラクトを生成し、gRPC トランスポートバインディングを接続します。

CPU によるイベントループの枯渇

動画のトランスコーディングや重い暗号処理を Node.js/TypeScript に配置します。対処法：CPU 集約型のロジックを、専用の Rust カテゴリー C マイクロサービスに切り出します。

ドメイン境界の侵食

複数のビジネスドメインが同じデータベーススキーマに直接アクセスします。対処法：プライベートデータストアと gRPC インターフェースでサービス境界を徹底します。

---

アンチパターン

• 同時実行数が $\ge 50,000$ RPS の場合に、「シンプルに保つ」ためにモノリスを生成する。
• ドメインをまたぐ外部キーを使って、すべてのサービスで単一の PostgreSQL データベースを共有する。
• バックエンド間の内部通信に、型付けされていない HTTP/JSON を使用する。
• Go または TypeScript の CRUD サービスに、ディープラーニングモデルの推論処理を組み込む。
• API Gateway を省略し、内部の gRPC ポートをパブリッククライアントに直接公開する。

---

完了基準

• 3 ベクトル評価が完了し、個別スコアと複合スコアが記録されている。
• 明示的なサービステーブルを含むアーキテクチャマニフェスト（microservices_manifest.toon）が出力されている。
• しきい値を超えた場合、モノリス禁止状態（allowMonolith: false）が設定されている。
• 通信規約により、North-South は REST、East-West は gRPC／ブローカーを厳格に適用している。
• 分割された各サービスに、専門のサブエージェントの役割とポリグロットスタックが割り当てられている。

---

段階的なリソース

• ベクトルスコアリングガイド：references/vector-scoring.md
• 技術スタックマトリックス：references/tech-stack-matrix.md
• 通信標準：references/communication-standards.md
• サブエージェントの役割分担：references/subagent-role-distribution.md
• 実例の解説：examples/fintech-scale-walkthrough.md、examples/ai-media-pipeline-walkthrough.md
• テンプレート：templates/microservices-manifest.toon、templates/docker-compose.microservices.yml、templates/service-contract.proto
• 検証スクリプト：scripts/evaluate-architecture.py