autonomous-agent-readiness

自律型エージェント対応状況の評価

自律型エージェントの実行に関する実証済みのパターンに照らしてコードベースを評価し、プロジェクトに合わせた推奨事項を提示します。

基本理念

エージェントの失敗の多くは、モデルの問題ではなくシステム設計の問題です。あらゆる段階で人間の承認を必要としたり、開発者のノート PC が起動していることに依存したりするエージェントは、自律的ではありません。自律性はインフラストラクチャ上の決定事項です。

評価ワークフロー

フェーズ 1：現状の把握

プロジェクトの現在の状態に関する情報を収集します。

1. プロジェクト構成を調べる

   • CI/CD 設定（.github/workflows/、Jenkinsfile、.gitlab-ci.yml）を確認します
   • コンテナ化の状況（Dockerfile、docker-compose.yml、devcontainer.json）を確認します
   • テストインフラストラクチャ（tests/、__tests__/、テスト設定ファイル）を特定します
   • 環境管理ファイル（.env.example、requirements.txt、package.json）を探します

2. 開発ワークフローを確認する

   • コントリビューションガイドライン、README、開発者向けドキュメントを読みます
   • サンドボックス化や分離のパターンを確認します
   • データベースのセットアップスクリプトやフィクスチャを探します
   • 依存関係の管理方法を特定します

3. 現在の自動化を評価する

   • 既存の CI/CD パイプラインを確認します
   • 自動テストのパターンを確認します
   • 環境のプロビジョニングスクリプトを探します
   • クリーンアップやティアダウンの手順を特定します

フェーズ 2：原則に照らして評価する

各評価項目を 0～3 点で採点します。詳細な評価基準については、references/assessment-criteria.md を参照してください。

評価項目	確認する内容
サンドボックスによる分離	一時的な環境、コンテナのサポート、実行ごとのクリーンな状態
データベースの独立性	ローカル DB のセットアップ、コード内のマイグレーション、外部 DB 依存の排除
環境の再現性	明示的な依存関係、隠れた状態がないこと、決定論的なセットアップ
セッションからの独立性	リモート実行機能、ユーザーセッションに依存しないこと
成果重視の設計	明確な受け入れ基準、手順への依存を最小限に抑えること
直接的なインターフェース	CLI 優先のツール、OS プリミティブ、抽象化レイヤーの最小化
フレームワークのオーバーヘッドの最小化	シンプルなインターフェース、重いオーケストレーションがないこと、組み合わせ可能な CLI ツール
明示的な状態	ワークスペースディレクトリ、ファイルベースの成果物、確認可能なログ
ベンチマーク	測定可能な品質基準、自動検証
コストへの配慮	リソース制限、使用状況の追跡、明示的なプロビジョニング
検証可能な出力	自動検証、決定論的な結果、明確な終了コード
インフラストラクチャによる権限制限	システムによる制約、最小権限、実行時のプロンプトがないこと

フェーズ 3：推奨事項を作成する

評価項目のスコアが 2 未満の場合、それぞれについて以下を提示します。

1. 現状：現在あるもの
2. 不足点：自律的な実行に必要なもののうち、欠けているもの
3. 推奨事項：具体的で実行可能な改善策
4. 優先度：影響と労力に基づく高／中／低

以下の点を考慮して、プロジェクトに合わせた推奨事項を提示します。

• 技術スタック
• チームの規模とワークフロー
• 既存のインフラストラクチャ
• デプロイ先

出力形式

# Autonomous Agent Readiness Assessment

## Project: [name]
## Assessment Date: [date]

## Executive Summary

[1-2 paragraphs summarizing overall readiness and top priorities]

**Overall Readiness Score: X/36** (sum of dimension scores)

## Dimension Scores

| Dimension | Score | Status |
|-----------|-------|--------|
| Sandbox Isolation | X/3 | [emoji] |
| Database Independence | X/3 | [emoji] |
| ... | ... | ... |

Status: 0-1 = needs work, 2 = adequate, 3 = strong

## Detailed Findings

### [Dimension Name] (X/3)

**Current State:**
[What exists]

**Gap:**
[What's missing]

**Recommendation:**
[Specific action]

**Priority:** [High/Medium/Low]

[Repeat for each dimension]

## Prioritized Action Plan

### Immediate (This Week)
1. [Highest impact, lowest effort items]

### Short-term (This Month)
1. [Important foundational changes]

### Medium-term (This Quarter)
1. [Larger infrastructure investments]

## Quick Wins

[2-3 changes that can be made today with minimal effort]

基本原則の参照

すべてをサンドボックスで実行する

エージェントの各実行は、それぞれ独自の一時的で隔離された破棄可能な環境で実行します。環境はクリーンで、書き込み可能なファイルシステム、コマンド実行機能、範囲を限定したネットワークアクセスを備えます。出力を検証した後、環境を破棄します。

外部データベースを使わない

エージェントはサンドボックス内に独自のデータベースを作成します。必要に応じてパッケージをインストールし、DB をローカルで起動して、マイグレーションを実行し、データを明示的にシードし、最後にティアダウンします。共有状態なしで、再現可能な実行を実現します。

環境に蓄積する不要なものは無視できない

長期間使われる環境には、余分なファイル、中途半端にインストールされたパッケージ、キャッシュされた状態、孤立したプロセスが蓄積します。新しい環境なら正しさが明らかになりますが、永続的な環境では問題が見えにくくなります。

ユーザーセッションから独立して実行する

エージェントのループをブラウザーのタブ、ターミナルセッション、開発者のマシンから切り離します。タスクを開始したらノート PC を閉じ、完了した成果物を後で確認できるようにします。実行時間の上限、リソース制限、自動クリーンアップによって制御します。

手順ではなく成果を定義する

手順を一つずつ示す計画や、ツールレベルでの細かな指示は避けてください。望ましい成果、受け入れ基準、制約を定義します。計画と実行はエージェントに任せます。

直接的で低レベルなインターフェース

コマンドの実行、永続ファイル、ネットワークリクエストに直接アクセスできるようにします。抽象化レイヤーよりも OS のプリミティブを優先します。CLI 優先のシステムは、見た目以上にデバッグしやすく、高い能力を発揮します。

状態を明示的に保持する

中間結果、ログ、部分的な出力、計画用の成果物を保存できる、書き込み可能なワークスペースディレクトリを用意します。ファイルは検査可能で決定論的なため、実行後の分析にも役立ちます。

ベンチマークを早期に導入する

ベンチマークはできるだけ早く導入します。品質を測る、代表性があり再現可能な指標を用意します。粗雑なベンチマークでも、ないよりは有用です。

フレームワークのオーバーヘッドを最小限にする

実際のエージェントのワークフローの多くは、コマンドの実行、ファイルの読み書き、ネットワークリクエストに集約されます。CLI 優先のシステムは、見た目以上に推論やデバッグがしやすく、高い能力を発揮します。抽象化レイヤーがタスクより複雑になると、それがボトルネックになります。

コストを見越して計画する

トークン使用量を見積もり、コンピューティングリソースを明示的に割り当て、システムによって上限を適用します。自律性によってコストが発生する場所は変わりますが、コストがなくなるわけではありません。

検証可能な出力

人によるレビューなしで検証できる出力にします。自動検証、決定論的な結果、明確な成功・失敗の終了コードを用意します。品質を測定できなければ、自律運用で信頼することはできません。

インフラによる権限の制約

権限はプロンプトや実行時の判断ではなく、環境によって制約します。明示的に機能を許可し、危険な操作をサンドボックスで制限し、デフォルトでは最小権限を適用します。実行時の権限確認プロンプトは不要です。