performance-engineer

Visão geral da skill performance-engineer

O que a skill performance-engineer faz

A skill performance-engineer é um fluxo focado de troubleshooting e otimização para diagnosticar sistemas lentos, encontrar gargalos e transformar reclamações vagas como “este endpoint está lento” em correções mensuráveis. Ela foi feita para trabalho de otimização de performance, não para revisão geral de código, então seu valor está em impor um ciclo de baseline-medir-profile-verificar em vez de ficar no achismo.

Para quem a performance-engineer é indicada

Esta skill atende bem desenvolvedores, SREs, engenheiros backend e usuários de agentes de IA que já têm um sistema para inspecionar e querem ajuda para reduzir onde tempo, memória ou throughput estão sendo perdidos. Ela é especialmente útil quando você tem uma lentidão reproduzível, uma meta de latência ou um hotspot suspeito, mas não quer começar de um prompt em branco.

O trabalho real que ela resolve

A maioria das pessoas não quer apenas “código mais rápido”. O que elas precisam é responder perguntas práticas:

• Qual métrica está realmente ruim?
• Onde está o gargalo: banco de dados, API, frontend, rede ou runtime?
• O que deve ser medido antes de alterar o código?
• Como provar que a otimização ajudou e não causou regressão de comportamento?

A skill performance-engineer é mais forte quando usada para estruturar essa investigação.

Por que esta skill é diferente de um prompt genérico

Um prompt genérico costuma pular direto para correções especulativas. A performance-engineer é melhor para otimização de performance porque coloca explicitamente no centro:

• métricas de baseline e metas
• profiling antes de otimizar
• localização do gargalo por camada
• validação após as mudanças
• templates leves de relatório e profiling vindos de scripts/

Isso a torna mais útil para trabalho real de engenharia, e não apenas para gerar ideias.

O que verificar antes de instalar

Esta skill é uma boa escolha se você puder fornecer:

• uma codebase ou endpoint para inspecionar
• um caminho lento reproduzível
• pelo menos uma meta de performance mensurável
• permissão para rodar comandos de profiling, logs ou benchmark

Ela é menos indicada se seu problema for principalmente de correção, escolha de arquitetura ou estimativa de custo sem nenhum sintoma de performance observado.

Como usar a skill performance-engineer

Como instalar a performance-engineer

Instale a partir da coleção de repositórios com:

npx skills add https://github.com/zhaono1/agent-playbook --skill performance-engineer

Se você estiver avaliando a skill antes de instalar, inspecione:

• skills/performance-engineer/SKILL.md
• skills/performance-engineer/README.md
• skills/performance-engineer/references/checklist.md
• skills/performance-engineer/references/monitoring.md
• skills/performance-engineer/references/optimization.md
• skills/performance-engineer/scripts/profile.py
• skills/performance-engineer/scripts/perf_report.py

Quais entradas a skill performance-engineer precisa

A skill performance-engineer funciona melhor quando recebe contexto operacional, e não apenas código. Entradas fortes incluem:

• o endpoint, query, página, job ou comando lento
• latência, throughput, memória ou CPU atuais versus a meta
• detalhes do ambiente, como linguagem, framework, runtime e infra
• como reproduzir o problema
• qualquer saída existente de profiler, traces ou logs
• camada suspeita: DB, API, frontend, rede, cache ou compute

Sem isso, a skill ainda pode sugerir um processo, mas a qualidade da saída cai porque ela precisa inferir coisa demais.

Como transformar um pedido vago em um prompt forte

Fraco:

Optimize this code.

Melhor:

Use the performance-engineer skill on this Python API endpoint. Current p95 latency is 1.4s, target is under 500ms. Traffic spikes at 50 concurrent requests. We use PostgreSQL and Redis. Please identify what to measure first, likely bottlenecks, profiling commands to run, and the order of fixes to test.

Por que isso é melhor:

• define a métrica
• informa a meta
• nomeia a carga de trabalho
• restringe as camadas de gargalo mais prováveis
• pede uma sequência de investigação, não ajustes aleatórios

Fluxo recomendado da performance-engineer na prática

Um bom padrão de performance-engineer usage é:

