The five principles

Parity. Whatever the user can do through the UI, the agent should be able to achieve through tools. Without parity, every other principle breaks. The discipline: when you add any UI capability, ask whether the agent can reach the same outcome.

Granularity. Tools are atomic primitives. Features are outcomes an agent achieves by operating in a loop. A tool is read_file; a feature is “organize the downloads folder.” The test: to change behavior, do you edit prompts or refactor code? If you refactor code, you have bundled judgment into the tool.

Composability. With atomic tools and parity, new features are new prompts. A “weekly review” feature is a prompt that tells the agent to review modified files, summarize changes, and suggest priorities. Ship features by adding prompts. Users customize by modifying prompts or writing their own.

Emergent Capability. The agent accomplishes things you did not design for. “Cross-reference my meeting notes with my task list and tell me what I committed to but have not scheduled” works if the agent can read notes and tasks, even though you never built a commitment tracker. This reveals latent demand — you discover what users need instead of guessing.

Improvement Over Time. Agent-native applications get better without shipping code. Accumulated context persists across sessions via context files. Developers ship updated prompts for all users. Users customize prompts for their workflow. The mechanisms compound.

Files as the universal agent interface

The filesystem is the best agent interface for four reasons:

1. Already known. Agents already understand cat, grep, mv, mkdir. File operations are the primitives they handle most fluently.
2. Inspectable. Users can see what the agent created, edit it, move it, delete it. No black box.
3. Portable. Export and backup are trivial. Users own their data.
4. Self-documenting. /projects/acme/notes/ is self-documenting in a way that SELECT * FROM notes WHERE project_id = 123 is not.

The design heuristic: if a human can look at your file structure and understand what is going on, an agent probably can too.

The context.md pattern

A markdown file the agent reads at session start and updates as state changes. It holds identity, user preferences, what exists, recent activity, guidelines, and current state. It is portable working memory without code changes — the same idea as the folder-as-agent thesis in The Folder Is the Agent - Context Accumulation as Specialization, where accumulated context in the folder is what specializes the agent.

This maps directly to the Write/Select pattern in Context Engineering: inject the right context before reasoning begins, and update it as the session progresses.

Anti-patterns to avoid

• Agent as router. Using agent intelligence to route to the right function, not to act. Wastes most of what agents can do.
• Build-then-add-agent. Building features as code, then exposing them to an agent. The agent can only do what your features already do. No emergent capability.
• Request/response thinking. Agent gets input, does one thing, returns output. Misses the loop where the agent pursues an outcome and handles unexpected situations along the way.
• Defensive tool design. Over-constraining tool inputs with strict enums and validation at every layer. Safe, but prevents the agent from doing things you did not anticipate.

The ultimate test

Describe an outcome to the agent that falls within your application’s domain but that you did not build a specific feature for. Can it figure out how to accomplish it, operating in a loop until it succeeds? If yes, you have built something agent-native. If no, the architecture is too constrained.

Related Notes

• Agent Harnesses — parent note; the orchestration layer these principles operate within
• The Folder Is the Agent - Context Accumulation as Specialization — context.md is the folder’s accumulated context; change the folder, not the model, to get a different specialist
• AXI Principles - Agent-Ergonomic Interface Design — tool design principles that complement these interface principles (Efficiency, Robustness, Discoverability, Fallback)
• Context Engineering — context injection maps to the Write/Select pattern; context.md is the portable implementation
• Claws - Persistent Looping Agents as App Replacement — claws implements the agent-native pattern; apps expose APIs for persistent agent loops

Source: Dan Shipper + Claude, Every (Jan 2026, ~5k words). Clipping: Agent-native Architectures.