agent-native

エージェントネイティブ

エージェントネイティブなアプリケーションでは、エージェントを第一級のユーザーとして扱います。人間が UI を通じてできることはすべて、エージェントもツールを通じて実現できます。機能とは、プロンプトで記述された成果であり、エージェントがアトミックなツールを使い、完了するまでループを繰り返して実現します。

参照ファイル

ファイル	読むタイミング
references/core-principles.md	既定：同等性、粒度、合成可能性、創発的能力を理解するとき
references/tool-design.md	ツールを設計するとき — アトミックなプリミティブ、CRUD、ドメインツール、動的な発見
references/files-and-context.md	状態管理 — エンティティディレクトリ、context.md、コンテキスト注入、ファイルとデータベースの比較
references/agent-ui-communication.md	エージェントのフィードバックを構築するとき — 完了シグナル、部分的な完了、イベントの種類
references/mobile-specifics.md	iOS／モバイル — チェックポイント／再開、iCloud ストレージ、バックグラウンド実行

コア原則

• 同等性 — エージェントは、ユーザーが UI を通じてできることをすべて実現できます。機能マップを作成し、すべてのギャップを埋めます。
• 粒度 — ツールはアトミックなプリミティブです。判断と意思決定のロジックはツールの実装ではなく、プロンプトに置きます。振る舞いを変えるときは、コードではなく文章を編集します。

  # Anti-pattern: workflow-shaped tool
  analyze_and_organize(folder)  # bundles judgment into code
  
  # Agent-native: atomic primitives
  list_files(folder) → read_file(path) → move_file(src, dst) → write_file(path, content)
  # The agent decides what to move and where — judgment stays in the prompt
  

• 合成可能性 — 新機能は新しいプロンプトで実現できます。アトミックなツールと同等性があれば、成果を記述するだけで、エージェントが達成するまでループを繰り返します。
• 創発的能力 — エージェントは、設計時に想定していなかったリクエストにも対応します。ユーザーのリクエストを観察し、そこから生まれるパターンを定式化します。
• 時間とともに改善 — 状態はコンテキストファイルを通じて保持されます。コードをリリースしなくても、すべてのユーザー向けにプロンプトを更新できます。

設計ワークフロー

1. 機能の監査 — すべての UI 操作をエージェントで実現できる方法に対応付けます。ギャップがあれば埋めます。core-principles.md を読みます。
2. ツールサーフェスの設計 — すべてのエンティティに対するアトミックなプリミティブ（CRUD）を定義します。語彙、ガードレール、または効率性のためにのみ、ドメインツールを追加します。tool-design.md を読みます。
3. コンテキストと状態の計画 — context.md ファイル、エンティティディレクトリの構成、システムプロンプトへの注入方法を設計します。files-and-context.md を読みます。
4. エージェントと UI のフィードバック設計 — 完了シグナル、イベントの種類、共有ワークスペース、承認ゲートを定義します。agent-ui-communication.md を読みます。
5. 検証 — 以下のチェックリストを実行します。まだ構築していない成果を記述し、エージェントがその実現方法を見つけられるかテストします。

設計チェックリスト

設計中にコピーして進捗を記録します。

Agent-native design progress:
- [ ] Capability map: every UI action has an agent equivalent
- [ ] Tools are atomic primitives (judgment in prompts, not tools)
- [ ] Every entity has full CRUD tool coverage
- [ ] System prompt injects available resources and capabilities
- [ ] Agents and users share the same data space
- [ ] Agent actions reflect immediately in UI
- [ ] Completion is signaled explicitly (no heuristic detection)
- [ ] External APIs use dynamic capability discovery where possible
- [ ] Approval model matches stakes and reversibility
- [ ] Ultimate test: describe an unbuilt outcome — can the agent figure it out?

検証ループ

リリース前に、以下を確認します。

1. 機能の網羅性 — UI 操作をランダムに 5 つ選び、それぞれをコードに触れずにエージェントが実現できることを確認します。
2. ツールのアトミック性 — すべてのツールを確認します。if/else の意思決定ロジックが含まれている場合は、分割します。
3. コンテキストの完全性 — エージェントのコンテキストをクリアしてセッションを開始します。エージェントは、何が存在するかを把握できていますか？
4. エンドツーエンドのシナリオ — 明示的に構築したことのない成果をエージェントに指示します。ツールを組み合わせて実現できますか？

アンチパターン

• ルーターとしてのエージェント — エージェントが判断を伴って行動するのではなく、コードに処理を振り分けています。構築したのはエージェントではなく、ディスパッチャーです。
• ワークフロー型ツール — analyze_and_organize は意思決定ロジックをツールにまとめています。read_file、move_file、write_file に分割します。
• 孤立した UI 操作 — ユーザーにはできるのに、エージェントにはできない操作があると、同等性が損なわれます。
• コンテキスト不足 — エージェントが何のリソースが存在するか把握できていません。すべてのシステムプロンプトにリソースと機能を注入します。
• 理由のないゲート — プリミティブでも実行できるべきなのに、ドメインツールだけが唯一の経路になっています。既定では制限を設けません。
• ヒューリスティックな完了検出 — 連続したアイドル反復で完了を検出します。明示的な完了ツールの呼び出しを必須にします。
• 静的な API マッピング — エンドポイント 50 個に対してツールを 50 個用意します。発見とアクセスを使います。

関連スキル

• define-architecture — エージェントネイティブ化する前に、リポジトリの構成とモジュール境界を定義します
• agents-md — エージェントへの指示の品質について、CLAUDE.md／AGENTS.md を監査します