agent-native-architecture

<why_now>

なぜ今か

ソフトウェアエージェントは今、確実に動作します。Claude Codeが実証したのは、bashとファイルツールにアクセスでき、目標を達成するまでループで動作するLLMが、複雑なマルチステップタスクを自律的に遂行できるということです。

驚くべき発見は次の通りです：本当に優れたコーディングエージェントは、実は本当に優れた汎用エージェントである。 Claude Codeがコードベースをリファクタリングできるのと同じアーキテクチャで、エージェントはファイルを整理したり、読書リストを管理したり、ワークフローを自動化したりできます。

Claude Code SDKがこれをアクセス可能にしています。あなたが書いたコードではなく、説明した結果がツールを持つエージェントによってループで動作しながら達成される、そのようなアプリケーションを構築できます。

これは新しい分野を開きます：Claude Codeが動作する方法のソフトウェアが、コーディングをはるかに超えたカテゴリーに適用されます。 </why_now>

<core_principles>

コア原則

1. パリティ

ユーザーがUIで実行できることは、すべてエージェントがツールで達成できるべきです。

これは基礎的な原則です。これなしには、他の何も重要ではありません。

ノートアプリを構築したと想像してください。ノートを作成、整理、タグ付けするための美しいインターフェースがあります。ユーザーがエージェントに「会議をまとめたノートを作成して、緊急というタグを付けて」とリクエストします。

ノート作成のUIを構築したがエージェント機能がない場合、エージェントは行き詰まります。謝罪するか、質問するかもしれませんが、人間がインターフェースを使う場合は簡単なアクションなのに、役に立ちません。

解決策： エージェントがUIで実行できることをすべて達成できるツール（またはツールの組み合わせ）を持っていることを確認してください。

これはUIボタンとツールの1:1マッピングを作成することではありません。エージェントが同じ結果を達成できることを確認することです。時には単一のツール（create_note）です。時には、プリミティブを組み合わせることです（ノートディレクトリに適切にフォーマットしてwrite_fileします）。

規律： UI機能を追加するたびに、エージェントはこの結果を達成できるか？と自問してください。できない場合は、必要なツールまたはプリミティブを追加してください。

キャパビリティマップが役に立ちます：

ユーザーアクション	エージェントがそれを達成する方法
ノートを作成	ノートディレクトリにwrite_file、またはcreate_noteツール
ノートを緊急とタグ付け	メタデータをupdate_file、またはtag_noteツール
ノートを検索	search_filesまたはsearch_notesツール
ノートを削除	delete_fileまたはdelete_noteツール

テスト： ユーザーがUIで実行できるアクションを選んでください。エージェントに説明してください。結果を達成できますか？

---

2. 粒度

アトミックなプリミティブを優先します。フィーチャーはループで動作するエージェントによって達成される結果です。

ツールはプリミティブな機能です：ファイルを読む、ファイルを書く、bashコマンドを実行する、レコードを保存する、通知を送信します。

フィーチャーはあなたが書く関数ではありません。プロンプトで説明する結果で、ツールを持ち、結果に達するまでループで動作するエージェントによって達成されます。

粒度が低い（エージェントを制限します）：

Tool: classify_and_organize_files(files)
→ 決定ロジックを書きました
→ エージェントはあなたのコードを実行します
→ 動作を変更するには、リファクタリングします

粒度が高い（エージェントに力を与えます）：

Tools: read_file, write_file, move_file, list_directory, bash
Prompt: "ユーザーのダウンロードフォルダを整理します。各ファイルを分析し、
        コンテンツと最新性に基づいて適切な場所を決定し、
        そこに移動します。"
Agent: ループで動作します—ファイルを読み、判断を下し、ものを移動し、
       結果を確認します—フォルダが整理されるまで。
→ エージェントが決定を下します
→ 動作を変更するには、プロンプトを編集します

主要な転換： エージェントは判断によって結果を追求し、振付られたシーケンスを実行しません。予期しないファイルタイプに遭遇し、アプローチを調整したり、明確化の質問をしたりするかもしれません。結果が達成されるまでループは続きます。

ツールがより原子的であるほど、エージェントはより柔軟にそれらを使用できます。意思決定ロジックをツールにバンドルすると、判断をコードに戻してしまいました。

テスト： フィーチャーの動作を変更するために、散文を編集しますか、それともコードをリファクタリングしますか？

---

3. 合成可能性

アトミックツールとパリティにより、新しいプロンプトを書くだけで新機能を作成できます。

これは最初の2つの原則の報酬です。ツールがアトミックで、エージェントがユーザーができることをすべてできる場合、新機能は単なる新しいプロンプトです。

アクティビティをまとめ、優先順位を提案する「週次レビュー」フィーチャーが必要ですか？それはプロンプトです：

