DIRECT: Six Principles for Designing Software That AI Agents Can Use

After three months of intensive collaboration with Claude, resulting in 3,500+ commits, 300+ releases, and over 1 million lines across 124 public repositories, I’ve collected some of my general thoughts in 7 Techniques for Scaling AI Usage , but also wanted to provide some specific thoughts on the Agent Experience (AX) and how to make agent-friendly software in a set of principles that I call DIRECT. These principles are designed to help us think about designing the Agent Experience, the same way that SOLID changed how we think about object-oriented design (OOD).

The Conversation Has Started — Now We Need to Codify It

The industry has started to discuss Agent Experience, or AX. Netlify launched agentexperience.ax to define AX as “the holistic experience AI agents have when interacting with a product, platform, or system” — the AI counterpart to UX and DX. This is important , and their call for community collaboration is valuable.

While discussion is a start, we need more. We need codified principles that developers and agents can apply and tools can enforce. That’s what DIRECT provides.

What is DIRECT?

DIRECT is to Agent Experience what SOLID is to Object-Oriented Design: a foundational set of principles that guide the creation of interfaces AI agents can reliably use.

• Deterministic: Agents trust the system to behave the same way each time, making safe recovery from errors natural.

• Introspectable: Agents explore capabilities and understand data structures without requiring external docs or humans

• Recoverable: Agents can diagnose what went wrong and take corrective action without human intervention

• Explicit: Agents operate within clear boundaries and constraints so they act with confidence

• Consistent: Agents build mental models once and apply them everywhere, scaling their effectiveness

• Testable: Agents can try actions safely before committing, learning what works without causing harm

These aren’t abstract ideals. Each principle addresses a specific failure mode I encountered repeatedly while working with agents.

Interactive version at https://grokify.github.io/direct-principles/

AX Over DX: A Counterintuitive Approach

Here’s what surprised me most: I stopped using traditional Developer Experience and started relying on Agent Experience.

I built 25+ integrations for my PlexusOne stack across LLM providers (OpenAI, Anthropic, Google, xAI, Ollama), observability platforms (Opik, Langfuse, Phoenix), voice services (Deepgram, ElevenLabs, Twilio), search APIs, and infrastructure tools. Instead of reading documentation or learning SDKs myself, I provided information to Claude, such as OpenAPI specs, Python SDK source code, and we discuss the implementation together.

I know what good DX looks like, from both from using many APIs/SDKs and my time on the RingCentral Developer Program, which won seven industry awards including API World’s Best in Communications APIs (2018, 2019, 2021), DevPortal Awards’ Best Developer Dashboard, and Nordic APIs’ Best Public API.

But when working with agents, I’ve learned to make different choices. For example:

• When a human developer sees 400 Bad Request, they read the error message, check the docs, maybe search Stack Overflow. They iterate through understanding.

• When an agent sees 400 Bad Request, it can hallucinates a fix that makes things worse. Agents don’t “understand” in the human sense, so I need to step in. They need structured, unambiguous interfaces to operate reliably.

This realization led me to develop DIRECT.

How I Learned This (The Hard Way)

In Q1 2026, I ran an experiment: use AI agents as my primary development partner for as much work as possible. The results were staggering in scale:

• Commits: 3,561

• Releases: 304

• Lines Added: 1,696,636

• Lines Deleted: 689,678

• Net New Lines: 1,006,958

• Repositories: 124

But raw numbers don’t tell the entire story. The story is in what worked and what didn’t.

• What worked: When I gave Claude well-structured specifications, explicit constraints, and consistent patterns, it produced code I could trust. Iteration was fast. Errors were recoverable.

• What didn’t work: When interfaces were ambiguous or counterintuitive, when error messages were vague, when behavior varied unpredictably- the agent would spin. I’d watch it make the same mistake multiple times, until I needed to step in and suggest alternative approaches.

The pattern became clear: agent effectiveness depends more on interface design than on model capability.

The Three Things You Should Do With Agents

Working this intensively with agents taught me there are three complementary activities, all of which can benefit from DIRECT experiences:

1. Working With Agents

