The Blueprint - Stop prompting in the dark

Before you let AI touch a line of code, you need to tell it what to build. That means documentation.

Every software project starts with an idea. But ideas are cheap, and turning that spark into something that actually works, and keeps working, means getting your hands dirty with structure. In the old world, that was planning, architecture docs, and requirements gathering. In the new world of AI-assisted development? It should still be all of those things, but your primary output is documentation.

In Prompt-Driven Development (PDD), that documentation isn't a dusty afterthought; it's the beating heart of the entire process. Think you can just skip to prompting? Good luck with that.

Let me be clear: before I even dream of creating a readme.md or an overview.md, I’m already in a deep debate with an AI. I’m throwing my raw idea at it, explaining what I think I want to build, down to the finest detail. I sketch out user flows, explain features, how i see things connecting and communicating. A literal brain dump, but in a very logical, layered and chronological order.

And then, the crucial part: I let the AI rip it apart. I instruct the AI to use its "perspective" and ask me questions, lots of them.

This isn't about getting the AI to write code yet. This is about leveraging its massive knowledge base to pressure-test my thinking, to expose the gaping holes in my brilliant plan before I waste time building the wrong thing. This back-and-forth is what turns those napkin scribbles into a concrete product vision. Then, and only then, do I start thinking about the real documentation.

Why documentation isn't just "nice to have", it's non-negotiable

Try building something serious without clear docs when you're using AI. Go on, I dare you. What you'll get is AI in reactive mode. It’ll build based on the last sentence you typed, the particular mood of your phrasing that morning, or whatever random example it pulled from its training data. The result? Utter, inconsistent chaos. The same feature implemented three different ways in one codebase, just because your prompts were vibes, not specs.

Good documentation flips that script. It becomes the system specification. The AI stops guessing, instead it starts executing your plan.

Remember that Jira-syncing card system I talked about in previous articles? The one that almost drowned me in AI-generated spaghetti code? Here’s the kind of documentation I should have built before letting the AI run wild (and what I did build when I started PDD):

• overview.md: What is this app for? What are our architectural principles? What’s the tech stack? How are we naming things so it doesn’t look like a ransom note?

• cards.md: A detailed description of the "Card" feature. User flows that a human can understand. Checklists of what "done" actually means.

• cards-model.md: The precise schema for the Card data model. No ambiguity.

• cards-backend.md: Every single endpoint. Create, update, delete, fetch. What they expect, what they return.

• cards-frontend.md: Each UI component, broken down into tasks. What it looks like, how it behaves. Find libraries, components, get it all together.

• cards-permissions.md: Who gets to touch these cards? How does access control actually work? Can everyone see them, but not everyone gets to modify them?

• cards-jira.md: The specific logic for how these cards sync with the external Jira issues.

Each file has to be crystal clear, self-contained, yet linked. The beauty of this? The AI doesn’t need to "understand" the whole app in one go – a task it usually fails at spectacularly. I just point it to the relevant, scoped documentation file. One piece of the puzzle at a time.

Structure that AI can actually follow

Your docs just need to be structured. Here’s a bare-minimum but surprisingly powerful stack for any given feature:

• feature.md: High-level overview. User stories (actual stories, not wishful thinking). A concrete feature checklist.

• feature-model.md: Schema definitions, relationships, and any important database indexes.

• feature-backend.md: Endpoint definitions (routes, methods, parameters). Core logic flow. Expected request/response shapes.

• feature-frontend.md: List of components, all their states & key interactions.

AI, for all its supposed brilliance, works best when it has:

1. One clear job.

2. One defined scope.

3. One unambiguous reference point.

With your docs in place, that’s exactly what you’re giving it. No more psychic debugging once the vibe wears out.

Let AI help you in planning and documenting your project

Here’s one of the best tricks in the PDD playbook: use the AI intensively early on before writing code. Include it during your planning and documentation phases, and stop thinking of it as just a code generator. I'm spending a ton of time on the debate & planning process, way more than it takes me to actually build a feature. Use the AI to organize your brain dump, get it to ask you questions, create diagrams, user flows, map things out however makes you understand what you're building, ask it smart questions:

• "Here’s my user flow for feature X – what obvious edge cases am I completely missing?"

• "Based on these user stories for the checkout process, what API endpoints will I realistically need? How should the request & response look like?"

• "Can you draft an outline for the backend logic of this random-feature.md feature, hitting these key requirements?"

Take its answers, refine them, and turn them into your official documentation. This makes the AI an active participant in your planning, not just a downstream grunt.

Make use of the model's large context window and all the information you fed it, and get it to create for you the rules for AI, define the tech stack, requirements, create the general documentation for the project then dive deeper into feature docs and everything else, establish best practices, structure, and see how easily what started as an idea can turn into a well structured and defined system.

Once this blueprint is solid, then it’s time to execute.