Detailed Analysis
A Reddit post detailing a practical workaround for one of Claude Code's most persistent friction points has gained traction among developers using the tool for extended coding sessions. The core problem the user identifies is context compaction — the process by which Claude Code summarizes or trims earlier conversation history once a session grows too long for the active context window. While compaction preserves the tangible artifacts of a session (the code itself), it strips out the reasoning trail behind decisions: why a queue was chosen over a cron job, why a database field was made nullable, why an ORM call was deliberately replaced with a raw query. Without that reasoning intact, Claude frequently reintroduces previously rejected approaches, forcing the developer to re-explain and relitigate choices that had already been settled hours earlier.
The fix described is notably low-tech: the user instructs Claude, via a CLAUDE.md configuration file, to maintain a running DECISIONS.md log, appending a single line each time a non-obvious choice is made — what was chosen, what was rejected, and a one-sentence rationale. The critical second half of the trick is instructing Claude to read that file at the start of every planning step. This ensures that even after compaction wipes conversational memory, the model deliberately reloads its own prior reasoning from a file that exists outside the context window entirely. In the concrete example given, mid-migration and four hours into a session, post-compaction Claude began reintroducing an ORM call that had been rejected earlier due to a locking issue under batch processing; rather than requiring human correction, it consulted the log, found the rejection reason, and proceeded correctly.
This matters because it exposes a structural limitation in how large language model coding agents handle long-horizon tasks. Context windows, no matter how large, are finite, and compaction or summarization is an unavoidable mechanism for managing that constraint during extended agentic sessions. What gets lost in compaction isn't usually the "what" — code, file structure, task state — but the "why," which is precisely the information most expensive to reconstruct and most costly to lose, since it governs whether the model repeats past mistakes. The workaround effectively externalizes memory into the filesystem itself, treating a plain markdown file as a lightweight, human-readable, persistent knowledge store that survives session boundaries in a way the model's internal context cannot.
The approach also reflects a broader pattern emerging in how developers work with agentic coding tools like Claude Code: rather than waiting for vendors to ship formal memory or retrieval systems, practitioners are building ad hoc scaffolding using the tools already available — configuration files, markdown logs, and explicit read/write instructions embedded in system prompts. This mirrors earlier community-driven patterns such as maintaining PLANNING.md or TODO.md files to track task state across sessions, but this technique specifically targets decision provenance rather than task progress. It's a cheap, dependency-free solution that requires no MCP server, no vector database, and no external memory architecture — just disciplined prompting and a text file. The thread's closing question, about whether a more structured entry format (rather than freeform notes) would help Claude parse its own history more efficiently, points toward where this pattern likely evolves next: quasi-standardized logging schemas that agentic coding tools could eventually adopt natively, turning a community hack into a built-in feature for managing long-running, context-constrained development sessions.
Read original article →