agent-native-architecture

今なぜ取り組むのか

ソフトウェアエージェントは、今や安定して動作します。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)
→ You wrote the decision logic
→ Agent executes your code
→ To change behavior, you refactor

粒度が細かい（エージェントの能力を高める）：

Tools: read_file, write_file, move_file, list_directory, bash
Prompt: "Organize the user's downloads folder. Analyze each file,
        determine appropriate locations based on content and recency,
        and move them there."
Agent: Operates in a loop—reads files, makes judgments, moves things,
       checks results—until the folder is organized.
→ Agent makes the decisions
→ To change behavior, you edit the prompt

重要な考え方の転換： エージェントは、決められた手順を実行するのではなく、判断を伴いながら成果の実現に取り組みます。予期しないファイル形式に遭遇したり、アプローチを調整したり、確認の質問をしたりすることもあります。成果が実現するまでループを続けます。

ツールがアトミックであればあるほど、エージェントは柔軟に活用できます。ツールに判断ロジックを組み込むと、判断をコードに戻したことになります。

確認方法： 機能の動作を変更するには、文章を編集しますか、それともコードをリファクタリングしますか？

---

3. 合成可能性

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

これは最初の2つの原則がもたらす成果です。ツールがアトミックで、エージェントがユーザーにできることを何でも実行できるなら、新機能は新しいプロンプトを書くだけで実現できます。

アクティビティを要約して優先事項を提案する「週次レビュー」機能が欲しいですか？ それはプロンプトで実現できます。

"Review files modified this week. Summarize key changes. Based on
incomplete items and approaching deadlines, suggest three priorities
for next week."

エージェントは list_files、read_file、そして自身の判断を使ってこれを実現します。週次レビュー用のコードを書く必要はありません。達成したい結果を記述すれば、エージェントはそれが実現するまでループ処理を続けます。

これは開発者にもユーザーにも有効です。 プロンプトを追加することで新機能を提供できます。ユーザーはプロンプトを変更したり、自分で作成したりして動作をカスタマイズできます。「『これをファイルして』と言ったら、必ず Action フォルダーに移動して緊急とタグ付けする」という指示は、アプリケーションを拡張するユーザーレベルのプロンプトになります。

制約： これが機能するのは、ツールが想定していなかった方法でも組み合わせられるほどアトミックであり、エージェントがユーザーと同等の機能を利用できる場合に限られます。ツールにロジックを詰め込みすぎていたり、エージェントが重要な機能にアクセスできなかったりすると、合成はうまくいきません。

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

---

4. 創発的な能力

エージェントは、明示的に設計していないことも実行できます。

ツールがアトミックで、パリティが保たれ、プロンプトを組み合わせられるなら、ユーザーは想定していなかったことをエージェントに依頼するでしょう。そして多くの場合、エージェントはその方法を見つけられます。

「会議のメモとタスクリストを照合して、私が約束したのに予定に入れていないことを教えてください。」

「約束管理」機能を作ったわけではありません。しかし、エージェントがメモを読み、タスクを読み、それらについて推論し、回答できるまでループ処理を続けられるなら、これを実行できます。

これにより、潜在的な需要が明らかになります。 ユーザーがどんな機能を望んでいるか推測する代わりに、エージェントに何を頼んでいるかを観察できます。パターンが見えてきたら、ドメイン固有のツールや専用のプロンプトで最適化できます。事前に予測する必要はありません。実際の利用から発見できるのです。

フライホイール：

1. アトミックなツールとパリティを備えて構築する
2. ユーザーが想定していなかったことを依頼する
3. エージェントがツールを組み合わせて実行する（または失敗して不足を明らかにする）
4. どのような依頼が寄せられているか、パターンを観察する
5. よくあるパターンを効率化するため、ドメインツールやプロンプトを追加する
6. これを繰り返す

これによって、製品の作り方が変わります。あらゆる機能を最初から想像しようとするのではありません。十分な能力を備えた基盤を作り、そこから生まれるものを学んでいくのです。

テスト： エージェントに、あなたのドメインに関連する自由形式の依頼をしてみましょう。成功するまでループ処理を続けながら、妥当な進め方を見つけられますか？ ただ「その機能はありません」と答えるだけなら、アーキテクチャに制約が多すぎます。

