AI coding needs better specifications, not less architecture

There is a useful discussion on X right now about GitHub’s spec-kit, specification-driven development and the idea that AI tools should execute specifications rather than just respond to vague prompts.

That may sound like a tooling debate. It is not.

For founders, product owners and CTOs, the important point is much simpler: AI-supported software development does not remove the need for product judgement and architecture. It makes them more important.

When writing code becomes faster, unclear intent becomes more expensive.

The bottleneck moves. It is no longer only “can someone implement this feature?” It becomes “do we know exactly what should be built, why it matters, what must not break, which trade-offs are acceptable and how we will know that the result is good?”

That is where serious AI delivery starts.

The lesson behind the trend

The last wave of AI coding enthusiasm was about speed.

A person could describe an app in natural language, watch an agent create files, fix errors, add authentication, connect a database and deploy a working prototype. For early exploration, that is genuinely useful. It lowers the cost of trying ideas. It helps teams see a product shape before they commit months of budget.

But speed also creates a trap.

If the prompt is vague, the code will still be produced. If the business rule is missing, the agent will infer one. If the security requirement is not stated, the tool may choose the simplest path. If the architecture is unclear, the implementation can still look impressive in a browser.

The visible result arrives quickly.

The hidden decisions arrive with it.

That is why the current discussion around specification-driven development matters. The useful part is not any single tool or command set. The useful part is the shift in thinking: before an AI agent writes code, the team needs a clear contract for what the software is supposed to do.

”Vibe coding” is not the operating model

Vibe coding is a fine way to explore.

It is not a complete operating model for a serious product.

There is nothing wrong with using AI to sketch an interface, test a workflow or build a throwaway prototype. In fact, it can be a very good use of AI. The mistake is treating that first working version as if it has already passed the disciplines that production software needs.

A prototype answers one question:

Can this idea be made visible quickly?

A product has to answer different questions:

• Does it solve the right customer problem?
• Does the workflow match how people actually work?
• Is the data model still sensible when the business grows?
• Are permissions and roles explicit?
• Can the system be tested, operated and changed?
• Can another developer understand it six months later?
• What happens when an edge case appears in production?

AI can help with all of this. But only if the team gives it a better target than “build this app”.

The specification is where product judgement lives

A good specification is not a bureaucratic document written to satisfy a process.

It is where important product and business decisions become explicit.

For AI-supported development, a useful spec should describe the intent of the system before it describes the implementation. It should make the business outcome, users, workflows, constraints and acceptance criteria clear enough that a human or an agent can reason about them.

For example, instead of asking an agent to “build a customer portal”, the team should be able to express:

• who the users are;
• which jobs they need to complete;
• which data they can see;
• which data they must never see;
• which workflows need approval;
• which parts must be auditable;
• which integrations are required;
• what success looks like;
• which trade-offs are allowed for the first version.

This is not about writing longer prompts.

It is about reducing ambiguity before ambiguity becomes software.

Separate the product spec from the technical plan

One practical discipline matters a lot: keep the “what” separate from the “how” until both have been considered properly.

The product specification should explain what the software must achieve and why. It should not prematurely decide every technical detail.

The technical plan should then translate that intent into architecture:

• data model;
• API boundaries;
• frontend structure;
• authentication and authorization;
• integration strategy;
• deployment model;
• testing approach;
• observability;
• operational ownership.

AI agents often blur these layers. A prompt asks for a feature, and the agent immediately chooses libraries, database shapes, folder structures and API conventions. Sometimes that is fine for a prototype. In a real product, those choices carry cost.

The wrong data model can slow down every future feature. The wrong authorization approach can become a security problem. The wrong integration boundary can make operations painful. The wrong test strategy can make fast delivery fragile.

Architecture is not ceremony. It is how a business keeps options open.

Acceptance criteria should become executable

The strongest form of specification is one the team can test.

This is where AI-supported development becomes genuinely powerful. If the desired behaviour is clear, an agent can help generate tests, implementation tasks, edge-case lists and review checklists. It can compare code against the intended behaviour. It can help find gaps between what was specified and what was built.

