Vibe-writing the DDD Book
Part I: Dialectic-Driven Development, Now in Two Modes
Programming keeps climbing the abstraction ladder: from assembly to high-level languages to today’s agent era. What’s missing isn’t more prompting tricks; it’s a methodology built for agents as the primary implementers. Dialectic-Driven Development (DDD) is that methodology—optimized for what agents are good at (tireless iteration, test/write/refactor loops) and for what humans are good at (editing, constraints, judgment). Its core principles are explicit: AI as generator, human as editor; disposable artifacts, durable insight; parsimony over extensibility; system legibility.
DDD starts from an economic reality: AI collapses the cost of code generation, documentation, and refactoring. That flips the value equation—artifacts become expendable; clarity and architectural insight become the durable assets.
The Two Modes of DDD
DDD isn’t one process—it runs in two distinct modes tuned to the level of uncertainty you’re facing:
- Discovery Mode: when the problem or approach is uncertain. You use the full four-document harness—
SPEC.md,PLAN.md,README.md,LEARNINGS.md—and toy-model discipline to explore, validate, and capture constraints. The emphasis is systematic experimentation and falsifiable contracts. - Execution Mode: when patterns are established and you’re building on proven foundations. Here, the center of gravity shifts to
CODE_MAP.md—a living architectural map—plus mandatory refactoring after every feature/integration. The goal is orchestration and quality maintenance, not discovery.
DDD is explicit about when to use which: pick Discovery for novel algorithms, uncertain requirements, new tech, or foundational components; pick Execution for adding features to mature codebases with known patterns. Most work is Execution work; switch into Discovery only when uncertainty resurfaces.
Discovery Mode (the exploration engine)
Discovery Mode runs a crisp loop:
- Docs — tighten SPEC/PLAN for a minimal slice; keep READMEs current.
- Tests — derive from the spec (goldens + error cases).
- Implementation — minimal code to pass; prefer single-file spikes.
- Learnings — record what held, failed, and what constraints surfaced.
It’s also where DDD’s “debugger mindset” shows up: pure CLIs with JSON I/O and structured error JSON so both humans and agents can single-step pipelines, bisect, and verify deterministically via golden tests.
A key differentiator: you don’t write the docs—the AI does. In Discovery, the agent generates the SPEC/PLAN/tests/impl; the human edits for parsimony and correctness.
Execution Mode (the delivery engine)
Once patterns are proven, DDD focuses on keeping the system coherent as it grows. The backbone is CODE_MAP.md:
- Living architecture: a concise, constantly-updated map that orients humans and agents to the current structure. Updated with every commit that changes structure—excessive for humans, optimal for agents.
- Integration cycle (five steps): Orient (read CODE_MAP) → Plan (fit it in) → Implement (follow patterns) → Refactor (mandatory) → Update CODE_MAP (reflect changes).
- Mandatory refactoring after every change keeps quality rising instead of decaying—feasible now because AI makes refactors cheap.
And if uncertainty pops up mid-execution? Switch back to Discovery for a focused experiment, then return to Execution. The methodology is intentionally bi-stable.
Why this is different
DDD isn’t “spec-first with fancy terms.” It’s agent-first operations: the agent generates and maintains the docs (Discovery) or the code map and refactors (Execution); the human edits, constrains, and decides. That division of labor is the point.
Part II: A Short History of DDD
Like many methodologies, Dialectic-Driven Development wasn’t conceived in a whitepaper — it was hammered out in the middle of a messy project.
The earliest proving ground was what became Case Study II: Spatial MUD Database. The problem: realizing a long-held vision of building MUDs not as compressed grids of “rooms,” but as truly vast, sparse spaces structured by quadtrees. The challenge wasn’t implementation but ambiguity: nothing like this had been done before, and it wasn’t clear what would even work.
Throwing an LLM at the problem produced familiar failures: sprawling over-engineered contraptions with too many “axes of complexity,” spiraling before the fundamentals were understood. Out of that frustration came the insight that agents needed discipline: constrain complexity to a single axis, build tiny toys, and let complexity emerge through iteration rather than front-loaded design. The loop of SPEC → PLAN → IMPLEMENTATION → LEARNINGS was born, along with the ethos that code is disposable but insights are durable. That was the crucible of Discovery Mode.
The next project — Case Study I: ChatGPT Export Viewer — posed the opposite problem. This wasn’t open-ended research; it was a clear, tractable build: a suite of CLI tools to browse ChatGPT archives. Here, Discovery Mode felt heavy. What was needed wasn’t speculative toys but steady progress and clean integration. Out of that tension emerged Execution Mode: a workflow centered on a living CODE_MAP.md and mandatory refactoring, with the same “single axis of complexity” discipline baked into the planning stage.
Together, these two case studies gave DDD its dual-mode structure:
- Discovery Mode for foggy, R&D-style problem spaces.
- Execution Mode for roadmap-driven delivery.
And importantly, the two modes overlap: planning in Execution still inherits Discovery’s minimalism (one primitive at a time, then integrate), while Discovery borrows Execution’s demand for legibility and testability.
In other words, DDD wasn’t a manifesto written in advance — it was a survival strategy that grew into a methodology, forged in the gap between what agents do badly on their own and what they can excel at with the right scaffolding.
Part III: Vibe-Writing a Book About Vibes
If Dialectic-Driven Development grew out of experiments in coding with agents, the book that now codifies it grew out of experiments in writing with them. The irony is delicious: the methodology that warns against vibecoding was itself documented through what the author calls vibe-writing.
The difference is subtle but real. Vibecoding doesn’t quite feel like programming, and vibe-writing doesn’t quite feel like writing. The human isn’t laboring over syntax or prose — they’re acting more like Rick Rubin in the studio: setting the vibe, deciding what fits, cutting what doesn’t. The agents play the instruments; the human produces the album.
The transition began after the two case studies. By then the methodology had been captured in a growing forest of .md files — agent-oriented scaffolding. The next step was turning that into a human-oriented book. Instead of outlining in Word or sweating through LaTeX, the author asked an agent to bootstrap the publishing stack: Bash and Python scripts to migrate the notes into an mdBook structure, wire up SUMMARY.md, and set up continuous checks. The book began life not as a manuscript but as a software project.
From there, vibe-writing took over. The human role was not to “write chapters” in the conventional sense but to smell when something was off — the literary equivalent of code smell. A paragraph too ornate, a section over-engineered, a metaphor not carrying its weight. The agents drafted, restructured, refactored; the human read, cut, and redirected.
The Git history of the repo shows the method in action. Early commits are chaotic migrations and reorganizations (docs(v1) → docs(v2)), the discovery phase of vibe-writing. Midway, the key conceptual shift appears in commits like “rename workflow modes to Discovery/Execution” — the breakthrough moment where the dual-mode structure was born. Later commits polish the voice: FAQs, licensing clarifications, guidance for AI collaboration. In miniature, the repo itself mirrors DDD’s dual modes: first Discovery, then Execution.
The result is a book that wasn’t exactly “written” in the traditional sense. It was vibe-written: produced in collaboration with a chorus of agents, curated by a human whose main job was to sense when the vibe was wrong and steer it back on track.