---

5. 時間とともに改善する

エージェントネイティブなアプリケーションは、コンテキストの蓄積とプロンプトの改善を通じて、より良くなります。

従来のソフトウェアとは異なり、エージェントネイティブなアプリケーションはコードをリリースしなくても改善できます。

コンテキストの蓄積： エージェントはセッションをまたいで状態を維持できます。何が存在するか、ユーザーが何をしたか、何がうまくいき、何がうまくいかなかったかを保持できます。エージェントが読み取り、更新する context.md ファイルは、その第一段階です。より高度なアプローチでは、構造化されたメモリや学習した設定を利用します。

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

• 開発者レベル： すべてのユーザーに対するエージェントの動作を変える、更新済みのプロンプトをリリースします
• ユーザーレベル： ユーザーが自身のワークフローに合わせてプロンプトをカスタマイズします
• エージェントレベル： エージェントがフィードバックに基づいて自身のプロンプトを変更します（高度な手法）

自己変更（高度な手法）： 自身のプロンプト、あるいは自身のコードまで編集できるエージェントです。本番環境で使用する場合は、安全策の追加を検討してください。承認ゲート、ロールバック用の自動チェックポイント、ヘルスチェックなどです。今後はこの方向に進んでいきます。

改善の仕組みは、まだ模索されている段階です。コンテキストとプロンプトの改善は実証済みです。自己変更は発展途上です。明らかなのは、このアーキテクチャが従来のソフトウェアではできない方法での改善を支えていることです。

テスト： コードを変更しなくても、1 か月使った後のほうが、初日よりアプリケーションの動作は良くなっていますか？ </core_principles>

## エージェントネイティブなアーキテクチャのどの側面についてサポートが必要ですか？

1. アーキテクチャの設計 - 新しいエージェントネイティブシステムを一から計画する
2. ファイルとワークスペース - ファイルを汎用インターフェースとして使う、共有ワークスペースのパターン
3. ツールの設計 - プリミティブなツール、動的な機能の検出、CRUD の網羅性を実現する
4. ドメインツール - ドメインツールを追加するタイミングと、プリミティブなツールを使い続けるタイミングを判断する
5. 実行パターン - 完了シグナル、部分的な完了、コンテキスト制限
6. システムプロンプト - プロンプトでエージェントの動作と判断基準を定義する
7. コンテキストの注入 - 実行時のアプリケーション状態をエージェントのプロンプトに注入する
8. アクションの同等性 - エージェントがユーザーの行えることをすべて実行できるようにする
9. 自己変更 - エージェントが安全に自身を進化させられるようにする
10. プロダクト設計 - プログレッシブディスクロージャー、潜在需要、承認パターン
11. モバイルのパターン - iOS のストレージ、バックグラウンド実行、チェックポイントと再開
12. テスト - エージェントネイティブなアプリの機能と同等性をテストする
13. リファクタリング - 既存のコードを、よりエージェントネイティブにする

先に進む前に、回答をお待ちください。

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

リファレンスを読んだ後、パターンをユーザー固有の状況に適用します。

<architecture_checklist>

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

エージェントネイティブなシステムを設計する際は、実装前に以下を確認してください。

コア原則

• 同等性： すべての UI 操作に対応するエージェント機能があります
• 粒度： ツールはプリミティブであり、機能はプロンプトで定義される成果です
• 合成可能性： プロンプトだけで新しい機能を追加できます
• 創発的な能力： エージェントは対象分野の自由形式のリクエストに対応できます

ツール設計

• 動的か静的か： エージェントに完全なアクセス権を与える外部 API には、動的な機能検出を使用します
• 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", "Read any file", { path: z.string() }, ...),
  tool("write_file", "Write any file", { path: z.string(), content: z.string() }, ...),
  tool("list_files", "List directory", { path: z.string() }, ...),
  tool("complete_task", "Signal task completion", { summary: z.string() }, ...),
];

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

## Your Responsibilities
When asked to organize content, you should:
1. Read existing files to understand the structure
2. Analyze what organization makes sense
3. Create/move files using your tools
4. Use your judgment about layout and formatting
5. Call complete_task when you're done

You decide the structure. Make it good.

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

