Why your coding agent keeps undoing your architecture

Your coding agent is not malicious. It's amnesiac.

Every session starts fresh. The agent sees your code but not the eighteen months of decisions that shaped it. So when it spots something that looks suboptimal—a service boundary that adds latency, a data model that seems over-normalized, an auth flow with extra steps—it "fixes" it.

I watched this happen on a project last month. An agent consolidated three microservices into one because the separation "added unnecessary complexity." The separation existed because we'd learned the hard way that those services scaled differently under load.

Architecture is still important, and it always will be for anything that matters. Architecture lives in decisions, not just code.

The agent didn't know that. It couldn't know that. The knowledge existed only in conversations and memories, not in anything retrievable. This is likely sometime you spend 30 minutes going in a direction and throwing everything out when the agent ultimately goes against some decision it wasn't aware of.

The fundamental problem is context window limits. LLMs have working memory, not long-term memory. Your entire architectural rationale doesn't fit in the prompt. What doesn't fit gets dropped. What gets dropped gets ignored.

Think of your codebase as a state machine. The code is the current state. The decisions that shaped it are the transitions. Your coding agent can see the state. It cannot see the transitions.

We are doing all kind of things to keep the agent up to date in this manner. Writing long architectural documents that obsolete as soon as they are written. Writing ADRs that in themselves describe the change and various reasons for it is easy to keep up to date and also easy to understand and supersede.

Architecture Decision Records are purpose-built for this. An ADR captures a decision, its context, and its consequences. That's exactly the information an agent needs to avoid destructive "improvements."

But most teams treat ADRs as passive documentation. The insight is treating them as an agent-navigable graph of decisions and their consequences.

Add machine-readable metadata to each ADR: Status (proposed, accepted, superseded), Subsystem (api/auth, db/schema), Supersedes (the decision this replaces), Related (connected decisions). Now you have a linked decision log. An agent touching the auth subsystem can walk back five decisions and understand why things look the way they do.

The protocol I've settled on: agents must read AGENTS.md (or whatever) plus recent or relevant ADRs for affected subsystems before starting work. When proposing significant changes, they must draft a new ADR explaining what they're changing and why. The agent becomes a participant in the decision log, not just a code generator.

The result is continuity. The agent can't rely on chat history across sessions. But it can rely on ADRs, because they persist in-repo and reload on demand.

So stop treating ADRs as human documentation. Start treating them as agent memory.

Agents that understand why, won't undo what works.

I might share my workflow at some point here, subscribe if you are interested.