agent-architecture-lens

エージェントアーキテクチャの視点

エージェントの制御フロー、状態、障害処理がどのように構成されているかを確認する際に、このスキルを使用します。ReAct ループ（推論、実行、観察、反復）は、あらゆるエージェントの基本単位であり、正しいものです。しかし、それだけでは不十分です。実行が長く複雑になるにつれて、劇的な障害が一度起きるのではなく、静かにその限界を超えていきます。

ループとは、1 つのノードと、そのノード自身に戻る 1 つのエッジで構成されるグラフです。基本原則は、アーキテクチャはタスクの形と期間に従うということです。図の美しさに従うのではありません。

すべてのレビューでは、2 つの指針を軸にします。グラフはアップグレードではありません：構造は実際に直面した要件への対応です。そのような要件のないタスクにはループを維持し、レビューでもその旨を明確に伝えます。記録簿であり、トランスクリプトではありません：何があっても失われてはならない進捗は、モデルが覚えていることを期待するメッセージ履歴ではなく、永続的な成果物に保存します。レビューでは、この 2 つを名前を挙げて示してください。

最初の確認：6 つのシグナル

構造を推奨する前に、6 つのシグナルのうちどれが該当するかを番号で示してください。

1. 状態が 1 つのコンテキストウィンドウを超える。 実行が、モデルの作業メモリに収まらない量の情報を追跡します。
2. 実行をクラッシュ後も継続する必要がある。 実行途中で失われることが許容できません。数分間の作業、実際に発生する API 費用、待機中のユーザーが関わります。
3. 実行途中で人間の承認が必要。 エージェントが続行する前に人が確認する必要があり、確認に数時間かかる場合もあります。
4. ワークフローに並列の分岐がある。 直列化すべきでない、真に独立したサブタスクが存在します。
5. 複数のモデルやエージェントが連携する必要がある。 ステップごとに異なるモデル、ツール、権限が必要です。
6. 実行を再現可能かつ監査可能にする必要がある。 後から「この実行で具体的に何が起きたのか」と尋ねられます。

該当するシグナルが 0 個の場合は、ループを維持するよう推奨して終了します。率直に述べてください："シグナルは該当しません。これはループのままにします — グラフはアップグレードではありません。" ここで構造を追加しても、遅延とテスト対象が増えるだけで、得るものはありません。

1 個以上該当する場合、それぞれのシグナルが設計に求める具体的な仕組みを示し、以下の確認項目では該当するものだけを検証します。それ以外を持ち込まないでください。

段階的な拡張

各段階は前の段階よりコストがかかるため、構造は次の順序で追加します。各段階は、実際に該当したシグナルによって正当化されなければなりません。

1. 状態を外部化する。 実行が記憶すべき情報をメッセージ一覧から取り出し、名前付きフィールドと宣言されたデフォルト値を持つ型付き構造にします。最も効果が高く、最もコストが低い方法です。モデルが 6 ステップ前に生成した値を探すために、自身の過去の推論を掘り返さずに済みます。
2. チェックポイントを追加する。 各ステップの後に状態を書き込み、クラッシュ後に最初からやり直すのではなく再開できるようにします。これがループからグラフへの実際の移行です。
3. 責任を名前付きのステップに分ける。 ステップごとに異なるモデル、ツール、権限、エラー処理が必要な場合は分割します。1 つのステップに 1 つの役割を持たせます。
4. 分岐と並列化を行う。 最後に行います。真に独立した作業、または真に異なる経路がある場合に限ります。

通常、シグナル 1 と 6 は段階 1 で対応できます。シグナル 2 と 3 には段階 2 が必要です。シグナル 5 には段階 3 が必要です。段階 4 が必要なのはシグナル 4 だけです。

実装の視点

次の 5 つの領域を順に確認します。該当するシグナルがない領域は飛ばしてください。

状態

実行が何を記憶し、どこに保存し、誰が書き込み、増加にどれだけコストがかかるかを確認します。

次の点を確認してください。

1. 現在のコンテキストウィンドウを超えて保持する必要がある値はどれですか。また、本当に一時的な値はどれですか？
2. 保存される各フィールドに型とデフォルト値があり、2 つのステップがそのフィールドに書き込む場合のルールが定義されていますか？
3. 状態が失われた場合、永続的な入力から再構築できますか。それとも状態だけが唯一のコピーですか？
4. 大きなペイロードは状態内に直接保存されていますか。それとも外部ストアの ID を介して保存されていますか？
5. メッセージ履歴の増加は何によって抑えられていますか。トークン数のしきい値に達したときの要約ステップですか。それとも何もありませんか？

リトライ

リトライを決めるのはモデルではありません。 モデルの推論内でリトライ回数を管理すると、デッドエンドポイントへの15回の試行と、1回だけ試して結果を捏造するという、どちらの失敗パターンも起こり得ます。

確認事項：

1. 試行回数は次の実行で読み取れる場所に記録されていますか。それとも毎回、記憶から再導出されますか？
2. カウンターは試行の_前に_加算されますか？ 試行の途中でクラッシュしても、試行として数える必要があります。
3. 回数が上限に達したときのフォールバック先は何ですか。名前の付いたエスカレーションですか。それとも未処理の行き止まりですか？
4. リトライ対象のステップは、一時的な障害と恒久的な障害を区別しますか。それとも両方を同じようにリトライしますか？
5. 失敗するツールを、外部から回数を制限されることなく再度呼び出せる経路はありますか？

終了条件

