Most of us are committing the wrong artifact to version control.
When you commit code today, you're committing the output of a process. The thinking happened somewhere upstream (a Linear ticket, a Slack thread, a notebook, a conversation with the team), and what survived that thinking is the code in the repo. The spec, the trade-offs, the constraints you considered and rejected? Mostly gone. The code is the record. The repo is the source of truth.
We had this exact conversation a decade ago. It was about servers.
Before Terraform, the server WAS the truth. You'd SSH in, install packages, edit configuration files, restart services. Maybe you wrote a runbook. The runbook went stale. The server kept going. When something broke, you debugged the server, not the runbook. The version of truth was the running machine.
Then IaC happened. The .tf file became the source of truth. The server became the build artifact. You stopped backing up servers and started backing up .tf files. When a server drifted from the .tf, you didn't reach for the server to figure out what changed. You ran terraform plan, saw the diff, decided whether to update the .tf or re-apply. The server stopped being something you protected. It became something you could reliably regenerate.
We didn't stop having servers. We stopped versioning them.
AI changes the cost of regenerating code from a description of what it should do.
Not perfectly. Not in every case. But enough that, for a growing set of work, the implementation is cheaper to regenerate from intent than to maintain by hand. And once that's true, the implementation can move into the role the server played: the build artifact. The thing you keep around but don't treat as the canonical source.
What plays the role of the .tf file? The spec. Or whatever you want to call it: the acceptance criteria, the contract, the intent-doc. The thing that says what should be true about the behavior, captured in a form structured enough to regenerate the code from.
That's the thing worth versioning.
If intent is the source of truth, several things shift.
PRs stop being about code diffs and start being about intent diffs. The reviewer asks: did the spec change? does the new spec make sense? does the code match? The interesting conversation moves upstream of the implementation. The downstream check (code matches spec) gets cheaper, often automatable.
Tests come from the spec, not from the code. Acceptance criteria become failing tests before any implementation exists. The code has to satisfy them. This is what test-first really means once code becomes regenerable.
Drift, when it happens, gets repaired differently. If the code stops matching the spec, you don't reach into the code to fix it. You decide whether the spec was right (in which case, regenerate the code) or the spec was wrong (in which case, fix the spec, then regenerate). The same loop terraform plan teaches you.
History and memory attach to the spec. The reasons a decision was made, the alternatives considered, the failure mode that bit you in production last quarter, those belong with the spec they shaped. The code is downstream. It inherits those reasons but doesn't carry them.
The natural pushback is: but code is still code. You still have to read it, debug it, run it, pay for it in CPU cycles. It doesn't go away just because it's downstream.
Right. Servers don't go away under Terraform either. You still SSH in when things break. You still tail logs. You still get woken up at 2am. The change wasn't that the artifact disappeared. The change was where the source of truth lived.
Code in an intent-versioned workflow is the same. It stays in the repo. You can read it. You can debug it. You can ship it. But when you need to change WHAT the system does, you change the spec, and the code follows. When the code drifts from the spec, you investigate why, and the fix lands upstream more often than not. The shift isn't "no more code." The shift is "code answers to something now."
This is what Speccraft is built around.
Specs are first-class versioned artifacts in the repo, not throwaway prompts. Code generation flows from those specs through a structured process. Tests come from the spec before implementation, enforced by a hook that blocks production edits without a corresponding test edit. Decisions, conventions, and scars attach to specs and persist across sessions, so the next contributor (human or model) inherits the rationale, not just the diff.
It's the .tf file for code. The thing you version, the thing you review, the thing you treat as canonical. The code becomes what it should have been all along: the runnable expression of an intent the team agreed on.
What would your repo look like if the spec was the source of truth and the code was the build artifact? Most of us already half-believe this. We just haven't restructured anything to act on it yet.
Have you started treating intent as a versioned artifact in your workflow? Or is the spec still living in a ticket somewhere?
