Evaluate Agent Framework

オープンソースのエージェントフレームワークの投資準備性を構造化評価する。新規価値はステップ2-3にある: 貢献生存率を通じてコミュニティ健全性を定量化し、外部エンジニアリング努力が無駄になる最も一般的な理由である置き換えリスクを計測する。最終分類（INVEST / EVALUATE-FURTHER / CONTRIBUTE-CAUTIOUSLY / AVOID）が、開発サイクルを投じる前にリソース配分を較正する。

使用タイミング

• エージェントフレームワークを本番採用するかを評価するとき
• プロジェクトが依存するフレームワークの依存リスクを評価するとき
• 外部プロジェクトにエンジニアリング努力を貢献するか決めるとき
• build-vs-adopt 決定のために競合フレームワークを比較するとき
• メジャーリリース、ガバナンス変更、買収後にフレームワークを再評価するとき

入力

• 必須: framework_url — フレームワークリポジトリの GitHub URL
• 任意:
  • comparison_frameworks — ベンチマーク用の代替フレームワーク URL のリスト
  • use_case — アーキテクチャ整合性評価のための想定ユースケース（例: 「マルチエージェントオーケストレーション」、「ツール使用パイプライン」）
  • contribution_budget — 計画されたエンジニアリング時間、投資ティア較正用

手順

ステップ1: フレームワークセンサスを集める

より深い解析の前に、プロジェクトの規模、活動、ランドスケープ位置に関する基礎データを集める。

1. README.md、CONTRIBUTING.md、LICENSE、任意のアーキテクチャドキュメント（docs/、ARCHITECTURE.md）を取得し読む
2. 定量指標を集める:
   • スター、フォーク、オープン issue、オープン PR: gh repo view <repo> --json stargazerCount,forkCount,issues,pullRequests
   • 依存リポジトリ: GitHub の "Used by" カウントまたは gh api repos/<owner>/<repo>/dependents を確認
   • リリース周期: gh release list --limit 10 — 頻度と semver 準拠かを記す
3. バスファクターを計算: 過去 12 ヶ月のコミット数で上位 5 貢献者を特定する。トップ貢献者がコミットの >60% を占めるなら、バスファクターは致命的に低い
4. ランドスケープ位置をマップ:
   • Pioneer: 先駆者、カテゴリを定義する（高い影響力、フォロワーへの高い置き換えリスク）
   • Fast-follower: pioneer の 6 ヶ月以内にローンチ、概念を反復する
   • Late entrant: カテゴリ安定後に到着、機能やガバナンスで競う
5. comparison_frameworks が提供されていれば、各代替について同じ指標を集める

期待結果： ターゲット（および提供されていれば比較対象）のスター、フォーク、依存数、リリース周期、バスファクター、ランドスケープ位置を伴うセンサス表。

失敗時： リポジトリが非公開または API レート制限なら、手動 README 解析にフォールバックする。指標が利用不能（例: セルフホスト GitLab）なら、ギャップを記し定性評価で進む。

ステップ2: コミュニティ健全性を評価する

プロジェクトが外部貢献者を迎え入れ、支援し、保持しているかを定量化する。

1. 外部貢献生存率 を計算する:
   • 直近 50 のクローズ済み PR を取得: gh pr list --state closed --limit 50 --json author,mergedAt,closedAt,labels
   • 各 PR 著者を internal（org メンバー）または external に分類
   • 計算: survival_rate = merged_external_PRs / total_external_PRs
   • 健全閾値: >50% 生存率; 懸念: <30%
2. 応答性を計測:
   • Issue 初応答時間: issue 作成から最初のメンテナーコメントまでのメジアン時間
   • PR マージ遅延: 外部 PR のオープンからマージまでのメジアン時間
   • 健全: 初応答 <7 日、マージ <30 日; 懸念: 初応答 >30 日
