Agent Experience — a field guide from practice

A teammate with no memory

Every morning a brilliant engineer joins your team. They type faster than anyone you've met, they've read more code than you ever will — and they remember nothing. Not yesterday's decisions, not the deploy ritual, not the one directory nobody is allowed to touch. Whatever they need to know, they must find in the next few minutes, inside your repository, or they will guess.

That is the working condition of every AI coding agent — Claude Code, Cursor, Codex, Copilot, aider. And it reframes a question most teams haven't asked yet: we spend enormous care on developer experience for humans; what is the experience of the agent?

Here's what makes this urgent rather than academic. It took the industry two decades to take DX seriously — linters, onboarding docs, one-command dev environments. AX is in year two, agents are already writing a meaningful share of the world's code, and the repos they work in were designed for readers who remember things. The gap between a repo that onboards an agent well and one that doesn't is now a productivity gap between you and everyone else.

Stop asking “how do I prompt better?” — that optimizes one conversation. Start asking “what does every agent session inherit from my repo?” — that optimizes all of them, forever.

Six months ago I started treating that question as an engineering problem. This post is what I can back with sources: the definitions, the handful of practices that survive adversarial fact-checking, the popular claims that don't — and a case study where I mined five weeks of my own Claude Code transcripts, distilled them into a workflow.md, and then used AX principles to refactor it.

What Agent Experience actually is

The term has a birthday. On January 28, 2025, Netlify CEO Mathias Biilmann published Introducing AX,¹ defining Agent Experience as “the holistic experience AI agents have when interacting with a product, platform, or system.” The community site that grew around it, agentexperience.ax,² decomposes that experience into three properties, and they make a surprisingly sharp checklist:

fig. 1 — every line of agent-facing docs should improve at least one of these; otherwise it's dead weight

The second framing worth keeping comes from Sean Grove of OpenAI, in his AI Engineer World's Fair 2025 talk.⁸ Watching teams prompt an agent, merge the generated code, and throw the prompt away, he observed:

“You shred the source and then very carefully version-control the binary.” — Sean Grove, AI Engineer World's Fair 2025

The prompt — the intent — was the real source. The practical consequence: the files that steer your agents (CLAUDE.md, AGENTS.md, a workflow.md) are not throwaway config. They are durable, git-versioned artifacts, and when a session goes well, the decisions that made it go well belong back in the file.

The constraint that governs everything

Almost every verified AX practice turns out to be downstream of a single fact: the context window is the scarcest resource in an agentic session, and model quality degrades as it fills.

This isn't vibes. Anthropic's official Claude Code guidance states it flatly — “LLM performance degrades as context fills… the context window is the most important resource to manage”³ — and Chroma's Context Rot study found the same pattern empirically across all eighteen production models it tested, with accuracy declining monotonically as input grows, long before the window is technically full.⁴

Now connect that to how steering files load. They are eager, startup-time injections: read once when the session starts, placed at the front of the context, paid on every session whether or not they're relevant to the task.⁶ Every always-loaded line competes with the code the agent is actually trying to hold in its head. A bloated rules file doesn't just waste tokens — it actively makes the agent worse at the task and worse at following the rules themselves.

Which is why the single most counter-intuitive finding in the vendor docs is this: bloat is a correctness bug. Anthropic again: if Claude keeps ignoring one of your rules, “the file is probably too long and the rule is getting lost.”³

When an agent disobeys a rule, almost everyone adds emphasis — bold it, repeat it, CAPS IT. The evidence says do the opposite: delete other rules. Disobedience is a symptom of crowding, not defiance.

Sit with that for a second, because it inverts a deep habit. Every ignored instruction you've ever "fixed" by shouting louder probably got fixed by coincidence — the real lever was always the total weight of everything else in the file.

Six practices that survived verification

I put the popular advice through an adversarial research pipeline (three independent skeptic votes per claim — more on the machinery in the case study). Of twenty-five candidate claims, nine survived. They merge into six practices you can apply today.

