Why the Source of Truth in Software Development Is Changing

Code Used to Be the Final Word

For most of software history, this was settled: if you wanted to know what a system actually did, you read the code. Not the design doc — that was probably stale. Not the README — half-written and two versions behind. Not the comments — optimistic at best. The code. The code was what ran, and what ran was what mattered.

This wasn’t a philosophy. It was a practical truth. Everything else — specs, diagrams, tickets, documentation — drifted from reality the moment engineers started implementing. Code was the only artifact that stayed honest because the machine enforced it.

That assumption is now breaking down. The source of truth in software development is shifting, and understanding why matters if you’re building anything with AI.

What “Source of Truth” Actually Means

Before getting into what’s changing, it helps to be precise about what we mean.

A source of truth is the artifact you trust above all others when there’s a conflict. When the spec says one thing and the code says another, which one is right? When a new engineer joins and needs to understand what a feature does, where do they look? When something breaks in production, what do you use to reason about intent versus implementation?

For decades, the answer was the code. Specifically: the running, version-controlled code in your main branch. Everything else was secondary.

This made sense when humans wrote every line. If a human made a decision about how to implement something, that decision was captured in the code they wrote. Reviewing the code was reviewing the decision.

But AI coding agents have complicated this. When an AI generates 500 lines of code from a prompt, what exactly is the decision being recorded? The implementation exists. But the intent — the reasoning, the constraints, the business logic — lives somewhere else entirely. Or nowhere at all.

How We Got Here: The Abstraction Ladder

Programming has always moved upward through levels of abstraction. Each step let developers express more intent with less effort and fewer details about the underlying machine.

Machine code: You told the CPU what to do, bit by bit.
Assembly: Named instructions, but still close to the metal.
C and compiled languages: Express logic without managing registers.
High-level languages (Python, JavaScript, TypeScript): Work with data structures and functions without thinking about memory.
Frameworks and libraries: Don’t build auth from scratch. Import it.

Each abstraction layer didn’t eliminate the one below it — it just made it irrelevant to most builders. You don’t think about assembly when you write TypeScript. It’s still running underneath. You just don’t have to care.

The progression from assembly to TypeScript to spec follows the same pattern. The question isn’t whether lower layers exist — they do. The question is which layer you work in, and which layer carries meaning.

For most of software history, the answer was TypeScript (or its equivalent). The spec was a plan. The code was the reality.

That’s what’s changing.

Why AI Makes Code an Unreliable Source of Truth

When you write code yourself, there’s a tight feedback loop between your intent and the implementation. You make a choice, you write it down in code, and the code reflects that choice. If you made the wrong choice, the code is still an accurate record of what you decided.

AI changes this in a subtle but important way.

When an AI generates code from a description or a prompt, the implementation is derived — not authored. The AI is guessing at what you meant based on the language model’s training data and your prompt. If the code looks right, great. If it doesn’t quite do what you wanted, you’re not looking at a recorded decision. You’re looking at an inference about your intent.

This creates a fundamental problem: the code doesn’t know what it was supposed to do. There’s no way to look at AI-generated TypeScript and reliably extract the business logic or constraints that were intended. The implementation exists. The intent is gone.

This is why most AI-generated apps fail in production. It’s not that the code is wrong on its face. It’s that there’s no durable record of what “correct” means for this specific application, so every iteration introduces drift. You fix one thing and break another. You add a feature and lose a constraint. Each prompt is ephemeral. The chat log isn’t a spec.

The Spec as the New Source of Truth

The solution isn’t to trust code less. It’s to introduce a layer above code that carries intent durably and precisely.

This is what spec-driven development proposes. The spec is the document you trust above all others. It describes what the application does — its behaviors, its data model, its rules, its edge cases — in a form that both humans and AI agents can read and reason about.

Code is derived from the spec. Not the other way around.

This inversion is the core of what’s changing. In traditional development:

You write a spec (optional, often informal)
You write the code (the real work)
The spec drifts; the code is the truth

In spec-driven development:

You write the spec (the real work)
The code is compiled from the spec
The spec stays in sync; it is the truth

The analogy that holds up: no one writes assembly by hand to build a web app. But assembly is still running. The TypeScript you write compiles down to something the machine can execute. The TypeScript is not “fake” because it’s compiled — it’s just the appropriate level of abstraction for human expression.

A spec is the next step up that ladder. The code becomes the compiled artifact.

What Makes a Spec Different From a Requirements Doc

This is where a lot of people get skeptical. “We’ve had specs and design docs forever,” they say. “They always drift. Why would this be different?”

Fair question. The answer is that traditional requirements documents were always secondary artifacts — things written to communicate intent, not to drive implementation. They had no formal relationship with the code. Nobody compiled the requirements doc.

