Why Claude Code forgets architecture decisions - and how teams stop re-explaining them

Claude Code opens a mature service and finds two ways to create a customer account.

One path creates the account before payment. The other waits until payment succeeds. The second path looks cleaner, so the agent proposes making both flows consistent.

The code is not missing. The tests are not missing. What is missing is the decision from six weeks ago: guest checkout must create the account first because a payment provider returns asynchronously in one market, and the team already rejected the cleaner design after it broke recovery.

Someone explains this. Claude fixes the plan. Three sessions later, the same suggestion returns.

This is the failure people describe as "Claude Code forgot our architecture." More precisely, Claude can still read the architecture. It has lost the reasoning that tells it which parts are intentional.

Claude Code remembers code better than reasons

A repository is a strong record of what the system is now. It contains interfaces, tests, comments, dependencies, and patterns that an agent can inspect.

But architecture is more than the current shape of the files. It includes decisions such as:

• why one boundary sits in the API instead of the client;
• which edge case made the obvious abstraction unsafe;
• why the team accepted duplication for now;
• which product promise constrains a technical change;
• who can approve an exception;
• whether an older rule is still active.

Those facts often live in Slack, a planning call, a ticket, a pull request, or one person's memory. A coding session sees only a slice of them.

Anthropic describes context as a finite resource that agents must manage deliberately. Compaction, retrieval, and tools can keep a long task moving, but none can recover a decision that was never stored in a form the next session can identify as current and authoritative. That is why context engineering matters, but it does not remove the need to decide what deserves to survive.

The symptom shows up after the first good session

The first session often feels excellent. The team explains the codebase, the customer constraint, and the plan. Claude works inside that rich context and produces a sound change.

Trouble appears later:

1. A new session starts with the repository but not the conversation.
2. An old session is compacted into a shorter summary.
3. Another engineer opens the same repo with a different personal setup.
4. The team switches between Claude Code, Cursor, and another agent.
5. Two agents work in parallel from different slices of the brief.

Each agent can make a locally reasonable choice. The conflict only becomes visible in review, integration, or production.

This is not a model-intelligence problem. It is a team-state problem.

What the common fixes solve - and where they stop

Chat history

Chat history is useful when one person needs to replay a recent session. It preserves detail and can explain how the agent reached a result.

It is a poor source of team truth. A long conversation mixes ideas, corrections, rejected options, pasted customer data, and the final call. The next reader must infer which sentence won. Another teammate may not have the same history at all.

Session summaries

A good summary reduces the cost of continuing work after compaction. It should carry the current objective, completed work, open questions, and important constraints.

But a summary belongs to a run. It can omit the exact reason a design was rejected, and it rarely records who owns a decision or what later replaced it. Use it to resume work, not to govern every future task.

CLAUDE.md

CLAUDE.md is the right baseline for stable instructions Claude should read in a repository: commands, directory structure, coding conventions, hard safety rules, and durable invariants.

It becomes fragile when teams use it as a running decision log. The file grows, old calls remain beside new ones, and product or customer decisions outside the repository never arrive. Nobody can tell whether a sentence is a current rule, an old preference, or one person's note.

The practical split is simple:

• put stable operating instructions in CLAUDE.md;
• put important decisions in records that can show owner, reason, status, and replacement;
• link the two when a decision must shape nearly every task.

For a broader comparison of the available context layers, see the best tools for giving AI coding agents your team's context.

Memory plugins and MCP servers

Memory plugins can preserve facts across sessions, and MCP servers can let an agent query live systems during a task. Both are valuable.

The remaining question is not only whether the agent can retrieve something. It is whether the retrieved statement is approved, current, relevant to this code path, and safe to act on.

A memory system may recall both "keep the legacy endpoint" and "remove the legacy endpoint." A team needs to know which one won and why.

Our guide to the best MCP servers for engineering teams explains where live context fits and why fewer, focused sources usually beat a large tool list.

ADRs

Architecture Decision Records are the strongest existing answer for important technical calls. A good ADR records the context, decision, consequences, and alternatives. It sits near the code and survives sessions.

The weakness is coverage. Someone must notice the decision, write the ADR, update its status, and make sure agents read it. Product decisions, customer promises, and cross-team exceptions may never become ADRs even when they constrain the architecture.

ADRs should stay. The next step is making their current decisions available to every relevant agent, alongside the non-architecture calls that affect the same work.

Save decisions, not entire conversations

When an architecture decision matters to future agent work, preserve a small, clear record:

• Verdict: what the team chose.
• Reason: why this option won.
• Rejected option: what looked plausible but failed, and why.
• Owner: who can confirm or change the call.
• Scope: the services, paths, APIs, product behavior, or customers it affects.
• Evidence: the incident, experiment, requirement, or tradeoff behind it.
• Status: proposed, approved, superseded, or expired.
• Replacement: the newer decision when the answer changes.

This record is more useful than a giant transcript because an agent can tell what it must honor without replaying the whole discussion.

It also serves the whole team. A product person can see which product promise shaped the architecture. An engineering lead can see who owns an exception. A developer can see why the unusual branch should not be "cleaned up." A coding agent can read the same active constraint before changing the code.

A workflow that survives the next session

A workable team loop looks like this:

1. Capture the call where it happens. Draft the decision from the Slack thread, ticket, PRD, review, or meeting instead of waiting for someone to remember later.
2. Ask the owner to confirm it. The system should not turn every sentence into a rule. One person approves the verdict and scope.
3. Connect it to the code it governs. Name the repository, paths, APIs, or capabilities affected.
4. Brief the agent before work starts. Retrieve only the active decisions relevant to the task.
5. Record conflicts instead of guessing. If the request contradicts an approved decision, stop and ask the owner.
6. Supersede decisions visibly. Keep the history, but mark the current answer clearly.

This is shared decision memory: not a copy of every conversation, and not a personal note file, but the small set of approved team calls that people and agents must carry forward.

When several agents work in parallel, the need becomes sharper. Two AI agents can each produce a reasonable change and still leave one codebase inconsistent if they start from different decisions.

How Lockstep handles the missing layer

Lockstep captures possible decisions from the tools where teams already work, asks the owner to confirm them, and keeps the approved record tied to what it affects. An MCP-compatible agent can retrieve the relevant active decisions before it changes code.

It does not replace CLAUDE.md, ADRs, Git, or your issue tracker. It connects the important calls across those systems and makes their status readable to both people and agents.

If you are choosing where to keep those calls today, compare decision-log tools for product and engineering teams. The best setup is the one your team will both update and read.

Claude Code does not need every conversation your company has ever had. It needs the right active decisions before it acts.

That is how teams stop explaining the same architecture twice.