We were in UAT for a React checkout rebuild when someone said the thing that still haunts me. "Well, that's how it used to work, so we assumed it would continue to work that way." This was a completely new project. New codebase. New architecture. The new specs never defined that behavior, but the assumption felt so reasonable to them that nobody thought to ask.
The project was evergreen. Fresh repository, blank slate, no inherited patterns to fall back on. The kind of greenfield project that feels liberating until you realize you're building without guardrails.
We'd spent months on the React frontend. Defined the interfaces. Built the components. Handled the edge cases we knew about. Then UAT started, and the gaps revealed themselves one by one. Not technical failures. Specification failures. Behaviors that existed in the old system that nobody thought to document because everyone assumed they'd carry over.
Not technical failures. Specification failures.
The phrase that still scares me: "That's how it used to work, so we assumed..." It wasn't irrational. From their perspective, it was practical. Why wouldn't it work that way? Except it was a completely new project, and that behavior was never in the spec. We never built it because we never knew it was expected.
Looking back, the problem wasn't communication volume. It was contract clarity. We had meetings. We had tickets. We had documentation. What we didn't have was an explicit agreement about what "done" actually meant before we started building.
The Syntax Illusion
Every junior engineer thinks the job is the syntax. The semicolons. The function names. The clever abstraction.
Every senior engineer who's been promoted twice knows better. The job is the conversation in the room three weeks before the syntax. The translation of ambiguity into specification. The pushback when the requirement doesn't match the system.
I've shipped enterprise commerce platforms for over a decade. The expensive problems were never missing semicolons. They were assumptions that looked like requirements, requirements that shifted between meetings, behaviors that "everyone knew" except the people building the system.
The expensive problems were never missing semicolons. They were assumptions that looked like requirements.
The keyboard work was always the easy part. It just looked hard because we spent so much time doing it.
The Learning
After that UAT, we had to build differently. Not more documentation. Clearer contracts.
We started defining contracts at every phase. Interface agreements before implementation. Acceptance criteria that didn't depend on interpretation. What "done" looked like, written down, agreed upon.
This led to spec-driven development. Not as bureaucracy. As survival. When the spec is clear, the code writes itself. When the spec is ambiguous, every engineer invents their own version of the truth, and every stakeholder assumes the old rules still apply.
When the spec is clear, the code writes itself.
The same contracts that helped us communicate with each other turned out to help with AI. The machine can't infer what you meant. It can only build what you specified. Ambiguity that creates human confusion creates machine confusion too. Clarity that prevents human error prevents machine error.
What AI Changes
Now everyone is panicking that AI writes the code. They're panicking about the wrong thing.
AI is brilliant at the thing engineers always claimed was hard. It's terrible at the thing engineers always pretended was easy.
It cannot sit in a meeting with a VP of Merchandising and ask the follow-up question that reveals the assumption nobody voiced. It cannot push back when the requirement contradicts the system the team next door just shipped. It cannot tell you that the acceptance criteria you just wrote contains a gap that will surface in UAT.
AI is brilliant at the thing engineers claimed was hard. It's terrible at the thing engineers pretended was easy.
The engineers who built their identity around being the smartest person in the room with a keyboard are discovering that wasn't actually the moat. The ones who learned how to translate ambiguity into specification just had their value compounded.
The New Divide
There are two kinds of engineers now. Those who can write specs that make AI productive. And those who can't.
The first group is shipping faster than ever. They describe the architecture, the constraints, the edge cases. AI generates the implementation. They review, redirect, refine. The bottleneck moved from their fingers to their judgment.
The second group is still fighting the same battles. Assumptions that surface in UAT. Requirements that shift between meetings. Code that does what was asked but not what was needed. They have the same problems, just with a faster typing assistant.
The bottleneck moved from their fingers to their judgment.
The Specification Skill
Writing clear requirements is a skill. Like any skill, it can be learned. Like any skill, most people don't bother.
It starts with explicit contracts. What goes in. What comes out. What happens at the edges. Not "handle errors gracefully." "Return 400 for missing fields, 409 for conflicts, 500 for downstream failures."
It continues with behavioral specifications. Not "fast." "P95 under 200ms, tested at expected peak load."
It ends with context that doesn't fit in tickets. The dependency on the team next door. The constraint from the legacy system. The stakeholder who needs to sign off but doesn't attend standups.
Writing clear requirements is a skill. Like any skill, it can be learned.
This is the work that matters now. The translation layer between human intent and machine execution. AI eliminated the transcription tax. It didn't eliminate the thinking tax.
The Reveal
The engineers who will dominate this transition aren't the ones who code faster. They're the ones who specify clearer.
They learned something years ago that the industry is just discovering. The keyboard was never the hard part. It was just the part we could see.
Now everyone gets to find out.
One email a week from The Builder's Leader. The frameworks, the blind spots, and the conversations most leaders avoid. Subscribe for free.
Top comments (0)