3. 貢献者多様性を評価:
   • 過去 6 ヶ月の external/internal 貢献者比

   • =2 のマージ済み PR を持つ一意な外部貢献者数（リピート貢献者は健全なエコシステムの信号）

4. ガバナンス成果物を確認:
   • CONTRIBUTING.md が存在し実行可能（「PR を出せ」だけでなく）
   • CODE_OF_CONDUCT.md が存在
   • ガバナンスドキュメントが意思決定プロセスを記述
   • issue/PR テンプレートが貢献者を導く

期待結果： 生存率、応答時間、多様性比、ガバナンス成果物チェックリストを伴うコミュニティ健全性スコアカード。

失敗時： PR データが不十分（クローズ PR <20 の新規プロジェクト）なら、サンプルサイズ制限を記し他信号を重く重み付けする。プロジェクトが非 GitHub プラットフォームを使うなら、クエリをそのプラットフォームの API に適合させる。

ステップ3: 置き換えリスクを計算する

外部貢献が内部開発によって陳腐化される可能性を判定する — フレームワーク採用者と貢献者にとっての最大のリスク。

1. 直近 50-100 のマージ済み外部 PR をサンプリング（少なければすべて）
2. 各マージ済み外部 PR について、貢献コードが後で次のいずれかになったかを確認:
   • Reverted: PR を参照する明示的 revert コミット
   • Rewritten: 同じファイル/モジュールが 90 日以内に内部貢献者により実質的に変更
   • Obsoleted: 機能が後続リリースで除去または置換
3. 計算: supersession_rate = (reverted + rewritten + obsoleted) / total_merged_external
4. 公開ロードマップ（あれば）を外部貢献者がアクティブな領域とマップ:
   • 高重複 = 高置き換えリスク（内部が外部作業の上に構築する）
   • 低重複 = 低置き換えリスク（外部が内部が手をつけないギャップを埋める）
5. 「貢献の罠」を確認: 貢献に親しみやすそうに見えるが内部書き換えが予定されている領域
6. 参照ベンチマーク: NemoClaw 解析は外部 PR の 71% が 6 ヶ月以内に置き換えられることを示した — 較正点として使う

期待結果： タイプ別内訳（reverted/rewritten/obsoleted）を伴う置き換え率（パーセンテージ）。ロードマップ重複評価。

失敗時： コミット履歴が浅いまたは squash-merged（属性を失う）なら、外部 PR ファイルパスを後続リリースで変更されたファイルと比較して置き換えを推定する。推定の信頼度低下を記す。

ステップ4: アーキテクチャ整合性を評価する

フレームワークのアーキテクチャがあなたのユースケースを過剰なロックインなしにサポートするかを評価する。

1. 拡張点をマップ:
   • プラグイン/拡張 API: フレームワークは文書化されたプラグインインターフェースを公開しているか？
   • 設定面: フォークなしに挙動をカスタマイズできるか？
   • フック/コールバックシステム: 重要箇所でフレームワーク挙動を傍受・変更できるか？
2. ロックインリスクを評価:
   • 書き換えコスト: 移行に要するエンジニアリング努力を見積もる（日/週/月）
   • データポータビリティ: データ/状態を標準形式でエクスポートできるか？
   • 標準準拠: フレームワークはオープン標準（agentskills.io、MCP、A2A）を使うか、プロプライエタリプロトコルか？
3. API 安定性を評価:
   • メジャーリリース毎の破壊的変更を数える（CHANGELOG、移行ガイド）
   • 非推奨ポリシーを確認（除去前の事前警告）
   • semver 準拠を評価（破壊的変更はメジャーバージョンのみ）
4. 特定ユースケースとの整合性を確認:
   • use_case が提供されていれば、フレームワークのアーキテクチャがそれを自然にサポートするか評価する
   • 回避策を要するアーキテクチャの不一致を特定する
5. 相互運用性を評価:
   • agentskills.io 互換性（スキルモデル整合）
   • MCP サポート（ツール統合）
   • A2A プロトコルサポート（エージェント間通信）