すべての実行には、3つの終了条件が必要です。成功、リトライ上限到達、そしてハード上限（最大ステップ数、最大トークン数、支出上限、または期限）です。3つのうち2つしかない場合、停止条件を装った無制限の実行になります。

確認事項：

1. この実行を成功として終了する条件は何ですか？ それは状態値ですか。それとも完了したというモデルの判断ですか？
2. 作業を完了できない場合はどうなりますか。名前の付いた失敗終了条件がありますか。それともループしますか？
3. ハード上限は、モデルの協力なしに数えられる単位で、どのように設定されていますか？
4. 上限に達したことを誰が検知し、何が表示されますか？
5. 長時間実行するものや有料のものについて、支出上限は設定されていますか。また、ユーザーにはそれが伝えられていますか？

副作用

判断（「この内容でメールを送信する」）と実行（「メールを送信する」）を分離します。判断のステップは安全に再実行できますが、実行のステップは冪等でなければなりません。副作用の発生後、チェックポイントを記録する前にクラッシュすると、復旧時にそのステップが再実行されるためです。

確認事項：

1. 実行の外部に書き込むステップはどれですか。メッセージ、コミット、PR、チケット、支払い、デプロイなどですか？
2. 各ステップには、効果を実行する_前に_状態へ書き込まれ、再実行時に最初に確認される、安定したキーがありますか？
3. 実行する判断は実行そのものと別に記録され、再実行時には後者だけが再実行されますか？
4. 2つの並列ステップが同じ状態フィールドに書き込んだり、同じレート制限付き API にアクセスしたりする可能性はありますか？
5. ツールはステップごとにスコープが設定されていますか。そのため、読み取りのみを行うべきステップが書き込みを行えないようになっていますか？

復旧とゲート

確認事項：

1. 人間によるゲートで実行を一時停止する場所はどこですか？ また、承認はプロセスの再起動後も保持されますか。それとも、消えてしまう会話ターンですか？
2. 再開時に実行を識別するものは何ですか。また、再開するステップをどのように特定しますか？
3. クラッシュ後の再開テストはありますか。実行を途中で強制終了し、再起動して、適切なカウンターを使って正しいステップから再開することを検証しますか？ これは任意ではなく、必須の統合テストです。
4. 実行トレースから、「何が、どの順番で、どの入力と出力を使って実行されたか」が分かりますか？
5. 古いチェックポイントを削除するのは何ですか。また、監査期間はどれくらいですか？

グラフにかかるコスト

構造を推奨する際は、そのコストも明示してください。これがあるからこそ、このレンズは単純なループに対して proceed を返せます。

コスト	どのようなものか
レイテンシ	チェックポイントごとに書き込みが発生し、境界ごとにシリアライズのサイクルが発生します。実際に存在しますが、通常は目に見えません。サブ秒の対話型処理では重要になります。
調整	並列ブランチには合流点が必要で、各ブランチは独立して失敗します。そのため、ループ版より多くのエラー処理コードが必要です。
パスの爆発	条件分岐が3つあると、最大8つの実行パスが生まれ、それぞれのパスにテストが必要です。
スキーマ設計	すべての状態フィールドに型、デフォルト値、書き込みルールが必要です。誤りがあると、あらゆるステップでエラーが表面化します。
保守	再試行ロジック、フォールバック経路、エラーハンドラー、上限は、いずれもループにはなかった新たなコードです。

グラフの信頼性が高いのは、オーケストレーションをモデルに任せないからです。その信頼性には、エンジニアリングの工数が必要です。

design-gate のもとでは、呼び出し元が定めた正規のゲート結果を使用してください。これにより、単独での出力や編集の仕組みは不要になります。レンズ固有の結論は、安定した検出結果 ID とともに、検出結果または review_focus に記載してください。インタビューでは、既存の決定記録に判断フィールドを追加してください。

単独出力の契約

次を返してください。

1. verdict：proceed または revise。
2. signals_fired：該当する6つのシグナルを番号で示し、それぞれに根拠を1行で記載します。空のリストも有効であり、よくある結果です。
3. blocking_findings：計画の変更が必要な、重要な検出結果（proceed の場合は空）。
4. advisory_findings：実装に引き継ぐ価値のある、ブロック要因ではない所見。
5. required_changes：番号付きの計画修正（revise の場合のみ）。

このレンズによって作業内容が変わる場合は、1行で説明してください。

Agent architecture lens: signals [n] fire, so [mechanism owed]; [main risk], bounded by [ceiling].

注意点

1. 設計がより本格的に見えるからという理由で、グラフを推奨してはいけません。シグナルがゼロなら、答えはループです。
2. 並列処理を高度さの証と見なしてはいけません。テスト対象を増やすため、最初ではなく最後の段階です。
3. 終了条件として「エージェントが完了したら停止する」を認めてはいけません。3つの終了条件が必要です。
4. 再試行の上限が文章でしか示されていない場合は認めてはいけません。試行回数をモデルの外部で数えるものがなければ、上限はありません。
5. チェックポイントを際限なく蓄積させてはいけません。状態が際限なく増大すると、徐々に障害につながります。

参考資料

事前にではなく、必要に応じて読み込んでください。

• references/failure-modes.md — 症状から構造的な対策までを解説し、上限のない実行が実際にどこまで続くかの目安を示します。
• references/state-and-checkpoints.md — 型付き状態のスキーマ設計、チェックポイントの間隔、TTL とパージについて解説します。
• references/topologies.md — ループ、ルーター、オーケストレーターとワーカー、評価と最適化、合流点を設けた並列ファンアウトについて解説します。