My AI agent doesn't forget code. It forgets why we made the decision

I've noticed a different kind of context problem while working with AI coding agents.

• The agent can read the code.

• It can inspect the git history.

• It can find the files it needs.

But sometimes it still misses something important:

Why we made a particular decision in the first place.

For example:

• Why we deliberately didn't use an abstraction

• Why an API is handled differently in one workflow

• Why a certain dependency is pinned

• Why a seemingly duplicated piece of code exists

• Why we chose a less elegant solution because of a product constraint

None of that is necessarily obvious from the code.

So I've started writing down decisions separately from implementation.

Not a huge document.

Just things like:

Decision: Keep this logic local.

Reason: The shared abstraction created problems with two existing workflows.

Or:

Decision: Don't auto-retry this request.

Reason: The operation isn't idempotent.

That small amount of context changes the next AI session quite a bit.

The agent isn't just seeing:

"Here's the code."

It's seeing:

"Here's the code, and here's why this code ended up this way."

I'm starting to think that as AI writes more of the codebase, decision history may become as important as documentation.

How are you preserving the reasoning behind architectural or product decisions in AI-assisted projects?