"今週修正されたファイルをレビューします。主要な変更をまとめます。未完了のアイテムと
今後の期限に基づいて、来週の3つの優先順位を提案します。"

エージェントはlist_files、read_file、その判断を使用してこれを達成します。週次レビューコードを書きませんでした。結果を説明し、エージェントはループで動作してそれを達成します。

これは開発者とユーザーの両方で機能します。 プロンプトを追加することで新機能を出荷できます。ユーザーはプロンプトを修正したり、自分たちで作成したりして動作をカスタマイズできます。「『ファイルする』と言ったら、常にそれをAction フォルダに移動して緊急とタグ付けして」はユーザーレベルのプロンプトになり、アプリケーションを拡張します。

制約： これは、ツールが予想しなかった方法で合成できるほど十分にアトミックであり、エージェントがユーザーとのパリティを持つ場合にのみ機能します。ツールが多すぎるロジックをエンコードする、またはエージェントが重要な機能にアクセスできない場合、合成は崩壊します。

テスト： 新しいコードを追加せずに、新しいプロンプトセクションを書くことで新機能を追加できますか？

---

4. 新興能力

エージェントは明示的に設計していないものを達成できます。

ツールがアトミック、パリティが維持され、プロンプトが合成可能な場合、ユーザーは予想していないものをエージェントに求めます。そして多くの場合、エージェントはそれを理解できます。

「会議ノートをタスクリストと相互参照して、コミットしたが予定していないものを教えてください。」

「コミットメントトラッカー」フィーチャーを構築していません。しかし、エージェントがノートを読み、タスクを読み、それらについて推論できる場合—結果を得るまでループで動作します—これを達成できます。

これは潜在的な需要を明らかにします。 ユーザーが何のフィーチャーを望んでいるかを推測する代わりに、彼らがエージェントに何を求めるかを観察します。パターンが現れるとき、ドメイン固有のツールや専用プロンプトでそれらを最適化できます。しかし、予期する必要がありませんでした—発見しました。

フライホイール：

1. アトミックツールとパリティを使って構築
2. ユーザーが予想していないものを求める
3. エージェントはツールを合成してそれを達成します（またはギャップを明らかにして失敗します）
4. 要求されているものであるパターンを観察する
5. 一般的なパターンを効率化するドメインツールまたはプロンプトを追加
6. 繰り返す

これはプロダクト構築方法を変えます。あらかじめすべてのフィーチャーを想像しようとしていません。機能的な基礎を作成し、何が現れるかから学んでいます。

テスト： エージェントにドメインに関連するオープンエンドなリクエストを与えます。ループで動作しながら合理的なアプローチを理解できますか？「その機能がない」と言うだけの場合、アーキテクチャは制約が強すぎます。

---

5. 時間の経過による改善

エージェント・ネイティブアプリケーションは、蓄積されたコンテキストとプロンプト改善を通じて改善されます。

従来のソフトウェアとは異なり、エージェント・ネイティブアプリケーションはコードを出荷せずに改善できます：

蓄積されたコンテキスト： エージェントはセッション間の状態を保持できます—何が存在し、ユーザーが何をしたか、何が機能し、何が機能しなかったか。エージェントが読んで更新するcontext.mdファイルがレイヤーです。より洗練されたアプローチは構造化メモリと学習された環境設定を含みます。

複数レベルでのプロンプト改善：

• 開発者レベル： すべてのユーザーのエージェント動作を変更する更新プロンプトを出荷
• ユーザーレベル： ユーザーはワークフロー用にプロンプトをカスタマイズ
• エージェントレベル： エージェントはフィードバックに基づいて独自のプロンプトを修正（上級）

自己修正（上級）： 独自のプロンプトやコードさえ編集できるエージェント。本番ユースケースの場合、安全策の追加を検討してください—承認ゲート、ロールバック用の自動チェックポイント、ヘルスチェック。これが向かっているところです。

改善メカニズムはまだ発見されています。コンテキストとプロンプト改善は実証済みです。自己修正は出現しています。明確なのは、アーキテクチャは従来のソフトウェアでは利用できない方法で改善されることをサポートしているということです。

テスト： コード変更なしに、使用開始1ヶ月後にアプリケーションは1日目より良く機能しますか？ </core_principles>

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