1. Definir o caminho do usuário ou a operação do sistema afetada.
2. Registrar as métricas de baseline.
3. Fazer profiling ou inspecionar o caminho lento.
4. Mapear os achados para as camadas de gargalo mais prováveis.
5. propor primeiro a menor correção com maior impacto.
6. Medir novamente após cada mudança.
7. Documentar achados e checagens de regressão.

Isso espelha a própria estrutura de fases da skill e mantém a otimização ancorada em evidências.

Arquivos do repositório para ler primeiro

Leia estes arquivos nesta ordem se quiser o caminho mais rápido de adoção:

1. SKILL.md para os sinais de ativação e as fases de análise
2. references/checklist.md para a disciplina mínima do processo
3. references/optimization.md para alavancas comuns de otimização
4. references/monitoring.md para o que acompanhar após o rollout
5. README.md para exemplos de metas e scripts auxiliares

Os scripts não são profilers por si só; eles são templates que ajudam a padronizar a saída da investigação.

Scripts nativos que apoiam o uso da performance-engineer

Dois scripts de apoio agregam valor prático a este performance-engineer guide:

• python scripts/profile.py gera um template de profiling com campos de ambiente, carga de trabalho e hotspots.
• python scripts/perf_report.py gera um relatório em markdown para resumo, ownership, métricas de baseline, achados, recomendações e validação.

Exemplo:

python scripts/profile.py --name "checkout latency" --tool "cProfile" --command "python app.py" --duration "60s"
python scripts/perf_report.py --name "checkout API" --owner "payments-team"

Eles são úteis quando você quer notas de investigação repetíveis, em vez de uma saída de chat pontual.

O que a skill performance-engineer foi otimizada para detectar

O material de origem orienta o usuário para locais comuns de gargalo, como:

• problemas de banco de dados, como queries N+1, índices ausentes ou conjuntos de resultados grandes
• over-fetching em API ou serialização ineficiente
• hotspots de runtime encontrados via saída de profiler
• ineficiências de payload e rede
• lacunas de cache em caminhos quentes

Isso significa que a skill é mais valiosa quando existe um gargalo real para isolar, e não apenas um desejo amplo de “deixar tudo mais rápido”.

Padrão prático de prompt para resultados melhores

Use esta estrutura ao acionar performance-engineer for Performance Optimization:

Use the performance-engineer skill.

System:
- Service/page/job:
- Language/framework:
- Infra/dependencies:

Problem:
- Symptom:
- Current metric:
- Target metric:
- Reproduction steps:

Evidence:
- Logs/traces/profile snippets:
- Suspected bottleneck layer:

Task:
- Define measurement plan
- Identify likely root causes
- Recommend ordered fixes
- Specify how to validate improvement

Esse padrão de prompt normalmente produz uma saída mais acionável do que um simples “por que isso está lento?”.

Bloqueios comuns na adoção

Antes de depender da performance-engineer install, observe as principais limitações:

• ela não substitui profilers reais nem ferramentas de APM
• precisa de sintomas mensuráveis para ser eficaz
• ajuda menos quando a carga de trabalho não pode ser reproduzida
• não consegue validar ganhos se você não fornecer um caminho de benchmark

Em outras palavras, a skill melhora o método de investigação; ela não gera medições confiáveis magicamente por conta própria.

Quando usar prompts comuns em vez da performance-engineer

Se você só precisa de uma limpeza rápida de estilo de código, micro-otimizações em um script pequeno ou dicas de tuning específicas de linguagem sem investigação, um prompt padrão pode bastar. Use a performance-engineer skill quando o impacto for maior e você precisar de um caminho estruturado do sintoma até uma correção validada.

FAQ da skill performance-engineer

A performance-engineer é boa para iniciantes?

Sim, se o iniciante já tiver um cenário concreto de lentidão. A skill fornece uma sequência disciplinada — baseline, profile, gargalo, validar — que ajuda a evitar otimização prematura. Ela é menos amigável para iniciantes se a expectativa for aprender do zero todos os fundamentos de observabilidade ou benchmarking.

O que torna a performance-engineer melhor do que pedir para uma IA otimizar código?

A principal diferença é o controle de processo. Um prompt normal costuma sugerir cache, indexação, trabalho assíncrono ou refactors imediatamente. A performance-engineer skill é mais útil quando você primeiro precisa determinar se o problema está no banco de dados, na camada de API, no comportamento de memória, no tamanho do payload ou em um hotspot de runtime.

