DESIGN.md works as agent memory only insofar as it survives the context reset: its prose can carry design intent that session-start and post-compaction re-injection reload as context, but nothing in the format enforces recall, and no measured study yet proves which part of it agents actually keep.
Every session starts from zero — that is the problem DESIGN.md answers
Agent design work loses its context at every session boundary, because each Claude Code session begins with a fresh context window How Claude remembers your project. DESIGN.md is an attempt to carry design intent across that boundary as a file.
The design.md repository describes the format as giving agents “a persistent, structured understanding of a design system” design.md repository. The premise is that an agent’s default state is amnesia: nothing from a previous session is present until something is re-read from disk. Google’s Stitch announcement makes the same bet, saying the format lets Stitch “understand the reasoning behind your design system” rather than guess at it Stitch DESIGN.md announcement. Anthropic’s own context-engineering guidance frames the underlying risk as context rot, where recall accuracy falls as tokens accumulate Context engineering cookbook. DESIGN.md is best read as a file written to be re-injected, not as memory in the human sense.
Claude Code already has a two-tier memory — and DESIGN.md is neither tier
Claude Code’s documented carry-over mechanisms are CLAUDE.md files (user-written) and auto memory (Claude-written), and both are loaded at the start of every session How Claude remembers your project. Auto memory is capped at the first 200 lines or 25KB of its file each session.
Neither tier is a design file. CLAUDE.md holds project rules and conventions, and auto memory holds Claude’s own notes about corrections and preferences. DESIGN.md therefore sits beside them, and its persistence depends on being referenced from one of them. The two-tier model also explains why a carefully authored design file can still be invisible: if nothing points to it at session start, the agent has no reason to open it. This is a placement problem before it is a format problem, which is why the comparison table below marks DESIGN.md’s survival as conditional.
What /compact keeps and what it silently drops
After compaction, Claude Code re-injects project-root CLAUDE.md, unscoped rules, auto memory, and skill descriptions from disk. Nested CLAUDE.md files and path-scoped rules reload only when matched again Explore the context window. So where a design file is referenced from determines whether it still reaches the agent after a long session.
The documentation’s own diagnostic for a vanished instruction is that it was given only in conversation, lives in a nested CLAUDE.md that has not reloaded, or is a path-scoped rule that has not matched a file since Explore the context window. The prescribed fix is to move conversation-only instructions into CLAUDE.md. For DESIGN.md, a file referenced only from a subdirectory may not be re-injected, and the agent will not necessarily know it existed. Placement is not a detail. It decides whether the memory mechanism fires at all.
“Context, not enforced configuration” — memory is advice, not law
Claude Code’s documentation states that memory files are treated as context, not enforced configuration, and points to PreToolUse hooks for hard blocks How Claude remembers your project. The exact wording is: “Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead” How Claude remembers your project.
Google’s philosophy document takes the same stance from the design side: “The token values serve as context and are not rendering instructions” PHILOSOPHY.md. Both vendors describe the same ceiling from opposite ends. The file informs; it does not compel. A rule such as “nothing animates longer than 300ms” is only as strong as the agent’s choice to honor it, and any claim that DESIGN.md enforces a design system overstates what either format promises.
The prose-first tradeoff — intent beats precision, until you need a check
The DESIGN.md philosophy puts the weight on prose. The document states that “the quality of a generated design is determined less by the precision of its values than by how clearly the intent is described” PHILOSOPHY.md. The spec standardizes only a name plus a few categories (colors, typography, spacing, rounded, components) and leaves motion, iconography, and elevation to the author.
That is a real strength for memory. Intent such as “what a color is for” tells an agent why a choice was made, which a bare hex value cannot. The weakness is equally real. Prose is not verifiable, and the spec explicitly declines to require tokens. The result is a format that is strong at carrying intent and silent on whether the intent was followed. For the token side of this debate, see our piece on design tokens as agent-readable language.
What a computable check can and cannot verify about a design
The philosophy document gives a concrete division of labor. In its motion example, the linter accepts the token values and agents read the prose around them: “the linter accepts these values and agents read the prose” PHILOSOPHY.md. Google’s announcement goes further, saying agents can “validate their choices against WCAG accessibility rules” Stitch DESIGN.md announcement.
What a check can confirm is narrow: that a value is present and well-formed, and that a color claim is measurable against a standard. What no check can confirm is whether the agent still holds the rule after a context reset, or whether the prose was loaded at all. A computable check validates the file, not the recall. For a stricter contract on the component side, see our piece on component spec files as an agent contract.
The tools agents actually need
The documented primitives in Anthropic’s guidance are compaction (summarize history), tool-result clearing (drop re-fetchable output), and the memory tool (structured notes in external storage) Context engineering cookbook. Each solves a storage problem. None verifies that a particular design decision survived.
Three gaps follow, and each is an open question rather than a documented feature. First, a recall check that confirms the agent still holds a design rule after a reset. Second, a hook that blocks a design-rule violation, as opposed to advising against it. PreToolUse hooks exist, but no DESIGN.md-specific rule hook is documented. Third, retrieval into the design file on demand rather than loading the whole file at session start. That last idea is the subject of targeted context lookup, and it matters because a whole design file in every session is wasteful when one rule is relevant.
Where DESIGN.md fits in the memory stack
DESIGN.md persists when a mechanism that reloads points to it. In the documented setup, a project-root CLAUDE.md is re-injected after compaction, and AGENTS.md can be read in place of CLAUDE.md How Claude remembers your project. A root memory file that references the design file is therefore the natural trigger, and the design file is the payload.
The weak link is the reference itself. The memory documentation’s own example of a pointer is a CLAUDE.md that tells Claude in words to read AGENTS.md. Under that pattern, Claude “sees AGENTS.md only if it decides to open the file” How Claude remembers your project. Whether the same holds for a DESIGN.md pointer is unverified. The repository’s roughly 28.4k GitHub stars show interest in the format, not that this wiring has been standardized or tested design.md repository.
The Bottom Line — what survives, what does not, what is unproven
Prose intent placed in a reloadable file survives resets and compaction as re-injected context. Anything left only in conversation does not. Token values carry no enforced rendering behavior, and whether agents retain prose better than tokens is untested Explore the context window.
What survives is placement. A design file referenced from a root memory file is re-injected as context. What does not survive is anything given only in chat, and any token value the agent treats as a suggestion PHILOSOPHY.md. What is unproven is the comparison at the heart of the format, since no measured study compares prose and token retention across sessions. DESIGN.md is a well-designed carrier for a memory mechanism that is still unenforced and unmeasured at the recall step.
Comparison table
| Memory mechanism | Survives session reset? | Survives /compact? | What kind of content it fits |
|---|---|---|---|
| CLAUDE.md (user-written) | Yes — loaded at the start of every session How Claude remembers your project | Yes — project-root file re-injected from disk Explore the context window | Project rules and conventions moved out of conversation |
| Auto memory (Claude-written) | Yes — first 200 lines or 25KB loaded each session How Claude remembers your project | Yes — re-injected from disk Explore the context window | Claude’s own notes on corrections and preferences |
| DESIGN.md prose | Conditional — survives if a reloadable file references it; the loading path for DESIGN.md itself is an open question design.md repository | Conditional — only via the referencing file’s re-injection; direct survival unverified Explore the context window | Design intent and reasoning, such as what a color is for or animation rules like “nothing animates longer than 300ms” |
| DESIGN.md tokens | Treated as context, not rendering instructions PHILOSOPHY.md | No independent mechanism; persistence depends on the containing file (open question) | Reference values a linter can check, not enforced rendering |
FAQ
Q: Does DESIGN.md survive a context reset? Only if a mechanism that reloads points to it. Claude Code loads project-root CLAUDE.md and auto memory at session start, so a DESIGN.md referenced from those files has a path to the agent. A design file that exists only in conversation, or only in a nested location, does not reliably reload.
Q: Is DESIGN.md enforced configuration? No. Claude Code’s documentation says memory files are context, not enforced configuration, and the DESIGN.md philosophy says token values are context, not rendering instructions. Both rely on the agent choosing to comply. Hard blocking needs a separate mechanism such as a PreToolUse hook.
Q: Why does the DESIGN.md spec avoid token requirements? The philosophy holds that design quality depends less on exact values than on how clearly intent is described. So the spec standardizes only a name and a few categories, and leaves motion, iconography, and elevation to prose PHILOSOPHY.md.
Q: What does /compact throw away? Compaction summarizes history but re-injects project-root CLAUDE.md, unscoped rules, auto memory, and skill descriptions from disk. Nested CLAUDE.md files and path-scoped rules reload only when matched again. Instructions given only in conversation do not come back Explore the context window.
Q: Has anyone measured whether agents retain prose rules better than tokens? No. No measured study comparing design-decision retention for prose versus token DESIGN.md was found for this review. Any such claim here is untested, and the evidence is documentation of reload behavior plus the stated philosophy.
Honest gaps and unverified claims
The Stitch DESIGN.md format page and specification page failed to scrape twice, so the published section list of the format is unverified here. This review relies on the repository, the philosophy document, and the Google announcement. No measured study compares design-decision retention across sessions, so every retention claim above is labeled untested. This review is based on official documentation — we did not run the tool hands-on.
How This Guide Was Built
This review was drafted by a multi-model pipeline. A research pass collected six primary pages: the Google Labs announcement, the design.md repository and philosophy document, two Claude Code documentation pages, and the Anthropic cookbook. Two Stitch spec pages failed to load and are reported as gaps. The orchestrator link-checked all eight external links (8 verified OK, 0 dead) and a separate QA pass checked claims against the saved source pages before publication.
HERO_IMAGE_PROMPT: A minimal editorial illustration of a glowing design-spec document half-dissolving into scattered tokens at a boundary line, the left side intact and structured, the right side fading into empty context, muted blue and warm amber palette, flat vector style, generous negative space, no text.