1. アーキテクチャを設計 - ゼロからエージェント・ネイティブシステムを計画
2. ファイルとワークスペース - ファイルを汎用インターフェースとして、共有ワークスペースパターン
3. ツール設計 - プリミティブツール、動的キャパビリティ発見、CRUD完成度
4. ドメインツール - ドメインツールを追加するとき、プリミティブのままにするとき
5. 実行パターン - 完了シグナル、部分的完了、コンテキスト制限
6. システムプロンプト - プロンプトでエージェント動作を定義、判断基準
7. コンテキストインジェクション - エージェントプロンプトにランタイムアプリ状態をインジェクト
8. アクションパリティ - エージェントがユーザーが実行できることを確認
9. 自己修正 - エージェントが安全に進化できるようにする
10. プロダクト設計 - プログレッシブディスクロージャー、潜在的需要、承認パターン
11. モバイルパターン - iOSストレージ、バックグラウンド実行、チェックポイント/再開
12. テスト - エージェント・ネイティブアプリをキャパビリティとパリティでテスト
13. リファクタリング - 既存コードをよりエージェント・ネイティブにする

レスポンスを待ってから進めてください。 </intake>

<routing> | レスポンス | アクション | |----------|--------| | 1, "design", "architecture", "plan" | [architecture-patterns.md](./references/architecture-patterns.md)を読み、下記のアーキテクチャチェックリストを適用 | | 2, "files", "workspace", "filesystem" | [files-universal-interface.md](./references/files-universal-interface.md)と[shared-workspace-architecture.md](./references/shared-workspace-architecture.md)を読む | | 3, "tool", "mcp", "primitive", "crud" | [mcp-tool-design.md](./references/mcp-tool-design.md)を読む | | 4, "domain tool", "when to add" | [from-primitives-to-domain-tools.md](./references/from-primitives-to-domain-tools.md)を読む | | 5, "execution", "completion", "loop" | [agent-execution-patterns.md](./references/agent-execution-patterns.md)を読む | | 6, "prompt", "system prompt", "behavior" | [system-prompt-design.md](./references/system-prompt-design.md)を読む | | 7, "context", "inject", "runtime", "dynamic" | [dynamic-context-injection.md](./references/dynamic-context-injection.md)を読む | | 8, "parity", "ui action", "capability map" | [action-parity-discipline.md](./references/action-parity-discipline.md)を読む | | 9, "self-modify", "evolve", "git" | [self-modification.md](./references/self-modification.md)を読む | | 10, "product", "progressive", "approval", "latent demand" | [product-implications.md](./references/product-implications.md)を読む | | 11, "mobile", "ios", "android", "background", "checkpoint" | [mobile-patterns.md](./references/mobile-patterns.md)を読む | | 12, "test", "testing", "verify", "validate" | [agent-native-testing.md](./references/agent-native-testing.md)を読む | | 13, "review", "refactor", "existing" | [refactoring-to-prompt-native.md](./references/refactoring-to-prompt-native.md)を読む |

参照を読んだ後、これらのパターンをユーザーの特定のコンテキストに適用します。 </routing>

<architecture_checklist>

アーキテクチャレビューチェックリスト

エージェント・ネイティブシステムを設計するときは、実装前にこれらを確認してください：

コア原則

• パリティ： すべてのUIアクションに対応するエージェントキャパビリティがある
• 粒度： ツールはプリミティブ；フィーチャーはプロンプト定義の結果
• 合成可能性： 新機能はプロンプトのみで追加可能
• 新興能力： エージェントはドメイン内のオープンエンドなリクエストを処理可能

ツール設計

• 動的対静的： エージェントが完全なアクセスを持つべき外部APIについては、Dynamic Capability Discoveryを使用
• CRUD完成度： すべてのエンティティが作成、読み取り、更新、削除を持つ
• プリミティブ、ワークフローではない： ツールはキャパビリティを有効にし、ビジネスロジックをエンコードしない
• APIをバリデータとして： APIがバリデートする場合、z.enum()ではなくz.string()入力を使用

ファイルとワークスペース

• 共有ワークスペース： エージェントとユーザーは同じデータスペースで動作
• context.mdパターン： エージェントは蓄積知識のためコンテキストファイルを読み取り/更新
• ファイル組織： エンティティスコープのディレクトリと一貫した命名規則

エージェント実行

• 完了シグナル： エージェントは明示的なcomplete_taskツール（ヒューリスティック検出ではない）を持つ
• 部分的完了： マルチステップタスクは再開するため進捗を追跡
• コンテキスト制限： 開始から制限されたコンテキスト用に設計

コンテキストインジェクション

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

UI統合

• エージェント→UI： エージェント変更はUIに反映（共有サービス、ファイル監視、またはイベントバス）
• サイレントアクションなし： エージェント書き込みはUI更新を直ちにトリガー
• キャパビリティディスカバリー： ユーザーはエージェントが実行可能なことを学べる

モバイル（該当する場合）

• チェックポイント/再開： iOSアプリ中断を適切に処理
• iCloudストレージ： iCloud優先でマルチデバイス同期用ローカルフォールバック
• コスト認識： モデルティア選択（Haiku/Sonnet/Opus）

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

