Cognitive Debt

April 7, 2026

As people use agents to write more code, they are discovering they are trading "tech debt" for "cognitive debt".

When we develop software by hand, we certainly write lines of code. But we also do the cognitive work that builds our internal model of the program. We generally understand the theory of how data flows through the system, how it is transformed, and its resting place.

But when we outsource code writing, we risk skipping this hard but necessary step. Our understanding is shallow, so if we have to create a theory about it, we're stuck. For example, when I encounter a bug in prod (I ship bugs, too!), I form an idea of the root cause. I do this based on my internal representation of the program as a system.

Now that I get agents to write all the code, I have to find other ways to build that mental model. I have two strategies: architectural patterns and decomposition.

I specialize in backend. I typically build event driven microservices. As I work with the agent to get it to build the software, I always ask it about event flow through the system. When it adds features, I know exactly which service it touches. So I may not know the exact code, but I know what the service does and how it does it via the messages it processes.

For decomposition, I'm quite strict about separation of concerns. A regular question I ask of the agent: what are the bounded contexts for this, and what is the concern? This technique has often nudged it to change the home of some new feature it was implementing.

Together, these let me form a mental model of the system as a whole: what the services do and the messages that flow through them. So when I encounter a bug, I can pretty quickly figure out which service is the most likely suspect, and when I drill into the service I can find the message handling code that does it.

Yes, I have debt on the code, but I am always up to speed on the system.