The most dangerous phrase in AI-assisted development is that a project builds and tests pass, yet the screen remains unverified. When Claude Code finishes a task, the compiler might be happy, but the user interface might still be broken. A recent deep-dive from Flowdeck Studio highlights the critical gap between code correctness and visual functionality, arguing that developers must implement structured validation harnesses to ensure agents actually see what they build.

The Validation Ladder

Flowdeck proposes a validation ladder where each rung costs more than the one below it. The baseline involves focused tests and repository gates, followed by a build. However, the article argues this is insufficient for UI work. Higher rungs require the agent to launch the app, capture screenshots of the changed flow, and verify edge states like empty views or dark mode. The top of the ladder includes checking orientation, window size, and running tests on a second device. This tiered approach ensures that validation depth scales with the risk of the change, preventing token waste on trivial copy edits while enforcing rigorous checks on complex layout adjustments.

The Problem With Self-Reported Success

In a baseline test, Claude Code fixed a bug and built the project but explicitly reported, "I didn't launch the app in a simulator, so I haven't seen the fix on screen." While this honesty is commendable, it shifts the burden of verification entirely to the human developer. Relying on the agent's summary is a bet that the report is accurate, but an honest report only confirms what the agent did, not whether the change actually works in a live environment.

Custom Rules vs. Built-In Harnesses

Developers can attempt to fix this by writing custom validation rules in CLAUDE.md, instructing the agent to take screenshots. In Flowdeck's testing, this approach yielded before-and-after images, but it introduced maintenance overhead. The agent chose arbitrary simulators and stored evidence in temporary folders, lacking a standardized location for review. Flowdeck argues that using a dedicated harness, which moves validation logic out of prompts and into the runtime, ensures consistent evidence collection and report formatting without requiring developers to maintain agent-specific rule sets. The harness offers presets like Lean, Balanced, and Thorough to control the depth of validation automatically.

Key Takeaways

  • Trusting an agent's self-report is risky for UI changes, as compilation does not equal visual correctness.
  • Custom CLAUDE.md rules can enforce screenshotting but create maintenance burdens and inconsistent evidence storage.
  • A structured validation ladder allows developers to scale testing depth based on change risk, from simple builds to multi-device checks.
  • Dedicated harnesses provide standardized, persistent evidence trails that are easier to review than ad-hoc agent outputs.

The Bottom Line

Stop treating code compilation as proof of functionality; use a structured validation harness to force agents to provide visual evidence before you ever open the diff.