What We Set Out to Build
In early 2024, we were building automation pipelines fast. Too fast. The pattern was always the same: a new requirement would come in, someone would open a chat window with an LLM, start typing, and within twenty minutes we had code. It felt productive. It was not.
The problem surfaced when we started tracking how much of that code actually survived into production unchanged. The answer was uncomfortable. We were spending the majority of our iteration cycles not on the original build, but on fixing outputs that almost worked. The LLM had answered the question we typed, not the problem we actually had. Those are different things, and the gap between them is where time disappears.
According to McKinsey's The State of AI in 2024, organizations are increasingly moving beyond ad-hoc experimentation toward more deliberate design and planning phases before AI deployment. We were living on the wrong side of that shift. This article is about what we changed, what broke when we changed it, and what we'd do differently now.
What Happened When We Jumped Straight Into Prompting
The failure mode is specific and repeatable. You open a chat interface, describe what you want in natural language, and receive something that looks correct. You paste it into your project. It runs. Then, three hours later, you discover it handles edge cases incorrectly, the output format doesn't match what the next step in your pipeline expects, or the logic is subtly wrong in a way that only surfaces under real data.
You go back to the LLM. You describe the problem. You get a fix. The fix introduces a new issue. This loop is not a failure of the AI tool. It is a failure of the process. You handed the model an underspecified problem and it gave you a fully specified answer to that underspecified problem. That is exactly what it should do.
We hit this wall hard while building a classifier component. I spent a week trying to get the model to output exactly 3 sentences per classification. The prompt said "EXACTLY 3 sentences. Not 2, not 4. Three." It still wrote 4. My instinct was to keep refining the instruction. That instinct was wrong. The fix wasn't better phrasing. It was reframing the constraint as a system-level enforcement rule: "CRITICAL: This is a hard technical constraint enforced by automated validation. If you write 4 sentences, the output will be rejected. Count your sentences before outputting." That worked. LLMs do not treat polite instructions the same as system constraints. Every automation we now ship uses emphatic constraint blocks for any hard output requirement, not because it sounds more authoritative, but because it changes how the model weights the instruction during generation.
The deeper lesson from that week: we were treating the LLM as a mind-reader rather than a specification executor. The prompt-first approach invites this mistake because you start with the tool before you've fully defined the problem.
The Design-First Shift: What It Actually Means
Design-first is not a philosophy. It is a specific sequence of steps that you do before you open a chat window.
Step one: write down the inputs and outputs of the thing you're building. Not in code. In plain language. "This component receives a JSON object containing a Jira ticket title and description. It outputs a risk score between 1 and 5 and a one-sentence rationale." That's a specification. It takes five minutes to write and it eliminates an entire category of LLM output failures.
Step two: identify the constraints before you prompt. What format must the output be in? What happens if the input is malformed? Are there length limits? Are there values the output must never contain? Write these down as a list. When you eventually write your system prompt, these become your constraint blocks, not polite suggestions buried in a paragraph.
Step three: sketch the pipeline before building any node. If you're building a multi-step automation, draw the data flow. What does step one produce? Does step two actually need all of that, or just part of it? Where does branching logic live? This sketch takes ten minutes and routinely surfaces integration problems that would otherwise appear as bugs two days into the build.
Step four: only now do you open the chat window. At this point, your prompt is not "build me a classifier." It is "here are the inputs, here are the outputs, here are the constraints, here is the format. Build the function that connects them." The model has a fully specified problem. It gives you a fully specified answer. Iteration drops sharply.
This is what ForgeWorkflows calls agentic logic when it's applied across multi-node pipelines: each component knows its contract before it's built, and the connections between components are designed before any single component is coded. The result is that components actually fit together on the first attempt, rather than requiring adapter layers and format-conversion hacks after the fact.
If you want to see this applied to a real project, our token optimization playbook walks through how pre-specifying output contracts reduced unnecessary token usage in a live pipeline.
Where This Approach Breaks Down
Design-first is not universally superior. It has a real cost: upfront time. For exploratory work, where you genuinely don't know what the output should look like yet, forcing a specification too early produces a bad specification. You end up building to the wrong contract and then redesigning anyway.
The approach works best when the problem is well-understood but the implementation is complex. It works poorly when you're in discovery mode, trying to figure out whether a thing is even possible. In those cases, prompt-first exploration is the right tool. The mistake is staying in exploration mode after you've found your answer. That's when you need to stop, write the spec, and then build.
There's also a team coordination cost. Design-first requires that someone owns the specification before anyone starts building. In solo projects, that's straightforward. In teams, it requires a brief alignment step that some developers resist because it feels like overhead. It isn't overhead. It's the work that prevents rework. But you will have to make that argument explicitly, because the instinct to start building immediately is strong.
Our piece on why AI tools feel hard for DevOps engineers covers a related version of this problem: the tooling is often fine, but the process around it hasn't matured to match.
Applying This to Real Automation Builds
The clearest place we've seen design-first pay off is in sprint planning and project risk tooling. These pipelines involve multiple data sources, conditional logic, and outputs that feed into human decision-making. Getting the output format wrong doesn't just produce a bug. It produces a misleading signal that someone acts on.
When we built the Jira Sprint Risk Analyzer, we spent the first session writing nothing but contracts. What does a "risk signal" mean in this context? What fields does it require? What's the difference between a risk score of 3 and a risk score of 4, and can we define that difference precisely enough that an LLM will apply it consistently? Only after those questions had written answers did we write a single node. The setup guide walks through how those contracts translate into the actual pipeline configuration.
The design phase for that build took roughly half a day. The build itself took less time than comparable pipelines we'd built prompt-first, and the output required no post-processing corrections. That's the trade: invest time at the front, recover it in the middle.
As of mid-2026, the tooling landscape has matured enough that this approach is practical without significant friction. Most LLM APIs support system prompts with enough token budget to include full constraint blocks. Orchestration tools like n8n make it straightforward to define node contracts visually before wiring them together. The infrastructure for design-first development exists. The bottleneck is process, not tooling.
For teams doing a broader audit of their AI build process, the AI tech stack audit framework is a useful companion. It covers how to evaluate whether your current toolchain actually supports the workflow you're trying to run, which is a prerequisite for design-first to work at the team level.
What We'd Do Differently
Start every new build with a one-page spec, even for small components. We resisted this for months because it felt like bureaucracy on small tasks. It isn't. A one-page spec for a small component takes fifteen minutes and eliminates the most common failure mode: building the right thing for the wrong problem. We'd make this the first deliverable on any AI-assisted build, not an optional step.
Treat constraint language as a first-class engineering concern, not a prompting trick. The classifier incident I described above cost a week. The fix was a single reframing of how we wrote constraints. We'd now build a constraint template into every system prompt from day one, with emphatic language for any hard output requirement. This isn't about being aggressive with the model. It's about understanding that instruction weight matters, and vague politeness doesn't carry the same weight as explicit enforcement framing.
Build a library of your own output contracts before you need them. The most expensive part of design-first is the first time you do it for a new output type. Once you've defined what a "risk signal" or a "classification result" or a "summary block" looks like in your system, that definition is reusable. We'd invest earlier in maintaining a shared contract library so that new pipelines start from proven formats rather than reinventing them. That library is what turns a methodology into a repeatable process, which is the actual goal.
