Most AI-assisted development goes wrong in the same place: the developer opens the chat before they have thought through what they are building. The prompt gets written first. The understanding comes later — if it comes at all.
This is not a failure of prompting skill. It is a failure of sequencing. The thinking that should happen before the AI gets involved is happening after, in response to AI output. The result is a system built on decisions made implicitly by the model rather than explicitly by the developer. That is the source of brittleness — not bad prompts, not a weak model, but missing upfront design work.
Workflow-first design is the discipline of thinking through human tasks before delegating to AI. Not all of it — requirements evolve, understanding deepens — but enough to know what you are asking for and how to evaluate what you get back. It is the difference between handing a task to a capable junior developer who has been properly onboarded and to one who has never seen the codebase and is guessing about everything.
Why prompts written first produce brittle systems
The standard failure mode has a name: prompt-fail-fix. Write a prompt, get an output, it fails, improve the prompt, get a different output, a different failure, improve the prompt again. The loop produces real improvements. Prompts do get better. But the corrections are always made at the wrong level.
When a prompt fails, the correct diagnosis is almost never "this prompt needs better wording." It is almost always "I didn't know what I wanted precisely enough before I delegated." The spec was missing, or underspecified, or it named what rather than defining it. Iterating on the prompt without reverting to that problem yields cleaner instructions that address the same design gap.
The brittleness emerges from a second mechanism: AI scope is bounded by the prompt. The
model optimizes against what it was told, not against your system. Without pre-delegation
work that defines where code belongs, what conventions exist, and which invariants must be
respected, the AI places things wherever it feels plausible. Ask it to add email
validation to a signup controller without telling it about the /validators
directory — it adds validation inline. Tests still pass. Six months later, the project
has two email validators with no authoritative one, three if you count the one a different
session added to the service layer. Nobody knows which is current.
That is a local optimization failure. Each individual change was locally correct. The system became globally incoherent because no one had defined the system boundaries before delegating.
A third mechanism: when you skip pre-delegation thinking, you are asking the AI to build something you do not yet understand yourself. The model fills that understanding gap with plausible defaults. Over time, the codebase reflects the AI's plausible defaults — not any coherent design concept — because no coherent design concept was ever established.
What workflow-first design means in practice
The principle is simple: complete the human thinking work before delegating. In practice, it operates at three levels of scale.
At the function level: spec and tests before the prompt
Before opening the chat for any non-trivial coding task, write a spec. Five questions are enough:
- What does this do? One sentence. If you cannot write it, the function does not yet exist.
- What are the inputs? Type, range, worst valid input.
- What does it return? Type, structure, special values — precision matters. "A dict-like object" gives the AI permission to invent.
- What can fail? Exception or return value?
- What are the constraints? Pure or impure? Dependencies? Performance?
This takes three to five minutes. By the time the answers are written down, you have resolved the edge cases, named the constraints, and made implicit design decisions explicit. The AI's output is then evaluable because you know what correct looks like — not because the spec constrained the model, but because writing it constrained your own thinking first.
Then write tests — before the prompt, before the AI sees the task. Keep them private. Tests written before delegation cannot be correlated with the AI's potential misunderstanding of the spec. They independently verify the contract. If you ask the AI to write tests for code that the AI just wrote, you have generated two artifacts from the same source. If there was a misunderstanding, both would be wrong in the same direction and would pass each other.
The spec defines what correct looks like. The tests verify it independently. Both are established before the AI gets involved.
At the session level: know where code belongs before you open the chat
Before starting a session — not inside it — decide:
- Which module does this belong in?
- Which layer? (Controller, service, validator, repository — not "wherever feels right.")
- Which existing conventions must this follow?
- What must not change?
These are architectural decisions. The AI cannot make them correctly because it does not
know your system. You can tell it in a prompt, but the per-prompt context expires with the
task. The right place for architectural decisions is a persistent context document — a
CLAUDE.md or AGENTS.md — that loads into every session
automatically.
CLAUDE.md is not magic memory. It is written-down senior knowledge: where
validation lives, which naming conventions apply, which patterns are deprecated, and what
the AI should never reach for in this project. Each rule in that document governs every
future session without being re-stated. It is onboarding that does not expire.
At the agentic level: plan beforehand
For longer autonomous tasks — work you hand off and leave running — the same principle scales up. Before handing a task to an agent, produce a plan: a structured description of what needs to happen, iterated with the agent until all decision points are resolved and the approach is clear.
The plan-first pattern inverts the interactive model. Interactive sessions keep the developer continuously present: every agent output is a prompt for re-engagement, every unexpected output requires redirection. Plan-first concentrates human work upfront in a planning phase, then releases the agent to autonomously implement. The developer's attention is required only at phase transitions — approving the plan and reviewing the result — not throughout.
Without a plan, the agent makes architectural decisions during implementation. Some will be wrong. They will surface late, at review time, after the implementation is complete. With a plan, the decisions are made during planning, when they are cheap to change.
The correction target principle
The most clarifying rule in workflow-first design: when output is wrong, the correction target is the spec, not the prompt.
This sounds obvious. In practice, the instinct is almost always to fix the prompt. The spec was missing, or the tests were written after, or the session-level conventions were not encoded anywhere — and the response to bad output is to add more words to the prompt.
That is the wrong level. If the output is wrong because the spec is vague, a
better-worded prompt cannot fix it. If the output puts code in the wrong layer because
the architectural conventions were never written down, a guardrail in one prompt cannot
fix a missing CLAUDE.md. The fix belongs at the level where the failure
actually occurred.
The correction target principle also governs the time investment: time spent improving a
prompt is dedicated to a single task. Time spent writing a spec, a CLAUDE.md
entry, or an independent test is spent on all future tasks. The compounding is
significant. Prompt improvements expire; system investments persist.
What workflow-first is not
Workflow-first design does not mean requirements are fixed before coding starts. That assumption — that you can fully specify the problem upfront before exploring the solution — is demonstrably false. Requirements co-evolve with the solution. Understanding develops during implementation. The spec at the start of a task is a hypothesis about what correct looks like, not a binding specification.
What workflow-first requires is only that the current hypothesis is explicit
before delegation. The spec is written, the tests are defined, the architectural decisions
are recorded — and they are updated as understanding evolves. When the implementation
reveals that the spec was wrong, you update the spec. When a convention changes, you
update CLAUDE.md. The artifacts are living documents, not frozen commitments.
This is the crucial distinction from the "specs-to-code" methodology, which treats the spec as complete and stable and lets AI translate it directly to implementation. That approach removes the developer from the discovery process. Workflow-first design keeps the developer as the thinker — using AI as an implementation accelerator within a process the developer controls.
The minimum investment
You do not need to redesign everything at once. Four changes, in order:
Write CLAUDE.md before the next session. Five to ten rules:
where things belong, what conventions exist, and what the AI should never do in this
project. One-time investment; governs every future session.
Write a spec before every delegation. Three to five minutes with the five questions. The spec is your thinking, not the AI's constraint.
Write tests before the AI sees the task. Independent, covering happy path, boundaries, and failure modes. The structural fix for the most dangerous failure mode: code that looks right but is wrong because the spec was imprecise.
Read the diff before accepting. Every changed line. "Do I understand what changed?" not "did it pass?" The goal is code you can defend, not just code that runs.
These four habits change what kind of failure you encounter. Not less failure — different failure. Fast, visible, correctable failure instead of structural, silent, compounding failure.
Workflow-first design is not a constraint on AI productivity. It is what makes AI productivity durable.