Article 5 of 12 · ARTHA Craft
The code was correct. The UI was complete. Even I could not use it.
There is a version of AI-assisted development that feels like collaboration.
You describe what you need. The agent interprets. It fills in the gaps, makes the calls, decides how things connect. It moves fast. It is confident. It produces something complete.
And for the first few weeks, that felt like exactly the right way to work.
Then I looked at what we had actually built.
The functionality was there. The code was correct. Every feature I had described had been implemented. But the interface, the thing a real user would sit in front of and try to use, was so technically oriented, so shaped by implementation logic rather than human logic, that even I struggled to navigate it the first few times.
Not because the agent had failed. Because I had given it the wrong brief.
The agent is an extraordinary executor. [1] Given a clear brief, it implements with speed and precision no human developer can match. Given an ambiguous brief, one that leaves design decisions open, it fills those gaps with its own judgment.
And its judgment is technical. Not wrong. Not careless. Technical.
When left to decide how something should look or flow, the agent defaults to what is architecturally logical. What is clean from an implementation perspective. What makes sense if you understand the system from the inside out.
The agent cannot simulate that perspective unless you give it that perspective. Explicitly. In the brief.
Before any coding session, before the agent writes a single line of implementation code, the planning is done. Separately. Deliberately. In a session whose only job is to think, not to build.
Two things happen in the planning session that never happened before:
First: design decisions are locked. Not left open for the agent to interpret. Every decision about how the feature should work, look, and feel: answered, documented, approved before a line of code is written.
Second: the UI is reviewed before the code exists. The interface is designed and mocked up as a visual artifact in a dedicated design step, and the architect reviews and approves it, or rejects it and asks for changes. Only after that approval does the go-ahead get given, and the approved design becomes an input to the brief, not something the coding agent invents while it builds. This single step eliminated an entire category of rework from every project I have run since.
The planning agent and the coding agent should not be the same session.
A planning session has a fundamentally different job than a coding session. Planning requires challenge, exploration, devil's advocacy, gap-surfacing. Coding requires precision and execution. The mindset that makes a great planning agent, curious, questioning, surface-every-gap, is actively unhelpful in a coding agent that needs to execute a locked brief without second-guessing it.
The Deep Thinker
Planning SessionA dedicated session whose only job is to analyse the requirement, challenge assumptions, explore design options, surface every gap, and propose the UI direction. It never writes implementation code. It produces the brief: a structured document capturing every decision made and every question resolved.
The Architect
YouReviews what the planning session produced. Makes the final calls. Locks the decisions. Approves the UI direction. Signs off on the brief. Only you give the go-ahead, and go-ahead means all decisions are locked, all questions are answered, all design choices have been made. Not mostly made. Completely made.
The Coding Agent
Execution SessionReceives the locked brief. Executes precisely. Makes no design decisions, because none remain to be made. Fills no gaps, because no gaps remain to be filled. Builds exactly what was designed. No more. No less. No interpretation required.
Three sessions. Three distinct jobs. No single session trying to think and build at the same time. This is not overhead. It is specialisation: the same principle that made human software teams better when architects were separated from developers.
❌ Asking
"Build me a user dashboard."
An invitation to invent. The agent fills every gap with its own judgment: technically coherent, potentially misaligned with what your user actually needs.
✅ Telling
"Build a user dashboard with these specific sections, this layout, this navigation pattern, these data points in this priority order, as approved in the mockup from the planning session."
A brief. The agent builds exactly what was designed. No more. No less. No interpretation required.
That gap, between asking and telling, is where most AI-assisted development goes wrong. And it goes wrong quietly, because the output looks complete. The code runs. The tests pass.