But that only works when acceptance criteria are concrete.

Weak acceptance criteria sound like this:

• “The dashboard should be user friendly.”
• “The import should handle errors.”
• “Admins should be able to manage customers.”

Better acceptance criteria sound like this:

• “A user with the finance role can export invoices for their own company only.”
• “If a CSV row fails validation, the import continues, stores the rejected row and shows the reason.”
• “An admin can deactivate a customer account, but the action requires confirmation and is written to the audit log.”

Those statements are not just clearer for humans. They are much better input for AI agents.

They can become tests. They can become implementation tasks. They can become review criteria. They can become the difference between a convincing demo and a reliable system.

Specs are not fixed forever

A common objection is that specifications feel too rigid for modern product work.

That is a fair concern if the spec is treated as a frozen document.

But in AI-supported development, the better pattern is a living specification. It changes as the team learns, but it changes deliberately. When a decision changes, the spec changes. When the architecture changes, the reasoning is recorded. When a feature is cut, the non-goal is made explicit.

This matters because AI tools are good at continuing from context.

If the context is messy, stale or contradictory, the agent will inherit that mess. If the project has a clear product spec, current architecture notes and explicit constraints, the agent has a much better chance of producing useful work.

The spec becomes shared memory for the team and the tools.

That is especially valuable in small companies and Mittelstand environments, where knowledge often lives in a few people’s heads. AI can accelerate delivery, but it cannot safely infer every commercial, operational and compliance constraint from a short prompt.

What this changes for founders

For founders, the practical lesson is not “stop using AI tools”.

The lesson is: use AI to move faster, but do not outsource product clarity.

Before asking an AI tool to build the next version, answer a few uncomfortable questions:

• What is the smallest business outcome this release must achieve?
• Which users and workflows are in scope?
• Which workflows are explicitly out of scope?
• What data will the system touch?
• What would create legal, operational or reputational risk?
• Which decisions can be changed later, and which will be expensive?
• What must be true before real customers use it?

This does not need to become a heavy enterprise process. A focused two-page specification can be enough for an early product. The important thing is that the team makes the decisions before the implementation makes them accidentally.

What this changes for CTOs and product owners

For technical leaders, AI coding shifts the review burden.

The question is not only whether the code compiles. The question is whether the implementation matches the product intent and architecture.

That means review should include:

• Does the code satisfy the stated acceptance criteria?
• Did the agent introduce hidden business rules?
• Did it choose a data model that supports future changes?
• Are permissions explicit and testable?
• Are errors handled in a way operations can support?
• Did the implementation create coupling that will slow the next release?
• Are the generated tests meaningful, or just coverage theatre?

This is where architecture-first delivery pays off. The clearer the target, the easier it is to use AI without letting the system drift.

The McDougall Digital view

At McDougall Digital, this is the practical middle ground we care about.

AI can make software delivery faster. It can help generate code, explore options, test edge cases and reduce repetitive work. But serious products still need product judgement, architecture, maintainability, security and operations.

The winning workflow is not “human writes everything” or “AI decides everything”.

It is a structured collaboration:

• humans define intent, constraints and trade-offs;
• AI helps turn that intent into implementation options;
• architecture keeps the system coherent;
• tests and reviews make quality visible;
• operations make the result supportable.

That is the difference between an impressive prototype and software a business can rely on.

How we can help

If you are building with AI coding tools, the most useful next step is often not another prompt. It is a clearer delivery frame.

McDougall Digital helps founders, product owners and technical teams turn AI-assisted work into maintainable software. That can mean shaping a product specification, reviewing an AI-built prototype, defining the architecture for a serious first version, hardening permissions and data flows, or setting up a delivery process where AI accelerates the team without quietly creating long-term debt.

The current X discussion around spec-driven development is timely, but the underlying point will last.

When implementation gets faster, the value moves upstream.

The teams that benefit most from AI will not be the ones that prompt the most. They will be the ones that know what should be built, why it matters and what quality has to mean before the code appears.