Agent-native architecture: pragmatism over hype

Technical discussion around AI agents has revolved for months around the same concepts: orchestration, tools, context. But most existing software was not designed with the assumption that an LLM would operate it. Layering an agent on top of traditional architecture is possible, but generates friction that accumulates. That is the central premise of the article Pragmatic Agent-Native Architecture, published this week and shared on Hacker News.

The author, Geoff Mays, argues that there is a substantial difference between "software with AI" and "agent-native software". The first adds LLM capabilities to pre-existing systems. The second is built assuming from the outset that its primary consumers will be autonomous agents, not human user interfaces.

What the article proposes

Mays articulates several principles that, read together, form a fairly applicable design guide:

• Small, well-defined action surfaces. Instead of generic APIs that return large blocks of data, agent-native software exposes atomic operations with clear semantics. An agent should not have to infer what an endpoint does; the contract must be explicit.
• Observable and recoverable state. Agents fail, get interrupted, and restart. A system well-designed for them persists intermediate state and allows resuming tasks without repeating work already done.
• Errors as structured data, not opaque exceptions. If an agent receives a generic error message, it cannot reason about it. Errors need codes, context, and when possible, correction suggestions.
• Idempotence as a requirement, not an optimization. An agent may invoke the same action multiple times by design or by failure. Operations must tolerate that without unwanted side effects.
• Explicit capability contracts. The system must be able to declare what it can do, under what conditions, and with what limitations. Something analogous to what MCP already formalizes in the Claude ecosystem.

Why it matters now

This type of reflection arrives at a moment when the use of Claude Code with sub-agents and MCP servers is normalizing the direct consumption of services and internal systems by agents. When the consumer of your API is Claude Opus 4.7 orchestrating complex tasks with a 1M token context window, design assumptions change in non-trivial ways.

The usage patterns we are seeing in MCP integrations suggest exactly what Mays describes: agents benefit enormously from well-scoped action surfaces. An MCP server that exposes fifty generic tools is much less useful than one that exposes ten precise operations with well-defined input and output schemas. The number of tokens dedicated to resolving ambiguity decreases, and error rates do too.

In the context of Claude Code, this translates into how plugins and skills are designed. A skill that assumes the agent will read reference documentation to understand how to use it is a poorly designed skill. The instruction needs to be self-contained enough for the agent to make correct decisions without additional context.

Who it's useful for

The article is fundamentally directed at engineering teams building or redesigning internal services and want those services to be consumable by agents without friction. It is also relevant for those developing MCP servers, Claude Code plugins, or any system that will be invoked programmatically by agents.

It is not an article for teams that simply want to add a chatbot to their product. The approach is structural: it involves making architectural decisions that affect API design, state management, and error handling strategy from the beginning of the system's lifecycle.

Comments on Hacker News are still sparse at the time of writing, which likely reflects that the piece is technical and specific, not a headline-grabbing story. That does not diminish its value; on the contrary, it is the type of content shared internally among teams before an architectural decision.

---

EP's take: The principles Mays describes are not new in software engineering, but systematizing them with the agent as an explicit consumer is a useful exercise that was missing rigor. It is worth keeping nearby the next time you design an MCP server from scratch.