The Velocity Trap: Why AI Coding Agents Make Technical Debt Harder to See
The PR throughput chart is going up and to the right. Cycle time is down. Story points completed per sprint have climbed sharply since the team rolled out coding agents in earnest. The CTO update writes itself.
This is roughly when I start asking uncomfortable questions.
Not because the numbers are wrong. They are probably right. But every dashboard I have seen that looked this good, this fast, in a domain this hard, was measuring something narrower than it appeared to measure. Velocity is an indicator of output. It has never been a reliable indicator of system health, and with agents in the loop, the gap between the two is widening in ways most engineering organizations are not instrumented to detect.
The pattern deserves a name. Call it the velocity trap: the period during which a team's metrics improve while the underlying system becomes progressively harder to reason about, until the curve breaks and the cost of every subsequent change goes vertical.
The honest case for agents
Before the critique, the steel-man, because it is strong.
AI coding agents are a real productivity shift. Solo builders and small teams are reporting compressed timelines that, even discounted heavily, are meaningful. Parallel execution loops, persistent memory layers, and closed-loop verification systems are maturing quickly. The right framing at the system level is that capability is a function of model, harness, tools, environment, and evaluator together. Teams with strong evaluators and disciplined harnesses appear to be getting durable leverage, not just demo-grade output.
Every prior productivity tool, from compilers and IDEs to Stack Overflow and Copilot, provoked the same anxiety, and every one was absorbed. The argument that this time is different needs to clear a high bar.
Here is why I think it does.
The hidden layer is no longer deterministic
Compilers hid assembly. ORMs hid SQL. Both were absorbed because the hidden layer was deterministic and inspectable. When the output was wrong, you could open the abstraction, walk down a layer, and find the bug. The mental model the engineer built on top of the abstraction stayed valid because the abstraction did not lie.
Agents hide a different kind of layer. The output is plausible, frequently correct, and sometimes wrong in non-human ways. These are patterns that pass code review because they look like something a competent engineer would write, but encode assumptions no one on the team ever made. The abstraction does not preserve a clean interface you can drop below. There is only the artifact and whatever map of it the agent did or did not leave behind.
This is the structural difference, and it is what makes the prior-tools analogy weaker than it looks. We are not hiding deterministic complexity behind a stable interface. We are generating non-deterministic complexity behind a thin one.
The debt is cognitive, not just architectural
The standard frame for AI-generated technical debt is code quality. That frame is too narrow.
The deeper problem is that the engineer who would normally build a mental model of the system while writing it never builds one. PR volume climbs while comprehension drops. The code gets written. The understanding does not.
This matters because technical debt detection has always relied, in part, on someone remembering why a decision was made. Lint rules, static analysis, and architectural fitness functions catch a band of problems, the ones humans tend to create at human rates. They were never the whole detection mechanism. A meaningful share of it has always been a senior engineer noticing, in a code review or a debugging session, that something did not match the model in their head.
When fewer people ever built the model, that mechanism fires less often. The debt is not only hidden in the code. It is hidden in the absence of anyone who carries the code.
"Ninety percent done" means something different now
The widely reported pattern that agents get to roughly 90% quickly and the final 10% is disproportionately hard is usually treated as a finishing problem. I think it is at least as much a legibility problem.
Human-built 90% comes with a mental map of where the remaining 10% lives: which edge cases were skipped, which assumptions were load-bearing, which integrations were stubbed. Agent-built 90% does not come with that map by default. The final 10% therefore requires reverse-engineering the system the agent produced before any fix can be made. The work that looks like finishing is partly archaeology.
This is also why scope creep with agents can feel like progress. Each additional feature compounds at the rate the agent can generate code, which is fast. The reverse-engineering cost compounds at the rate humans can rebuild lost context, which is not. The two curves diverge quietly until something breaks and the team discovers the gap.
Velocity metrics were already weak. Agents stretch them further.
I have written before about ARR becoming a vanity metric in AI-native companies, a number that looks healthy right up until you decompose it and discover a meaningful share is pilot revenue that may not convert. The velocity-with-agents problem rhymes with that.
PR count, story points, cycle time, and lines changed were always imperfect proxies for engineering health. They worked tolerably because human output rates were bounded, so the proxies stayed roughly correlated with real progress. Agents loosen the bound. A team can multiply throughput on every dashboard while net system comprehension drops, and the dashboards will not flag it. They were not designed to.
This is the same disease as the billing system that "looks like plumbing." The most expensive failures are often the ones the dashboard says are fine. Velocity-as-vanity-metric is what happens when the proxy decouples from the thing it was proxying for, and nobody updates the instrumentation.
What closed-loop agents do and do not catch
The strongest counterargument is that closed-loop agents, the self-verification cluster that iterates until tests pass, narrow the undetected-debt window. If the agent verifies its own output against specs, the claim weakens.
It weakens for functional bugs. It does not weaken much for architectural debt, and that distinction matters.
A closed-loop agent that iterates against a test suite is optimizing for the property the test suite encodes. Test suites encode behavior, not structure. They do not encode whether the same concept got modeled three different ways across the codebase. They do not encode whether the agent invented a new abstraction that overlaps with two existing ones. They do not encode whether a module's responsibilities now violate a boundary the team's senior engineers had been maintaining deliberately.
These are the failure modes that compound. Functional bugs get caught. Architectural drift can accumulate underneath green test runs, and at agent speed it accumulates faster than human review cadences were designed for.
Memory for agents is not comprehension for humans
The agent ecosystem is investing heavily in persistent memory, and the engineering is real. Context will survive sessions, skills will become more auditable, agents will remember more of what they did. That investment is valuable, but it does not solve this problem.
Memory for agents helps the agent stay coherent across invocations. Comprehension for humans is a different artifact. It lives in people's heads, gets built through the act of writing and debugging code, and decays when that act is delegated. You cannot retrofit it from a memory store, any more than you can retrofit a senior engineer's intuition from reading their commit history. And the investment flowing into agent memory is not the investment that would produce agent-aware debt detection: the static analysis, fitness functions, and review systems calibrated for non-human failure modes and agent-scale output. Both are needed. Only one is being funded.
The org chart hides the trap longer than the code does
The "Builder" pattern, one person orchestrating agents across what used to be multiple disciplines, is presented as liberation, and for the individual it often is. At the organizational level it carries a cost that takes time to surface.
Fewer people hold any given system in their head. When the Builder leaves, or the agent vendor deprecates a model, or the harness gets replaced, the bus factor on that system can drop sharply. There is no second engineer who built a parallel model of the system, because there was no second engineer. There may be no documentation that captures the load-bearing assumptions, because the assumptions were never articulated. They were generated, accepted, and shipped.
This is the comprehension analog of the structural problem I have written about elsewhere: AI strategy without an organizational home produces stalled pilots, and AI-built systems without a comprehension home produce systems that are expensive to change. The org chart will show a healthy engineering function for some time after comprehension has thinned, because the people are still there and the velocity is still up. The trap is fully sprung when someone has to make a non-trivial change to a system no one understands deeply, and discovers that the cost of understanding it is now comparable to the cost of rewriting it.
What I would actually do
The framing matters here. The trap is conditional, not inherent. Teams with strong evaluators, disciplined harnesses, and senior engineers who refuse to delegate comprehension can avoid it. The question is not whether to adopt agents. It is what surrounding system you build so that velocity and comprehension stay coupled.
Five things I would do, in order:
Stop reporting velocity metrics without a comprehension metric beside them. If PR throughput is on the dashboard, so is something that measures whether the team can still answer architectural questions about the systems they own. A crude version: pick three production systems per quarter, ask the team to whiteboard them from memory, score the gap. It is not rigorous. It is better than nothing, which is what most organizations have.
Require a human-authored design artifact for any agent-generated change above a complexity threshold. Not a PR description. A document that articulates the load-bearing assumptions and the reasons for the structural choices. If the human cannot write it, the human does not understand what was shipped, and the change does not merge.
Invest in agent-aware review tooling, not just agent memory. The review stack was calibrated for human-rate output and human failure modes. It needs to be extended for plausible-but-wrong code at agent throughput. This is the gap the ecosystem is underinvesting in, which means individual organizations have to close part of it themselves for now.
Name the comprehension owner for every system, separate from the Builder. The person whose job is to hold the model in their head. This is not a documentation role. It is a senior engineering role with the authority to reject changes that erode legibility, even when the tests pass and the velocity numbers would benefit.
Decompose velocity reporting the way you would decompose ARR. Throughput on net-new comprehension-bearing work is different from throughput on systems no one understands anymore. Reporting them as one number is the same category of error as reporting pilot revenue and committed revenue as one ARR figure. The board will weight them identically, and the weighting will be wrong.
The pattern, again
Every domain I have worked in has a version of this. Billing that looks like plumbing and turns out to be the decision layer. ARR that looks like growth and turns out to include experimental spend. AI strategy that looks like a task force and turns out to be the absence of a home. The boring layer is the strategy. The exciting capability is the easy part. Value is decided in the layer everyone agreed not to think about.
Agents are not the danger. The danger is filing them under "productivity tool" the way billing got filed under finance and ARR got filed under recurring revenue, and discovering some quarters later that the dashboards were green right up until they weren't.
The teams that will get this right are not the ones moving slowest. They are the ones who refuse to let velocity and comprehension decouple, and who build the instrumentation to know when they have.