agent-retro

エージェントの振り返り

これらのセッションで発生した問題を防げた、エージェントの環境の変更点を見つけてください。レポートを返し、何も変更しないでください。

手順

1. このスキルのディレクトリから python3 scripts/collect.py --since <date> を実行します。期間を指定しない場合は、現在のセッションを確認してください。
2. ログを最初からすべて読む前に、問題を検索します。ユーザーによる訂正、中断、拒否または失敗したツール呼び出し、承認やサインインのプロンプト、ブラウザーの自動操作、ユーザーが貼り付けた内容、元に戻された編集、繰り返された検索、繰り返し指摘されたレビュー所見、複数のセッションで繰り返されたコマンドやインラインスクリプトを探します。それぞれの前後の抜粋を読みます。
3. 問題を原因ごとに分類します。複数のセッションにまたがる場合は、少なくとも2つのセッションで発生した原因だけを残します。サブエージェントやレビューのスレッドは、それを開始したセッションの一部として数えます。各原因に、グローバル、特定のリポジトリ固有、特定の技術スタック固有のいずれかのタグを付けます。
4. スクリプトが一覧表示する各 Remove-When: トレーラーについて、その条件と、コミットが名指しする原因が再発したかどうかを確認します。条件が満たされているもの、より上位の層の修正でカバーされているもの、または誤作動している修正の削除を提案します。修正後に原因が再発した場合は、より上位の層での修正を提案します。
5. 以下のカテゴリから原因ごとに修正を提案し、タグが示す場所に配置します。優先順位は、設定またはインストール済みツール、スクリプト・リンタールール・コンパイラの非推奨化・CI チェック、ハーネスフック、スキル、常時読み込まれる指示の順です。フックまたはそれより後の手段を選ぶ場合は、より上位の層での修正を見送った理由を示します。フックは、1つのハーネス内で条件に一致するすべての呼び出しで実行されるため、対象を厳密に絞り、該当した場合のみ出力し、ほかのどのハーネスに影響が及ばないかを明記します。追加する修正にはそれぞれ Remove-When: トレーラーを付け、修正が存在したまま確認できる条件（ツール、モデル、上流の変更など）を記載します。修正が機能している間、原因は発生しないため、原因が発生していないことを修正不要の根拠にしてはいけません。提案する指示には write-for-agents を適用します。
6. 各原因の再発頻度と発生コストに基づいて、候補に順位を付けて返します。各候補には、カテゴリ、タグ、証拠（セッション、日付、秘密情報を伏せた短い引用）、修正案を記載します。修正がすでに存在する原因には「修正済み」と記し、修正の効果を確認する方法を説明します。スクリプトが読み取ったハーネス名を列挙し、出力されたエラーがあれば引用します。手順3のすべての原因に候補があり、手順4のすべてのトレーラーに結果が出たら終了します。

カテゴリ

• navigation。エージェントがファイルや事実を見つけるのに時間がかかった、またはファイル間の隠れた依存関係を見落としました。エージェントが最初に調べた場所にポインターを追加してください。
• checks。自動チェックで検出できるミスをエージェントが犯したか、マージ前にリポジトリで lint、型チェック、テストのチェックが実行されていません。まずリポジトリのチェックコマンドと CI を確認してください。チェックが存在するのに接続されていない、または壊れている場合は、それが指摘事項です。
• codify。エージェントがセッションをまたいで、ステータスのポーリング、API クライアントの作成、ログの抽出、セットアップ手順の実行など、定型作業を繰り返しました。作業対象のリポジトリに、失敗時にゼロ以外の値を返す、コミット済みのスクリプトまたはタスクランナーのターゲットを提案してください。
• review。レビュ―エージェントまたはスキルがミスを見落としたか、同じミスを繰り返し指摘しています。禁止された API やインポート形式など、機械的に判定できる違反には、lint ルール、フック、または CI ジョブによる確定的なチェックを提案してください。判断が必要なレビュー規則はそのままにしてください。
• instructions。エージェントが指示ファイルまたはスキルを無視した、誤読した、起動すべきでないときにスキルが起動した、または起動すべきときに起動しなかった、あるいは指示が何も変えていません。指示を移動する前に、文言を修正してください。
• tools。エージェントがコストの高いツール呼び出しや同じツール呼び出しを繰り返した、またはツールや MCP サーバーがトークンを無駄にしています。同じサービスで CLI が使えるのに、MCP サーバーが失敗する、またはサインインを求める場合は、そのサーバーの削除を提案してください。
• access。エージェントにサーバーログやサービスへの読み取り専用アクセスなど、必要な情報がありませんでした。または、MCP サーバーや CLI で同じ作業ができたにもかかわらず、ブラウザー自動化やユーザーが貼り付けたコンテンツを通じてサービスにアクセスしました。そのサービスの MCP サーバー、またはすでにインストールされていて正常に動作する場合はその CLI を提案し、必要なサインイン方法を明記してください。