Cognitive debt: the real cost of AI-generated code
The agent solved the problem and the theory stayed in the prompt. Notes on what gets left behind when the code is clean and the model in your head isn't.
I have been running autonomous coding agents on IGNIO for weeks. The code is clean. The tests pass. PRs merge themselves. By every chart I can point at, the system is working.
But sometimes I open a file and realize I have no idea why it was built that way. The agent made the decision. I approved it. The understanding never made the trip from the prompt into my head.
There is a name for it. Cognitive debt.
Different from technical debt
Technical debt is something you can see. A duplicated function, a hardcoded variable, a class doing the work of two. It lives in the files, you can point to it, and you pay it down by refactoring.
Cognitive debt lives in your head, or rather, in the absence of something that should be there. The code can be clean, well-structured, fully covered by tests, and the debt is still real if nobody on the team can explain why the design looks the way it does. The shape of the system is on disk. The reason for the shape is not.
The real program is not the text on the screen. It is the mental model the author holds: why these components connect, why this approach won over the others, how the thing will react when you change one part of it. When the agent produces the code, that model can fail to transfer at all.
Cognitive residue
The phrase that hit hardest came from a community thread on the topic. Someone called it cognitive residue.
When you iterate with an agent you prompt it, you reject option A, you reject option B, you land on option C. The rejected options do not vanish. They leave ghost paths in your brain. You spent real attention reading them, evaluating them, dismissing them. Days later you cannot reconstruct how you arrived at the final answer, because the reasoning is scattered across a chat log you will never reopen.
Textbooks and official documentation used to filter the bad ideas for you. An editor had already done that work. Now the agent generates infinite options and you are the filter. The filtering itself has a tax.
My own wake-up call
The pattern showed up on IGNIO when I started merging more agent PRs. Code clean, tests green, review passed. Weeks later I opened certain files with the sinking feeling that I shipped them and could not explain them.
One case in particular. The agent restructured how email preferences behave when subscription tiers are bypassed. The fix was correct, the tests proved it, the PR description summarized the change. When a related bug came up a month later I had to reread the entire diff to reconstruct the reasoning, because the mental model was never mine to begin with.
The agent solved the problem. The theory stayed in the prompt.
What I changed
The first move was a rule in the agent workflow: every PR description has to document not just what changed, but why it was done that way. The reader is future me. The agent already knows the what by the time it opens the PR; making it write the why costs almost nothing and pays back the first time a related bug shows up.
Decision files came next. The CLAUDE.md and AI_INSTRUCTIONS style, where the reasoning behind real architectural choices lives in prose. When a new agent session starts, those files are the first thing it loads. The theory does not have to live in my head if it lives in a file the next session will read.
The harder change is slowing down on the calls that matter. Speed is intoxicating when the agent makes everything feel instant, and every shortcut is a small withdrawal from your own understanding of the system. Sooner or later the account is overdrawn.
AI already knows the what. The part nobody else can do for you is the why.
Inspired by Margaret-Anne Storey’s post on cognitive debt and the discussion it started.