P1Keep the always-on file ruthlessly small

Anthropic best practices · Cursor rules docs^3,7

Focused, actionable, scoped rules; split anything big into composable files. Treat every ignored instruction as a signal to cut the file, not to emphasize the rule.

P2Pointers, not payloads

Anthropic engineering — context engineering⁵

Agents can fetch at runtime. auth flow: see docs/auth.md beats pasting the auth flow; verify with make test beats describing the test suite. Lightweight identifiers mirror how humans use bookmarks and indexes instead of memorizing corpuses — slightly slower per lookup, massively cheaper per session.

P3Layer context hierarchically

OpenAI Codex AGENTS.md guide⁶

Steering files merge root-to-cwd, and the file nearest the working directory wins (it appears last in the combined prompt). So: a minimal universal core, with module-specific conventions, build commands, and gotchas pushed into nested files that only load — or only dominate — where they apply.

P4Load conditionally — progressive disclosure

Cursor rules docs⁷

Cursor makes the pattern explicit with frontmatter: always-on rules, glob-attached rules, description-triggered rules, manual ones. Whatever your tool, emulate the shape: an always-on minimal core, with task-specific guidance in skills and scoped files that enter context only when the situation matches.

P5Know the loading mechanics of your tool

OpenAI Codex docs & issue tracker⁶

Steering files are read before any work begins and cached for the session — mid-session edits don't take effect until restart. Your file is effectively an extension of the system prompt. Budget it like one. (And re-check the mechanics occasionally; they are actively changing across tools.)

P6Version intent, not just output

Sean Grove, AI Engineer 2025⁸

When a session produces a great result, the diff is the least interesting artifact. Fold the effective decisions, constraints, and corrections back into the versioned steering file, so the next session — tomorrow's amnesiac genius — starts where this one ended.

fig. 2 — hierarchical + conditional loading (P3, P4): pay for context only where it earns its keep

The folklore that didn't survive

This part rarely makes it into blog posts, and it might be the most useful section here: 64% of the field's popular claims died under verification. Sixteen of twenty-five candidates were killed — mostly for overreach beyond what their sources actually say. AX is young enough that its conventional wisdom formed faster than its evidence. If you've seen these repeated as settled fact, treat them as open questions:

0–3

“Specs are a lossless format; the spec-writer is the programmer now.”Rhetoric from a great talk, not an established result.

0–3

“Context rot is universal and caused by n² attention.”Degradation is real and measured; this mechanistic formulation overreaches.

0–3

“Verification loops let agents iterate fully autonomously.”Feedback loops help; 'no human needed' is unsupported.

0–3

“Self-updating CLAUDE.md loops measurably improve later sessions.”Untested rather than false — nobody has published the measurement.

0–3

“AGENTS.md has a 32 KiB combined size cap.”Widely quoted, not in the docs. Don't build on it.

Two honest caveats about the survivors, too: the evidence base is dominated by first-party vendor documentation — authoritative on how the tools behave, potentially self-serving on how much it matters — and the field is young enough that loading mechanics change under your feet. Verify against current docs before hard-coding any of this.

Case study: teaching an agent how I work

Theory is cheap, so here is the whole loop, run on myself. I use Claude Code daily — at my day job on a production platform, and at night on side projects. Every session leaves a transcript on disk, and almost everyone treats those transcripts as exhaust. They're not.

Your agent transcripts are a behavioral dataset about you — every correction you've typed is a labeled training example of what you actually want. Nobody is mining them. Mine them.

Step 1 — Mine the transcripts

I pointed the agent at five weeks of its own history: 380 interactive sessions across 24 projects — about 1,600 human-typed messages. Six analyzer sub-agents ran in parallel, one per project group, each hunting for durable signals: how I phrase requests, what I approve without review, and — most valuable of all — every moment I pushed back. The rule: a pattern had to appear three or more times to count. One-offs were discarded.

fig. 3 — mining five weeks of transcripts; corrections were the richest ore

