agent-native-architecture

<essential_principles>

プロンプトネイティブの哲学

エージェントネイティブエンジニアリングは、従来のソフトウェアアーキテクチャを逆転させます。エージェントが実行するコードを書く代わりに、プロンプトで結果を定義し、エージェントにそれを達成する方法を考えさせます。

基本原則

ユーザーができることは、エージェントもできる。開発者ができることの多くも、エージェントができる。

エージェントを人為的に制限しない。ユーザーがファイルを読んだり、コードを書いたり、ウェブを閲覧したり、アプリをデプロイできるなら、エージェントもそれらのことができるべきです。エージェントは結果を達成する方法を考え出します。事前に書かれた関数を呼び出すだけではありません。

機能はプロンプト

各機能は結果を定義し、エージェントに必要なツールを与えるプロンプトです。エージェントはそれを達成する方法を考え出します。

従来型: 機能 = エージェントが呼び出すコードベース内の関数 プロンプトネイティブ: 機能 = 望む結果を定義するプロンプト + プリミティブツール

エージェントはあなたのコードを実行しません。あなたが説明した結果を達成するためにプリミティブを使用します。

ツールは動作ではなく能力を提供

ツールは能力を可能にするプリミティブであるべきです。プロンプトがその能力で何をするかを定義します。

誤り: generate_dashboard(data, layout, filters) — エージェントがあなたのワークフローを実行 正解: read_file, write_file, list_files — エージェントがダッシュボードの構築方法を考え出す

純粋なプリミティブが良いですが、ドメインプリミティブ（store_feedbackなど）はロジックを含まない場合（単なる保存/取得）は問題ありません。

開発ライフサイクル

1. プロンプトから開始 - 新機能は結果を定義する自然言語として始まる
2. 迅速に反復 - コードをリファクタリングせず、散文を編集して動作を変更
3. 安定したら卒業 - 要件が安定し、速度/信頼性が重要になったらコードに強化
4. 多くの機能はプロンプトのまま - すべてがコードになる必要はない

自己修正（上級）

上級層：自身のコード、プロンプト、動作を進化させることができるエージェント。すべてのアプリに必要ではありませんが、未来の大きな部分です。

実装時：

• コード変更の承認ゲート
• 修正前の自動コミット（ロールバック機能）
• 変更後のヘルスチェック
• 再起動前のビルド検証

このアプローチを使用しない場合

• 高頻度の操作 - 毎秒数千回の呼び出し
• 決定論的要件 - 毎回まったく同じ出力
• コスト敏感なシナリオ - APIコストが禁止的な場合
• 高セキュリティ - ただしこれはほとんどのアプリで誇張されている </essential_principles>

エージェントネイティブアーキテクチャのどの側面で助けが必要ですか？

1. アーキテクチャ設計 - 新しいプロンプトネイティブエージェントシステムを計画
2. MCPツール作成 - 哲学に従ったプリミティブツールを構築
3. システムプロンプト作成 - プロンプトでエージェントの動作を定義
4. 自己修正 - エージェントが安全に自己進化できるようにする
5. レビュー/リファクタリング - 既存のコードをよりプロンプトネイティブにする
6. コンテキスト注入 - ランタイムのアプリ状態をエージェントプロンプトに注入
7. アクションパリティ - エージェントがユーザーができることすべてをできるようにする
8. 共有ワークスペース - エージェントとユーザーを同じデータスペースに設定
9. テスト - エージェントネイティブアプリの能力とパリティをテスト
10. API統合 - 外部API（HealthKit、HomeKit、GraphQL）に接続

進む前に応答を待ってください。

| 応答 | アクション | |----------|--------| | 1, "設計", "アーキテクチャ", "計画" | [architecture-patterns.md](./references/architecture-patterns.md)を読み、その後以下のアーキテクチャチェックリストを適用 | | 2, "ツール", "mcp", "プリミティブ" | [mcp-tool-design.md](./references/mcp-tool-design.md)を読む | | 3, "プロンプト", "システムプロンプト", "動作" | [system-prompt-design.md](./references/system-prompt-design.md)を読む | | 4, "自己修正", "進化", "git" | [self-modification.md](./references/self-modification.md)を読む | | 5, "レビュー", "リファクタリング", "既存" | [refactoring-to-prompt-native.md](./references/refactoring-to-prompt-native.md)を読む | | 6, "コンテキスト", "注入", "ランタイム", "動的" | [dynamic-context-injection.md](./references/dynamic-context-injection.md)を読む | | 7, "パリティ", "UIアクション", "能力マップ" | [action-parity-discipline.md](./references/action-parity-discipline.md)を読む | | 8, "ワークスペース", "共有", "ファイル", "ファイルシステム" | [shared-workspace-architecture.md](./references/shared-workspace-architecture.md)を読む | | 9, "テスト", "検証", "バリデーション" | [agent-native-testing.md](./references/agent-native-testing.md)を読む | | 10, "api", "healthkit", "homekit", "graphql", "外部" | [mcp-tool-design.md](./references/mcp-tool-design.md)（動的能力発見セクション）を読む |

