Why it matters: AI models redraw architectural boundaries they never understood in the first place, and nothing in your pipeline flags it as a mistake.
The Details:
Every session an AI model runs starts from zero. The tradeoffs that shaped a module, why validation stays separate from persistence, why one class does not own two concerns, existed only inside the conversation that produced them. Once that conversation ends, the code remains but the thinking behind it is gone, so the next session re-derives the design from scratch.
Bigger context windows do not fix this. A larger window still resets at the start of every new session, and inside a single long session the model does not weight information evenly: a constraint documented in the middle of a file gets less attention than code sitting at the edges. The model can see a boundary and still discount it, not from carelessness but from how attention spreads across a long prompt.
Two modules that split authentication from authorization look, on a fresh read, like an obvious merge candidate: same user, same vocabulary, same gatekeeping role. Without a record of why they were split, an AI or a new engineer merges them and reintroduces the exact security flaw the split was built to prevent.
The fix is not a wiki page or a project-level config file read once at session start. It is a short note placed directly inside the file, at the point of decision, explaining why the boundary exists and what broke before it did. Proximity is what makes the reasoning survive contact with the next editor, human or model.
Bottom Line: Codebases now need their design reasoning written where the next reader will actually be standing, because that reader arrives at every keystroke with no memory of what came before.
Enjoy this article?
Listen to the Claude Code Conversations radio show or join the community.
