Summary: Agent-native Architectures

2026-01-13 | 6 min | 1078 words | Jonas

The guide “Agent-Native Architectures”, by Dan Shipper and Claude, explores a fundamental shift in software development: moving away from traditional, code-heavy applications toward “agent-native” systems. In this new paradigm, AI agents are not just add-on features but the primary engine of functionality. The document, co-authored by Dan Shipper and Claude, synthesizes lessons learned from building agentic apps like Reader and Anecdote, arguing that we are entering an era where software works the way “Claude Code” does—by operating in a loop with access to tools until an objective is achieved.

1. The Core Shift: From Code to Outcomes

Traditionally, software features are hard-coded sequences of logic. If a developer wants to add a “summarize and tag” feature, they write the specific code to handle that workflow. In an agent-native architecture, a feature is an outcome described in a prompt. The agent uses a set of atomic tools (like reading and writing files) to achieve that outcome through its own judgment and iteration. This transition means that “code ends” in the sense that the developer focuses on providing a capable environment and clear objectives rather than scripting every possible user path.

2. The Five Principles of Agent-Native Design

The guide outlines five foundational principles that differentiate agent-native apps from traditional software:

• Parity: This is the most critical rule. Anything a user can do through the graphical user interface (UI), the agent must be able to do through tools. If a user can delete a note but the agent cannot, the agent’s utility is capped. Parity ensures the agent is a “first-class citizen” in the application.
• Granularity: Tools should be atomic primitives (e.g., read_file, move_file) rather than complex, bundled functions. High granularity allows the agent to exercise judgment. If a tool is too complex (e.g., classify_and_organize_files), the logic is trapped in code; if it is granular, the agent can handle edge cases the developer never anticipated.
• Composability: Because tools are atomic, they can be combined in infinite ways. Developers can “ship” new features simply by writing a new prompt that instructs the agent to use existing tools in a specific sequence.
• Emergent Capability: This is the “flywheel” effect. When an app has parity and granular tools, users will inevitably ask the agent to do things the developer didn’t explicitly design. This reveals latent demand and allows the software to grow “organically” based on actual usage patterns.
• Improvement Over Time: Unlike traditional apps that only improve with new code deployments, agent-native apps improve as the agent accumulates context. By maintaining state in “context files,” the agent becomes more personalized and efficient the more it is used.

3. Implementation: The Agent Loop and Tooling

The architecture relies on an “agent loop.” Instead of a single request-response cycle, the agent observes the state, decides on an action, executes a tool, observes the result, and repeats until the goal is met.

Primitives vs. Domain Tools: Shipper suggests starting with pure primitives—basic file operations and bash commands. As patterns emerge, developers can “graduate” certain sequences into Domain Tools. These are shortcuts for common operations (like Notes) that provide guardrails or improve efficiency. However, domain tools should be “shortcuts, not gates.” The agent should always retain access to the underlying primitives to handle edge cases that the domain tool might not cover.

Graduating to Code: For “hot paths”—actions performed frequently where performance and determinism are critical—developers can eventually implement the logic in optimized code. However, the agent-native philosophy insists that the agent should still be the one to trigger these optimized paths, maintaining the flexibility to fall back to manual tool use if needed.

4. Files as the Universal Interface

A significant technical recommendation in the guide is using the filesystem as the primary interface for agents. There are several reasons for this “file-first” approach:

• Agent Fluency: LLMs are naturally skilled at using command-line tools like ls, grep, and cat.
• Transparency: Files are human-readable. Users can inspect, edit, or delete what the agent creates, removing the “black box” feel of traditional databases.
• Portability: Files are easily synced across devices (via iCloud or Dropbox) and are easy for users to export, ensuring they own their data.
• Self-Documentation: A well-organized folder structure (e.g., /projects/research/notes.md) is more intuitive for an agent to navigate than a complex relational database schema.

5. Mobile Challenges: Checkpointing and Persistence

Building agentic apps for mobile (specifically iOS) presents unique challenges because agents are “long-running” while mobile apps are ephemeral. iOS often kills background processes to save memory, which can interrupt an agent mid-task.

To solve this, the guide suggests a robust Checkpoint and Resume system. The agent’s state—including its message history, current task list, and iteration count—must be saved after every tool call. This allows the app to pick up exactly where it left off if the user switches apps or the system terminates the process. Additionally, using iCloud as the primary storage allows for seamless synchronization; an agent can start a task on a phone and the results can appear instantly on a laptop because they share the same filesystem.

6. Anti-Patterns to Avoid

The guide warns against several common mistakes when building with agents:

• Agent as Router: Using the agent only to decide which hard-coded function to call. This wastes the agent’s reasoning capabilities.
• Defensive Tool Design: Over-constraining tool inputs with strict enums. While safe, this prevents the agent from using tools in creative, unanticipated ways.
• The “Black Box” UI: Hiding the agent’s process. Shipper argues that “silent agents feel broken.” The UI should stream the agent’s “thinking,” show tool calls in real-time, and update progress bars to build user trust.
• Context Starvation: Failing to tell the agent what data is available. The system prompt should always include a summary of available resources (e.g., “You have 12 notes in the /research folder”).

Conclusion: The Future of Agent-Native

The “Agent-Native” guide posits that we are moving toward software that feels more like an “Excel for everything”—a tool that is simple to start with but infinitely powerful because it can be composed into complex systems. By treating the agent as the primary architect of the user’s experience and using the filesystem as a transparent, shared workspace, developers can build applications that are more flexible, personalized, and capable than anything possible in the era of “hard-coded” software. The ultimate goal is a system where changing the software’s behavior is as simple as changing a prompt, effectively ending the era of rigid, code-first development.