リファレンスを読んだ後、それらのパターンをユーザーの特定のコンテキストに適用してください。

<architecture_checklist>

アーキテクチャレビューチェックリスト（設計中に適用）

エージェントネイティブシステムを設計する際、実装前にこれらを検証：

ツール設計

• 動的 vs 静的: エージェントがフルユーザーレベルアクセスを持つべき外部API（HealthKit、HomeKit、GraphQL）には動的能力発見を使用。エージェントのスコープを意図的に制限する場合のみ静的マッピングを使用。
• CRUDの完全性: すべてのエンティティに作成、読み取り、更新、削除のツールがある
• ワークフローではなくプリミティブ: ツールは能力を有効にし、ビジネスロジックをエンコードしない
• APIがバリデータ: APIが検証する場合、z.enum()ではなくz.string()入力を使用

アクションパリティ

• 能力マップ: すべてのUIアクションに対応するエージェントツールがある
• 編集/削除: UIが編集または削除できるなら、エージェントもできる必要がある
• 書き込みテスト: 「[アプリの場所]に何か書いて」がすべての場所で機能する必要がある

UI統合

• エージェント → UI: エージェントの変更がUIに反映される方法を定義（共有サービス、ファイル監視、またはイベントバス）
• サイレントアクションなし: エージェントの書き込みは即座にUI更新をトリガーすべき
• 能力発見: ユーザーがエージェントの能力を学べる（オンボーディング、ヒント）

コンテキスト注入

• 利用可能なリソース: システムプロンプトに存在するもの（ファイル、データ、型）を含む
• 利用可能な能力: システムプロンプトでエージェントができることをユーザーの語彙で文書化
• 動的コンテキスト: 長いセッションではコンテキストを更新（またはrefresh_contextツールを提供）

アーキテクチャを設計する際、計画で各チェックボックスに明示的に対処してください。 </architecture_checklist>

<quick_start> 3ステップでプロンプトネイティブエージェントを構築：

ステップ1: プリミティブツールを定義

const tools = [
  tool("read_file", "任意のファイルを読む", { path: z.string() }, ...),
  tool("write_file", "任意のファイルを書く", { path: z.string(), content: z.string() }, ...),
  tool("list_files", "ディレクトリを一覧表示", { path: z.string() }, ...),
];

ステップ2: システムプロンプトで動作を記述

## あなたの責任
コンテンツを整理するよう依頼されたら、以下を行うべき：
1. 既存のファイルを読んで構造を理解する
2. どのような整理が理にかなっているか分析する
3. write_fileを使用して適切なページを作成する
4. レイアウトとフォーマットについて自分の判断を使用する

あなたが構造を決める。良いものにしてください。

ステップ3: エージェントに作業させる

query({
  prompt: userMessage,
  options: {
    systemPrompt,
    mcpServers: { files: fileServer },
    permissionMode: "acceptEdits",
  }
});

</quick_start>

<reference_index>

ドメイン知識

references/内のすべてのリファレンス：

コアパターン:

• アーキテクチャ: architecture-patterns.md
• ツール設計: mcp-tool-design.md - 動的能力発見、CRUDの完全性を含む
• プロンプト: system-prompt-design.md
• 自己修正: self-modification.md
• リファクタリング: refactoring-to-prompt-native.md

エージェントネイティブの規律:

• コンテキスト注入: dynamic-context-injection.md
• アクションパリティ: action-parity-discipline.md
• 共有ワークスペース: shared-workspace-architecture.md
• テスト: agent-native-testing.md </reference_index>

<anti_patterns>

やってはいけないこと

大罪: エージェントが物事を考え出す代わりにあなたのコードを実行する

これが最も一般的な間違いです。ワークフローコードを書いてエージェントにそれを呼び出させることに戻ってしまい、結果を定義してエージェントに方法を考えさせる代わりにしてしまいます。

// 誤り - あなたがワークフローを書き、エージェントはそれを実行するだけ
tool("process_feedback", async ({ message }) => {
  const category = categorize(message);      // あなたのコード
  const priority = calculatePriority(message); // あなたのコード
  await store(message, category, priority);   // あなたのコード
  if (priority > 3) await notify();           // あなたのコード
});

// 正解 - エージェントがフィードバックの処理方法を考え出す
tool("store_item", { key, value }, ...);  // プリミティブ
tool("send_message", { channel, content }, ...);  // プリミティブ
// プロンプトで言う: 「アクション可能性に基づいて重要度を1-5で評価し、フィードバックを保存、>= 4なら通知」

エージェントができることを人為的に制限しない

ユーザーができるなら、エージェントもできるべき。

// 誤り - エージェントの能力を制限
tool("read_approved_files", { path }, async ({ path }) => {
  if (!ALLOWED_PATHS.includes(path)) throw new Error("Not allowed");
  return readFile(path);
});

// 正解 - フル能力を与え、ガードレールを適切に使用
tool("read_file", { path }, ...);  // エージェントは何でも読める
// 読み取りへの人為的制限ではなく、書き込みに承認ゲートを使用

ツールに決定をエンコードしない

