Agent experience

“Agent experience” (AX) is developer experience applied to coding agents: some codebases let agents work autonomously and well, others cause negative productivity. The difference is design, not luck.

• Embed domain knowledge in the code. AGENTS.md/CLAUDE.md, comments on the “what” not the “how”, domain-based names, and tests for corner cases.
• Code SEO. Agents navigate with find/grep/ls, so help them find code: synonyms, no duplicate file names, no abbreviations, a README per folder.
• Brevity. Quality drops as context management fills up, so split large files and remove dead code.
• Testability and conventions. TDD matters even more; boring tech and design patterns win because agents already know them.
• Guardrails. Hooks that refuse bad responses, CI that treats agent code as tainted, and mandatory human review (see code review with agents).

A recurring warning from the source: when agent output overwhelms your own cognition, quality drops sharply, so avoid parallel multi-agent swarms you can’t oversee. Rules files belong in the repo (see specs and planning), not in user-space memory.

Sources: 0013-marmelab-agent-experience.md

Edit wiki/agent-experience.md; see how we maintain the wiki.