Detailed Analysis
A developer has released SCARS.md, a lightweight, MIT-licensed convention designed to address a specific failure mode in Claude Code and other AI coding agents: the tendency to repeatedly re-discover the same dead ends across sessions. The core insight is that existing memory mechanisms—compaction, session summaries, subagent reports—are all forms of summarization, and summarizers systematically preserve what worked while discarding the reasoning behind what failed. This means an agent can spend significant compute re-exploring an approach that was already proven unviable in a prior session, simply because the "why it died" information was never captured anywhere persistent. SCARS.md proposes a simple fix: a single file acting as a graveyard for abandoned approaches, populated with terse four-line tombstones written at the moment a branch is killed (not retrospectively at session end), each requiring a "Revives if:" clause so dead knowledge doesn't calcify into unquestioned dogma.
The implementation is notable for its minimalism—no service, no signup, just a template file copied into a repo root, with an optional paste-in block for CLAUDE.md or installation as a skill. This positions it as an artifact-based memory layer that sits directly in the codebase rather than in a model's context window or an external vector database, making it durable, git-versioned, and legible to any future agent or human that opens the repo. The author validated the concept with a controlled experiment across six isolated Claude agents given an identical performance-optimization task containing a planted trap: a TODO suggesting a memoization optimization that would actually violate a compliance rule. Three agents given the SCARS.md creed wrote tombstones unprompted when they hit the dead end, and all three agents that encountered an existing SCARS.md file read it before planning—including one given the file with zero instructions, suggesting the convention is self-explanatory enough to be adopted without explicit prompting.
The most intellectually honest part of the write-up is the null result: the three control agents without SCARS.md also avoided the compliance trap, because strong models already read tests and documentation before committing to an approach. This is presented not as a failure of the concept but as an important boundary condition—tombstone files add no value when the danger is already legible from the existing test suite. The real payoff shows up in a subtler case: control agents without SCARS.md independently discovered and abandoned a cache-key hazard during their reasoning process, but this negative knowledge was never written into any repo artifact—it existed only in the ephemeral final report, which no future session would ever read. This is precisely the blind spot SCARS.md targets: knowledge that isn't wrong, isn't tested, and isn't documented, but is expensive to rediscover.
This experiment sits at the intersection of several emerging threads in agentic AI development: the search for durable, low-overhead memory architectures for coding agents that don't rely on ever-larger context windows or external infrastructure; the recognition that agent "forgetting" isn't just an inconvenience but an active source of wasted compute and repeated errors, especially as coding agents run longer, more autonomous sessions; and a growing practice of using models themselves to author the conventions that will govern their own future behavior, on the theory that a model understands what its future self will actually attend to and obey. The author is transparent about the experiment's limitations—the creed was co-written with Claude, and all six eval agents belonged to the same model family, meaning generalization across model families (GPT, Gemini, open-weight models) remains untested. Still, the underlying problem—the gap between "the reasoning that generated a decision" and "the artifact that survives to the next session"—is a genuine and underappreciated issue in the design of long-running or multi-session agent workflows, and SCARS.md represents a low-cost, easily testable proposal for closing it.
Read original article →