Directing agents
How a person steers an agent toward good UI — friction where judgment matters, a named concept instead of an adjective, one or two passes with a look between them, fixing the system rather than the screen, and a papercut pipeline that hands the agent evidence.
Raw markdown On GitHubreferences/meta/directing-agents.md
An agent reliably produces the average of what it has seen, so where the output lands depends on how it is steered. Spend judgment where your opinion changes the result: what to build, which direction to keep, and when to stop. Hand the agent work where your opinion adds nothing, such as research, summarising feedback or a known pattern with a lot of code.
Friction where your opinion matters
- Before building, get interrogated. For a new feature or flow, have the agent ask you questions, not propose answers, until the goal, the user and the "why" are written down. Skip this for research and summaries.
- Delegate known patterns; hand-tune the fabric. A command menu, a chart or a data grid is a pattern the agent knows: delegate it. Page layout, the type scale and spacing tweaks are often faster by hand, or with one precise prompt each.
Name it; don't describe the feeling
- "Make it smoother" leaves the agent guessing. "Origin from the trigger, 200ms, the strong ease-out, transform and opacity only" does not. Precise names are in design-vocabulary, and why they matter is in articulate-precisely.
- You don't need every number, only the concept: tabular figures, not "the numbers jump"; inner radius = outer − padding, not "the corners look off".
- A screenshot with arrows, or a link to an interface that does it right, often beats any word.
One or two passes, then look
Each pass is a bar the work must clear. Five at once give you a muddle that half-satisfies each. Run one or two, look at the screen, then run the next. The order for a screen is in stacking-chains ("Screen loop"). The whole-app pass before launch is the exception: ship crosses every cluster on purpose (ship-check).
Fix the system, not the screen
Probe the system with a one-sentence request for a real screen ("a dialog that publishes pending changes, using our components"). Every mistake in the result points at a hole:
| Mistake | Hole to patch |
|---|---|
| a raw hex or a one-off spacing value | a semantic token is missing or poorly named (color-token-tiers) |
an invented ghost or destructive variant | the variant union isn't closed or documented (component-api-design) |
a hand-rolled select instead of Select | the component has no "when to use" doc (design-system-docs) |
className overrides fixing spacing | an escape hatch is open (component-api-design) |
If you correct only the output, you fix one screen. Patch the hole and the next screen comes out right.
The papercut pipeline
Spot → document → delegate. Write the issue with the evidence: a screenshot with arrows, or for motion a recording scrubbed to the wrong frame together with the state at that frame. Name the cause if you know it, for example "the select renders in a portal, so the modal treats a click on it as outside". Then let the agent fix it while you keep working. It takes about two minutes to write up and saves a context switch.
Gotcha
When the agent keeps missing after two rounds, rephrasing a third time is the casino. Build a tool instead, either a generator or an inspector (build-a-tool). The opposite failure is real too: tooling up for a problem you hit once is procrastination with extra steps.
Sources
- Emil Kowalski's design-engineering practice, distilled by HKTITAN.
- Related: skill-router, prototype-picker, vibe-to-generator, review-format.
metaworkflowagentspromptingreview