I started keeping a tiny “decision log” for my AI coding sessions

One thing I've noticed after using AI agents across the same project for a while:

The agent usually doesn't forget what the code does.

It forgets why we decided to do it that way.

That distinction starts becoming painful after a few weeks.

You revisit a feature and the agent suggests:

• introducing an abstraction we deliberately avoided

• changing an API that has an unusual constraint

• removing a workaround that exists for a reason

• replacing a dependency we intentionally pinned

The code doesn't explain those decisions very well.

So I started keeping a very small decision log alongside the project.

Nothing complicated.

Just entries like:

Decision: Keep the validation inside this service.

Reason: Two other workflows depend on different validation rules.

Or:

Decision: Don't automatically retry this operation.

Reason: The operation isn't idempotent.

Then, before starting a larger task, I give the agent the relevant decisions along with the codebase context.

The interesting part is that this takes much less effort than documenting the whole architecture.

I'm not trying to document everything.

I'm documenting the decisions that would otherwise become mysterious six weeks later.

It has made me wonder whether AI-assisted projects need a new kind of documentation:

Not just:

"How does the system work?"

but also:

"Why did we choose to make it work this way?"

How are you preserving that reasoning in longer-running AI-assisted projects?