Why DocDD (Document-Driven Development) Matters More in the Vibe Coding Era — A Practical Guide to Avoiding AI Rework Hell [2026]

2025–2026 has been the moment when software development fundamentally shifted. With autonomous AI coding tools like Claude Code, Cursor, and GitHub Copilot, engineers can now produce large volumes of code simply by describing requirements in natural language — the era of vibe coding. But a new problem has emerged. "It works when I vibe it out, but it's not production-ready." "A tiny spec change means rewriting everything." "AI added unrequested cleverness and the codebase lost its coherence." This rework hell is canceling out the speed AI brought. This article walks through DocDD (Document-Driven Development) as the practical antidote.

The idea of "writing a Design Doc before implementing" is sometimes abbreviated as "DD," but that collides with DDD (Domain-Driven Design), which is already well-established in software engineering. To avoid confusion, this article uses the term DocDD (Document-Driven Development) as proposed in okikusan's Zenn article published in July 2025. In one sentence, DocDD means: *treat the document as the primary source of truth, and treat code and tests as derivatives generated from it*. We'll cover why this is especially powerful in the AI coding era below. Reference: okikusan, "A Practical Guide to AI-Driven Document-Driven Development (DocDD): Automating Design, Implementation, and Testing in a New Era" (Zenn, July 7, 2025)

The term "vibe coding" was popularized by Andrej Karpathy (former OpenAI founding member, former Director of AI at Tesla) on X in early 2025. The idea: you don't write code — you describe the vibe and let AI do it. With AI coding tools maturing rapidly, this workflow became common: - Describe a feature in natural language → AI writes the code - Check what it does, give feedback → AI adjusts - Loop until the feature feels right It is the fastest prototyping style ever invented. But in the production-quality, long-running phase of a project, the weaknesses become apparent.

When you let AI write from vibes alone, five typical problems recur: 1. Requirement drift: Each AI pass proposes slightly different implementations; after many iterations, it becomes unclear what was originally being built 2. Missing architecture: Individual features work, but there is no coherent architecture — every new feature contradicts the last 3. Data model inconsistency: API response shapes, DB schemas, and frontend types drift apart, and reconciling them later costs huge effort 4. "Looks right" code with no tests: Surface behavior is fine, but edge cases, exceptions, and concurrency bugs lurk underneath 5. Unhandoffable code: Design intent is neither in the code nor in comments, so the next engineer (or your future self) cannot understand it

DocDD (Document-Driven Development) means you write a Design Doc before you write any code, and implement from the doc. This has been a baseline practice at Google, Meta, Stripe, and other organizations running large-scale systems — and it is being rediscovered in the AI coding era. okikusan's article summarizes the core ideas of DocDD roughly as follows: - Position documents as the primary source of truth; treat code and tests as derivatives generated from them - Enforce the Why → What → How ordering to avoid partial optimization - Declare inter-document dependencies in Front-matter so that change propagation can be automated - Let humans focus on putting domain knowledge into words, while AI handles implementation and test generation This article translates that principle into concrete tactics that address the weaknesses of vibe coding. For the detailed theory, we recommend reading okikusan's original article alongside this one.

Before building a new feature, these are the minimum sections to capture:

With these seven sections in hand, you can give AI a concrete, unambiguous brief. okikusan's original article extends this further with Front-matter-level metadata (ID, `depends_on`, status, approvers) and tag management (`#approved`, `#DoNotEdit`, `#NeedsHumanCheck`) — recommended reading for larger projects.

At Oflight, we use the 7-section template as a starting point and wrap it in the following flow, which we've refined across internal and client AI development projects. It sits on top of okikusan's core DocDD principle (document as primary source of truth), adapted with our day-to-day practical tactics. 1. Jot down the 7 sections roughly: Quickly sketch background, goals, scope, and a rough direction in bullet form (10–15 minutes) 2. Brainstorm with AI: Hand those rough notes to Claude Code or Claude chat and ask, "Point out gaps, contradictions, alternatives, and edge cases." AI comes back with "this is ambiguous," "what about this constraint?", "this data model won't extend well," and so on 3. Write plan.md based on the exchange: Absorb the issues surfaced in the brainstorm and finalize the design doc as `docs/plan/<feature>.md`, following the 7-section template. This is where humans make the final calls 4. Feed plan.md to AI and ask for implementation: Point Claude Code at `docs/plan/<feature>.md` via `CLAUDE.md` and say, "implement according to this doc." AI starts from zero-ambiguity 5. When implementation reveals a mismatch, fix plan.md first: Never edit code first. Maintaining the document as primary source of truth is the iron rule The key insight: we use the AI brainstorm step to raise design quality before committing to plan.md. Instead of trying to write a perfect doc from scratch, we use AI as a design reviewer to polish the rough notes. This dramatically reduces rework compared to asking AI to implement immediately from fuzzy requirements.