<quick_start>

クイックスタート：エージェント・ネイティブフィーチャーを構築

ステップ1：アトミックツールを定義

const tools = [
  tool("read_file", "任意のファイルを読む", { path: z.string() }, ...),
  tool("write_file", "任意のファイルを書く", { path: z.string(), content: z.string() }, ...),
  tool("list_files", "ディレクトリをリスト", { path: z.string() }, ...),
  tool("complete_task", "タスク完了をシグナル", { summary: z.string() }, ...),
];

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

## あなたの責任
コンテンツを整理するよう求められたとき、以下を実行してください：
1. 既存ファイルを読んで構造を理解
2. どの整理が理にかなっているか分析
3. ツール使用してファイルを作成/移動
4. レイアウトとフォーマットについて判断を下す
5. 完了したら complete_task を呼び出す

構造を決めてください。良いものにしてください。

ステップ3：エージェントをループで動作させる

const result = await agent.run({
  prompt: userMessage,
  tools: tools,
  systemPrompt: systemPrompt,
  // エージェントは complete_task を呼び出すまでループします
});

</quick_start>

<reference_index>

リファレンスファイル

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

コアパターン：

• architecture-patterns.md - イベント駆動、統一オーケストレータ、エージェント→UI
• files-universal-interface.md - ファイルの理由、組織パターン、context.md
• mcp-tool-design.md - ツール設計、動的キャパビリティ発見、CRUD
• from-primitives-to-domain-tools.md - ドメインツール追加時期、コード段階化
• agent-execution-patterns.md - 完了シグナル、部分的完了、コンテキスト制限
• system-prompt-design.md - プロンプトとしてのフィーチャー、判断基準

エージェント・ネイティブ規律：

• dynamic-context-injection.md - ランタイムコンテキスト、インジェクト対象
• action-parity-discipline.md - キャパビリティマッピング、パリティワークフロー
• shared-workspace-architecture.md - 共有データスペース、UI統合
• product-implications.md - プログレッシブディスクロージャー、潜在的需要、承認
• agent-native-testing.md - 結果テスト、パリティテスト

プラットフォーム固有：

• mobile-patterns.md - iOSストレージ、チェックポイント/再開、コスト認識
• self-modification.md - Git基盤進化、ガードレール
• refactoring-to-prompt-native.md - 既存コード移行 </reference_index>

<anti_patterns>

アンチパターン

完全にはエージェント・ネイティブでない一般的なアプローチ

これらは必ずしも間違いではありません—ユースケースに適切かもしれません。しかしドキュメントが説明するアーキテクチャと異なると認識する価値があります。

ルーターとしてのエージェント — エージェントがユーザーが何を望んでいるかを理解し、右の関数を呼び出す。エージェントのインテリジェンスはルーティングに使用されます。これは機能しますが、エージェントができることのほんの一部を使用しています。

アプリを構築してからエージェントを追加 — フィーチャーを従来の方法（コードとして）構築してから、エージェントに公開。エージェントはフィーチャーが既にすることだけで行動できます。新興能力は得られません。

リクエスト/レスポンス思考 — エージェントは入力を取得し、一つのことをして、出力を返す。これはループを見落とします：エージェントは達成すべき結果を取得し、完了するまで動作し、途中で予期しない状況を処理します。

防御的ツール設計 — 防御的プログラミングに慣れているため、ツール入力を過度に制限。厳密な列挙型、各レイヤーでの検証。これは安全ですが、エージェントが予想していないことをすることを防止します。

コードの幸福なパス、エージェントが実行するだけ — 従来のソフトウェアはエッジケースをコードで処理します—Xが間違ったときに何が起こるかのロジックを書きます。エージェント・ネイティブはエージェントが判断を持つエッジケースを処理させます。コードがすべてのエッジケースを処理する場合、エージェントはただの呼び出し元です。

---

特定のアンチパターン

基本的な罪：エージェント実行がコードを処理、物事を理解しない

// 間違い - ワークフローを書き、エージェントが実行するだけ
tool("process_feedback", async ({ message }) => {
  const category = categorize(message);      // あなたのコードが決定
  const priority = calculatePriority(message); // あなたのコードが決定
  await store(message, category, priority);   // あなたのコードがオーケストレート
  if (priority > 3) await notify();           // あなたのコードが決定
});

// 正しい - エージェントがフィードバック処理を理解
tools: store_item, send_message  // プリミティブ
prompt: "重要度を1-5で実行可能性に基づいて評価し、フィードバック保存し、4以上で通知"

ワークフロー形状のツール — analyze_and_organizeは判断をツールにバンドル。プリミティブに分割し、エージェントに合成させ