Piyush-Nagar/coding-agents-skills

Você não pode corrigir o que não pode ver. A observabilidade é projetada desde o início, não é adicionada após um incidente. Se uma pergunta sobre produção precisa de uma alteração no código para ser respondida, a instrumentação está errada.

O que é coding-agents-skills?

Esta skill estabelece padrões rigorosos de observabilidade para sistemas de produção, garantindo que engenheiros possam diagnosticar problemas sem depender de alterações de código ou acesso direto a servidores. Ela define regras claras para logs, métricas e traces, baseadas nos três pilares fundamentais da observabilidade. A skill suporta qualquer plataforma de desenvolvimento que utilize OpenTelemetry, ferramentas de métricas como Prometheus ou Datadog, e sistemas de logging estruturado. Ao seguir estas regras, você consegue identificar regressões de performance, rastrear requisições completas entre serviços e alertar de forma inteligente com base em SLOs, evitando fadiga de alertas e garantindo que cada alerta tenha um runbook associado.

Funciona com~Claude Code~Codex CLI~Cursor

npx skills add https://github.com/Piyush-Nagar/coding-agents-skills/tree/HEAD/backend/core/nfr/observability

Documentação

Observabilidade

Regras

Três pilares: logs, métricas, traces. Cada um responde a uma pergunta diferente — o que aconteceu (logs), quanto e com que frequência (métricas), por que estava lento (traces). Você precisa dos três.
Apenas logs estruturados. JSON (ou similar). Grep não é uma estratégia em escala.
ID de correlação / trace em cada linha de log. Propague-o através de cabeçalhos entre limites de serviços. Um único ID costura toda a jornada de uma requisição.
Métricas RED em cada endpoint. Taxa, Erros, Duração (com P50/P95/P99). O mínimo necessário para detectar regressões.
Métricas USE em cada recurso. Utilização, Saturação, Erros — para CPU, memória, pools, filas, disco, rede.
Trace cada chamada entre serviços. Use OpenTelemetry. Capture consultas a banco de dados e acertos de cache como spans também.
Alerta em SLOs, não em métricas brutas. "CPU > 80%" acorda humanos às 3h da manhã à toa. "Latência P99 viola SLO por 5 min" captura dor real do usuário.
Health e readiness são endpoints diferentes. /health = "Estou vivo, não me reinicie." /ready = "Posso receber tráfego agora." Trate-os como tal.
Log no nível correto, log uma vez por evento. INFO para ciclo de vida da requisição, WARN para problemas recuperáveis, ERROR para coisas que precisam de um humano. Logs duplicados fazem dashboards mentirem.
Nunca logue PII ou segredos. Mascare no appender; não confie que os chamadores lembrarão.
Cada alerta aponta para um runbook. Um alerta sem uma ação documentada é uma notificação do Slack fingindo ser um chamado.

Bandeiras vermelhas

Depurar produção fazendo SSH em um pod.
Alertas que disparam rotineiramente e são ignorados. (Fadiga de alerta é um problema de confiabilidade.)
Logs que dizem "erro ocorreu" sem contexto, sem ID, sem stack.
Métricas que mostram apenas médias, sem percentis.
Um dashboard por serviço, zero dashboards por jornada do usuário.