This is where most people start. Use Claude, GPT, or Copilot to help you code. It works — sometimes brilliantly, sometimes frustratingly.

The frustration usually isn’t the agent’s fault. It’s the interface’s fault, which is why we’ve created the practice of prompt engineering.

2. Build Tools That Make Agents More Efficient

Once you see agents struggle with the same problems repeatedly, you start building solutions. Over Q1, I built or contributed to 11 tools specifically designed for agent-assisted development:

• agent-team-release: Release automation — R, C, T

• ax-spec: OpenAPI linting & enrichment — I, E

• design-system-spec: Design systems as code — I, C

• schemalint: Schema validation for static typing — D, E

• structured-changelog: Token-efficient changelogs — I, E, C

• traffic2openapi: Generate specs from HTTP traffic — I, E

• w3pilot: Browser automation for agents — I, R, T

Each tool embodies specific DIRECT principles and are agent-first. For example, structured-changelog is designed for changelog creation using LLM agents, unlike other solutions that use raw git logs determinisiticaly. It and other tools output in TOON format (Token-Oriented Object Notation) by default — approximately 8x more token-efficient than raw git log output. When agents pay for context in tokens, efficiency matters.

3. Orchestrating Agents in Teams

The most powerful pattern I discovered: agents working together, each with specialized capabilities, coordinated through well-defined interfaces.

This is where DIRECT principles become essential. When Agent A calls a tool that Agent B will consume the output of, every principle matters:

• Deterministic: Agent B can rely on consistent output structure

• Introspectable: Agent B can discover what the output contains

• Recoverable: Errors include enough context for Agent B to adapt

• Explicit: No hidden assumptions between agents

• Consistent: Patterns learned from one interaction transfer to others

• Testable: Agents can validate their plans before execution

My release agent team orchestrates multiple specialized agents (QA, security, documentation, release management) to handle software releases. Each agent operates on DIRECT-compliant interfaces, enabling autonomous coordination. The team structure and handoff forms are defined using multi-agent-spec—a formal specification that declares agent capabilities, workflow dependencies, and typed inputs/outputs between steps.

Example: Choosing ogen for OpenAPI code generation

When generating Go structs from OpenAPI specs, I evaluated several tools. The most “ergonomic” ones for humans — oapi-codegen, go-swagger — produce code that’s easier to read but makes assumptions that can confuse agents. They might flatten nested types, use interface{} for ambiguous schemas, or generate helper methods with implicit behavior.

I chose ogen instead. It’s more verbose, less ergonomic for humans, but extremely correct. Every type is explicit. Every field is deterministic. Every validation is clear.

For a human developer, this verbosity feels like friction. For an agent, it’s clarity. The agent never has to guess what a type contains or how validation works — it’s all explicit in the generated code.

This is DIRECT’s Explicit principle in action: when the choice is between human ergonomics and machine clarity, choose clarity. Humans can learn conventions; agents need explicit declarations.

What Does “Developer Program” Mean in 2026?

This raises a question I’ve been thinking about: what does it mean to run a developer program when your users are no longer just humans?

When I ran the RingCentral developer program, success metrics were human-centric: time-to-first-call, documentation satisfaction scores, SDK adoption rates, developer NPS. We optimized for humans reading docs, humans debugging in sandboxes, humans asking questions in forums.

But if agents are increasingly the ones consuming your APIs, the game changes rom traditional UX to AX:

• Readable documentation > Machine-parseable schemas

• Helpful error messages > Structured error codes with recovery hints

• Interactive tutorials > Deterministic sandbox environments

• Community forums > Introspectable capability endpoints

• SDK convenience methods > Explicit predictable behavior

The developer program of the future might measure: agent success rate on first API call, mean time to autonomous recovery, schema coverage percentage, and how often agents need to fall back to human intervention.

This doesn’t mean abandoning human developers. It means recognizing that the “developer” consuming your API might be Claude helping a human, or an autonomous agent in a pipeline, or a human who never reads your docs because their agent already understands the OpenAPI spec.

The platforms that win will be the ones optimized for both. DIRECT principles are one attempt to codify what “optimized for agents” actually means.

