Vibe coding won’t save you

In this guide, you'll learn how to:

1. Define the blueprint (project-constitution.md)
2. Write prompts that get results
3. Feed the AI only what it needs
4. Think, validate, and design with AI
5. Direct the AI inside your development tools
6. Maintain project clarity and continuity

You understand your domain deeply — whether it's product strategy, user experience, or business logic. What you may not do is write code. And that’s perfectly fine.

What doesn’t work is “vibe coding”—improvising as you go and hoping for the best. That path leads to confusion, wasted effort, and weak results. This playbook is here to help you lead with purpose, structure, and confidence—so you and your AI assistant can build products that stand the test of time.

Each section includes concise explanations and practical examples to help you steer the AI—without needing to write code yourself.

Project knowledge & management

Before you start working with AI, make sure the project has a solid foundation. This means clearly defining what you’re building, what you’re not building, and what the current focus is. The AI can only follow your direction if that direction exists. And is written down.

Here’s how to set that up.

Define the blueprint (project-constitution.md)

This is your master blueprint. It defines exactly what the project is — and is not. It helps the AI understand the purpose, scope, and rules, even if you’re not writing the code.

## 🧱 project-constitution.md

### 1. Project Goal & Purpose

**What to include:**
- A one-sentence summary of the product.
- A short paragraph about what the current development phase is trying to achieve.

### 2. Core Requirements

#### Functional Requirements
**What the product should do:**
- List user-facing functionality (e.g., playback, tempo controls, UI feedback).

#### Non-Functional Requirements
**What the product must be under the hood:**
- Accuracy, performance, reliability, maintainability, testability.

### 3. Architectural Overview

**What to include:**
- Tech stack: Languages, libraries, frameworks.
- File/folder structure: Show high-level layout.
- Component responsibilities: Clarify boundaries between UI, logic, and outputs.

### 4. Guiding Principles & Constraints

What to include:
	•	Philosophy behind the architecture (e.g., “engine drives state, UI reflects it”).
	•	Constraints (e.g., “no direct UI access to timing logic”).
	•	Code standards (TypeScript rules, testing expectations).

### 5. Key Design Decisions

What to include:
	•	Choices that define the system structure or approach.
	•	Deprecated components or previous systems.
	•	Justifications (optional but helpful).

### 6. Core Interfaces & Data Structures (High-Level)

What to include:
	•	Key data types used across the app.
	•	Interface contracts between components (methods, expected props).

### 7. Non-Goals (Out of Scope)

What to include:
	•	Features you deliberately are not building in this phase.
	•	Helps reduce scope creep and distraction.

### 8. Glossary

What to include:
	•	Project-specific terms and their definitions.

### 9. Usage with AI Assistant

What to include:
	•	Guidelines for referencing this document in your prompts.
	•	How to anchor tasks and reviews to specific sections.

Maintain this document alongside your source code. It is the project’s source of truth—treat it as both map and contract.

Here are a few key points to remember once you’ve created your Project Constitution:

1. Start small if you don’t have all the answers. It’s OK to begin with what you know and expand as the project evolves.
2. Seek guidance when you need it. If you’re unsure about a decision or approach, consult a reasoning model like Gemini or o3—they’re great for clarifying options and next steps.
3. Keep the document living. Regularly update your Project Constitution as things change. Better yet, let your AI assistant help you keep it current.

Don’t skip this step. Maintaining an up-to-date Project Constitution delivers outsized value and keeps your project aligned, focused, and on track.

Track the current focus (current-scope.md)

Think of this as the ‘focus zone.’ What are we actively building right now? This keeps everyone, including the AI, on task.

Example:

• Task: “Design and implement the user onboarding flow.” (/current-scope/task-xyz.md)
• Backlog: “Push notifications, gamification features.” (/current-scope/backlog.md)

Here’s my task template that proved itself to keep me and the AI assistant on track:

#### Task Metadata

Fill out all fields clearly. Use this to align work with the broader architecture and process.

id: MET-XYZ-##               # Unique task ID (e.g., MET-ENG-12)
title:      # E.g., “Refactor Audio Engine Initialization”
author: 
created: 2025-04-17
status: Active                # Options: Active | Blocked | Done
size: S                       # XS (≤½d), S (~1d), M (~2‑3d), L (>1w)
links:
	•	PR:
	•	issue:

⸻

Why

<Explain the reason this task exists. Focus on the problem, opportunity, or context—not the solution. One paragraph max.>

Definition of Done

Check all that apply for this task to be considered complete:
	•	Feature works as intended
	•	Test(s) pass (unit/integration as needed)
	•	Documentation updated
	•	Code reviewed & merged
	•	Aligns with Project Constitution (architecture, principles, or constraints)