A proper spec for spec-driven development is different in two ways:

First, it’s precise enough to be executable. It’s not just prose. It contains structured annotations — data types, validation rules, allowed values, edge cases — that carry enough precision to drive code generation reliably. This is what specification precision actually means: the spec doesn’t just describe the feature, it defines the behavior completely enough that an AI can generate correct code from it.

Second, it’s maintained as the canonical artifact. When you want to change the application, you change the spec. The code is recompiled. You don’t patch the implementation and hope someone remembers to update the docs. The spec is upstream of everything else.

This is the structural difference. Traditional docs described code. A proper spec is the application — the code is just its compiled output.

If you want to know how to write one, this practical guide to writing a software spec walks through what goes in it and how to structure it.

What This Changes for Developers

The shift has real implications for how developers work.

The skill that matters most shifts

Right now, the highest-leverage skill in AI-assisted development is something closer to prompt engineering — knowing how to ask AI tools for what you want. That skill is real but brittle. It produces output that doesn’t have a durable upstream artifact.

As spec-driven development matures, the high-leverage skill becomes specification. How well can you articulate what an application should do, with enough precision that the output is reliable? That’s a different kind of thinking than writing code — and in some ways harder.

It’s also more durable. A well-written spec survives model upgrades. Better models just produce better compiled output from the same spec. You don’t rewrite the application — you recompile it.

The role of code review changes

In traditional development, code review is the last line of quality defense. Reviewers check that the implementation matches intent and catches bugs.

In a spec-driven world, code review changes shape. Reviewing the spec is higher-leverage than reviewing the generated code — because the spec is what will be used to regenerate future implementations. If the spec is wrong, all future compilations will be wrong.

This doesn’t mean generated code goes unreviewed. But the attention shifts upstream.

Non-coders can build real things

One underappreciated consequence: if the source of truth is a spec written in annotated prose rather than TypeScript, then domain expertise becomes the primary qualification — not programming ability.

A healthcare operations manager who can write a precise, complete spec for a patient scheduling tool is more valuable in this model than a developer who can write clean TypeScript but doesn’t understand the business rules. Domain expert builders — people who know a field deeply but aren’t programmers — can now build real full-stack applications, not just configure no-code forms.

This doesn’t mean programming knowledge becomes worthless. Understanding how systems work still helps you write better specs. But the barrier to building has moved.

Vibe Coding vs. Spec-Driven Development

It’s worth drawing a line here, because these often get conflated.

Vibe coding is the practice of iterating on an application through free-form prompts — describing what you want, seeing what the AI produces, and continuing from there. There’s no persistent upstream document. The chat log is the history. When something breaks, you describe the problem and hope the next output is better.

This works for prototyping and exploration. It doesn’t work reliably for production applications, because there’s nothing to reason about at the spec level. There’s no document that defines what “correct” means.

Spec-driven development is structured. The spec is a real artifact, maintained deliberately, and it drives code generation in a traceable way. When output is wrong, you fix the spec and recompile. The spec accumulates the truth about what the application should do. The implementation follows from it.

The practical difference: in vibe coding, you’re always working in the present tense. In spec-driven development, the spec is a durable record you can return to, hand off, and evolve systematically.

How Remy Implements This

Remy is built directly on the idea that the spec is the source of truth.

In Remy, you write a spec — a markdown document that describes your application in annotated prose. The readable prose says what the app does. The annotations carry the precision: data types, edge cases, validation rules, business logic. From that spec, Remy compiles a full-stack application: backend, database, auth, frontend, deployment.

The spec is the program. The TypeScript is compiled output.

This means when you want to change the application, you change the spec. Remy recompiles. There’s no drift between what the app is supposed to do and what it does, because the spec is the canonical source from which the code is derived.

It also means the application gets better automatically as models improve. You don’t rewrite anything. Better compilation from the same spec produces better output. The spec is durable; the implementation quality tracks the frontier of what AI can produce.

The full-stack output is real: a real backend with TypeScript methods, a real SQL database with proper schemas and migrations, real auth with sessions and verification — not a prototype, not a static frontend with a cloud function bolted on.

You can try Remy at mindstudio.ai/remy and see what it builds from a spec.

What Stays the Same

It’s worth being clear about what this shift doesn’t change.

Code still runs. The TypeScript is still there. You can read it, modify it, extend it, and deploy it. There’s no black box. Remy’s repos are open source.

Software engineering judgment still matters. Writing a good spec requires understanding what makes software systems work — data models, edge cases, consistency, failure modes. The thinking doesn’t go away. It just happens at a different layer.

