| name | caching-strategy |
| description | Adds caching that speeds reads without serving stale or wrong data. Use when a read is expensive and repeated, when adding or tuning a cache layer, or when debugging stale-data and invalidation bugs. |
Caching Strategy
A cache trades freshness and complexity for speed. Gains are real; invalidation bugs serve wrong data
to users and are hard to reproduce. Cache deliberately — know what you're caching, for how long, and
exactly how it becomes correct again.
The caching patterns reference has layer selection, invalidation
models, key design, HTTP headers, stampede prevention, security, and the full checklist. Use this
skill for decisions; use the reference while implementing.
When to Use
- A read is expensive (slow query, remote call, heavy computation) and happens repeatedly
- The same data is requested far more often than it changes
- Adding or tuning a cache layer (in-memory, Redis, HTTP/CDN, client data layer)
- Diagnosing stale data, thundering herd, or invalidation bugs
Don't reach for a cache first — confirm there's a measured read cost ([[perf-budget]]); often a better
query or index ([[data-modeling]]) beats a cache. If the cache sits behind a network call, pair with
[[resilience]] for timeouts and graceful degradation when the cache or origin fails.
Process
- Confirm it's worth caching. All three must be true: expensive read (measured), read-heavy access
pattern, and explicitly acceptable staleness. Skip cheap reads, exactness-critical data, and huge
rarely-reused working sets. See When to cache in the reference.
- Pick the narrowest layer that fits. Request memo → process memory → shared cache → HTTP/CDN →
client — each adds scope and invalidation complexity. Don't stack layers without a reason. See the
layer table in the reference.
- Choose invalidation before writing cache code. TTL, write-invalidate, versioned keys,
event-driven purge, or stale-while-revalidate — pick one primary strategy and document what
"correct again" means. No strategy = don't ship the cache.
- Design keys to include every dimension. Tenant, user, locale, params, version — a key that omits
one serves wrong or leaked data. Namespace and hash large param sets. See Cache key design.
- Bound size and prevent stampedes. Eviction policy (LRU, TTL, max memory) so the cache can't
grow without limit. Single-flight, TTL jitter, or SWR for hot keys so expiry doesn't crush the
origin ([[resilience]]).
- Apply security rules for shared caches. No per-user or sensitive data in CDN/public cache without
scoped keys and correct
Cache-Control. Treat Redis entries as sensitive if they hold user data
([[hardening]]).
- Instrument and verify. Hit rate, miss latency, evictions, stale serves. A low hit rate is cost
without benefit — remove or fix keys/TTL ([[observability]]). Measure before/after on the hot path.
When debugging stale data: identify the layer, inspect the key, trace every write path for invalidation,
then reproduce with cache bypass. See Debugging stale-data bugs in the reference.
Common Rationalizations
- "Add a cache, it'll be faster." — Without invalidation, users get stale or wrong data; debugging costs more than you saved.
- "TTL of an hour is fine." — Only if an hour of staleness is acceptable to the product; decide explicitly.
- "The key is just the id." — Missing tenant, locale, or version leaks or corrupts data across users.
- "Cache everything." — Cheap or rarely reused data adds complexity and memory for no measured gain.
- "We'll invalidate later." — Every write path you miss stays wrong until TTL; design invalidation first.
- "Redis is fast enough." — A stampede on miss turns Redis into a fuse to your database.
Red Flags
- Cache added before read cost was measured on the hot path
- No defined invalidation strategy or missed write paths
- Keys missing an input the cached value depends on
- Unbounded in-memory or Redis usage with no eviction
- Personalized responses cached as
public or under a global key
- Hot key expiry causing origin overload (no single-flight or jitter)
- No hit-rate or miss-latency metrics; stale bugs reported by users first
Verification