Use visuals (diagrams/*.mermaid)

These are helpful visuals. You don’t need to create them, but knowing they exist helps you align thinking or explain flows. They also make it easier for the AI assistant to get acquainted with the big picture.

This diagram of my app’s architecture isn’t just for show—it’s here to prove a point. Throughout the project, I kept coming back to it whenever I needed to bring a “new pair of AIs” up to speed (pun intended) or refresh my Windsurf IDE’s project memory. Having a clear, visual reference made it easy to realign both myself and my AI assistants, no matter where we were in the process.

Context window limits

AI can’t remember everything. Only give it what it needs, when it needs it.

It’s crucial to recognize the memory limits of large language models. If you don’t actively manage what information you provide, the AI will still try to produce an answer—but it may have forgotten key context, leading to results that don’t fit your needs. As a developer or project lead, it’s your responsibility to guide the AI with just the right information at the right time. Otherwise, you risk getting output that’s incomplete, off-base, or simply unusable.

AI-driven development is a discipline of its own, and understanding the context window is a core part of that skill set. The ability to feed the AI just what it needs, when it needs it, is what separates effective AI collaboration from frustration and confusion. Mastering this is as important as any technical skill in the workflow.

Think, validate, and design with AI

AI is a powerful partner for thinking through design decisions before you commit to implementation. Treat it as a sounding board for your reasoning—ask it to weigh the pros and cons of different approaches or help you clarify your own thinking.

However, remember that AI can sound confident while still being wrong. Always apply your own judgment, especially when it comes to critical issues like security or user experience. Use AI to sharpen your ideas, not as a substitute for your expertise.

️Direct the AI inside your development tools

You don’t need to write code yourself to effectively direct the AI inside your development tools. Clearly communicate your requirements and expectations—such as enforcing coding standards or architectural guidelines—so the AI can act accordingly. But as I said, AI is not infallible. Even though that is up for debate with new models and tooling in 2025.

If you’re ever unsure about its output, seek a second opinion from a developer or consult another trusted AI model. Your oversight ensures that the results align with your project’s goals and standards.

You’re the director. Define the vision, guide architecture, validate outcomes. You don’t need to code, just steer the build.

Optional Tools That Make a Big Difference

While the following techniques aren’t strictly required, they can make a world of difference—especially in complex systems. Incorporating behavioral specifications, logic outlines, and API contracts can dramatically improve clarity and alignment for both humans and AI.

Above all, concrete examples are invaluable: they cut through noise and should be used as often as possible.

Behavioral specifications / Acceptance criteria

Always define what success looks like from the user’s perspective. Make the focus shift from “code that runs” to “product that works.”

Example:

• “As a returning user, I want to resume where I left off.”

Benefits:

• Anchors implementation to user value
• Makes testing expectations explicit
• Enables AI to simulate outcomes instead of just generating code
• Helps spot gaps in edge cases or flows

Algorithmic outlines / Logic specification (pseudo-code)

Outlining logic in plain steps decouples intent from syntax. It gives the AI (or teammate) an unambiguous path to implementation.

Benefits:

• Reduces hallucination and misinterpretation by the AI
• Keeps you focused on logic, not syntax
• Makes review and feedback easier before code is written
• Supports a “thinking before typing” workflow

Example:

“If the user is inactive for 7 days, send a reminder email.”

API Contracts & Data Structures

APIs are interfaces between components, teams, or systems. Defining them explicitly prevents mismatched expectations and runtime errors.

Benefits:

• Creates strong handoff boundaries between UI, logic, and storage
• Allows parallel development
• Enables type-checking and static validation
• Helps AI generate code that won’t break at integration points

Example:

User profile: {name:string, email: string, avatarUrk:string}

Concrete examples

Examples eliminate guesswork. They collapse ambiguity by showing the input/output shape in full fidelity.

Benefits:

• Prevents misinterpretation of abstract requirements
• Helps validate logic and expectations before coding
• Lets AI pattern-match more effectively
• Accelerates testing and review

Example:

• Input: UTC+1 → Output: Central European Time

If this feels like a lot of prep work, that’s because it is. And that’s the point. You don not need to apply all these all the time but it is good to know they exist.

You can’t build a lasting product by winging it. “Vibe coding” might feel fast and creative in the moment, but it doesn’t scale, it doesn’t collaborate, and it definitely doesn’t translate to AI. Without clear thinking upfront, the AI will guess—and you’ll spend your time cleaning up confusion instead of shipping quality.

This kind of prep isn’t overhead. It’s how you make sure everyone—AI, teammates, future-you—knows what “done right” looks like. Every spec, example, and diagram you write now saves hours of rework later. You’re not slowing down. You’re building with intent.

If you care about the quality and longevity of what you’re making, this is non-negotiable.

Process & workflow

If you want results you can trust (and build on), you need to be more structured than the average “vibe coder.” That means breaking things down into clear steps, showing where decisions come from, and giving feedback that moves things forward.

Don’t mistake rigidity for discipline here. You are settings things up so that both you and the AI can actually do great work. Consistently and confidently crunching that code, like a finely tuned machine. Iterating goes a long way.

Modular task decomposition

Break down features into smaller, manageable tasks.

Example:

• “Calendar module” → UI layout, date picker, event handling, timezone sync

Providing context

Always say where something comes from or what it refers to.

Example:

• “Use the diagram in signup-flow.mmd as a reference.”

Review and refinement cycle

Don’t fix output blindly. Diagnose and guide corrections.

Example:

• “The button works but isn’t accessible. Add aria-label for screen readers.”

Knowledge management & organization

Keep documents updated so others (and your future self) can stay aligned.

Example:

• Log decisions like: “Chose WebAudio API for latency benefits.”
• Update diagrams when flows change.

Putting it all into practice

You don’t need to be a coder to lead an AI-driven product. You need clarity, consistency, and structure. Define the goals, shape the vision, break down the work, and give feedback.

The AI is your builder. You're the architect. Guide it well and it will do the heavy lifting for you.

Here are some key takeaways:

• You are the director — AI is your assistant, not your replacement.
• Use a Project Constitution to establish scope and constraints early.
• Visuals, examples, and clear prompts improve outcomes.
• Always provide context because AI doesn’t guess.
• Break tasks into small, reviewable units.
• You don’t need to review code alone. Ask a human or another AI model.
• Good documentation today saves confusion tomorrow.

If your output starts drifting or feels off, revisit the Six Commandments. The answer is likely there.

Use this playbook to structure how you think, communicate, and lead. When you do, AI becomes a force multiplier.

And you do use a versioning system for the project you are working on, right?

Happy building and keep that game going. Who know what we’ll have at our disposal in 2026.