Concrete Example: Error Classification

Let me show how DIRECT principles translate to real code.

The problem: Different APIs return errors in different formats. An agent calling ElevenLabs gets different error structures than one calling Deepgram. Without standardization, agents need per-provider error handling logic.

The solution: Unified error classification with 8 categories.

// From omnivoice-core/resilience
type ErrorInfo struct {
  Category   ErrorCategory // transient, rate_limit, validation, auth, etc.
  Retryable  bool
  Code       string
  Message    string
  Suggestion string
  RetryAfter time.Duration
}

Now an agent can make decisions programmatically:

if err.IsRetryable() {
  time.Sleep(err.GetRetryAfter())
  // retry…
} else {
  log.Printf("Cannot retry: %s. Suggestion: %s",
  err.GetCode(), err.GetSuggestion())
}

This is Recoverable in action. The agent doesn’t parse error strings — it receives structured, actionable metadata.

The Website and Documentation

I’ve published the full DIRECT framework at grokify.github.io/direct-principles. The site includes:

• Detailed principle definitions with examples and anti-patterns

• Compliance levels (AX-L1, AX-L2, AX-L3) for progressive adoption

• Case studies showing DIRECT applied across the tooling ecosystem

• Spectral rules via ax-spec to enforce DIRECT for OpenAPI specifications

The case study on the Agent Tooling Ecosystem walks through how each tool applies specific principles.

Why This Matters Now

We’re at an inflection point. AI agents are moving from novelty to infrastructure. The companies and developers who figure out how to build agent-friendly interfaces will have a significant advantage. Consider:

• APIs that agents can discover, call, and recover from errors automatically

• CLIs that agents can compose into pipelines without human intervention

• Documentation that machines can parse as effectively as humans can read

• SDKs with layers optimized separately for agent and human consumers

This isn’t about replacing human developers. It’s about multiplying their effectiveness. In Q1, I shipped more than I ever have — not because I worked harder, but because agents could reliably handle more of the work.

The bottleneck was never the agent’s capability. It was always the interface.

Getting Started

If you want to apply DIRECT principles:

1. Start with one principle. Add `operationId` to every endpoint in your OpenAPI spec (Introspectable). Or ensure all errors return structured codes (Recoverable).

2. Use ax-spec to audit. Run `vacuum lint — ruleset ax-spec/rules/ax-openapi.json your-api.yaml` to see where your API falls short.

3. Design for the agent first. When adding a new endpoint or CLI command, ask: “Can an agent understand this without reading prose documentation?”

4. Test with actual agents. The best validation is using Claude or GPT to interact with your interface. Where do they struggle? That’s where DIRECT principles apply.

Conclusion

SOLID gave us a vocabulary for discussing object-oriented design. DIRECT aims to do the same for agent-facing interfaces.

The principles are:

• Deterministic — Same input, same output, every time

• Introspectable — Machine-readable capabilities and schemas

• Recoverable — Structured errors enable autonomous correction

• Explicit — All constraints declared, nothing hidden

• Consistent — Patterns that generalize across the interface

• Testable — Safe experimentation without consequences

We’re early in the age of AI agents. The interfaces we build today will shape how effectively agents can augment human work tomorrow.

I believe that DIRECT principles — or something like them — will become as fundamental to agent-oriented development as SOLID is to object-oriented design.

The code, documentation, and tools are all open source. I’d love to hear what you think.

Resources

• DIRECT Principles (https://grokify.github.io/direct-principles/) — Full documentation and case studies

• AX Spec (https://github.com/plexusone/ax-spec) — Spectral rules for OpenAPI compliance

• Agent Tooling Ecosystem Case Study (https://grokify.github.io/direct-principles/case-studies/agent-tooling-ecosystem/) — How DIRECT applies across 11 tools

• PlexusOne (https://github.com/plexusone) — Organization for agent tools and SDK integrations

• Multi-Agent Spec (https://github.com/plexusone/multi-agent-spec) — Specification for defining agent teams and workflows

• PlexusOne Integrations (https://plexusone.dev/integrations/) — 25+ integrations across LLMs, voice, search, and infrastructure