Claude Code finishes a change. The project builds. The tests pass. You still do not know whether the screen works.
That gap matters most when the change touches UI, navigation, or app state. The compiler cannot see a label that wraps or a name that gets cut off. Tests rarely cover layout.
This article compares your options for solving this problem, lists what a good answer should provide, and shows what we saw when we tested some of them.
What to expect
Ways to validate agent-made changes.
How to make the agent hand back evidence you can look at and read before you review the diff.
Harnesses with built-in validation, such as Flowdeck.
What a good validation approach should provide
Before comparing options, it helps to know what you are asking validation to do. Whichever option you pick, six things make it worth having:
Tests that cover the change. The agent runs the smallest relevant tests and the repository checks, and makes sure the change is covered. If it is not, the agent adds a test.
Evidence you can look at. Screenshots, a recording, an assertion. Something you can open before you read a line of the diff.
Depth that fits the change. A copy edit does not need a second device. A layout change does.
An honest report. The summary says what the agent did and what it skipped, so you know where to spend your own time.
The same expectations every time. Across sessions, and across agents, without rewriting rules.
A cost-sensitive approach. More checking takes more tokens and more minutes, so the depth should grow with the risk of the change. You should choose that on purpose.
Depth deserves a closer look, because it is where most of the judgment lives. Validation is a ladder, and each rung costs more than the one below it. Stop as early as the change allows: a copy edit can stop at launch, while a layout change should climb to orientation and a second device. The table shows what the agent should run at each rung and what you should expect back.
Run | Expectation |
|---|---|
1. Focused tests and repository gates | The change is covered by tests that pass. If it is not covered, the agent adds a test or says so. |
2. Build | The project compiles for the saved target. |
3. Launch | The app starts and stays up. Copy edits and refactors can stop here. |
4. The changed flow, on screen | Screenshots of the affected flow or visible state, with before and after when that helps. |
5. Other states, such as empty or error | Evidence of the states the change could break. |
6. Appearance, such as dark mode | The same screen in light and dark appearance. |
7. Orientation and window size | The layout in each supported orientation or window size. |
8. A second device | The same check on a device with a meaningful difference, such as screen size or OS version. |
Your three options
Option 1: Trust the agent's report
This costs nothing to set up. You read the summary, skim the diff, and decide.
The risk is that a report is a claim. If the agent never opened the app, the summary may say the fix works anyway, or it may say honestly that it did not check. Either way, you are now the one who has to run the app.
In our baseline run with Claude Code (no user-level or project-level CLAUDE.md), we ran the prompt below:
Claude Code read the code, fixed a bug, built the project, and told us: "I didn't launch the app in a simulator, so I haven't seen the fix on screen." That is a good report. It is also a change nobody has seen running.
Trusting the agent means treating its summary as the proof. That is a fair bet when the report is honest, and ours was. But an honest report says what the agent did, not whether the change works.
Option 2: Write your own rules
You can add a validation section to CLAUDE.md: run the app, take screenshots, report what you saw. Anthropic describes where Claude Code reads these files in “How Claude remembers your project”.
This works. It also leaves you with upkeep. You write rules for each agent you use. You keep them current as the project changes. A rule in a file is an instruction the agent reads, and nothing checks that it followed it. If you use two agents, you maintain two sets.
An example would be adding this to our CLAUDE.md or prompt:
Writing your own rules works. In our run with the updated prompt, the agent opened the app after fixing a bug and took before-and-after screenshots. What the rules did not give us was a place for that evidence, or a way to say which simulator to use, so the agent chose one and left the screenshots in a temporary folder. The effort moves from checking the app to maintaining the rules, one set for each agent you use.
The problem with this approach is that we did not measure how well handwritten rules perform, so we make no claim about them beyond the cost of maintaining them.
Option 3: Using a harness with built-in validation
Flowdeck moves the validation rules out of prompts and files and into the harness that runs the agent, so every session comes back with a report of the same shape and you spend your time on the evidence. You set the depth in Settings > AI Workflows > Validation.
For example, we ran the exact same prompt:
You start from one of three presets, each tied to the rungs of the ladder we saw earlier:
Lean (rungs 1–3): tests, build and launch. It runs the app only when those cannot prove the behavior.
Balanced (default, rungs 1–4): adds the changed flow on screen, with visual evidence when it helps.
Thorough (rungs 1–8): adds other states, appearance, orientation and a second device, and returns a detailed matrix.
We used the Balanced preset and received the following report:
This time the agent opened the app. It found the bug, fixed it, and checked the result on the simulator. The table below explains the validation options that Flowdeck supports:
Option | What it provides | Values |
|---|---|---|
Run the app | The runtime checks the agent performs after the required tests and checks pass. | Only when necessary; Changed features; Extended checks (also related flows, edge cases, and repeat interactions) |
Screenshots | Still images as evidence of UI, layout, styling, copy, or an important visual state. | No screenshots; Only when necessary; Always |
Screen recordings | Video evidence when motion, timing, gestures, or a multi-step flow cannot be shown in a few screenshots. | No recordings; Only when necessary; Always |
Additional devices | Repeats the runtime checks on more simulators or devices than the saved target. | Saved target only; Only when necessary; Multiple targets |
Final report | How much detail the agent's final response carries. It does not change which checks run. | Brief; Standard; Detailed |
Flowdeck Studio
Make Claude Code validate its work
Flowdeck runs tests, validates changes in the simulator, and provides evidence before code review.
Start 14-day trial
Conclusion
As we have seen, the problem starts when the agent says it is done and you cannot tell whether the app works. Trusting the report costs little, but a report is a claim: Claude Code was honest that it never opened the app, and the change still arrived with nobody having seen it run.
Writing your own rules worked in our run, with before and after screenshots, but it leaves the upkeep to you. A harness with built-in validation, such as Flowdeck, brings tests, evidence, and a report with a known shape, without rules to maintain.
Validation does not replace review, but it gives review something concrete and functional to look at.
Q&A
Can I just put validation rules in CLAUDE.md?
Does agent validation replace my UI tests?
Should the agent that wrote the change be the one that validates it?
Further reading
#ai-agents
#claude-code
#codex
#comparison
#ios-development
