Prompts as source of truth
Prompt-Driven Development (PDD) inverts traditional software development by treating prompts as the primary artifact — not code. The prompt is authoritative; code is a generated artifact that flows from it. This has three direct consequences:- Maintenance cost falls. 80–90% of software cost is post-creation. Patching accretes complexity; regeneration from a clear prompt preserves integrity.
- Intent is preserved. Prompts capture the “why” behind code in a way that comments rarely do. The prompt encodes goals, constraints, and rationale in one place.
- Batch leverage. Modern LLMs make full-module regeneration practical and cost-effective. Changing the prompt and regenerating is cheaper and safer than accumulating patches.
“Cheap generation” doesn’t mean “no effort.” Good prompts, comprehensive tests, and careful verification all require work. PDD shifts where effort is invested — to specification and constraints — rather than whether effort is required.
The Mold Paradigm
To understand why PDD represents a fundamental shift rather than just a new tool, consider manufacturing’s transition from wood carving to injection molding.The wood era (hand-written code)
In pre-industrial craftsmanship, materials were cheap and labor was expensive. Each piece was hand-carved and unique. Modifications meant carefully chipping away at existing work. The artifact accumulated the history of every cut, and skill resided in the craftsman’s hands. Traditional software development mirrors this exactly:- Compute is cheap; developer time is expensive
- Each codebase is hand-written and unique
- Bug fixes mean surgically editing existing lines
- Code accumulates patches, workarounds, and “temporary” fixes
- Skill is measured by navigating legacy complexity
The plastic era (generated code)
When injection molding emerged, it didn’t just make production faster — it triggered a value migration:- Tooling (molds) became the expensive upfront investment
- Per-unit cost approached zero
- Objects became disposable — regenerate identical copies at will
- Modifications meant changing the mold, not the object
- Skill shifted to mold design
- Value migrated to the mold (the specification)
| Injection molding | PDD |
|---|---|
| Mold | Tests + prompt |
| Mold walls | Individual test cases |
| Mold cavity | The behavioral space allowed |
| Injection point | Prompt requirements |
| Plastic material | LLM capability |
| Material formulation | Grounding (few-shot examples) |
| Molded object | Generated code |
| Production run | pdd generate |
| Mold refinement | Adding tests after bugs |
| Discarding defective units | Regenerating instead of patching |
The key insight
When plastic emerged, early adopters made a category error: “Now we can make cheaper wood-like things!” They focused on the output rather than the paradigm shift. Similarly, many view AI coding tools as “faster typing” — using LLMs to patch code, treating prompts as ephemeral instructions. They’re making cheaper wood. The real insight: value has migrated from the artifact to the specification. The prompt and tests are the mold; code is just what comes out.In wood carving, value lives in the artifact. In injection molding, value lives in the mold. In traditional coding, value lives in the code. In PDD, value lives in the prompt and tests.
The three capitals
PDD success depends on three types of accumulated “capital”:Test capital
Tests define the negative space — what generated code cannot violate. Each test is a mold wall. Each bug discovered adds a wall. More walls means more constrained output and more consistent regenerations.
Prompt capital
The prompt directs what fills the mold — intent, contracts, and requirements. It answers “what do we want?” while tests answer “what must it satisfy?”
Grounding capital
Grounding determines the properties of the material being injected. The same prompt with different grounding (few-shot examples) produces different implementation patterns.
The precision trade-off
As test coverage increases, prompt precision requirements decrease:| PDD scenario | Equivalent | Prompt precision needed |
|---|---|---|
| Few tests | 3D printing | High — prompt must specify every behavior |
| Many tests | Injection molding | Lower — tests constrain the output |
The compound interest of molds
| Investment | Returns |
|---|---|
| Write tests once | Constrain all future generations |
| Add test for a bug | Bug can never recur |
| Improve the prompt | All future regenerations improve |
| Grounding accumulates | Similar modules benefit automatically |
The ratchet effect
Each bug discovered → test added → wall becomes permanent → mold is more precise → regeneration is safer → more bugs found → more walls added. The system gets more constrained over time, not less. Unlike patched codebases that accumulate complexity, PDD codebases accumulate constraints while code stays clean because it is regenerated fresh each time.Mental model shifts
Working effectively with PDD requires three mental shifts:Prompt-first thinking
Prompt-first thinking
Always start by defining what you want in a prompt before generating any code. The prompt is the programming language. Code is the output.
Bidirectional flow
Bidirectional flow
Prompt → Code is the primary direction (generation). Code → Prompt is secondary but crucial — keeping prompts in sync when implementation learnings arise. PDD’s
update command back-propagates learnings from code into the prompt automatically.Modular prompts
Modular prompts
Just as you modularize code, modularize prompts into self-contained units that compose via explicit interfaces. One prompt maps to one file or narrowly scoped module. Modules integrate through their examples, which serve as token-efficient interfaces.
PDD design patterns
Dependency injection via auto-deps
Dependency injection via auto-deps
pdd auto-deps automatically discovers and injects relevant code examples and documentation files into a prompt as <include> directives. This prevents prompts from becoming islands that duplicate shared information and keeps dependencies explicit without manual curation.Bidirectional traceability
Bidirectional traceability
PDD maintains connections between prompt sections and generated code. The
pdd trace command finds the corresponding line in a prompt file for a given code line, enabling precise debugging. The pdd update command propagates code learnings back to the prompt, keeping the two in sync.Test-driven prompt fixing
Test-driven prompt fixing
When a bug is found, the first step is writing a failing test — not patching the code. This follows the mold refinement workflow: add a wall (test), regenerate, confirm the wall holds. The
pdd bug command automates this: it analyzes the bug and creates a failing test. pdd fix then resolves it. The test permanently prevents recurrence.Hierarchical prompt organization
Hierarchical prompt organization
Structure prompts from high-level architecture to detailed implementations. Large systems use a graph of prompt modules, each scoped to one file or concern, linked via minimal runnable examples that act as interfaces.
Interface extraction via example
Interface extraction via example
Each module has a minimal runnable example demonstrating intended use. This example is the interface consumed by dependent modules. Including only the example (rather than the full implementation) saves ~90% of tokens while providing the same contract information.
PDD vs interactive patching tools
Tools like Claude Code and Cursor excel at local, interactive edits. PDD is designed for a different purpose:| Dimension | PDD | Interactive tools (Claude Code, Cursor) |
|---|---|---|
| Source of truth | Prompt is primary and versioned | Code is primary; prompts are ephemeral |
| Workflow | Batch-oriented, reproducible runs | Live chat loops; implicit context |
| Scope | Scoped modules with clear interfaces | Local diffs; struggles as history grows |
| Synchronization | Prompts updated after fixes; tests accumulate | Prompt history rarely persists; docs drift |
| Context window | 100% allocated to generation task | 30–50% consumed by agent overhead |
Core doctrine summary
The PDD doctrine distills to twelve principles:Prompts as source of truth
Prompts as source of truth
Versioned prompts define behavior and constraints. Code, examples, tests, infra, and docs are generated artifacts.
Regenerate, don't patch
Regenerate, don't patch
Change the prompt, then regenerate affected surfaces. Avoid local edits that drift intent from implementation.
Synchronization loop
Synchronization loop
Always back-propagate implementation learnings to prompts. Keep prompts, code, examples, and tests in continuous sync.
Test accumulation
Test accumulation
Never discard passing tests after regeneration. Grow a regression net that preserves behavior as the system evolves.
Modular prompt graph
Modular prompt graph
Model systems as composable prompt modules linked via minimal usage examples that act as clear interfaces.
Intent first
Intent first
Capture goals (e.g., “Black Friday scale,” “HIPAA”), not just resource settings. Generation maps intent to implementation.
Batch-first workflow
Batch-first workflow
Prefer deterministic, scriptable batch generation over interactive patching. Optimize for reproducibility and cost.
Conceptual compression
Conceptual compression
Consolidate requirements, rationale, and constraints inside prompts to reduce scattered context across tickets and docs.
Progress over stasis
Progress over stasis
Evolve prompts and regenerate even if code diffs are large. Preserve behavior with tests, not line-level inertia.
Market effects matter
Market effects matter
Few-shot examples and patterns compound. Treat examples as assets that improve quality and reduce cost over time.
Security and compliance built in
Security and compliance built in
Express compliance and threat models in prompts; verify via tests and infra policies on every regeneration.
Sharp knives, safe defaults
Sharp knives, safe defaults