Agent experience (AX) is the experience an AI agent has when it uses a product on behalf of a human. Netlify CEO Mathias Biilmann coined the term in January 2025 for platforms, but the AX that decides your week is your own repository's.
Agent experience responds to ordinary engineering work. Building Blume (blume.codes), a sidecar that watches coding-agent sessions and suggests fixes, we see the same friction in almost every setup. Here are the seven highest-impact fixes as of August 2026, ranked. The first two are worth more than the rest combined.
| # | Fix | First action | Effort |
|---|---|---|---|
| 1 | Fix the tests that lie | Quarantine every test that failed intermittently this month | An afternoon |
| 2 | Speed up the feedback loop | Time a targeted test plus typecheck; get it under two minutes | A day or two |
| 3 | Write a curated AGENTS.md | Write down only the commands and gotchas agents got wrong | An hour |
| 4 | Move repeated rules into hooks and gates | Promote your three most-repeated corrections to hooks or CI | A day |
| 5 | Make the codebase greppable | Rename your three worst generic names | An afternoon |
| 6 | Agent-proof errors, CLIs, and docs | Rewrite the one error message that sent an agent in circles | An hour |
| 7 | Read your agent transcripts | Read your last five sessions end to end | An hour |
1. Fix the tests that lie to your agent
Quarantine or delete every flaky test this week. A smaller suite that tells the truth beats a bigger one that sometimes lies, because the agent cannot tell the difference and will trust the lie.
This is first because everything else runs on it. An agent works in a loop (change, verify, adjust) and your test suite is its only sense of truth. Anthropic's guidance is blunt: give the agent a check it can run, or you become the verification loop. Clipboard Health found 100 percent of pull requests in its two largest repos hit flaky end-to-end tests. Their engineer Rocky Warren: "Agents can't iterate against a test suite that lies to them." The agents retried, added sleeps, and fixed tests that were never broken. Clipboard cut the suite from 174 tests to 87, got flakes under 15 percent, and the doom loop stopped.
2. Make the feedback loop fast
Time your loop today. If a targeted test plus a typecheck takes more than a minute or two, split out a fast suite and cache what you can. Then document the fast path so agents find it first.
Loop speed is the speed limit on everything an agent does for you. A human tolerates a slow loop by fetching coffee; an agent idles expensively, dozens of times per session. Armin Ronacher calls Go's test caching "surprisingly crucial" for agent loops and notes that a 3 millisecond tool and a 5 second tool produce completely different agent economics. Ramp pointed an agent at the problem itself and cut CI from an 18 minute to a 6 minute P50.
3. Write a curated AGENTS.md, and keep it short
Write down only what agents actually got wrong: commands, gotchas, conventions. Cut every line whose removal would not cause a mistake. Skip generated boilerplate entirely; bloated files cause agents to ignore your actual instructions.
The measured payoff: across 124 mirrored pull requests, agents with an AGENTS.md finished 28.6 percent faster and used 16.6 percent fewer tokens, with no change in output quality. Note what that means: context files buy efficiency, not correctness. Correctness comes from fix number one. The good files read like a note to a competent house sitter:
## Commands
- pnpm test:unit # fast, no network
- pnpm typecheck # ~40s, run before you finish
- pnpm dev:e2e # sandboxed app state
## Gotchas
- e2e/checkout.spec.ts is quarantined. Do not "fix" it.
- Never edit src/generated/*. Regenerate with pnpm codegen.
- The db tests need Docker running. Say so if it is not.For context only some tasks need, use skills, loaded on demand instead of sitting in every session. When Netlify benchmarked its own agent experience with AXIS, skills raised agent scores by an average of 26 points out of 100 and cut time and tokens on every run.
4. Move repeated rules into hooks and gates
When the same correction shows up a third time, promote it out of prose: a hook that runs the linter after every edit, a CI job that greps for callers of every changed symbol, a stop condition on a passing build.
Instructions are advisory and decay as the context window fills. Checks are deterministic and never tire. Sourcegraph's framing: agents do the visible 80 percent of a task and miss the invisible 20 percent (the other callers, the audit logging, the migration script); gates make the invisible part block the merge. A correction in a chat helps one session. In the rulebook, every session. In a gate, it cannot be forgotten at all.
5. Make your codebase greppable
Rename your three worst generic names, then add lint rules that keep it that way, for example preferring named exports over default exports so every usage carries the real symbol name (Factory.ai's recommendation).
An agent has no colleague across the room; it navigates by grep. Names like handler, data, and process return fifty matches and force fifty reads. A unique feature name resolves in one. If a table is named work, a human can ask what it is for. The agent cannot.
6. Agent-proof your errors, CLIs, and docs
Rewrite errors to state cause and remedy, give every tool a non-interactive path with honest exit codes, and serve docs as plain markdown.
An error message is effectively a prompt; a bad one is paid for in tokens and wrong turns. Ronacher's rule: internal tools must survive "an LLM chaos monkey using them completely wrong." His process manager failed silently when a service was already running, so agents kept relaunching services on new ports. Harnesses run without a TTY, so an interactive wizard hangs until the timeout. On docs, Sentry goes furthest: it returns markdown to any request with an Accept: text/markdown header, on the theory that such a request is always an agent.
7. Read your agent transcripts
Read your last five sessions end to end and write down every place the agent stalled, guessed, or retried. That is your backlog, and it tells you which of the fixes above your repo actually needs.
Agents keep a diary: every session is on disk as a transcript, tool call by tool call. The wrong test command tried three times. The convention explained in eleven separate sessions. The afternoon spent grepping for a component named something else. Each one is a usability finding from your codebase's heaviest user. DX put it well: humans need surveys to surface friction, but "agents have full visibility into their own context." This is what Blume automates: it watches sessions locally, finds the friction that repeats, and proposes the instruction, skill, or hook that stops it. You decide what lands.
The one-hour AX audit
Paste this into your issue tracker:
- [ ] Read the last 5 agent transcripts; note every stall, guess, and retry
- [ ] Time a targeted test + typecheck; record the number
- [ ] List every test that failed intermittently this month; quarantine them
- [ ] Grep your worst generic name; count the matches
- [ ] Rewrite the error message that most recently sent an agent in circles
- [ ] Delete every AGENTS.md line whose removal would cause no mistakes
- [ ] Pick the correction you have typed 3+ times; make it a hook or CI gateWhy this works
The skeptic's evidence is real: METR found experienced developers 19 percent slower with early-2025 agents while believing they were faster, and two thirds of developers tell Stack Overflow their top frustration is "almost right" output. But the same class of models sits behind those results and behind Anthropic's 80 percent. The difference is the environment. Fast tests, honest errors, unique names, one source of truth: we used to call this good engineering. Humans compensate for its absence with tribal knowledge; agents just burn money against it, and they leave a written record of every rough edge. Agent experience is good engineering with the tolerance removed.
FAQ: agent experience
What is agent experience (AX)?
The experience an AI agent has when using a product, platform, or codebase on behalf of a human. Coined by Netlify CEO Mathias Biilmann in January 2025. For development teams it means the ergonomics of a repository for coding agents: verification loops, feedback speed, context files, and tooling that works without a human present.
Does AGENTS.md improve code quality?
Not directly. The only controlled study found 28.6 percent faster runs and 16.6 percent fewer tokens, with quality unchanged. Context buys efficiency; correctness comes from reliable tests, typecheckers, linters, and CI gates.
Where should I start improving my coding agent setup?
Read your recent agent transcripts and fix what they show agents hitting most. In most codebases that is flaky tests first and feedback-loop speed second. Tools like Blume automate the reading by watching sessions locally and proposing the fixes that would stop the friction from repeating.