Agent legibility
Also called Legibility, Ambient affordances
How easily an agent can find out what it needs by itself: names it can search for, errors that say what went wrong, logs it can query, an app it can start. Whatever an agent can't observe, it can only guess about.
Poor legibility is paid for in tokens and wrong guesses on every task. Most fixes are ordinary good engineering, with one twist: a name you can grep for now matters more, and code that assembles a name from pieces of text while it runs hides from search. Being findable saves reading, and so saves tokens.
“Make this debuggable without me. Add bun run dev:test, which boots the app on a free port with seed data and writes logs to .logs/app.jsonl, then show me you can find a failed request by searching that file. Replace routes built by string concatenation with literal names that rg can find.”