期待結果： 拡張点インベントリ、ロックインリスク評価（low/medium/high）、API 安定性スコア、ユースケース適合評価を伴うアーキテクチャ整合性レポート。

失敗時： アーキテクチャドキュメントが薄ければ、コード構造と公開 API 面から評価を導く。フレームワークが安定性履歴を持つには若すぎるなら、これを記しガバナンス信号を重く重み付けする。

ステップ5: ガバナンスと持続可能性を評価する

プロジェクトのガバナンスモデルが長期生存性と外部貢献者の公正な扱いをサポートするかを評価する。

1. ガバナンスモデルを分類:
   • BDFL（Benevolent Dictator for Life）: 単独意思決定者 — 速い決定、バスファクターリスク
   • Committee/Core team: 分散意思決定 — 遅いがよりレジリエント
   • Foundation-backed: 公式ガバナンス（Apache、Linux Foundation、CNCF）— 最も持続可能
   • Corporate-controlled: 単一企業が開発を駆動 — rug-pull リスクに注意
2. 資金と持続可能性を評価:
   • 資金源: VC 出資、企業スポンサー、補助金、コミュニティ資金、無資金
   • フルタイムメンテナー数: >=2 が健全; 0 はレッドフラグ
   • 収益モデル（あれば）: プロジェクトはどのように自身を持続させるか？
3. 貢献者保護を評価:
   • ライセンス種別: 寛容（MIT、Apache-2.0）vs コピーレフト（GPL）vs カスタム
   • CLA 要件: CLA 署名は貢献者を不利にする権利を移転するか？
   • 貢献者認知: 外部貢献者はリリース、changelog、ドキュメントでクレジットされるか？
4. セキュリティ姿勢を確認:
   • セキュリティ開示ポリシー（SECURITY.md または同等物）
   • CVE 開示からパッチリリースまでのメジアン時間
   • 依存更新慣行（Dependabot、Renovate、手動）
5. 軌道を評価:
   • ガバナンスモデルは進化しているか（例: foundation へ向かう）？
   • 最近のリーダー交代、買収、ライセンス変更はあったか？
   • メンテナーと貢献者の間に公の対立があるか？

期待結果： モデル分類、持続可能性評価（sustainable/at-risk/critical）、貢献者保護評価、セキュリティ姿勢概要を伴うガバナンス評価。

失敗時： ガバナンス情報が文書化されていなければ、その不在自体を黄旗として扱う。誰が PR をマージし、誰が issue をクローズし、誰がリリース決定をするかを調べて暗黙のガバナンスを確認する。

ステップ6: 投資準備性を分類する

すべての発見を、具体的な根拠と実行可能な推奨を伴う 4 ティア分類に統合する。

1. 各次元を採点（1-5 スケール）:
   • コミュニティ健全性: 生存率、応答性、多様性
   • 置き換えリスク: 率、ロードマップ重複、貢献の罠（反転: 低い方が良い）
   • アーキテクチャ整合性: 拡張点、ロックイン、安定性、ユースケース適合
   • ガバナンス持続可能性: モデル、資金、保護、セキュリティ
2. 分類閾値を適用:
   • INVEST（全次元 >=4）: 健全なコミュニティ、低置き換え（<20%）、整合したアーキテクチャ、持続可能なガバナンス。採用してエンジニアリング努力を貢献するのは安全。
   • EVALUATE-FURTHER（混合、いずれの次元も <2 ではない）: 具体的フォローアップを要する混合信号。明確化が必要なものを文書化し、再評価日を設定する。
   • CONTRIBUTE-CAUTIOUSLY（いずれかの次元が 2、いずれも <2 ではない）: 高い置き換え（>40%）またはガバナンス懸念。貢献を、明示的に要請された作業、メンテナー承認のスコープ、または core から疎結合のプラグイン/拡張開発に限定する。
   • AVOID（いずれかの次元が 1）: クリティカルなレッドフラグ — 放棄プロジェクト、外部に敵対的（生存率 <15%）、互換性のないライセンス、差し迫った rug-pull 兆候。エンジニアリング努力を投じない。
