Agent experience is developer experience for agents

Some codebases let agents work well; others cause negative productivity. The difference is design. Embed domain knowledge in the code via AGENTS.md and comments on the what. Help agents find code with synonyms, consistent structure, and READMEs per folder. Keep files small since quality drops as context (see: context management is the dominant variable in agent quality and cost) fills.

The practices that help agents are the same ones that help humans: small focused modules, consistent naming, comprehensive tests, clear documentation. The difference is that agents benefit more from explicit structure because they lack the osmosis that humans pick up from being in the room. A README in every folder, a comment explaining the business rule behind a function, a test that documents an edge case: these are gifts to your future self that also happen to be exactly what the agent needs to work autonomously.