A skill inclui ferramentas reais?

Parcialmente. O repositório inclui geradores de template em scripts/profile.py e scripts/perf_report.py, além de docs de referência para checklist, monitoring e alavancas de otimização. Ainda assim, você continua precisando dos seus próprios profilers de runtime, logs, benchmarks e comandos específicos do ambiente.

A performance-engineer é só para serviços backend?

Não. O README inclui metas de performance que cobrem APIs e métricas no estilo page-load, e as referências citam eficiência de payload e rede. Ainda assim, os exemplos pendem mais para investigação de aplicações e serviços do que para análise profunda de rendering no frontend.

Quando eu não devo usar a performance-engineer?

Evite usar quando:

• ainda não existe um problema de performance mensurável
• você só quer brainstorming amplo de arquitetura
• a questão é confiabilidade ou correção, e não velocidade
• você não consegue reproduzir a carga de trabalho nem coletar métricas

Nesses casos, a estrutura da skill agrega menos valor.

A performance-engineer pode ajudar com monitoring depois das correções?

Sim. references/monitoring.md incentiva o acompanhamento de percentis, throughput, taxas de erro e alertas de regressão. Isso é útil se você quiser que a skill apoie a validação do rollout, e não apenas um ajuste pontual.

Como melhorar a skill performance-engineer

Forneça baselines melhores, não prompts maiores

A forma mais rápida de melhorar o performance-engineer usage é fornecer:

• latência atual p50, p95 ou p99
• throughput e taxa de erro
• sintomas de memória ou CPU
• benchmark exato ou caminho da requisição
• plano de comparação antes e depois

Isso vale mais do que adicionar um contexto narrativo longo.

Inclua o ambiente e o formato da carga de trabalho

Conselhos de performance mudam conforme a carga. Informe para a skill:

• concorrência de requisições
• tamanho do dataset
• estado de cache quente ou frio
• restrições de CPU e memória
• ambiente local, staging ou produção

O template incluído em scripts/profile.py é um bom lembrete do que capturar: ambiente, carga de trabalho, comando, duração e hotspots.

Peça correções ranqueadas com etapas de validação

Um bom prompt de continuação é:

Use the performance-engineer skill to rank the top three likely bottlenecks by expected impact and confidence. For each, give the measurement to confirm it, the smallest fix to test, and the benchmark to verify improvement.

Isso reduz respostas vagas do tipo “tente tudo” e barateia a iteração.

Evite modos comuns de falha

As formas mais comuns de obter resultados fracos com performance-engineer são:

• ausência de métricas de baseline
• ausência de carga de trabalho reproduzível
• ausência de evidência de profiler ou trace
• pedir correções antes de isolar o gargalo
• misturar vários sistemas em um único pedido vago

Se seu primeiro resultado parecer genérico, normalmente está faltando um desses pontos.

Use o checklist da performance-engineer como gate de qualidade

references/checklist.md é curto, mas importante. Trate-o como padrão mínimo:

• métricas de baseline registradas
• gargalos identificados
• correções verificadas com benchmarks
• testes de regressão adicionados

É nesse checklist que a skill deixa de ser apenas consultiva e passa a ser operacional.

Documente os achados para melhorar a próxima iteração

Após a primeira rodada, gere um relatório com scripts/perf_report.py e alimente a próxima execução com ele. Isso ajuda a performance-engineer skill a refinar recomendações usando achados reais, ownership e notas de validação, em vez de recomeçar do zero a cada vez.

Melhore prompts da performance-engineer com trechos de evidência

Em vez de dizer “o DB parece lento”, cole um bloco compacto de evidências, como:

• amostra da duração de queries
• principais funções no profiler
• resumo dos spans do trace
• tempos do endpoint por percentil

Mesmo evidência parcial melhora bastante a qualidade da saída, porque a skill consegue conectar as recomendações aos hotspots observados em vez de recorrer ao padrão genérico.

Entenda o limite entre diagnóstico e implementação

O fluxo performance-engineer for Performance Optimization é mais forte em diagnóstico, priorização e planejamento de validação. Ele fica mais eficaz quando combinado com uma segunda rodada focada em implementar a correção escolhida na sua stack. Use primeiro para decidir o que realmente importa; depois use ajuda de coding para aplicar a mudança com segurança.