const result = await agent.run({
  prompt: userMessage,
  tools: tools,
  systemPrompt: systemPrompt,
  // Agent loops until it calls complete_task
});

</quick_start>

<reference_index>

リファレンスファイル

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

コアパターン：

• references/architecture-patterns.md - イベント駆動型、統合オーケストレーター、エージェントから UI への連携
• references/files-universal-interface.md - ファイルを使う理由、構成パターン、context.md
• references/mcp-tool-design.md - ツール設計、動的な機能検出、CRUD
• references/from-primitives-to-domain-tools.md - ドメインツールを追加するタイミング、コードへの移行
• references/agent-execution-patterns.md - 完了シグナル、部分的な完了、コンテキストの制限
• references/system-prompt-design.md - プロンプトとしての機能、判断基準

エージェントネイティブなプラクティス：

• references/dynamic-context-injection.md - 実行時のコンテキスト、注入する内容
• references/action-parity-discipline.md - 機能の対応付け、同等性を確保するワークフロー
• references/shared-workspace-architecture.md - 共有データ領域、UI 統合
• references/product-implications.md - 段階的な情報開示、潜在的な需要、承認
• references/agent-native-testing.md - 成果のテスト、同等性テスト

プラットフォーム固有：

• references/mobile-patterns.md - iOS ストレージ、チェックポイント／再開、コストへの配慮
• references/self-modification.md - Git ベースの進化、ガードレール
• references/refactoring-to-prompt-native.md - 既存コードの移行 </reference_index>

<anti_patterns>

アンチパターン

エージェントネイティブとは言い切れない一般的なアプローチ

これらが必ずしも間違っているわけではありません。ユースケースによっては適切な場合もあります。ただし、このドキュメントで説明するアーキテクチャとは異なるものとして認識しておく価値があります。

エージェントをルーターとして使う — エージェントがユーザーの意図を判断し、適切な関数を呼び出します。エージェントの知能は実際に作業するためではなく、ルーティングに使われます。これは機能しますが、エージェントができることの一部しか活用できていません。

アプリを構築してからエージェントを追加する — 従来の方法で（コードとして）機能を構築し、その後でエージェントに公開します。エージェントにできるのは、既存の機能でできることだけです。創発的な能力は得られません。

リクエスト／レスポンスの考え方 — エージェントが入力を受け取り、ひとつの処理を行って、出力を返します。この方法では、ループが考慮されていません。エージェントは達成すべき成果を受け取り、完了するまで処理を続け、その途中で予期しない状況にも対処します。

防御的なツール設計 — 防御的プログラミングに慣れているため、ツールの入力を過度に制約します。厳密な列挙型を使い、あらゆる層で検証します。これは安全ですが、エージェントが想定外のことを行うのを妨げます。

ハッピーパスはコードで処理し、エージェントには実行させるだけ — 従来のソフトウェアでは、エッジケースをコードで処理します。つまり、Xで問題が起きたときの処理を自分で記述します。エージェントネイティブな設計では、エージェントが判断してエッジケースに対処できます。コードがすべてのエッジケースを処理するなら、エージェントは単なる呼び出し役です。

---

具体的なアンチパターン

最大の過ち：エージェントに状況を把握させず、コードを実行させる

// WRONG - You wrote the workflow, agent just executes it
tool("process_feedback", async ({ message }) => {
  const category = categorize(message);      // Your code decides
  const priority = calculatePriority(message); // Your code decides
  await store(message, category, priority);   // Your code orchestrates
  if (priority > 3) await notify();           // Your code decides
});

// RIGHT - Agent figures out how to process feedback
tools: store_item, send_message  // Primitives
prompt: "Rate importance 1-5 based on actionability, store feedback, notify if >= 4"

ワークフロー型のツール — analyze_and_organize に判断処理をまとめています。これをプリミティブに分割し、エージェントに組み合わせさせます。

コンテキストの不足 — エージェントがアプリ内にどのリソースがあるかを把握できません。

User: "Write something about Catherine the Great in my feed"
Agent: "What feed? I don't understand what system you're referring to."

対処法：利用可能なリソース、機能、用語をシステムプロンプトに注入します。

UI 操作の未対応 — ユーザーは UI を通じて操作できるのに、エージェントには実現できません。対処法：機能の同等性を維持します。

