May 8, 2025

AI Is Not Your CTO, It Needs Instructions

Technical guide

Software development is entering a strange new phase, one where we don’t just write code, we collaborate with machines to produce it.

AI now contributes to over a quarter of Google’s codebase.

At Y Combinator, some startups report AI writes 95% of their code (a little optimistic if you ask me).

And Anthropic forecasts that virtual employees could become real within the year.

Software development is experiencing its own kind of industrial revolution—not powered by steam, but by prompts and chats.

This transformation raises a crucial question: How should we work with AI to build software effectively?

We’ve grown comfortable with the chat interface, it feels intuitive, even natural. But conversation isn’t how we design software: we rather write specs, or collaborate on engineering projects. Chatting has its place (when checking status or discuss changes), but when clarity, consistency, and coordination matter, it quickly becomes a liability.

Chats are hard to follow both for humans and AI because context gets quickly scattered. As requirements evolve, the thread becomes a tangle of  half-formed ideas and outdated assumptions, and even contradicting updates. On top of that, we tend to be vague or lazy in chat. It’s human nature: we conserve effort, skip details, and assume too much. This is part of why “vibe coding” has taken hold: a pattern where we toss casual prompts at an AI and hope it fills in the gaps we didn’t articulate.

The Rise of "Vibe Coding"

Welcome to what is now called "Vibe Coding”: this emerging practice where users (typically developers) provide minimal direction and expect AI to somehow capture their unspoken intentions without even checking the produced code.

You've probably experienced the following scenario with tools like Lovable or Bolt: you describe what you want to an AI assistant, it generates code, you accept whatever they produced, but the result doesn't quite match your vision. Then you start to chat your way through what you have in mind only to give up at some point because the AI is diverging from your idea and cannot fix the issues it's facing.

As an example, imagine we want to build an email auto-responder for our software team. A typical prompt might be: "Write an email auto-reply for the software team. It should include updates from the latest PRs."  

At first glance, it sounds straightforward—but it’s packed with ambiguity:

  • "Auto-reply" — Should the AI send the email automatically, or just draft it for review?
  • "Include updates" — What kind of updates? A summary? A changelog? Just titles?
  • "Latest PRs" — How many? The last two? Since the last email? Merged or open PRs?
  • "Software team" — Which team members? All of them? Are there rules about tone or formatting?

For quick prototypes, weekend projects or simple features, vibe-codings works and can feel magical. But as projects grow more complex, serious issues emerge:

  • Context overload: The AI loses track of your original intent as conversations grow longer
  • Codebase confusion: The code becomes increasingly difficult to understand and maintain
  • Documentation scatter: Requirements are buried in chat history instead of clearly documented
  • Assumption misalignment: The AI fills gaps with assumptions that don't match your vision without making them explicit in the chat
Vibe coding is not a formal development methodology, but rather the expensive art of discovering requirements through trial and error instead of documenting them upfront.

Learning from Software History

Long before AI entered the scene, software teams ran into the same communication problems. Their solution? **Product Requirements Documents (PRDs)**, a structured documentation that clearly outlines what needs to be built and why.

PRDs aren't just paperwork; they're thinking tools that force you to:

  • They clarify your intent  
  • Reveal hidden assumptions  
  • Fill in knowledge gaps  
  • Force explicit decisions  

That same need for structure hasn’t gone away. In fact, it’s more important than ever. As AI becomes a collaborator in the coding process (and not being as up to date with your company as experienced developers), the risk of miscommunication grows. Without clear requirements, AI tools can only guess at your intent drawing for the extensive training data they have seen, often amplifying ambiguity instead of resolving it. Just like before, structured thinking remains the foundation of reliable software.

A Better Approach: Specification-to-Code with AI

Rather than surrendering to the limitations of unstructured Vibe Coding, there's a better way to collaborate with AI: PRD-to-Code.

Here’s how it works:

  1. Start with your idea: begin with a high-level concept
  2. Collaborate with AI on a PRD: use natural language to co-author structured requirements
  3. Refine the PRD: work through edge cases, requirements, user stories and specifications before writing any code
  4. Implement based on clear specifications: let the AI write code based on your finalized PRD document

