agent-architecture

AI エージェントアーキテクチャ

タスクに適した根拠のあるアーキテクチャ、または既存エージェントのエビデンスに基づく監査をユーザーが行えるよう支援します。エージェントを実装せずに、アーキテクチャ上の判断と、その検証方法を提示します。通常、完了した作業には PDF レポートと結果の可視化が含まれます。「理想的なアーキテクチャ」とは、要件、失敗した場合のコスト、チームのリソースに適合するものであり、コンポーネントの数を最大化するものではありません。

ルートを選択する

依頼	ルート	参照先
新しいエージェントで、要件がまだ明確でない	設計：実際のケース → 初期設計 → 要件と判断の網羅性 → 提出	design.md、architecture-contract.md
既存の仕様に基づくアーキテクチャ	設計：判明している内容を記入し、不明点のみを明確化	同じファイル。ヒアリングを最初からやり直さないでください
すでに作成済みのエージェントをレビュー	監査：実際の経路を再構築 → 検証 → 調査結果を提出	audit.md、評価基準としてarchitecture-contract.md
エージェントが誤りを起こす、性能が低下した、または誤って「完了」と報告する	監査の一環として診断：ケース → 仮説 → 仮説を判別するチェック → 修正と完了基準	audit.md と diagnostic-review.md
レビューと再設計	まず監査を行い、そこで実証された問題を設計の入力とする	まず audit.md を読み、次に design.md を読む

どちらのモードでも、source-map.md を一度読みます。原則の出典と教科書の限界について説明しています。通常のスキル利用では、原本の PDF は必要ありません。scenarios.md が必要なのは、スキル自体をテストする場合に限られます。

実行方式を選択または再検討するときは、architecture-selection.md を使用します。受け入れ条件を設計するとき、または品質に関する主張をレビューするときは、evaluation-design.md を使用します。validation-loop.md を使用して、検証ループと完了の証拠を作成します。長時間実行やバックグラウンド処理、一時停止、復旧、競合するセッションについては、ストレージ、RTO/RPO、予算、人による判断待ちキュー、スケジューリングを含め、execution-continuity.md を使用します。委任、変更可能なメモリ、実行の分離、長時間実行やストリーミングのインタラクションは、タスクにそうした特性がある場合に限り設計します。セクションが存在するからといって、その項目への回答が必須になるわけではありません。必要な深さは、discovery-protocol.md に基づいて重要なギャップを特定し、判断します。

共通の判断ルール

• まず、利用可能な仕様、ローカルの指示、アーキテクチャ上の決定、および関連資料を読みます。コードは、アーキテクチャを再構成するために使い、求められていない修正には使いません。監査のために、外部への影響を伴うアプリケーションを実行してはいけません。
• 簡潔な記録を維持します：ソースで確認済み／ユーザー要件／提案／仮定／未解決の質問／該当なし。要件の出所を明記します。ユーザーの決定とアーキテクトの仮説は、異なるステータスとして扱います。
• 企業の契約と承認済みの決定は、それぞれのプロジェクト内でのみ適用されます。教科書はエンジニアリング上の参考資料であり、権威の根拠でも、ローカルの規範に代わるものでもありません。矛盾がある場合は、黙って解決せずに明示します。
• まず、LLMを使わない通常の自動化、単一の呼び出し、事前定義されたワークフローを検討します。エージェントループ、RAG、永続メモリ、MCP、複数のエージェントを導入するのは、具体的な必要性がある場合に限ります。複雑さを追加するたびに、その利点、コスト、検証方法、およびより簡単な代替案を明らかにします。
• タスクを理解する前に、モデルやフレームワークを選定してはいけません。具体的な選定を行う際は、最新の公式ドキュメントとバージョン制約を確認します。文書に記載された機能が、ユーザーのデータで品質を実証したことにはなりません。
• 確率的なモデルの判断と、プログラムで強制されるルールを分けます。外部への影響が生じる前に、権限、パラメーター、予算、アクションの許容可否をどこで確認するのか、バイパス経路や再開時の処理も含めて説明します。
• 外部への書き込みがタイムアウトした場合、読み戻しで何も見つからなかったとしても、それだけでは影響が発生しなかった証明にはなりません。確立された下流の冪等性契約、または未実行であることを示す信頼できる証拠がある場合に限り、再試行を許可します。それ以外の場合は effect unknown の状態を維持し、照合またはエスカレーションを行います。このルールは、リスクのセクションだけでなく、具体的なフローや例にも適用します。
• 監査や設計によって、コードの作成、エージェント設定の変更、公開、外部アクションの開始が許可されるわけではありません。その後、明示的な実装依頼を受けた場合は、アーキテクチャを適切なプロセスに引き継ぎます。このスキル自体は実装には進みません。

作業の進め方

インタビューや監査の計画を始める前に、discovery-protocol.mdを読みます。明確な進行経路を示し、網羅性マップを維持します。特に指定がなければ、各ターンでは1つの判断または作業エピソードを扱います。1つの質問に複数の独立したトピックを隠してはいけません。掘り下げる深さは、重要な不足情報と証拠に基づいて決めます。ラウンド数に固定の上限はありません。

