A few weeks ago, I came across a post from a developer who had spent six months working with five or six Claude Code terminals open at once. His description of the experience was funny, but also uncomfortably familiar: most of the time, he was simply waiting for agents to finish and pressing Enter.
His conclusion was blunt: “Claude Code is melting my brain.”
I’ve been seeing variations of this concern more and more often. Developers who use AI heavily start wondering whether they are becoming less sharp because the machine is doing too much of the actual coding. At the same time, another term has started appearing in discussions around AI-assisted development: comprehension debt.
I think that term captures the problem remarkably well.
Technical debt appears when a codebase accumulates decisions that will have to be dealt with later. Comprehension debt appears when the codebase evolves faster than the people responsible for it can maintain a mental model of what is happening inside it. The software keeps moving forward, but your understanding of it falls further and further behind.
Eventually, you can end up in a strange position: you are responsible for a system that you technically own, but no longer fully understand.
These look like two different problems:
- AI making developers “dumber”
- AI creating comprehension debt
... but I suspect they are mostly the same problem viewed from two angles. And, more importantly, I think they have the same solution.
The problem is not AI. The problem is you going full auto.
There is a peculiar productivity competition happening in software engineering right now. Every week I see another impressive number: hundreds of thousands of lines generated, thousands of commits, dozens of agents running in parallel, or thousands of pull requests produced by AI-assisted development pipelines.
Uber, for example, has publicly discussed an internal AI coding system producing roughly 1,800 pull requests per week (1 PR each 80 seconds).
That is certainly an impressive throughput number. But whenever I see metrics like this, I find myself asking a slightly uncomfortable question:
What exactly are we optimizing?
A pull request is a unit of software delivery. It is not a unit of product value.
A software product is, at some level, encoded business logic. Its purpose is to solve problems: make something easier for a user, automate a process, reduce costs, create revenue, satisfy a regulatory requirement, improve reliability, or enable some new capability.
So the interesting question is not how quickly an organization can manufacture changes to a repository. The interesting question is how quickly it can discover, validate and deliver meaningful changes to the product.
Imagine someone tells you that their AI workflow can generate a thousand PRs in a relatively short period of time. Fine. Now ask them a different question: can you name the next important feature your product needs—right now?
And I don’t mean something sitting in the backlog already. I mean a genuinely new requirement. Something that has been validated rather than hallucinated by AI. Something supported by customer feedback, user behavior, business analysis, stakeholder needs, market research or other evidence that suggests building it will actually create value.
That is much harder. And definitely not possible at the rate of 1 feature per 80 seconds.
The reason is simple: once implementation becomes extremely fast, implementation stops being the primary bottleneck. Product discovery does not suddenly become a hundred times faster because your coding agent did. Neither do requirements analysis, UX research, architectural reasoning, stakeholder alignment or understanding what customers actually need.
At some point, enough is enough.
There is a finite amount of meaningful change that a product can discover, validate, absorb and maintain. Once AI gives us effectively abundant implementation capacity, maximizing the amount of code produced becomes a strange goal in itself.
And this is where I think full-auto development becomes dangerous. Not necessarily because AI writes bad code, but because execution can begin moving faster than understanding.
That is where comprehension debt starts accumulating.
My approach: Semi-Automatic AI-Native Development
The workflow I use has a deliberately cumbersome name: Semi-Automatic AI-Native Development with Human in the Loop.
I described the broader workflow in another article, so I won’t repeat the whole thing here. The important part for this discussion is the human in the loop.
I almost never use AI in full-auto mode for meaningful development work. I use it aggressively, but I try to be very deliberate about which part of engineering I delegate.
For me, AI is an extremely fast electronic typewriter, an implementation engine, a research assistant, a second opinion and a tool for validating assumptions. What I do not want it to become is a replacement for engineering judgment.
Before I ask an agent to implement something, I try to define the system it is going to operate inside as precisely as the task justifies. Depending on the feature, that means thinking through types, validation rules, business requirements, functional behavior, file structure, data flow, relationships between modules, API contracts, architectural boundaries and test expectations.
And one thing I care about particularly strongly is semantics.
What does this entity actually represent? Who owns this state? Where does this transformation belong? What responsibility does this module have? What does this abstraction mean in terms of the domain? Which concepts are genuinely different, and which are merely different names for the same thing?
Those questions are not formatting preferences. They are architecture.
Once those constraints are clear, AI can do what it is extraordinarily good at: execute quickly inside them.
Recently I came across a post from Robert "Uncle Bob" Martin that described a surprisingly similar philosophy.
His approach is more extreme than mine. He says he does not read the code generated by his agents; instead, he surrounds those agents with extensive constraints: unit tests, Gherkin tests, QA procedures, quality metrics, mutation testing, coverage and many other forms of automated verification.
I do still read AI-generated code. But the underlying idea resonates with me: the engineer’s job increasingly becomes designing the environment in which automated implementation is allowed to happen.
You create the constraints. You define the architecture. You specify the semantics. Then you let the machine move quickly inside that system.
Why I still review the code
When people argue that developers should review AI-generated code, the usual explanation is safety: AI can hallucinate, misunderstand a requirement, introduce a security problem or simply produce incorrect code.
All of that is true. But for me, there is another reason that is at least as important.
The generated code is feedback on the architecture I designed.
Before implementation begins, an architecture is partly a hypothesis. I believe these responsibilities belong in these modules. I believe this abstraction is sufficiently general. I believe this data flow is clean. I believe this type model represents the domain correctly. I believe these boundaries will continue to make sense when the next requirement arrives.
Then the AI implements the feature at high speed, and that hypothesis collides with reality.
Perhaps the abstraction turns out to be awkward. Perhaps data starts leaking across boundaries that were supposed to be clean. Perhaps a type requires exceptions everywhere. Perhaps two concepts that looked independent are much more tightly coupled than expected. Perhaps the agent repeatedly struggles with one particular part of the design.
Those are not merely implementation problems. They are signals.
When I review the result, I am not only checking whether the agent wrote acceptable code. I am checking whether my model of the system survived implementation.
That creates an extraordinarily powerful learning loop.
AI can make you learn faster, not slower
This is the part of AI-assisted development that I think gets far less attention than it deserves.
Without AI, much of a developer’s working day is consumed by execution. You design something, then spend hours or days typing it into existence. You write boilerplate. You perform repetitive refactorings. You search through documentation. You implement the twentieth variation of a pattern you already understand.
AI can compress a huge percentage of that execution time.
If you keep yourself inside the reasoning loop, the time you save does not have to disappear. It can be reinvested into the parts of software engineering where the real intellectual work happens: architecture, modeling, semantics, constraints, trade-offs and validation.
My workflow increasingly looks like this:
Design → constrain → let AI execute → inspect the result → learn → adjust the design.
Then another requirement arrives and the loop starts again.
The interesting part is the speed. Suppose I design an architectural approach and implementing enough of it to discover its weaknesses would traditionally take several weeks. With an agent, I may get that feedback in hours. Sometimes much faster.
That means AI does not merely accelerate implementation. Used this way, it accelerates the architecture-feedback loop.
You make a design decision. Reality tests it almost immediately. You learn. Then you make another design decision.
Do that repeatedly and something interesting happens: instead of spending most of your time exercising your ability to type code, you spend much more of it exercising your ability to design systems.
That is almost the opposite of “AI melting your brain.”
It is closer to deliberate practice for software architecture, with an implementation engine attached.
Of course, this only works if you actually stay in the loop. If you delegate the decisions, delegate the implementation, accept the output and move directly to the next prompt, the mechanism reverses. AI keeps learning about your codebase while you gradually stop doing so.
That is comprehension debt.
I probably won’t generate 1,800 PRs a week. That’s fine.
A semi-automatic workflow with deliberate human involvement is obviously slower than telling a swarm of agents to modify a repository as quickly as possible.
That does not bother me.
I want to produce exactly as much code as meaningful product development requires. If AI makes me capable of implementing useful changes faster than a product organization can discover and validate those changes, I have already won. More implementation throughput beyond that point has rapidly diminishing value.
The objective of software engineering is not to maximize the amount of software produced. It is to solve useful problems with software.
AI gives us an extraordinary opportunity to remove a large amount of mechanical work from that process. I think the mistake would be to remove ourselves from the intellectual work at the same time.
So yes, review the code. It may contain bugs. It may contain security issues. It may misunderstand your requirements. Those are all perfectly good reasons.
But review it for another reason too.
- Review it because it tells you whether your architecture was right.
- Review it because it forces you to maintain a mental model of the system you are responsible for.
- Review it because every implementation is an experiment, and every experiment gives you feedback.
And if AI can run those experiments dramatically faster than before, perhaps the technology that supposedly makes developers stop thinking can—used correctly—make us learn faster than we ever could before.
There is one line from Uncle Bob’s recent posts that summarizes the responsibility better than anything I could add:
That is the point.
You are not the engineer because you typed every line of code. You are not the engineer because you can explain every keystroke that created the repository. And you are certainly not the engineer because your AI generated more pull requests than somebody else’s.
You are the engineer because you are accountable for the system that comes out the other side.
What do you think?
How are you managing the balance between AI speed and system comprehension in your codebase? Do you use a human-in-the-loop workflow, or have you experimented with full-auto agents? Let me know in the comments below!
Top comments (0)