A Convincing Diagram Can Still Describe Broken Code

Key takeaways

• When AI handles implementation, the IDE also needs to help people understand and review the design.
• A clear diagram does not establish that the underlying code works correctly.
• AI-written code and its explanation can share the same mistaken assumption.
• Design views become more useful when they connect directly to code, changes, and test results.

An AI agent can write a feature, explain its design, and be wrong in both places for exactly the same reason. That makes a polished explanation a tricky basis for approving a change. Whiteboard raises a useful question about the future of development tools: what should an interface show us before we trust the implementation?

The editor is only part of the job

An IDE without direct code editing sounds like a strange proposition. The editor has an obvious place at the center of the workflow when a developer is typing the implementation.

Hand that implementation to an agent, though, and the human’s immediate questions change.

Suppose you ask it to add login. A list of changed files tells you where work happened. It may tell you much less about where user information lives, where access checks run, or how a request moves through the system.

A design view could make those relationships easier to follow. Instead of reconstructing the architecture from individual files, you could start with the request path and investigate the relevant code.

The useful question is how well that view supports review. Removing the editor is a product choice. Helping someone make an informed approval decision is the job.

One box can hide a serious difference

Consider this diagram:

User request → Permission check → Data retrieval

Easy to read. Also compatible with several very different implementations.

The permission check might only establish that the user is logged in. It might verify that the requested document belongs to that user. It might perform the right check but fail to stop execution when access is denied.

All three can disappear inside the same tidy box.

Diagrams are readable because they leave things out. During code review, the omitted detail may be the part that determines whether the feature is safe to ship.

That makes the distinction between intended design and implemented behavior essential. A box labeled “Permission check” gives the reviewer somewhere to look. The implementation still has to show what gets checked and what happens when the check fails.

Agreement is not independent evidence

Now imagine the same AI writes the code and explains its architecture.

It assumes that any logged-in user should be allowed to read every document. The code checks login status. Its explanation says that document access is restricted to authenticated users.

The explanation accurately describes the code. Both still miss the requirement that users should only read their own documents.

This is the gap between authentication and authorization: knowing who someone is does not establish which resources they can access.

A consistency check between the explanation and the implementation would miss that mistake. The review has to return to the requirement and test the boundary directly. Can one user retrieve another user’s document?

An explanation can help a reviewer understand a decision. It cannot independently validate a decision built on the same faulty premise.

Every design claim needs a path to evidence

What I would want from a tool like this is a way to keep investigating after the diagram makes sense.

Three capabilities would matter:

• Follow a diagram element to the code that implements it.
• Compare versions to see changes in data flow or access rules.
• Inspect relevant tests and execution results beside the behavior being described.

Clicking “Unauthorized requests are blocked,” for example, should reveal the enforcement code and tests covering denied requests. Even a passing test needs context: which users, resources, and conditions did it exercise?

Open source adds another useful distinction. Being able to inspect the tool’s own code is valuable. Being able to trace a particular explanation to supporting evidence is valuable too. One does not automatically provide the other.

Whiteboard offers a starting point for thinking about how development environments can support human judgment as agents take on implementation. A useful diagram makes the code easier to question. Before approving the change, the reviewer still needs answers the implementation and tests can support.