Add or fix a cache
A cache trades freshness for speed, and every cache goes stale in a specific way. Write the story before the code: key, scope, lifetime, invalidation, the race that can leave a stale value behind, and what happens when the cache is down. A cache without an invalidation plan is a bug on a delay.
Steps
- Prove the need. A measurement showing the same expensive read repeated (the
performance-profilingskill). If the fix is "stop calling it twice", batch the query, or add an index (thesql-query-performanceskill), do that instead. - Choose the innermost layer that solves it. Request-scoped memo (no invalidation
problem); process memory (fast, per instance, diverges across instances); a shared
store such as Redis (consistent across instances, one more dependency); HTTP caching
(RFC 9111:
Cache-Control,ETag/If-None-Match→304, CDN). Callsearch_lorefor the repo's cache helper, key prefixing and serializer; use it. - Design the key. Every input that changes the output is in the key: identifiers,
tenant, the caller's permission scope, locale, query parameters, and a schema or code
version. Missing tenant = data leak; missing version = old shapes after a deploy.
HTTP:
Varyon every request header the response depends on. - Set the TTL from the data. Ask how stale this can be before someone is harmed; that is the TTL. Add ±10–20 % jitter so keys written together do not expire together. TTL is the safety net, not the invalidation plan.
- Invalidate on every write path, after commit. List each code path that changes the source data in a comment beside the cache, and delete (not update) the key after the transaction commits. Deleting before commit lets a reader repopulate the old value. Also close the stale-set race: reader A misses and reads the old row, writer B commits and deletes the key, A then sets the old value, which stays until TTL. Guard with one of: versioned keys (bump a version on write; readers use the current version), a compare-on-set against a version tombstone (the write path replaces the entry with a tombstone carrying the new row version instead of deleting it, and a set succeeds only if its version is ≥ the stored one — a plain delete leaves nothing to compare), lease tokens that a delete invalidates (as in Facebook's memcache), or a short TTL when brief staleness is acceptable and stated.
- Guard against stampedes on expensive keys. On a miss, let one caller recompute
and the rest wait or serve stale: request coalescing / single-flight per key in
process, a short lock key (
SET key NX PX) across processes, probabilistic early refresh (XFetch), orstale-while-revalidate/stale-if-error(RFC 5861) for HTTP. The lock needs a timeout and a fallback so a crashed recomputer does not block reads; an expiring lock is acceptable here only because it guards work, not correctness (a lock that protects a write needs fencing: theconcurrency-and-asyncskill, step 5). - Fail open. A cache timeout or outage falls back to the source with a short client timeout; it is never a user-facing error. Do not cache errors; cache "not found" only deliberately and briefly. Emit hit, miss and eviction counters so the cache's value and a cold or failing store are visible.
- Never share what must not be shared. Authorization decisions, secrets and
per-user data are per-user keys or not cached. Responses that vary by session are
Cache-Control: privateorno-store; a CDN never caches a response carryingSet-Cookieor user data. - Test each behaviour, one test per AC exercising the AC's own behaviour, plus: hit,
miss, invalidation after each listed write path, TTL expiry with a fake clock (no
sleeps), cache-down fallback, two tenants never sharing a value, and for expensive
keys N concurrent misses causing one recomputation (parallel, per the
concurrency-and-asyncskill's step 9). For HTTP, assert the exactCache-Control,ETagandVaryheaders and the304path. - Evidence with the
record-evidenceskill: before/after numbers and test output.
Done when
- The key, TTL, invalidation paths and stale-set guard are written next to the code.
- Every write path invalidates after commit and is covered by a test.
- Cache outage degrades to the source; stampede is bounded for expensive keys.
- No per-user or authorization data can be served to another user or tenant.
Anti-patterns
- TTL-only caching of data users edit and expect to see immediately.
- Invalidating before commit, or updating the cached value in place from the write path.
- Keys built from a subset of the query parameters.
Cache-Control: publicon an authenticated response.- Tests that sleep for the TTL instead of advancing a fake clock.
Capture lore
This skill is one of the places durable, reusable knowledge naturally surfaces:
While designing the key you learn what is cached where, how it is invalidated and what went wrong the last time it was stale. That kind of fact is lore. Capture it via the lore-capture
protocol in your brief (CLAUDE.factory.md, step 11 "Memory contribution"):
call the Memory MCP suggest_lore once at the close of your work — reusable
conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.
