mcpField

agent-readiness

github.com/supatest-aiエージェントワークフロー256 回インストール2 週間前に更新
リポジトリ

agent-readiness について

agent-readinessは、タスク仕様からローカル検証までをコーディングエージェントが進められるリポジトリか評価します。スクリプトは静的チェックと任意のセッションログ分析を行い、スコアや課題、対策を含むHTMLレポートを生成します。

主な機能

  1. 01リポジトリの対応状況を自動評価
  2. 02任意のコーディングエージェントログ分析
  3. 03エンジニアリング項目ごとの採点
  4. 04優先アクション付きHTMLレポート

活用シーン

  1. 01エージェントへのタスク依頼前にリポジトリの課題を特定
  2. 02コーディングエージェントのセッションで反復する失敗を確認
  3. 03ローカル検証ワークフローの改善順を決定

MCP 対応

利用可能なセッションログから、MCPスキーマに関する反復的な問題を検出できます。MCPサーバーやクライアントの機能は記載されていません。

インストール

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

$npx skills add https://github.com/supatest-ai/supa-skills --skill agent-readiness

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

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

scripts/
analyze_sessions.py
compact_sessions.py
render_html_report.py
run_readiness_check.py
sample_sessions.py
session_events.py
test_session_events.py

詳細

エージェント対応度の評価

自律型コーディングエージェントが、人間の手助けを受けずに仕様から実装、ローカルでの検証までタスクを進めるための十分な構造が、リポジトリに備わっているかを評価します。

自動分析（デフォルト）

このスキルには、scripts/ ディレクトリに分析スクリプトが含まれています。Python 3 を利用できる場合は、セッションログのパターン分析を含む評価全体を実行する統合ランナーを使用します。

# Full assessment (with session log analysis)
python3 scripts/run_readiness_check.py \
  --sessions-dir ~/.claude/projects/PROJECT-NAME \
  --repo .

# Static audit only (no session logs needed — fastest)
python3 scripts/run_readiness_check.py \
  --repo . \
  --skip-sessions \
  --output /tmp/agent-readiness-report.html

出力されるHTMLレポートは /tmp/agent-readiness-report.html にあります。成熟度レベル、各評価項目のスコア、失敗パターン、重大な不足点、優先順位付きのアクションプランが記載されています。

セッションログ分析

セッションログ（Claude Code、Codex、Cursor などの ~/.claude/projects/ にある .jsonl ファイル）を利用できる場合、分析ツールは以下を検出します。

  • 分類の分布（調査のみ、検証のみ、ブロックされたタスク、タスク完了者など）
  • 失敗したツールとコマンドの上位項目
  • 繰り返し発生する失敗パターン（ブラウザー認証、テストの失敗、MCP スキーマの問題など）
  • 編集後の検証率
  • 選択したセッションの簡潔な定性的な要約

反復作業の際にサンプル数を減らすには、--max-sessions N を渡します。分析ツールは解析結果をファイルハッシュ単位でキャッシュするため、再実行はほぼ瞬時に完了します。

スコアリングチェックリスト

手動でスコアを付ける場合（または自動出力を検証する場合）は、次の基準を使用します。

項目対象確認事項欠けている場合の影響
1仕様の明確さAC、エッジケース、対象外事項を含む構造化テンプレートテンプレートなし → 上限 3
2エージェント向け指示スタック、パス、コマンドを記載したルートの AGENTS.mdなし → 上限 2
2エージェント向け指示リスクの高い不変条件（マイグレーション、シークレットなど）を文書化不足 → −1
3コードの明確さ厳密な TypeScript または同等の静的型付けなし → 上限 2
3コードの明確さビジネスロジックをフレームワーク固有の接着コードから分離混在 → −1
4検索性機能のフローを名前やルートから発見可能隠れている → −1
4検索性生成コード／ベンダーコードを明確に表示混在 → −0.5
5ローカル環境依存関係のロックファイルをコミットロックファイルなし → 上限 2
5ローカル環境1 コマンドで実行できるセットアップスクリプト手動 → −1
6テストユニットテスト、統合テスト、E2E テストが存在なし → 上限 1
6テスト対象範囲ごとに絞り込んだテストコマンド一括実行のみ → −0.5
7静的検証リンターを設定し、使い方を文書化なし → 上限 2
7静的検証コミット前フックまたは CI フックで lint を強制なし → −0.5
8ビルド時のフィードバックパッケージ単位のビルドコマンドが存在ルートのみ → −0.5
8ビルド時のフィードバックHMR を使う開発モードを文書化なし → −1
9デバッグのしやすさテストで診断用成果物（スクリーンショット、トレース）を生成なし → −1
9デバッグのしやすさ構造化されたエラー型エラーが通知されない → −1
10安全性破壊的なマイグレーションのワークフローが明確暗黙的 → 上限 3
10安全性シークレット／環境ファイルを .gitignore に記載除外されていない → 上限 2
11ブラウザー自動化認証のバイパスでログインページを回避手動ログイン → 上限 2
11ブラウザー自動化安定したセレクター（data-testid または a11y ロール）CSS クラス → −1

各評価項目を 3 から始め、チェックリストに従って加点・減点します。最大は 5、最小は 1 です。

評価項目
#評価項目
1コードの理解しやすさ — 強い型付け、明確な名前、予測可能な構造
2コンテキストとドキュメント — AGENTS.md、README、ADR、インラインの理由説明
3検証可能性とテスト — テストピラミッド、型チェッカー、リンター、CI ゲート
4開発環境の再現性 — 1 コマンドでのセットアップ、ロックされた依存関係、コンテナ化されたサービス
5スタイルと検証ツール — 厳格なリンター、フォーマッター、pre-commit フック
6ビルドシステム — 再現可能なビルド、高速なフィードバック、HMR
7可観測性とデバッグのしやすさ — 構造化ログ、ヘルスチェック、対処可能なエラー
8セキュリティとガバナンス — ブランチ保護、シークレットスキャン、CODEOWNERS
9タスクの発見とスコープ設定 — イシューテンプレート、受け入れ基準、完了の定義
10仕様と計画の品質 — 構造化された PRD、API 契約、測定可能な成功基準
11CI/CD とデプロイパイプライン — 自動化されたゲート、ステージング、ロールバックのドキュメント
成熟度レベル
レベルスコアエージェントが実行できること
不安定<2.0調査のみ。綿密な監督が必要
ドキュメント化済み2.0–2.9綿密なレビューのもとで小規模な変更
標準化済み3.0–3.9スコープが明確なタスクとローカルでの検証
最適化済み4.0–4.4軽いレビューのもとで複雑な複数ファイルにまたがるタスク
自律的4.5+仕様からテスト済みの実装までを、戦略的な監督のもとで実行
手動モード（Python なし）

Python 3 を利用できない場合は、上記のチェックリストを使って各評価項目を手動で 1～5 点で採点します。全体レベル、評価項目の表、重大なギャップ、アクションプラン、網羅率の表を含むレポートを作成します。出力形式の参考として、自動生成レポートを参照してください。

レポートの提供

チームでアーティファクト／ドキュメントツールを利用できる場合は、HTML ドキュメントのアーティファクトとしてレポートを保存します。それ以外の場合は、概要をチャットに表示し、完全な HTML ファイルのパス /tmp/agent-readiness-report.html を記載します。

更新情報

このスキルは supatest-ai/supa-skills マーケットプレイスから提供されます。スクリプトの信頼できる唯一の情報源は、supatest-ai/aiden リポジトリの .agents/skills/agent-readiness/scripts/ にあります。

コメント

Markdown 対応