状態変更が反映されない操作 — エージェントが状態を変更しても、UI が更新されません。対処法：リアクティブバインディングを備えた共有データストアを使うか、ファイルシステムの変更を監視します。

ヒューリスティックによる完了検出 — ツール呼び出しのない反復が連続した場合や、想定される出力ファイルを確認する場合など、ヒューリスティックによってエージェントの完了を検出します。これは不安定です。対処法：complete_task ツールを通じて、エージェントが完了を明示的に通知するようにします。

動的 API に対する静的なツールマッピング — 50 個の API エンドポイントに対して 50 個のツールを構築するより、discover と access のパターンを使うほうが柔軟性を高められます。

// WRONG - Every API type needs a hardcoded tool
tool("read_steps", ...)
tool("read_heart_rate", ...)
tool("read_sleep", ...)
// When glucose tracking is added... code change required

// RIGHT - Dynamic capability discovery
tool("list_available_types", ...)  // Discover what's available
tool("read_health_data", { dataType: z.string() }, ...)  // Access any type

不完全な CRUD — エージェントは作成できますが、更新や削除はできません。

// User: "Delete that journal entry"
// Agent: "I don't have a tool for that"
tool("create_journal_entry", ...)  // Missing: update, delete

対処法：すべてのエンティティに完全な CRUD を用意します。

サンドボックスによる分離 — エージェントがユーザーとは別のデータ領域で作業します。

Documents/
├── user_files/        ← User's space
└── agent_output/      ← Agent's space (isolated)

対処法：双方が同じファイルを操作する共有ワークスペースを使います。

理由のないゲート — ドメインツールだけが操作手段になっており、アクセスを制限する意図がありません。デフォルトではオープンにします。ゲートを設ける具体的な理由がない限り、プリミティブを利用可能な状態に保ちます。

人為的な機能制限 — 具体的なリスクではなく、漠然とした安全上の懸念からエージェントにできることを制限します。機能の制限は慎重に検討してください。一般に、エージェントにはユーザーができることを実行できるようにします。 </anti_patterns>

<success_criteria>

成功基準

以下を満たしたとき、エージェントネイティブなアプリケーションを構築できたと言えます。

アーキテクチャ

• エージェントが UI を通じてユーザーにできることをすべて実現できる（機能の同等性）
• ツールはアトミックなプリミティブであり、ドメインツールは近道であってゲートではない（粒度）
• 新しいプロンプトを作成することで新機能を追加できる（構成可能性）
• 明示的に設計していないタスクをエージェントが実行できる（創発的な能力）
• 動作を変更する際、コードをリファクタリングするのではなくプロンプトを編集する

実装

• システムプロンプトに、アプリの状態に関する動的なコンテキストが含まれている
• すべてのUI操作に対応するエージェントツールがある（操作の同等性）
• エージェントツールが、ユーザーの用語を使ってシステムプロンプトに記載されている
• エージェントとユーザーが同じデータ領域で作業する（共有ワークスペース）
• エージェントの操作がすぐにUIへ反映される
• すべてのエンティティで完全なCRUD（作成、読み取り、更新、削除）ができる
• エージェントが完了を明示的に通知する（ヒューリスティックによる検出はしない）
• 蓄積した知識を記録するcontext.mdまたは同等のものがある

プロダクト

• 簡単なリクエストは、学習コストなしですぐに実行できる
• パワーユーザーが、予想外の方向へシステムを活用できる
• ユーザーがエージェントに何を依頼するかを観察することで、ユーザーのニーズが分かる
• 承認要件が、リスクの大きさと取り消し可能性に見合っている

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

• チェックポイントと再開で、アプリの中断に対応できる
• iCloudを優先したストレージと、ローカルへのフォールバックがある
• バックグラウンド実行で、利用可能な時間を有効に使う
• タスクの複雑さに応じたモデルのティアを選ぶ

---

究極のテスト

アプリの領域内にありながら、専用の機能を実装していない成果をエージェントに説明してください。

エージェントは、成功するまでループしながら、その成果を達成する方法を見つけられますか？

できるなら、エージェントネイティブなものを構築できています。

「そのための機能はありません」と答えるなら、アーキテクチャにはまだ制約が多すぎます。