[BUG] Claude is constantly forgetting what we did 5 minutes ago, or yesterday, or whatever

Environment

• Platform (select one):
• [x] Anthropic API
• Claude CLI version: 1.0.51 (Claude Code)
• Operating System: Manjaro
• Terminal: Konsole

Bug Description

So this isn't a bug per se, but it feels like a fundamental design flaw that's limiting the way that I want to work with Claude Code.

I've been working with Claude Code a lot these past few months. One of the things that I've noticed that is really frustrating - we will implement together some functionality, get it to work in a certain way. And then we'll go back and refactor that. Wow, this is so dangerous, because Claude has forgotten all of the original specifications that we painstakingly discussed. Claude ends up building something crazy that diverges from the original spec, and then we spend time trying to find our way back.

I'm wondering if something can be done so that Claude has a more canonical place to store the design specs and their evolution. Already, I do my best to have Claude update documentation and tests, and to store inline documentation in the code (I've found this works way better than putting it in separate files, because if the docs are inline then Claude will automatically read them when it is reading the relevant code.) I use slash commands to standardize the operating procedures for Claude. But somehow this isn't enough to prevent divergence.

I notice Claude's commit format seems to be somewhat baked into the model, or baked into the preamble. I wonder if git would be the proper place to capture design specs and their evolution? Maybe if Claude had more of an instruction to associate the original design specs with the implementation checkin, and if subsequently Claude also had the knowledge to go back and check on this commit history when doing a refactor.

I can (and will) experiment with implementing this through slash commands. But I wanted to document the experience here, because I know you're constantly improving the base model and experience, and it feels like something where better default behavior would probably save your users a lot of time and frustration.

I know we're breaking new ground here, and reconstructing human processes which have become "obvious" and subconscious for many of us. So it requires resurfacing and revisiting our own learning experiences to determine "how could I give Claude better affordances so that it knows the right thing to do?" Very similar to working with human employees...

Cheers to the Anthropic team, and thanks for all you do!

Steps to Reproduce

Kind of hairy, but I'm thinking this is something that anecdotally many of us are experiencing?

I've experienced this on a ~10,000 LOC project, and on a ~1500 LOC project. I most recently observed this when refactoring a query runner which previously had mixed execution/parsing implementations into something with clear boundaries between parse and execution, and that is where feature regression/misinterpretation happened. The tests weren't sufficient to prevent it, because the functionality appeared to be correct, but Claude had actually pulled from the wrong data to accomplish it.

If you want I can try to construct a better reproduction environment for this. But tell me if this is something that even interests the team to work on and if you need that.

Expected Behavior

Claude should understand the original functionality and match it when performing a refactor.

Actual Behavior

Divergence from the spec, implementation of features and ways of working that were never asked for.