Workflow

Adding design review to your agent: what the workflow looks like

How to add a design judgment step to Claude Code, Cursor, or any agent that builds UI. What to call, when to call it, how to read the response, and what the loop looks like across multiple builds.

Most agent workflows that build UI don't have a design review step. The agent builds, lints, type-checks, and opens a PR. Design feedback comes later — in a human review cycle that runs at human speed, after the code is already written and the layout is already embedded in the codebase.

Setup guides: Claude Code and Grok Build · Codex · Cursor. This note covers the workflow once it's installed.

Adding a design judgment step to the build loop changes when feedback arrives. Instead of catching a dashboard-for-a-deciding-job after the PR is open, you catch it before the agent finishes the first build. The cost of the fix drops significantly: the agent patches against structured feedback rather than a human reviewer's comments, and it can loop — score, patch, re-evaluate — until the fit is good.

Here's what that workflow looks like with TheDesignAgent.

The setup: one file in the repo

Adding TheDesignAgent to an existing project starts with a single call. The agent invokes the /ux or /visual MCP tool with the task description, the artifact (the UI code or a description of the UI being built), and optionally some codebase context. On the first call with no prior project context, discovery runs: the system infers the domain, personas, jobs, and day-shape from the input and returns a .thedesignagent file.

The agent commits that file to the repo root. Every subsequent call from any agent working on the repo — whether that's Claude Code, Cursor, or anything else — will pick up the project context automatically. Discovery doesn't re-run; the profile is there.

This is the only configuration step. There's no dashboard to set up, no schema to define, no settings to configure. The file is the config.

The call: when and what

The design review call fits naturally into the agent's build loop at the point where the agent has a working UI artifact to evaluate. This is typically after the first build is functional but before the PR is opened.

Task: build a review interface for [description]
→ Agent builds first version
→ Agent calls /ux: { task, artifact, project_id }
→ Receives: fit_score, patches[], flags[]
→ Agent applies patches
→ Agent calls /ux again: { task, updated_artifact, project_id }
→ Receives: higher score, remaining patches
→ Loop until fit or diminishing returns
→ Agent opens PR

The /ux call evaluates whether the layout serves the job. The /visual call evaluates whether the design is well-crafted. Most builds benefit from both. The order matters: structural problems (JTBD, cognitive load) should be addressed before visual ones, because fixing the structure changes what visual patches are relevant.

Reading the response

The response contains three things that drive the next action.

The fit score is a 0-100 number that tells you where the build is. It's directional — use it to understand the delta between calls, not to optimize toward 100. An 87 that came from 42 is a better signal than an 87 that's been at 86 for two calls.

The patches are the actionable output. They're ordered by priority — critical patches should be applied first because they often change what subsequent patches are even relevant. Each patch has a change (what to do) and a reason (why). The reason is important: it tells you whether the patch is addressing a structural problem or a visual one, which helps you understand whether the score will move significantly on the next call.

The flags are named anti-patterns. layout_fights_action means the layout structure is working against the job. high_extraneous_load means the interface is adding overhead the job doesn't require. Flags are diagnostic — they tell you the category of problem more quickly than reading the full patch list.

What the loop looks like

A typical first-build evaluation for a non-trivial UI returns a score in the 45-65 range and a set of three to six patches with two or three at critical or high priority. The agent applies all of them and calls again.

The second evaluation typically scores 20-35 points higher. The remaining patches shift toward medium and low priority — visual craft issues, accessibility refinements, edge cases in the interaction model. If the score is still below 75 after the second pass, the remaining gap is usually in one or two specific sub-scores, and the patches for those are the ones to focus on.

Three calls is a reasonable target for most builds: init (discovery + first score), patch pass (major structural and cognitive fixes), refinement (visual and accessibility). Beyond three calls, the marginal gain per loop typically drops into single digits, and the remaining work is better addressed in a human review.

Adding it to CLAUDE.md

If you want Claude Code to run the design review step automatically on UI builds — without being asked each time — add a hook to your project's CLAUDE.md:

When building or significantly modifying UI components, call the TheDesignAgent 
/ux MCP tool after the first working build and apply critical and high-priority 
patches before opening a PR. Use the project_id from .thedesignagent if it exists.

This makes the design review step part of the agent's standard workflow for UI work rather than something you have to remember to request. The agent knows when it's building UI (it's working on components, pages, layouts); the instruction tells it to add the quality gate at that point.

The result is a build loop that includes design judgment alongside the other quality checks already in the pipeline — not as an afterthought, but as a step in the workflow.