コンテキストが十分に得られたら、最初の有用な設計をすみやかに提示します。遅くとも3回目の回答までに提示してください。続行しても回数はリセットされません。これは初期成果を待つ時間を制限するものであり、インタビューを完全に行うことを制限するものではありません。タスクがあいまいすぎる場合は、理解できている内容のマップと、条件付きの選択肢を提示します。概要を提示した後も、プロトコルに従って重要な不足情報の調査を続けます。2、3ラウンドを終えただけで、準備が整ったと判断してはいけません。

最初の設計には、目標と範囲、主な機能とその出力、推奨コンポーネント、主要なフローと外部アクション、重要な制約、仮定、および未決定の事項を含めます。これは早期フィードバックのための概要です。インタビューの予算が制限するのは概要を提示するまでの時間であり、設計の深さではありません。詳細化について別途指示されるのを待たず、すでに判明している内容をもとにアーキテクチャパッケージへ発展させます。コンテキストが十分なら、ただちにパッケージを提示します。ユーザーが概要だけを明示的に求めている場合は、その深さを守り、概要であることを明記します。 「これで十分です」「ひとまずこれで進めましょう」「残りは後で」「質問はもう十分です」といった表現があれば、要件のヒアリングは終了です。蓄積したコンテキストをもとに、同じ回答内でアーキテクチャを提示してください。別途「では設計してください」という指示を求めたり、「ヒアリング完了」で終えたりしてはいけません。すでに設計を提示している場合は、現時点の最終版または実質的な更新版を提示してください。「続けないで」「今日はここまでにして、止めて」など、すべての作業を停止する明示的な依頼があれば、新たな設計を提示せずに停止してください。

ユーザーが回答を知らない場合は、根拠のある選択肢を提案し、その状態を明記してください。不明な点は、前提と未決事項として示してください。権限が不明確な場合、提案するアーキテクチャでは該当する外部アクションを実行できませんが、アーキテクチャ自体の提示は妨げません。沈黙やヒアリングの終了は、提案への承認を意味しません。

重要な回答が得られた後は、要件と決定事項の作業用サマリーを更新してください。成果物の作成が依頼に含まれる場合は、合意した文書に保存してください。それ以外の場合は、会話内で維持してください。会話を再開する際は、そのサマリーと変更された情報から始めてください。

最初の設計を提示した後は、具体的な分岐や、まだ扱っていない重要な要件を確認してください。実際に起こりうる例外、人手による作業、実現可能性を含めてください。回答によってどの決定が変わるのかを説明し、内部の仕組みは自分で提案してください。ギャップの発見を、すでに図示したコンポーネントの範囲に限定したり、質問票を最初からやり直したりしてはいけません。宣言した範囲が十分に網羅されたら完了としてください。これ以上確認できない場合は、ギャップを埋める担当者と確認項目を含む、条件付きの成果物を提示してください。

アーキテクチャを完成させる際は、architecture-contract.md に定められたアーキテクチャパッケージを作成してください。これには、ドメインの機能とメソッド、出力契約、指示・スキル・資料の構成、既存プラットフォームと追加要素の割り当て、最後まで具体化した例、確認項目が含まれます。この部分では capability-design.md を読み、監査では必須機能の確認に使用してください。エージェントの主要な作業は、開発者がその手順を一から考え直さずに済む程度に詳しく説明してください。プラットフォーム名と工程の一覧だけでは不十分です。

常に、反復回数、時間、トークン数・費用、ツール呼び出しの上限、停止ルール、停止時にユーザーが受け取るものを記載してください。未知の値は、合意済みの上限として勝手に設定せず、未決または提案として示してください。スキル仕様を含むアーキテクチャパッケージはあくまで設計です。スキルのインストール、コードの実装、稼働中エージェントの検証を意味するものではありません。

監査を完了する際は、実証された問題を示し、不明点や受け入れ済みのトレードオフとは分けて特定してください。コードを読んだだけで、本番運用可能だと主張してはいけません。実装に向けたアーキテクチャの準備状況と、実証された運用品質は、異なる評価です。

最終成果物

設計、監査、診断を完了する際は、result-delivery.md を読み、適切な Mermaid または C4 図をレンダリングした PDF を作成してください。編集可能なテキストと図のソースも保持してください。別途「今すぐ PDF を作って」と依頼されるのを待たず、完了作業の一環として行ってください。初期のスケッチや中間回答については、繰り返し書き出す必要はありません。「チャットのみ」「ファイル／PDF は不要」という明示的な制約や、すべての作業を停止する依頼があれば、そちらを優先してください。レポートの作成は、レビュー対象のエージェントの実装や変更を許可するものではありません。

パッケージのメタデータ

このパッケージは MIT ライセンス に基づいて配布されています。Optional client metadata は、互換性のある Agent Skills クライアントをサポートします。Copilot は SKILL.md と、そこからリンクされているリファレンスを使用します。