mcpField
A
agent-architecture-analysis

agent-architecture-analysis

github.com/existential-birdsエージェントワークフロー85213 回インストール11 週間前に更新
リポジトリ

agent-architecture-analysis について

12-Factor Agents の原則に照らしてコードベースのエージェント設計を評価するスキルです。13 項目の証拠に基づく採点を行い、課題と改善案をまとめます。

主な機能

  1. 0113 項目のエージェント設計を評価
  2. 02コードとドキュメントから証拠を検索
  3. 03Strong・Partial・Weak で適合度を採点
  4. 04課題と実行可能な改善案を記録
  5. 05採点前に必須ゲートを確認

活用シーン

  1. 01既存の LLM システムのレビュー
  2. 02本番エージェントアプリの監査
  3. 03新規システムの設計判断の評価
  4. 04エージェントコードベースの改善計画

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/existential-birds/beagle --skill agent-architecture-analysis

インストール後、Claude Code で/agent-architecture-analysisを入力して読み込まれたか確認します。

同梱ファイルreferences/factors.md

詳細

12-Factor Agents 準拠分析

参考資料：12-Factor Agents

入力パラメーター

パラメーター説明必須
docs_pathドキュメントディレクトリのパス（既存の分析用）任意
codebase_path分析対象のコードベースのルートパス必須

分析フレームワーク

各要素の原則、検索パターン、ファイルパターン、準拠基準（強・部分的・弱）およびアンチパターンをまとめた完全な評価基準は、references/factors.md にあります。分析ワークフローでは、実行する検索パターンと評価基準を確認するため、該当する要素のセクションを参照してください。

#要素焦点
1自然言語からツール呼び出しへLLM によるスキーマ検証済みの構造化出力
2プロンプトを自分で管理するプロンプトを第一級の、バージョン管理されたテンプレート付きコードとして扱う
3コンテキストウィンドウを自分で管理する履歴・状態・ツールの結果を独自にフォーマットする
4ツールは構造化出力である検証済み JSON が決定論的なコードを起動する
5実行状態を統合する実行状態とビジネス状態を統合した単一の状態オブジェクト
6起動・一時停止・再開任意の場所で起動、一時停止、再開できる API
7ツールで人間に連絡する構造化されたツール呼び出しとして人間への連絡を行う
8制御フローを自分で管理するフレームワークのデフォルトではなく、独自のルーティングと再試行を行う
9エラーをコンテキストに取り込む自己修復とエスカレーションのため、エラーをフィードバックする
10小さく、特化したエージェント責任範囲を絞り、各エージェントを3〜10ステップで構成する
11あらゆる場所から起動するCLI／REST／WebSocket／チャット／Webhook のエントリーポイント
12ステートレスなリデューサー純粋な (state, input) -> (state, output) エージェント
13コンテキストを事前取得する必要になる可能性が高いデータをあらかじめ取得する

上記のすべての要素に関する完全な評価基準については、references/factors.md を参照してください。

出力形式

ゲートの順序： 対象範囲の要素について、分析ワークフローの後に記載されているハードゲートを満たすまでは、「強」「部分的」「弱」の判定を割り当てたり、推奨事項を確認済みの事実として扱ったりしないでください。

エグゼクティブサマリーテーブル
| Factor | Status | Notes |
|--------|--------|-------|
| 1. Natural Language -> Tool Calls | **Strong/Partial/Weak** | [Key finding] |
| 2. Own Your Prompts | **Strong/Partial/Weak** | [Key finding] |
| ... | ... | ... |
| 13. Pre-fetch Context | **Strong/Partial/Weak** | [Key finding] |

**Overall**: X Strong, Y Partial, Z Weak
要素ごとの分析

各要素について、次の内容を記載してください。

  1. 現在の実装

    • ファイル名と行番号を示した根拠
    • パターンを示すコードスニペット

  2. 準拠レベル

    • 根拠とともに「強」「部分的」「弱」を記載

  3. ギャップ

    • 12-Factor の理想と比較して不足している点

  4. 推奨事項

    • コード例を含む、実行可能な改善案

分析ワークフロー

  1. 初期スキャン

    • すべての要素について検索パターンを実行する
    • 各要素の主要なファイルを特定する
    • 既存の準拠ドキュメントがあれば記録する

  2. 詳細分析（要素ごと）

    • 特定したファイルを読む
    • 準拠基準に照らして評価する
    • ファイルパスを添えて根拠を記録する

  3. ギャップ分析

    • 現状と12-Factor の理想を比較する
    • 存在するアンチパターンを特定する
    • 影響度に基づいて優先順位を付ける

  4. 推奨事項

    • 実行可能な改善案を提示する
    • 変更前後のコード例を含める
    • ロードマップがあれば参照する

  5. 要約

    • エグゼクティブサマリーテーブルを作成する
    • 強みと重大なギャップを明らかにする
    • 改善の優先順位を提案する

厳格なゲート（スコアの前に証拠を確認）

以下を順番に実行してください。先に進まないでください。各 Pass は、内部的な確信ではなく、確認可能な客観的条件（ディスク上のパス、引用の有無など）です。

  1. スキャンゲート — 初期スキャン（ワークフローのステップ 1）の後、Pass： 各要因（1～13）について、(a) 調査対象となるリポジトリ相対パスまたは glob の検索結果が 1 件以上ある、または (b) 理由を添えた 1 行のメモがある（例：検索コマンド／出力、または「該当なし — コードベースでこの懸念事項が扱われていない可能性があります」）。中身のないあいまいな説明（「問題なさそう」）ではこのゲートを通過できません。
  2. 証拠ゲート（要因ごと） — その要因について Strong / Partial / Weak と記載する前に、Pass：「Current Implementation」に、codebase_path 内のファイルパスと行範囲または短い引用スニペットを含む引用が 1 件以上あるか、対象を絞って調査した後に明示的な証拠は見つからなかったという記述があります。検索しても証拠が見つからない場合、基準が明らかに該当しない場合（理由を記載してください）を除き、その要因は Weak としてください。
  3. 統合ゲート — エグゼクティブサマリーの表と要因ごとの分析セクションについて、Pass： 対象範囲内の要因についてゲート 1～2 を満たした後にのみ作成してください。推奨事項で新しいファイルやパターンに言及する場合は、提案として示してください。ステップ 2 の該当する引用がない限り、確認済みの事実として提示してはいけません。

クイックリファレンス：コンプライアンスのスコアリング

スコア意味対応
Strong原則を完全に実装しています維持し、軽微な最適化を行う
Partial一部は実装されていますが、大きなギャップがあります改善を計画する
Weak実装が最小限、または実装されていませんロードマップで優先度を高くする

このスキルを使用する場合

  • LLM を活用した新しいシステムを評価する
  • エージェントのアーキテクチャ上の決定をレビューする
  • 本番環境のエージェント型アプリケーションを監査する
  • 既存のエージェントの改善を計画する
  • フレームワークや実装を比較する

コメント

Markdown 対応