The corrections were gold. Four times in two weeks I'd told the agent the same thing when it updated a config file: replace the old entry, don't append a duplicate. More than once it claimed a fix that didn't survive a test in the running app. Twice it proposed a workaround when I had asked for a root cause. Each of those became one imperative line — “Replace config entries atomically.” “Verify fixes in the running app before claiming fixed.” “Never offer a workaround when asked for RCA.” — every rule traceable to an observed pattern, zero generic best practice. Version one: 95 lines, five sections.

Step 2 — Check it against the field

Then the question this post opened with: is a 95-line always-on file actually good AX? I ran a deep-research pipeline over the public literature — five parallel search angles, 24 sources fetched, 104 claims extracted, the top 25 each judged by three independent skeptic agents told to refute the claim and to default to refuted when uncertain.

fig. 4 — a 64% kill rate at verification: most of what the field repeats about itself doesn't hold up as stated

Step 3 — Refactor with what survived

The verdict on v1: good bones — short imperative rules, no prose, everything observed — but it violated P1 and P3. It was universal and always-on, while roughly half its lines only mattered inside specific repositories. Side-project sessions were paying, on every prompt, for the deploy rituals of repos they would never touch.

So it became an architecture instead of a file: a ~55-line always-on core (communication rules, autonomy boundaries, the hard “never” rules) with repo-specific conventions pushed down into per-repo files that load only there — untracked local files for shared team repositories, so my personal workflow never lands in anyone else's context. Payloads became pointers (P2): domain facts moved to memory files and per-repo docs the agent can open on demand. And the file now carries its own maintenance rule (P6): if an instruction here keeps getting ignored, shorten the file; fold durable lessons back in.

fig. 5 — the refactor: same knowledge, ~40% lighter on every session, stronger where it applies

The loop closes neatly: transcripts taught the file what to say; AX research taught it where to live. Both halves came from evidence, and the file now improves the very sessions that will generate the next round of evidence.

Do this yourself in an afternoon

Mine your own transcripts. Most agent CLIs keep session logs on disk (Claude Code: ~/.claude/projects/). Have the agent read a month of them and extract repeated signals — especially every correction you made. Require 3+ occurrences before anything becomes a rule.
Write the core file from evidence only. Short imperative rules, each traceable to an observed pattern. If you're inventing a rule the transcripts don't support, leave it out.
Split by scope. Universal behavior in the always-on core; repo conventions in per-repo files; rituals with steps in skills/commands that load on demand. Use untracked local files for personal rules in shared repos.
Convert payloads to pointers. Any pasted content the agent could fetch — replace with a path and one line of intent.
Adopt the deletion reflex. Ignored rule → shorten the file. Ruthlessly.
Close the loop. When a session goes unusually well or badly, fold the reason back into the file. It's source code for your working relationship — version it like source.

The whole thing — mining, confirmation, writing, research, refactor — took one evening of wall-clock time, with the agent doing the reading. The result is a file that makes every future session start warmer than the last. That's Agent Experience in one sentence: design for the teammate who forgets everything, and you end up with documentation, boundaries, and feedback loops that would have made your human team better anyway.

∞

Sources

Mathias Biilmann — Introducing AX: Why Agent Experience Matters, Jan 28, 2025
agentexperience.ax — community definition & resources
Anthropic — Claude Code best practices
Chroma Research — Context Rot: How Increasing Input Tokens Impacts LLM Performance, Jul 2025
Anthropic Engineering — Effective context engineering for AI agents, Sep 2025
OpenAI — Codex: AGENTS.md guide
Cursor — Rules documentation
Sean Grove — “The New Code”, AI Engineer World's Fair 2025

Method note: claims from these sources were verified by three independent skeptic agents each, instructed to refute and to default to “refuted” when uncertain. Only claims surviving at least 2 of 3 votes are presented as findings above; “corroboration-grade” marks numbers that appeared in verifier evidence but weren't independently confirmed.