3. 分類レポートを書く:
   • ティア分類と一文の根拠で先頭を切る
   • 主要証拠と共に各次元スコアを要約
   • contribution_budget が提供されていれば、ティアを踏まえてその時間をどう配分するか推奨する
   • EVALUATE-FURTHER については、答えが必要な具体的質問を列挙しタイムラインを提案する
   • CONTRIBUTE-CAUTIOUSLY については、安全な貢献タイプ（プラグイン、ドキュメント、テスト）vs リスキー（コア機能）を指定する
4. comparison_frameworks が評価されていれば、すべてのフレームワークをランク付けする比較マトリクスを作る

期待結果： ティア、次元スコア、証拠概要、投資文脈に合わせた実行可能な推奨を伴う分類レポート。

失敗時： データギャップが信頼できる分類を妨げるなら、何のデータが欠けてどう得るかを明示的に文書化して EVALUATE-FURTHER を既定とする。不確かなときに INVEST を既定としない。

バリデーション

• センサスデータが集められた: スター、フォーク、依存、リリース周期、バスファクター、ランドスケープ位置
• コミュニティ健全性が定量化された: 生存率、応答時間、貢献者多様性、ガバナンス成果物
• 置き換えリスクがタイプ別内訳（reverted/rewritten/obsoleted）と共に計算された
• アーキテクチャ整合性が評価された: 拡張点、ロックインリスク、API 安定性、ユースケース適合
• ガバナンスが評価された: モデル、資金、貢献者保護、セキュリティ姿勢
• 分類が作成された: INVEST / EVALUATE-FURTHER / CONTRIBUTE-CAUTIOUSLY / AVOID のいずれか
• 各次元スコアが解析からの具体的証拠と共に正当化された
• 推奨が実行可能で（提供されていれば）貢献予算に較正されている
• データギャップと信頼度制限が明示的に文書化された

よくある落とし穴

• 人気と健全性の混同: 高スターだが低貢献者多様性は単一障害点を意味する。1 メンテナーの 5 万スタープロジェクトは、15 アクティブ貢献者の 2 千スタープロジェクトより不健全。
• 置き換えリスクの無視: 外部貢献が失敗する最も一般的な理由。歓迎するコミュニティも、内部開発が日常的に外部作業を上書きするなら無意味。
• ガバナンス確認なしのアーキテクチャ過重視: 美しく設計されたフレームワークも、ガバナンスモデルが持続不能または外部に敵対的なら失敗しうる。
• EVALUATE-FURTHER を AVOID として扱う: 混合信号は調査を要し、却下ではない。具体的な再評価日を設定し、答えるべき具体的質問を列挙する。
• スナップショットバイアス: すべての指標は時点。優れた現指標を持つ衰退プロジェクトは、平凡な現指標を持つ改善プロジェクトより悪い。常に 6-12 ヶ月のトレンド方向を確認する。
• CLA 油断: 一部の CLA は著作権をプロジェクトオーナーに移転する、つまり貢献が彼らのプロプライエタリ資産になる。チェックボックスだけでなく CLA 本文を読む。
• 単一フレームワークへの錨付け: 比較フレームワークなしには、どのプロジェクトも素晴らしくも酷くも見える。インフォーマルでも常に最低 1 つの代替に対してベンチマークする。

関連スキル

• polish-claw-project — この評価が情報を与える貢献ワークフロー
• review-software-architecture — ステップ4のアーキテクチャ評価で使用
• forage-solutions — 比較用の代替フレームワーク発見
• search-prior-art — ランドスケープマッピングと先行作業解析
• security-audit-codebase — ステップ5で参照されるセキュリティ姿勢評価
• assess-ip-landscape — ライセンスと IP リスク解析