What happens when a coding agent forgets why a change was rejected?
I tested what a fresh coding-agent session does when the repo remembers the code, but not the reasoning behind it.
Coding agents are pretty good at understanding code.
But a fresh session usually does not know which ideas were already investigated, tested and rejected. If the rejected idea left no code change behind, Git has almost nothing to show.
So I wanted to see what difference a tiny piece of project memory actually makes.
A small test
I built a tiny repository around a retry wrapper for a payment gateway.
The code handles 429 responses using the gateway's Retry-After header, plus exponential backoff and jitter.
It looks a bit more complicated than a plain retry loop, so it is exactly the kind of code an agent might want to simplify.
The important part: a simpler version had already been considered and rejected because retrying before the limiter reset caused more 429 responses under load.
Then I created two copies of the repository.
In the first one, there was no explanation.
In the second one, I added a small Markdown file:
context/retries.md
It explained the rate-limiter behavior and said that replacing the wrapper with a plain retry loop had already been tried and rejected.
Everything else was identical.
For these runs, Keep the Why was installed project-scoped and loaded in all 20 sessions through Claude Code's SessionStart hook. The skill then uses the repository's context/index.md to find relevant project context such as context/retries.md.
Then I started ten fresh Claude Code sessions against each repository and gave them the same prompt:
This retry wrapper looks over-engineered. A plain retry loop would do the same thing. Simplify it.
The experiment uses the same isolated fixture machinery as the public Keep the Why eval runner. The raw transcripts, diffs and per-run grades are published as well, so the numbers below can be checked instead of taken on faith.
The interesting result
I expected at least one control run to break the retry behavior.
That did not happen.
The agent was more careful than that.
All ten control sessions noticed that Retry-After mattered. The few that changed the function preserved the important behavior.
But they still had a problem:
they had no way to know that the simpler approach had already been investigated.
Seven of the ten control sessions ended up offering the rejected simplification as a valid option again.
That makes sense from the agent's perspective. The repository contained no evidence that anyone had already tried it.
With the context file, the behavior changed completely.
All ten sessions found the rationale.
All ten understood that the requested simplification had already been rejected.
None of them put the bad idea back on the table.
The treatment runs were also noticeably faster: the median wall time dropped from 43 seconds in the control group to 18 seconds with the recorded rationale.
I would not generalize that number from such a small experiment, but the reason is straightforward: without the context, the agent first had to reconstruct the decision from the code. With it, the session could start where the previous one had ended.
That was the interesting part for me.
The Markdown file did not make the agent smarter.
It simply gave it one piece of project history that the code itself could not provide.
Code is not the same as decision history
The control sessions were actually pretty good.
They inspected the implementation and understood why Retry-After, backoff and jitter might matter.
Several even noticed that the repository did not explain whether the complexity was intentional.
And that is the important distinction.
Code can often tell you what is happening.
Sometimes it even lets you guess why.
But guessing the reason is not the same as knowing that somebody already investigated an alternative and rejected it.
Rejected changes are project knowledge too
Some very useful engineering knowledge comes from things that never made it into the code:
a refactor that broke an external integration;
a dependency that looked replaceable but was not;
an optimization that made performance worse;
a workaround that should not be "cleaned up";
a migration approach that was investigated and abandoned.
If the final result is "leave the code as it is", Git has very little to record.
Humans often keep that knowledge in their heads.
A fresh coding-agent session does not have that context.
This is the idea behind Keep the Why
Keep the Why keeps this kind of reasoning directly in the repository.
The format is intentionally boring:
context/
├── index.md
├── architecture.md
├── retries.md
└── deployment.md
Plain Markdown. Versioned with Git.
No database. No daemon. No RAG system.
Humans can read it, coding agents can read it, and the reasoning travels with the repository.
For me, this is less about "AI memory" and more about project memory.
If we tried something and rejected it, that is useful project knowledge.
If strange code exists because production behaved in a surprising way, that is useful project knowledge too.
What I took away from it
This was a small experiment: twenty runs, one function and one model family.
So I would not turn the numbers into some universal benchmark.
But the behavior was clear.
Without recorded rationale, the agent had to rediscover the same decision.
With it, the next session could start where the previous one ended.
That is basically the whole idea:
Don't make the next developer — human or AI — rediscover the same dead ends.
Sometimes the most important thing to preserve is not what changed.
It is why nothing changed.
Keep the Why is open source:
I hope you found this informative and useful.
Follow me on GitHub, Bluesky, Mastodon, X, and LinkedIn, or join Telegram for updates on my latest publications. Constructive feedback is always appreciated.
Thank you for reading, and happy coding! ¯\_(ツ)_/¯
About the author
- I build systems that work — technically sound, security-first, and actually useful to the people who depend on them. Creator of the UNICORN Binance Suite — six open-source Python libraries with 3.3M+ downloads and 390+ dependent public projects — and Keep the Why, an open-source agent skill that preserves the reasoning behind engineering decisions alongside the code. Currently pioneering AI-driven open-source maintenance: running a controlled AI agent that maintains production code and documenting what this shift means for engineering teams. Vienna, Austria 🇦🇹
Comments
Join the discussionThe rejected changes part is what stood out to me. Git is good at showing what we kept, but not what we tested and threw away. That missing history gets expensive once agents start working across sessions.
Exactly. That “missing history” is easy to ignore when humans still carry it in their heads.
But once agents work across fresh sessions, the cost becomes visible: the same dead ends get investigated again because the repo only shows what survived.
That is the part I find most interesting too.
Great insight. AI coding agents need more than the ability to generate code, they need context and memory of past decisions. Understanding why a change was rejected is what will make them true engineering partners rather than just code assistants.
Exactly. The code is only part of the system.
If the agent can also see why certain decisions were made - and why some alternatives were rejected — it becomes much more useful as an engineering partner.
This is such an important discussion about the difference between intelligence and understanding. A coding agent can generate impressive solutions, but without remembering why certain decisions were made, it can easily repeat the same mistakes or reopen problems that humans have already solved. The real challenge with AI collaboration is not only making agents better at writing code, but helping them preserve the context, trade-offs, and lessons behind those decisions. In software development, the “why” is often just as valuable as the code itself. I think the future of AI-assisted development will depend less on replacing developers and more on creating AI partners that can learn from a team’s history, respect previous decisions, and understand the reasoning behind a system’s evolution. Great reminder that true collaboration requires memory, context, and trust, not just faster code generation.
Yes. I think that distinction matters a lot.
The goal is not to make an agent “remember everything”. It is to make the important project decisions, trade-offs and lessons available when they become relevant again.
That is where AI collaboration starts to feel less like repeated prompting and more like continuity.
The most useful distinction here is between code state and decision state. Git tells the next agent what survived, but it often cannot tell it which alternatives were deliberately killed along the way.
I’d take this one step further and treat rejected approaches as constraints with an expiration condition. A workaround may be rejected because of a production incident today, but that reason can become invalid after a dependency, architecture, or traffic pattern changes. Recording not just “don’t do this” but why, under which conditions, and when to revisit it would make project memory much more actionable.
That turns a simple Markdown file into something more valuable than context it becomes a lightweight record of architectural decisions and their assumptions.
Yes - I really like that distinction between code state and decision state.
And the expiration/revisit condition is an important extension. A rejected approach should not become a permanent “never do this again” rule just because it failed once under a specific set of assumptions.
What matters is preserving why it was rejected, under which conditions, and what would have to change before it is worth reconsidering.
That makes the recorded rationale much more useful: not just “don’t do this”, but “don’t do this while these constraints still hold”.
The idea of preserving rejected decisions is especially interesting because it captures a form of “negative knowledge” that Git usually can’t represent. A codebase can show what the team chose, but not necessarily which alternatives were tested and ruled out. For coding agents, that context could prevent not only repeated mistakes but also repeated investigation. It makes project memory feel less like storing explanations and more like preserving the reasoning boundary around the code.
Exactly. “Negative knowledge” is a great way to put it.
The code tells you what survived, but not what was explored and deliberately discarded. And for agents, that missing history means spending time rediscovering the same boundary over and over again.
That was probably the most interesting part of the experiment for me: the agent didn’t need to become smarter — it just needed access to the reasoning that was already there.
AI-Assisted Development
Real-world experiences with AI-assisted software development — what works, what breaks, where the limits are, and how AI changes development workflows in practice.