This approach yields significant benefits for both technical and non-technical stakeholders:

  • For developers: clearer specifications lead to more accurate implementations and fewer rewrites
  • For non-technical: More predictable outcomes and product quality

But what if we could leverage "vibing" in a different way, one that plays to its strengths while avoiding the pitfalls of ambiguity? Instead of using AI to jump straight into code, we use that same fluid, conversational style to co-develop the specs. It’s still fast and intuitive, but now it’s directed toward discovering/refining ideas, surfacing edge cases, and aligning on intent—before a single line of code is written.

Vibing the Specifications

The core problem with vibe coding isn’t the chat interface, it’s the gap between how loosely we describe what we want, and how precisely code needs to be. Prompts are fuzzy; code is exact. That mismatch leads to misunderstandings, rewrites, and unreliable systems.

But what if we could vibe the specs instead? Use natural conversation with an AI not to generate code directly, but to iteratively refine the product requirements—to shape a shared understanding before anything gets built. This approach keeps the speed and fluidity of vibe coding, but applies it where ambiguity is useful: in exploring ideas, surfacing edge cases, and clarifying intent.

Once the spec is solid, code generation becomes far more reliable. And while PRD-to-code may involve more upfront effort (and yes, a few more AI calls), it pays off quickly in reduced friction and higher-quality output. We call this **vibing the specs**.

User Stories: Bridging Technical and Business Concerns

A powerful element of modern PRDs is the user story – a simple description that captures who wants what and why. User stories can be written like this.

"When [how things start], the AI agent [action taken]. The [outcome] must [expected outcome]

User stories translate directly into testable scenarios that verify your AI implementation works as intended.

Imagine we are building a response automation agent

For our example email response automation agent:

When a user receives an email from a client requesting a project update, the AI agent retrieves summaries of the last two merged pull requests related to that project and drafts a reviewable email response in Gmail. The email must sound professional yet friendly tone and formatting the content with bullet points for clarity.

This structure creates a verification cycle that bridges technical implementation and business needs:

  1. You define user stories in your PRD
  2. The AI creates test cases based on these stories
  3. The AI tests the implementation against these cases
  4. The AI address any gaps between expectations and reality

Finding Your Sweet Spot

Vibe coding isn’t the enemy, it’s just not a foundation. Used at the right time, it’s a powerful tool for speed and iteration.

The rule of thumb is simple:

  • Use vibe coding for small, low-risk changes—especially if you’re a developer familiar with the codebase and can clearly articulate what needs to be done.
  • Use PRD-to-Code for building complex features, coordinating across teams, or when reliability and alignment really matter.

That doesn’t mean vibe coding has no place in code generation—it absolutely does. But for anything ambitious, interconnected, or critical to your product, structure and clarity win every time.

If you start with a vague prompt, you’ll end up debugging intentions. If you start with a strong spec, you’ll spend your time building.

Unlocking AI's Full Potential Through Structure

The PRD-to-Code approach transforms how we work with AI coding assistants. By creating clear, detailed specifications before implementation, we ensure AI builds exactly what’s needed—without the frustrating back-and-forth of vibe coding.

This methodology isn’t just about avoiding mistakes, it’s about helping AI do its best work. When given clear instructions, AI can focus on building, not guessing.

The beauty of PRD-to-Code lies in its flexibility:

  • Works across different AI platforms and tools
  • Scales from small features to full applications
  • Fits teams of any size, from solo builders to large organizations
  • Leaves behind useful documentation that stays valuable over time

And most importantly, it puts *you in control*.

Instead of relying on vague prompts and hoping the AI gets it right, you guide the process with clarity and intent.

Vibe coding promises speed but often delivers trial and error instead.

So next time you start a project with an AI assistant, don’t rush in. Take a few minutes to define what you want. That small effort upfront will save you hours later—and lead to better, more reliable results.

In AI development, as in traditional coding, clarity is how you move fast and build right.

Technical guide
Writen by
Pasquale Antonante
Like what you read? Share with a friend