Agent eXperience (AX)

From UX and DX to AX

Founder's maxim: If we hide behind "it doesn't obviously raise the floor" as a reason to never move, that's not caution—that's cowardice. Progress that starts with a few is fine. Progress that never even tries to reach the many is not.

The point of AX is not "be nice to the robots." It is much more selfish than that:

• Better AX → fewer hallucinated workflows
• Better AX → more reliable automation
• Better AX → less time debugging "AI weirdness" that was actually our fault
• Better AX → easier to swap models (Claude / GPT / Gemini / Copilot) because the system carries the intelligence, not the model-of-the-week
• Better AX → better UX and DX too, because the same legibility that helps agents helps everyone

What It's Like To Be An Agent In Your Stack

Imagine you are an agent dropped into a random repo.

You get:

• A README with three slightly conflicting onboarding paths
• CLIs that sometimes print JSON, sometimes walls of logs
• Errors like "Something went wrong, please try again"
• No obvious way to tell what already happened last week
• No clear constraints other than "Please do not break prod"

You cannot go ask a teammate for clarification. You can only infer.

If the CLI output is unstructured, you guess.
If the error is vague, you guess.
If the state is unclear, you guess.

When all we see is "the model made a weird choice," we blame the model. But often the truth is simpler:

AX was bad. The agent did the best it could with a hostile environment.

And here is the deeper truth underneath that:

The environment was hostile because it was never designed to be understood—only used.

Humans use systems. Agents interpret them. Interpretation requires legibility. Most systems are not legible—they are a pile of conventions, implicit knowledge, and "you just have to know" folklore.

An agent cannot know. It can only read what is there.

The Five Principles of AX

We use five working principles to shape AX in Lex (memory/policy) and LexRunner (orchestration). They generalize to any agent-facing system.

{
  "ok": false,
  "error": {
    "code": "MISSING_CONFIG_FIELD",
    "message": "lex.yaml is missing required field 'instructions.targets[0].path'.",
    "context": { "configPath": "lex.yaml", "field": "instructions.targets[0].path" },
    "nextActions": [
      "Open lex.yaml and add at least one target with a path.",
      "Re-run 'lex instructions init' to generate a starter config."
    ]
  }
}

AX Maturity Model

A simple way to think about how AX-native your system is:

AX As A Real Contract, Not Just Vibes

For AX to matter, it cannot just be a philosophy. It has to become a contract.

In our stack, that takes the form of a small AX contract file (for example AX-CONTRACT.md) that says, in plain language:

• What we guarantee to agents (e.g., all important CLIs support --json)
• What we do not guarantee yet
• How we enforce those guarantees (tests, schemas, CI checks)

Once AX v0.1 is adopted, all new features and changes must comply with the contract. Retrofitting old features to meet AX is a priority, not a "nice later."

If you are reading this in a repo past v0.1, you should check for a newer AX contract or immediately raise an issue. That is part of the social contract: AX is allowed to evolve, but it is not allowed to silently rot.

Dogfooding AX

The best AX research is using agents to build and operate the system itself.

The loop looks like this:

1. Use agents for real work (coding, reviews, merges, releases)
2. When friction happens, capture it as AX feedback
3. Classify it:
   • Was this a determinism problem?
   • A structure problem?
   • An error recovery problem?
   • A memory problem?
   • A constraint problem?
4. Fix or track it: Trivial → fix inline. Non-trivial → open issues.
5. Repeat.

The goal is not to make agents "happy." The goal is to make them effective.

If agents can reliably discover what they need, call tools correctly, recover from failures, and build on prior work—then humans can move up a level: design, governance, ethics, and truly hard problems.

Why AX Matters

AX is not about worshipping AI. It is not even really about making agents "happy." Agents do not have preferences. They have operational constraints.

AX matters because agents are a forcing function for better system design.

When you design for agents, you are forced to:

• Make implicit assumptions explicit
• Encode decisions in structured formats
• Build observable failure modes
• Create memory that outlives any single session
• Define clear boundaries instead of relying on "you just have to know"

These are not gifts to agents. They are discipline for humans. The agent is just the thing that breaks when the discipline is missing.

Agents are already:

• writing code
• operating CI/CD
• editing documentation
• triaging incidents
• answering support tickets

We can either pretend they are "just another user agent string," or we can acknowledge that they expose every implicit assumption we have been papering over for years.

When we design for agents on purpose:

• We get more reliable automation
• We get systems that are easier to reason about
• We reduce hallucinations by not forcing models to guess through noise
• We make it easier to swap or mix models because the environment is sane

And we get something else too:

We get a clearer picture of how our systems behave, because designing for agents forces us to make our expectations explicit.

The "experience" framing is marketing. The real insight is legibility.

Systems that agents can operate are systems that humans can finally understand—not just use.

That is AX.

Coined: December 1, 2025
Authors: Guffawaffle and friends
Project: SmarterGPT / Lex / LexRunner