Of all the ironies of the AI coding era, my favorite is this one: the practices that a generation of developers gleefully declared obsolete — written specifications, decision records, careful requirements, tests-as-contracts — are being dragged back to center stage by the very technology that was supposed to bury paperwork forever. There's a lovely old idea from media theory that every new technology retrieves something an earlier era discarded. AI coding agents are retrieving the spec.
To see why, you have to name a kind of debt that's always existed but has never mattered this much: intent debt — the absence or erosion of the explicit goals, constraints, and rationale that explain what a system is for and how it should evolve.
The debt that lives in artifacts
Technical debt lives in code. The erosion of a team's shared understanding lives in people. Intent debt lives somewhere else: in artifacts — or, precisely, in the artifacts that don't exist. The requirements never written down. The architectural decision made in a hallway in 2023, rationale now unrecoverable. The performance budget and privacy constraint known to two people, one of whom just resigned. The spec that describes version one of a system now on version nine.
These artifacts are a system's externalized memory of purpose. When they're missing or stale, something insidious happens: the system keeps evolving — code changes ship daily — but nothing anchors that evolution to what the system was meant to do or whom it was meant to serve. Teams drift into optimizing what's measurable about the system and their process, while the actual users' actual needs fade from the decision loop. The tests pass; the product is quietly becoming the wrong product.
And here's the property that makes intent debt uniquely cruel, the one that separates it from its technical cousin: it can't be repaired later. Messy code can be refactored next quarter — the code is still there, holding all the information refactoring needs. But rationale not captured at the moment of decision is gone. Six months on, nobody accurately remembers why the queue was chosen over the stream, which constraints were real and which were guesses. You can reverse-engineer what a system does. You cannot reverse-engineer why it was supposed to do it. Intent has a capture window, and the window is the decision itself.
Why AI turned a chronic condition acute
Software teams have carried intent debt forever — requirements drift is as old as requirements. Two things changed.
First, hand-written code smuggled intent. A human choosing names, shaping abstractions, structuring modules was encoding purpose into the artifact as a side effect — imperfectly, but genuinely. Readers could partially excavate the why from the how. Generated code carries no such signal: the intent lived briefly in a prompt and evaporated on acceptance. The code is fluent and purpose-blind.
Second — and this is the retrieval mechanism — AI agents are now consumers of intent. An agent asked to refactor, extend, or test a system needs exactly what a new human hire needs: what is this for, what must it never do, what do these domain words mean, what does success look like? Feed it none of that and you get solutions that are technically correct and miss the point entirely — or agents that burn tokens and cycles wandering, or optimize with great competence toward the wrong objective. Practitioners feeling this pain have started calling it context debt: the missing information that makes agents flail. Much of context debt is just intent debt wearing a new name. What was once a nice-to-have for human onboarding is now, quite literally, a runtime dependency of your development tooling.
You can diagnose the debt by its symptoms: behavior drifting from what stakeholders believe the system does (discovered, at worst, during customer incidents); agents that need endless clarification or confidently produce beside-the-point solutions; non-functional constraints — performance, privacy, accessibility — gradually forgotten as their few keepers move on.
Paying it down: intent-first, and executable where possible
The repair strategy is to externalize on purpose what handcraft used to externalize by accident — and the modern toolkit is better than the documentation regimes we abandoned.
Where possible, make intent executable. Behavior-driven specifications and well-written tests aren't just verification — they're purpose, stated in a form that runs. When an executable intent artifact fails, it's telling you the system has drifted from its reason for existing. That's a fire alarm no prose document can sound.
Record decisions with their rationale — lightweight architectural decision records capturing what was decided, why, and what was rejected. Ten minutes at decision time versus an unrecoverable archaeology later; the trade is absurdly favorable. Alongside them, deliberate domain modeling — shared language, explicit concepts — makes the domain's intent legible before it's encoded.
Build context artifacts for your agents — instructions, playbooks, skills files, the emerging craft of engineering an environment where both humans and machines can look up what matters. Writing for the agent has a happy side effect: the same artifact onboards humans.
And above all, keep the user visible: who this is for, what problem it solves, what success looks like — revisited against real feedback, not enshrined once and forgotten. Every other artifact decays into ritual without that anchor.
One honest caveat: none of this is settled doctrine. Thoughtful practitioners disagree — some argue the past doesn't matter, only the path forward, and that context can be reconstructed as needed; others note that AI might itself help surface implicit intent, while skeptics reply that the human act of articulating intent was always the point. I land firmly on the capture side, for one reason: the deciding-what-the-system-is-for work is the one part of software that was never automatable, and an artifact trail is how that human work survives contact with machine-speed everything else.
We stopped writing things down because the code could speak for us. The code has stopped speaking — it's generated now, eloquent and empty. Time to start writing again.
