agent-native-architecture

エージェントネイティブアーキテクチャ

作業ルール

• 権限、スコープ、承認、実行時の分離は、信頼できるオーケストレーションで管理してください。プロンプトだけではこれらを強制できません。
• 完了と部分的な進捗を明示するシグナル、永続的な状態、観測可能なアクション結果を用意してください。
• 失敗や中断の経路も含む実際のタスクで機能を検証してください。使用時間の経過だけから改善を推測してはいけません。
• 元の入力から発見を評価してください。 候補を固定して再生すると、分類しか測定できず、検索方法の変更によって見落とされたり新たに見つかったりする候補は明らかになりません。各発見方法を、同じ完全な入力を使った新しいベースラインと個別に比較してください。クリーンタスクからの出力も含め、完全な結果セットにおける一致しない出力を独立して判定してください。
• モデルごとに判定ゲートを調整してください。 ランキング精度が向上していても、代替モデルの信頼度スコアに以前のモデルのしきい値をそのまま適用することはできません。別の調整用データセットでしきい値を適合させてください。未使用の代表的なケースを使い、本番の判定経路で偽陽性と偽陰性の挙動を検証してください。
• 選択したトピックの参考資料とアーキテクチャチェックリストを使い、根拠と未解決の制約を含む具体的な設計を作成してください。

コア原則

エージェントネイティブ設計は、5つの原則に基づきます。詳しい説明、例、テスト基準については、core-principles.md を参照してください。

原則	1行でのテスト
同等性	エージェントは、UIで可能なすべての結果を達成できますか？
粒度	振る舞いを変える際に、コードのリファクタリングではなく文章の編集で対応できますか？
合成可能性	新しいコードを書かず、新しいプロンプトを書くことで機能を追加できますか？
創発的能力	エージェントは、想定外の自由形式のリクエストに対応できますか？
時間とともに改善	コードを変更しなくても、1か月後にはアプリの動作が改善していますか？

フォーカス領域の選択

1. アーキテクチャの設計 - 新しいエージェントネイティブシステムをゼロから計画する
2. ファイルとワークスペース - ファイルを汎用インターフェースとして使用し、共有ワークスペースのパターンを採用する
3. ツール設計 - プリミティブなツール、動的な機能の発見、CRUD の完全性を実現する
4. ドメインツール - ドメインツールを追加する場合と、プリミティブなツールにとどめる場合を見極める
5. 実行パターン - 完了シグナル、部分的な完了、コンテキストの制限
6. システムプロンプト - プロンプトでエージェントの振る舞いと判断基準を定義する
7. コンテキスト注入 - 実行時のアプリ状態をエージェントのプロンプトに注入する
8. アクションの同等性 - エージェントがユーザーにできるすべての操作を実行できるようにする
9. 自己変更 - エージェントが安全に自己進化できるようにする
10. プロダクト設計 - 段階的な情報開示、潜在需要、承認パターン
11. モバイルのパターン - iOS ストレージ、バックグラウンド実行、チェックポイントと再開
12. テスト - エージェントネイティブアプリの機能と同等性をテストする
13. リファクタリング - 既存のコードをよりエージェントネイティブにする
14. アンチパターン - よくある間違いとその回避方法
15. 成功基準 - アーキテクチャがエージェントネイティブであることを検証する
16. フックのパターン - フックイベント、判断制御、MCP マッチャー、非同期フック
17. CLI インターフェース - エージェントが呼び出す CLI を設計する：出力チャネル、終了コード、自己記述、安全性の階層
18. 承認ループ - エージェントが下書きした外部送信に対する、永続的な人間の承認：コンテンツとの紐付け、単一の勝者による取得、不明な結果

リクエストまたは委任されたタスクでトピックが特定されている場合は、そのトピックに直接振り分けてください。重要なフォーカスが未解決の場合は、Claude Code では AskUserQuestion（必要に応じて ToolSearch で読み込む）、Codex では request_user_input、質問ツールが利用できないチャットでは番号付きの選択肢を使って、関連する選択肢を提示してください。その選択を解決するために必要な回答だけを待ってください。

リファレンスの振り分け

応答	アクション
1, "design", "architecture", "plan"	architecture-patterns.md を読み、その後 architecture-review-checklist.md を適用します
2, "files", "workspace", "filesystem"	files-universal-interface.md と shared-workspace-architecture.md を読みます
3, "tool", "mcp", "primitive", "crud"	mcp-tool-design.md を読みます
4, "domain tool", "when to add"	from-primitives-to-domain-tools.md を読みます
5, "execution", "completion", "loop"	agent-execution-patterns.md を読みます
6, "prompt", "system prompt", "behavior"	system-prompt-design.md を読みます
7, "context", "inject", "runtime", "dynamic"	dynamic-context-injection.md を読みます
8, "parity", "ui action", "capability map"	action-parity-discipline.md を読みます
9, "self-modify", "evolve", "git"	self-modification.md を読みます
10, "product", "progressive", "approval", "latent demand"	product-implications.md を読みます
11, "mobile", "ios", "android", "background", "checkpoint"	mobile-patterns.md を読みます
11a, "icloud", "storage", "documents", "file state", "entitlement"	mobile-storage.md を読みます
11b, "background task", "battery", "on-device", "cloud routing"	mobile-execution.md を読みます
11c, "model tier", "token budget", "cost-aware", "batch", "caching"	mobile-cost.md を読みます
12, "test", "testing", "verify", "validate"	agent-native-testing.md を読みます
13, "review", "refactor", "existing"	refactoring-to-prompt-native.md を読みます
14, "anti-pattern", "mistake", "wrong"	anti-patterns.md を読みます
15, "success", "criteria", "verify", "checklist"	success-criteria.md を読みます
16, "hook", "hooks", "PreToolUse", "decision control", "async hook", "permissionDecision"	hooks-patterns.md を読みます
17, "cli", "command line", "stdout", "exit code", "--format", "--dry-run"	cli-agent-interface.md を読みます
18, "approval", "approve before send", "outbound", "ledger", "double-send"	operator-approval-loop.md を読みます
0, "quick start", "getting started", "overview", "introduction"	quick-start.md を読みます

リファレンスを読んだ後、そのパターンをユーザーの具体的な状況に適用してください。

タスク固有のリファレンス

対応する動作を実装またはレビューする前に、関連するリファレンスを読んでください。

• エージェントネイティブなアーキテクチャを実装する前に、該当するアーキテクチャチェックリストの項目をすべて確認してください：architecture-review-checklist.md。

既存の専門リファレンス（該当するトピックに適用される場合）：

• durability-and-attestation.md。
• フック、スキル、またはプロンプトルールの制御された評価を行う場合は、intervention-evaluation.md を読んでください。