Imported from promovaweb/specsfy (
specialists/specsfy-specialist-redis/SKILL.md). Install upstream withnpx skills add promovaweb/specsfy --skill specsfy-specialist-redis. Copyright stays with the author.
Redis
Quando usar
- Acionar para desenhar cache, sessão, rate limiter, lock distribuído, fila simples ou stream sobre Redis/Valkey, ou para diagnosticar cache stampede, hot key, eviction inesperada ou indisponibilidade.
- Acionar também para revisar configuração de persistência (RDB/AOF), Cluster/Sentinel ou política de memória em produção.
- Não acionar para modelar o dado durável de origem: Redis é acelerador ou
estrutura efêmera; a fonte de verdade e sua integridade pertencem a
$specsfy-specialist-postgres(ou ao banco relevante). - Combinar com
$specsfy-specialist-observabilitypara métricas e alertas de cache em produção e com$specsfy-specialist-laravel/outro framework quando o driver de cache/fila da aplicação for Redis.
No Specsfy
-
Fonte de entrada por fase
- Em
specsfy-02-backlog, leia o item emspecs/backlog/e registre ali as decisões e sinais do especialista, além das dúvidas abertas. - Em
specsfy-03-specifyespecsfy-04-validate, use a spec aberta e devolva a conclusão à seção trabalhada pela fase. - Em
specsfy-05-tasks, ajude a sugerir e sincronizar especialistas e modos entre o cabeçalho, a seção 8 e as tarefas. Só essa fase escreve a seção 14. - Em
specsfy-06-implement, limite-se à tarefa indicada e ao passo carregado.
Nas fases com spec, leia a spec aberta indicada pela skill chamadora ou localizada por
specsfy status. Consulte a linha| Especialistas |, a subseção#### Especialistasem### 8. Plano técnicoe a seção pertinente à fase. Leia também.specsfy/STACK.md,.specsfy/RULES.mde, quando a chave ou a fila derivar de tabela existente,.specsfy/DATABASE.md. - Em
-
Siga o modo indicado na spec ou na tarefa, no formato
Especialista: $specsfy-specialist-redis. Sem indicação, confirme pelo "Quando usar" acima qual dado fica no Redis e qual é a fonte de verdade. -
Devolva a conclusão e as dúvidas abertas no destino indicado no item 1, no próprio backlog, na spec ou na tarefa da fase.
-
Não mude o estado da spec nem marque gate: isso pertence a
$specsfy-03-specify,$specsfy-04-validate,$specsfy-05-taskse$specsfy-06-implement. -
Quando a fase trabalhar o plano técnico da spec, registre chave, TTL, eviction e comportamento com Redis indisponível na seção 8. Indique quais dados são consultados no banco quando a chave expira ou o serviço cai.
Fluxo
- Definir a finalidade do dado (cache, sessão, fila, lock, contador), quem é o source of truth, a consistência necessária e a tolerância real à perda daquele dado se o Redis reiniciar vazio.
- Estimar cardinalidade, tamanho médio do valor, taxa de escrita/leitura, TTL necessário e o padrão de acesso (aleatório, sequencial, hot key concentrada).
- Escolher a estrutura de dado e um esquema de chave namespaced e estável
(
app:recurso:id), evitando chave dinâmica demais que exploda a cardinalidade de chaves. - Projetar explicitamente cache stampede, estratégia de invalidação, retry e o comportamento da aplicação quando o Redis está indisponível (fail open vs fail closed).
- Configurar limite de memória, política de eviction e persistência (ou ausência dela) conforme o papel do dado: cache tolera perda, lock e contador de negócio não.
- Testar concorrência (duas escritas simultâneas na mesma chave), expiração no meio de uma operação, indisponibilidade do Redis e recuperação (cold start após restart/failover).
- Medir hit rate, latência (p50/p99), uso de memória, número de conexões e hot keys antes de declarar a solução pronta.
Padrões
- Dar TTL explícito a toda chave de cache e definir, por chave, quem é responsável por invalidá-la (evento de escrita, TTL curto, ambos).
- Evitar comandos que travam o event loop single-threaded do Redis em
produção:
KEYS *,FLUSHALL/FLUSHDBfora de manutenção controlada,SORTsemLIMITem coleção grande; usarSCANcom cursor para iteração. - Usar operações atômicas nativas (
INCR,SETNX,GETEX) ou script Lua (EVAL/EVALSHA, executado atomicamente pelo Redis) quando a invariante exigir "ler e escrever" sem condição de corrida. - Tratar lock distribuído como lease com timeout e dono verificável: gerar
um token único no
SET key token NX PX ttl. Só liberar com script que confirmaGET key == tokenantes doDEL, nuncaDELincondicional. - Separar namespace/database lógico e política de eviction por workload incompatível: cache volátil e dado que não pode ser evictado (fila, lock) não competem pela mesma política de memória.
- Não serializar objeto sem versão de schema embutida (dificulta migração futura do formato) nem guardar segredo (senha, token bruto) em valor sem necessidade: Redis não é cofre de segredo.
- Confirmar a semântica de entrega antes de tratar Redis como fila: Pub/Sub é fire-and-forget (assinante ausente perde a mensagem); Streams com consumer group oferece at-least-once com ACK explícito e precisa de reprocessamento idempotente do lado consumidor.
- Confirmar servidor e versão (
INFO server) antes de usar recurso recente: política de eviction LRM, vector sets e os módulos JSON/Search/TimeSeries/ Bloom chegaram no Redis Open Source 8.x e não existem no Redis 7. Em Valkey, que segue linha própria, confirme se o comando ou módulo equivalente existe na versão instalada antes de depender dele.
Antipadrões
- Cache sem jitter no TTL: muitas chaves expirando no mesmo instante geram thundering herd contra o banco, adicionar variação aleatória ao TTL ou usar lock/refresh antecipado evita o pico simultâneo.
- Retry cego de comando não idempotente após timeout: se o comando original foi processado mas a resposta se perdeu, o retry duplica o efeito; use operação idempotente ou token de deduplicação.
- Chave com cardinalidade não controlada (
session:<uuid>sem TTL, acumulando para sempre): memória cresce sem bound até o Redis começar a evictar ou cair por OOM. - Lock distribuído implementado com
SETNX+DELsimples, sem TTL: um processo que trava ou morre antes doDELdeixa o lock preso indefinidamente. - Tratar
maxmemory-policypadrão (noeviction) como cache automático: commaxmemorydefinido enoeviction, o Redis passa a rejeitar escritas em vez de evictar, o que derruba a aplicação se ela não trata esse erro. Semmaxmemory, não existe limite nem eviction.
Validação
- Exercitar miss, hit, expiração no meio da operação, cache stampede simulado e Redis indisponível: cada cenário com o comportamento esperado documentado, não "deve funcionar".
- Verificar limite de memória, política de eviction, persistência e failover (Sentinel/Cluster) em ambiente que reproduz a topologia real, não apenas uma instância única de desenvolvimento.
- Observar
INFO, slow log (SLOWLOG GET) e métricas do cliente sem expor valor sensível nos logs. - Comparar o comportamento da aplicação com e sem cache para provar que o cache não introduziu dado desatualizado ou inconsistente no caminho crítico.
- Não declarar um lock "seguro" sem o teste de dois processos concorrentes disputando a mesma chave, nem uma fila "confiável" sem o teste de reprocessamento por reentrega.
Skills relacionadas
$specsfy-specialist-observabilitymede se Redis reduz o gargalo, verifica custo, cauda de latência e regressão sob carga e entrega as métricas e os alertas de cache em produção.$specsfy-specialist-postgresquando Redis for cache derivado de dado cuja fonte de verdade e integridade são do banco relacional.$specsfy-specialist-observabilitypara métricas, alertas e dashboards de cache em produção.$specsfy-specialist-laravelquando o cliente for o driver de cache/ fila/sessão do framework.$specsfy-specialist-dockerpara empacotar e operar Redis/Sentinel/Cluster, inclusive no cluster de produção.$specsfy-specialist-mysqle$specsfy-specialist-mongodbguardam a fonte de verdade que o cache e a fila nunca substituem.$specsfy-specialist-n8nquando o Redis for o broker do queue mode: aqui se define chave, TTL e eviction; lá se decide a topologia da fila.
Leia references/standards.md para estruturas de dado, persistência, cluster, segurança e padrões de cache.