// 誤り - ツールがフォーマットを決定
tool("format_report", { format: z.enum(["markdown", "html", "pdf"]) }, ...)

// 正解 - エージェントがプロンプト経由でフォーマットを決定
tool("write_file", ...) // エージェントが何を書くか選ぶ

プロンプトで過度に指定しない

// 誤り - 方法をマイクロマネジメント
サマリーを作成する際、正確に3つの箇条書きを使用し、
各箇条書きは20語未満で、emダッシュでフォーマットし...

// 正解 - 結果を定義し、知性を信頼
明確で有用なサマリーを作成。判断を使用。

エージェントネイティブのアンチパターン

コンテキスト飢餓 エージェントがアプリに存在するリソースを知らない。

ユーザー: 「私のフィードにエカテリーナ大帝について何か書いて」
エージェント: 「どのフィードですか？どのシステムを指しているのかわかりません。」

修正: 利用可能なリソース、能力、語彙をランタイムでシステムプロンプトに注入。

孤立した機能 エージェント相当のないUIアクション。

// UIに「フィードに公開」ボタンがある
Button("Publish") { publishToFeed(insight) }
// しかし同じことをするエージェントツールが存在しない

修正: すべてのUIアクションに対応するツールを追加し、システムプロンプトに文書化。

サンドボックス分離 エージェントがユーザーとは別のデータスペースで作業。

Documents/
├── user_files/        ← ユーザーのスペース
└── agent_output/      ← エージェントのスペース（分離）

修正: エージェントとユーザーが同じファイルで操作する共有ワークスペースを使用。

サイレントアクション エージェントが状態を変更するがUIが更新されない。

// エージェントがデータベースに書き込む
await db.insert("feed", content);
// しかしUIはこのテーブルを監視していない - ユーザーには何も見えない

修正: リアクティブバインディングを持つ共有データストア、またはファイルシステム監視を使用。

能力の隠蔽 ユーザーがエージェントの能力を発見できない。

ユーザー: 「読書を手伝って」
エージェント: 「何を手伝いましょうか？」
// エージェントがフィードに公開したり、本をリサーチしたりできることを言及しない

修正: エージェントの応答に能力ヒントを含めるか、オンボーディングを提供。

静的ツールマッピング（エージェントネイティブアプリの場合） エージェントにフルアクセスを持たせたい場合に、各APIエンドポイントに個別のツールを構築。

// 50のHealthKitタイプに対して50のツールを構築
tool("read_steps", ...)
tool("read_heart_rate", ...)
tool("read_sleep", ...)
// グルコーストラッキングが追加されたら...コード変更が必要
// エージェントは予測したものにしかアクセスできない

修正: 動的能力発見を使用 - 利用可能なものを発見する1つのlist_*ツール、任意のタイプにアクセスする1つの汎用ツール。mcp-tool-design.mdを参照。（注: 静的マッピングは意図的にスコープを制限した制約のあるエージェントには問題ない。）

不完全なCRUD エージェントは作成できるが更新や削除はできない。

// ❌ ユーザー: 「そのジャーナルエントリを削除して」
// エージェント: 「そのためのツールがありません」
tool("create_journal_entry", ...)
// 不足: update_journal_entry, delete_journal_entry

修正: すべてのエンティティにフルCRUD（作成、読み取り、更新、削除）が必要。CRUDの監査: 各エンティティについて、4つの操作すべてが存在することを確認。 </anti_patterns>

<success_criteria> プロンプトネイティブエージェントを構築できた場合：

コアプロンプトネイティブ基準:

• エージェントが関数を呼び出すだけでなく、結果を達成する方法を考え出す
• ユーザーができることは何でもエージェントができる（人為的制限なし）
• 機能はワークフローを定義するコードではなく、結果を定義するプロンプト
• ツールは能力を可能にするプリミティブ（read、write、store、call API）
• 動作を変更するにはコードのリファクタリングではなく散文の編集
• エージェントが予想しなかった賢いアプローチで驚かせることができる
• 新しいコードではなく新しいプロンプトセクションを書くことで新機能を追加できる

ツール設計基準:

• 外部API（エージェントがフルアクセスを持つべき場合）は動的能力発見を使用
• すべてのエンティティにフルCRUD（作成、読み取り、更新、削除）がある
• あなたのenum定義ではなくAPIが入力を検証
• 各APIサーフェスに発見ツール（list_*、discover_*）が存在

エージェントネイティブ基準:

• システムプロンプトにアプリ状態に関する動的コンテキスト（利用可能なリソース、最近の活動）が含まれる
• すべてのUIアクションに対応するエージェントツールがある（アクションパリティ）
• エージェントツールがシステムプロンプトでユーザーの語彙で文書化されている
• エージェントとユーザーが同じデータスペースで作業（共有ワークスペース）
• エージェントのアクションが即座にUIに反映（共有サービス、ファイル監視、またはイベントバス）
• 「[アプリの場所]に何か書いて」テストがすべての場所で合格
• ユーザーがエージェントの能力を発見できる（能力ヒント、オンボーディング）
• 長いセッションではコンテキストが更新される（またはrefresh_contextツールが存在） </success_criteria>