'Document-Driven Development: How I Built a Production Blog Without Writing [post] deterministic

Document-Driven Development: How I Built a Production Blog Without Writing a Single Line of Code By Hand

Look, I need to be honest with you about something that's been weighing on me. The term "vibe coding" makes me want to crawl out of my skin. It sounds like something a trust fund kid would say while sipping a $12 oat milk latte in a WeWork. It's reductive, dismissive, and—worst of all—it's become a slur that scared developers use to look down on anyone who dares to work differently than they do.

But here's the thing I've come to accept: sometimes you have to reclaim the language being used against you. If they're going to call what I do "vibe coding" with contempt in their voices, then fine—I'll own it. Because what they're really afraid of isn't the methodology. What terrifies them is obsolescence.

And I get it. I really do. When your entire professional identity is built on knowing the arcane syntax of seventeen different frameworks, watching someone build the same thing with plain English must feel like watching the ground disappear beneath your feet. But that fear doesn't give anyone the right to gatekeep progress or mock people for using the tools available to them.

So let's talk about what "vibe coding" actually means when you strip away the condescension. To me, it's simple: **using natural language to create functional software without requiring encyclopedic knowledge of implementation details**. It's about focusing on what you want to build rather than memorizing how to build it. It's about making software development accessible to people who have brilliant ideas but don't want to spend six months learning TypeScript before they can create something meaningful.

The Real Innovation: Document-Driven Development

Here's where things get interesting, and where I think we move beyond the dismissive "vibe coding" label into something with actual intellectual substance. I call my approach **Document-Driven Development**, and it's rooted in a principle that should be obvious but somehow isn't: **if you can't articulate what you're building with clarity and precision, you can't build it well—no matter how much code you write**.

The methodology is straightforward: create comprehensive, interconnected documentation that defines every aspect of your project *before you write a single line of code*. Not skeleton docs. Not placeholder READMEs. I mean real, thoughtful documentation that could guide a human developer or an AI agent through the entire development lifecycle.

I maintain a template repository of documents that serve as the foundation for most projects. You can clone it yourself:

git clone https://github.com/kliewerdaniel/workflow.git


This isn't just busy work or over-engineering. This is **documentation as architecture**. When you force yourself to think through accessibility standards, security protocols, testing strategies, and deployment procedures before you build anything, you're frontloading the cognitive work that most developers skip until it becomes a crisis.

The Pre-Prompt Methodology: Teaching AI to Think Like You

Here's where my process diverges from what most people do when they're just throwing prompts at ChatGPT and hoping for the best. I use what I call **pre-prompt prompting**—essentially, I write a prompt that instructs an LLM how to write the *actual* prompt I'll give to my coding agent.

It sounds meta, and it is, but there's a reason for the extra step. When you ask an LLM to help you craft a better prompt, you're leveraging its training to identify gaps in your thinking, suggest better structure, and anticipate edge cases you haven't considered. You're not just automating code generation; you're automating *requirements analysis*.

Here's the initial pre-prompt I use:

You are an expert in document drafting for technical documentation for software engineering. Your job is to build a prompt which I will then give to a coding agent to then iterively go through all of the listed files in the docs folder and construct all of the necessary documentation needed to drive a document driven development cycle of using coding agents to create code. Please instruct the LLM to draft the propmt to be given to the coding agent which will then only edit iterively all of the documents in the docs folder for our purpose.

Then I feed it the specific context about what each documentation file should contain. And I'm not going to lie—this part takes work. You need to think through what belongs in accessibility.md versus security.md versus ai_guidelines.md. You need to consider how these documents reference each other, how they'll be maintained, and how they'll guide development decisions six months from now when you've forgotten your original intent.

But that's the point. **Documentation isn't a chore that comes after development. It's the blueprint that makes development possible.**

The Complete Documentation Blueprint

After iterating on this process across multiple projects, I've developed a comprehensive framework for what should go in each documentation file. I'm including the full boilerplate prompt here because I think transparency matters more than hoarding "trade secrets":

``` You are an expert in document drafting for technical documentation for software engineering. Your job is to build a prompt which I will then give to a coding agent to then iterively go through all of the listed files in the docs folder and construct all of the necessary documentation needed to drive a document driven development cycle of using coding agents to create code. Please instruct the LLM to draft the propmt to be given to the coding agent which will then only edit iterively all of the documents in the docs folder for our purpose.

Below is a complete blueprint explaining how to compose each file, what to include, and why each matters in a professional-grade software engineering process.

The goal is to create a living documentation ecosystem: every file works together, reducing ambiguity and aligning developers, designers, and AI collaborators.

Remember: • Each .md file represents a single domain of truth. • Documents should be interlinked (use relative Markdown links). • Keep them modular — update one file without rewriting the others. • Version control documentation changes like code — documentation is part of the codebase.

⸻

1. README.md — Project Overview and Orientation

Purpose: The entry point for humans and AI systems alike. It provides a high-level summary of what the project is, how to run it, and where to find everything.

Include: • Project name and tagline • Mission statement / goal • System overview diagram • Quick start guide (installation, setup, run) • Directory structure (with descriptions) • Tech stack (languages, frameworks, major dependencies) • Links to all other major documents (architecture, standards, etc.) • Contributor guide (how to fork, branch naming, PR etiquette) • License information

⸻

2. requirements.md — Functional and Non-Functional Specs

Purpose: The contract between stakeholders and developers.

Include: • Functional requirements: each user-facing feature, described in behavior-driven style (Given/When/Then). • Non-functional requirements: performance, scalability, uptime, maintainability. • Constraints: technology limits, APIs, third-party dependencies. • Acceptance criteria per feature. • Priority tags (P0 = critical, P1 = important, etc.) • Future features (optional section for roadmap alignment).

⸻

3. architecture.md — System Design and Technical Blueprint

Purpose: Defines how the system is built, at both macro and micro levels.

Include: • High-level architecture diagram (frontend, backend, DB, external services). • Component breakdown: responsibilities, inputs/outputs, and dependencies. • Data flow diagrams (DFDs or sequence diagrams). • API design overview (link