When a DocDD-style design doc exists up front, AI coding accuracy goes up dramatically. The reason is simple: the doc itself is the highest-quality prompt you can give AI. - Ambiguity removed: Fuzzy words like "nicely," "normally," "appropriately" disappear, so AI has no license to invent details on its own - Reusable: The same doc can be handed to multiple AIs (Claude Code, Cursor, Codex, etc.) for comparison, and re-used across sessions - Reviewable: A human can review the doc before any code is written, catching design-level mistakes at their cheapest stage - Doubles as documentation: The doc becomes the codebase's design reference for future-you and future team members - Version-controlled: With the doc in git, design decisions gain a full history - Change propagation (okikusan's point): When dependencies are declared in Front-matter, a single requirement change can be propagated automatically across related docs, code, and tests by AI

Patterns for feeding DocDD docs to the major AI coding tools:

The common thread: keep the doc somewhere the tool can always see it. okikusan's article recommends pairing this with Front-matter metadata (ID, `depends_on`, status, approvers) and a structured `docs/` hierarchy — increasingly valuable as the project grows.

Typical objections to DocDD, and how to respond: Objection 1: "AI is so fast now — writing a design doc wastes time." → The rework cost of not writing one is far higher. Spending 1 hour on a doc to avoid 10 hours of rework is a 9-hour net profit. Objection 2: "We're agile, we don't write docs." → A DocDD doc isn't a heavy detailed-design document; it's a lightweight record of the current agreement. It's fully compatible with agile. Stripe and Linear use docs like this every day. Objection 3: "For prototypes, vibe coding alone is fine — write a doc after it works." → Throwaway prototypes are fine with vibe coding only. But the pattern where a prototype silently becomes production is painfully common. Habituating to docs early means prototype-to-production flows smoothly. Objection 4: "Why not just have AI write the doc too?" → The doc is where humans decide what to build. Letting AI decide what to build is how misalignment with business needs happens. Using AI as a brainstorming and review partner (our Step 2) is great — but the decisions stay human.

At Oflight Inc., DocDD-driven AI development is the default for internal and client projects: - Write a plan.md per feature: Before any new feature, a 1–3 page design doc is written (with AI brainstorm support) - Feed `CLAUDE.md` / `docs/plan` to Claude Code as context: Design intent is always within reach during implementation - Review PRs against plan.md: Reviews check whether the code did anything the doc didn't authorize - Version-control plan.md: Design decisions gain a commit history With this setup, we keep AI's speed while sustaining the quality needed for long-term operations. We apply it across web development, internal systems, and AI BPO engagements.

Q1. How long should a design doc be? Depends on feature size, but 1–3 pages (A4 equivalent) per feature is the target. Over 10 pages usually means too much detail; under 1 page often means scope is too small. Q2. Who writes it? Ideally, the engineer who will implement it. If someone else writes it, design intent doesn't transfer and the implementation drifts. On multi-person teams, a tech lead gives the final review. At Oflight, everyone personally runs the "7-section notes → AI brainstorm → finalize plan.md" loop. Q3. How is DocDD different from RFC? RFCs are heavyweight docs for organization-level decisions (language choice, auth platform, etc.). A DocDD plan.md is lightweight and feature-level. Think RFC ⊃ plan.md. Q4. Can AI review a design doc? Yes — asking AI to find holes, flag contradictions, and propose alternatives works well. In our flow, that's Step 2 (AI brainstorm). But the final call must be human. AI suggests plausible options but doesn't know what's correct for the business. Q5. How do we introduce DocDD mid-project? Start with new features only. You don't need to retroactively document all existing code. Even just covering new work, the difference shows within six months. okikusan's article assumes incremental adoption and proposes structured templates to support it. Q6. Good resources for learning DocDD? The okikusan Zenn article referenced at the bottom of this article is the most systematic primer in Japanese. In English, "Design Docs at Google," Stripe's Increment articles on design docs, and Will Larson's "An Elegant Puzzle" remain the standards. Q7. Can Oflight build with DocDD-driven AI development? Yes. We use DocDD-driven AI development across web development, internal systems, and AI BPO engagements. We also help teams migrate existing projects to AI-driven development and introduce doc templates. Start with Contact or see our AI Consulting page.

- okikusan, "A Practical Guide to AI-Driven Document-Driven Development (DocDD): Automating Design, Implementation, and Testing in a New Era," Zenn, published July 7, 2025. https://zenn.dev/okikusan/articles/024dfd71536d68 - The "DocDD" name, the "document as primary source of truth" principle, Front-matter-based dependency management and change propagation, and the idea of AI actively detecting contradictions are all credited to this article. Only a short summary of the concepts is reproduced here; the concrete tactical flow, Oflight's internal setup, and the FAQ are original to this article. For the full theoretical treatment, please read the original. - Andrej Karpathy, "vibe coding" (X post, early 2025)

The speed of AI coding only becomes a sustainable development pace when combined with DocDD's up-front design. A design doc is not a relic of old documentation culture — it's the best prompt for the AI era. To avoid rework hell, try the flow "7-section notes → AI brainstorm → plan.md → feed to AI and implement" on your next feature, starting today. - AI Consulting: Setting up AI-driven development practices - Software Development: Outsourced development with DocDD-driven AI as the baseline - Contact: Ask us about doc templates and migrating existing projects