Debugging still happens. When generated code has issues, you investigate. The difference is that your first move is to check whether the spec is precise enough on the relevant behavior, then recompile, rather than patching the implementation in isolation.

And collaboration still requires clear communication. The spec makes that communication explicit and durable rather than implicit and scattered across Slack threads and Jira tickets.

The Bigger Picture: What “Source of Truth” Will Mean

The phrase “source of truth” exists in every engineering organization. It usually refers to the database, the API contract, or the main branch of the codebase. It’s the thing you trust when everything else conflicts.

As AI-generated code becomes more common, the practical question of “what does this application actually do?” becomes harder to answer by reading code. The code was generated. It may not reflect a deliberate human decision. It may reflect a prompt, or a model’s interpretation of a prompt, or a series of patches applied to make tests pass.

The response to this isn’t to avoid AI coding tools. It’s to introduce a layer of documentation that sits above the code and persists independent of how the implementation was produced. A spec that defines the application, maintained as the authoritative record, from which implementations are compiled.

This is not a new idea in theory — model-driven and specification-first approaches have existed for decades in academic and formal verification contexts. What’s new is that AI can now compile from specs precisely enough to produce production-grade full-stack applications. The gap between “what the spec says” and “what runs” has collapsed enough to make this practical.

That’s the structural change. And it’s why questions about whether software engineering is dead are missing the real question, which is: what does the job look like when the source of truth shifts up a level?

The answer: you still build software. You still need to think carefully about what it does. You just express that thinking in a different artifact, one that both humans and agents can reason about.

Frequently Asked Questions

What is the source of truth in software development?

The source of truth is the authoritative artifact that defines what a system does. When there’s a conflict — between the docs and the code, or between the expected and actual behavior — the source of truth is what you trust. Traditionally this has been the codebase itself, specifically the version-controlled code in the main branch. The idea is that code is what the machine actually runs, so it’s the most honest record of system behavior.

Why is code no longer a reliable source of truth?

Code is still reliable as an execution artifact — it runs and produces results. The problem is that AI-generated code is derived from a prompt or description, not authored as a deliberate record of intent. If a large portion of your codebase was generated by an AI agent, reading the code tells you what it does, but not necessarily what it was supposed to do, or what constraints were intended. There’s no way to extract the business logic reliably from generated TypeScript. The intent lives in the upstream spec, if there is one — not in the code.

What is spec-driven development?

Spec-driven development is an approach where the application specification — a structured document describing behavior, data models, rules, and edge cases — serves as the primary artifact, and the code is compiled from it. You write the spec first, with enough precision that an AI agent can generate reliable implementations from it. When you want to change the application, you change the spec and recompile. The code is treated as derived output, not the source of truth.

How is a spec different from traditional requirements documentation?

Traditional requirements documents were secondary artifacts — written to communicate, not to drive implementation. They had no formal relationship with code and always drifted as development proceeded. A spec in spec-driven development is different because it’s precise enough to be executable (it carries data types, validation rules, and business logic in structured annotations) and it’s maintained as the canonical artifact that code is generated from. You don’t update the docs after you change the code; you change the spec and recompile the code.

Does spec-driven development mean you don’t need developers?

No. Writing a precise, complete spec is a skilled activity that benefits from understanding how software systems work. The shift is about where thinking happens — at the spec level rather than the code level — not whether thinking is required. What does change is that domain expertise matters more relative to syntax knowledge. Someone who understands the problem deeply can now build a production application if they can write a precise spec. And developers who master specification precision alongside technical understanding become significantly more productive.

What happens when AI-generated code has bugs?

In spec-driven development, the first question is whether the spec is precise enough on the behavior that failed. Often a bug in generated code points to an underspecified area of the spec — a case that wasn’t defined clearly enough for the model to handle correctly. You fix the spec, recompile, and the behavior changes. As models improve, the same spec produces better output. You don’t have to rewrite the application; you recompile it.

Key Takeaways

Code was the source of truth when humans authored every line and intent was recorded in implementation decisions.
AI-generated code breaks this assumption because implementation is inferred from prompts, not authored as deliberate records of intent.
Specs become the source of truth in spec-driven development — precise, structured documents from which code is compiled.
The abstraction ladder continues: just as TypeScript sits above assembly, specs sit above TypeScript. Lower layers still exist; you just don’t work in them.
Specification skill matters more than syntax knowledge as this model matures — defining what the application should do precisely is the high-leverage work.
Domain experts can build real applications when the source format is annotated prose rather than typed code.

If you want to see what building from a spec actually looks like, try Remy at mindstudio.ai/remy. Write a spec. See what it compiles into. The code is real, the backend is real, the database is real — and the spec is the thing you edit when you want to change any of it.