python-performance-optimization

Visão geral da skill python-performance-optimization

O que a skill python-performance-optimization faz

A skill python-performance-optimization ajuda um agente a diagnosticar por que um código Python está lento ou consumindo memória em excesso e, em seguida, propor correções direcionadas com base em profiling, e não em achismos. Ela foi feita para trabalho prático de performance: encontrar gargalos, separar problemas de CPU, memória e I/O, e escolher melhorias que realmente façam sentido para o caminho de código sob carga.

Para quem vale a pena instalar

Essa skill é mais indicada para desenvolvedores, engenheiros de dados, equipes de backend e fluxos com agentes que precisam de algo além de conselhos genéricos do tipo “deixe isso mais rápido”. Ela é especialmente útil quando você já tem um script, serviço, notebook ou pipeline funcionando do ponto de vista funcional, mas precisa melhorar latência, throughput ou comportamento de memória.

Trabalho real que ela resolve

A maioria dos usuários não precisa apenas de uma explicação sobre Big O — precisa de uma forma repetível de responder:

• o que está lento
• como medir isso corretamente
• qual otimização vale fazer primeiro
• como evitar mexer em código que não é o gargalo

É aí que a skill python-performance-optimization se destaca em relação a um prompt comum. Ela conduz o fluxo para profiling primeiro, otimização depois.

O que diferencia essa skill

O repositório cobre vários modos de profiling e várias camadas de otimização, em vez de tratar performance como se fosse um problema só. Ele abrange:

• profiling de CPU
• profiling de memória
• análise em nível de linha
• raciocínio com call graph
• padrões de implementação como cache
• caminhos mais avançados, como vetorização com NumPy, async I/O e paralelização

O diferencial prático está nessa abrangência combinada com uma mentalidade de profiling-first.

Casos em que encaixa bem — e em que não encaixa

Bom fit:

• endpoints, jobs, ferramentas de CLI, ETL ou processamento de dados lentos em Python
• crescimento de memória ou picos de RAM sem explicação
• decisão entre cache, mudança de algoritmo, vetorização ou concorrência
• preparação de planos de otimização antes de mexer em código de produção

Mau fit:

• codebases em que o gargalo real está na infraestrutura, na topologia de rede ou no schema do banco, e não há medições disponíveis
• equipes que esperam scripts de benchmark totalmente automatizados prontos para uso
• situações em que você quer apenas limpar estilo de código, e não diagnosticar performance

Como usar a skill python-performance-optimization

Contexto de instalação da python-performance-optimization

Instale a skill a partir do repositório wshobson/agents:

npx skills add https://github.com/wshobson/agents --skill python-performance-optimization

Depois de instalar, use-a quando seu prompt envolver claramente diagnóstico de performance em Python, profiling, uso de memória, redução de latência, ganho de throughput ou análise de gargalos.

Leia estes arquivos do repositório primeiro

Para entender mais rápido, comece por aqui:

1. plugins/python-development/skills/python-performance-optimization/SKILL.md
2. plugins/python-development/skills/python-performance-optimization/references/advanced-patterns.md

O SKILL.md traz o fluxo principal e as categorias de ferramentas. Já references/advanced-patterns.md é a segunda leitura mais útil quando o diagnóstico inicial aponta para vetorização, cache, ajuste de memória, async I/O ou cargas pesadas de banco de dados.

Que informações a skill precisa para funcionar bem

A qualidade de uso da python-performance-optimization depende muito das evidências que você fornece. Entregue ao agente:

• a função, arquivo, endpoint ou job que está lento
• o tamanho esperado da carga
• os sintomas reais: latência, saturação de CPU, crescimento de memória, timeout, número alto de queries
• saída de profiling, se houver
• restrições: não pode adicionar dependências, precisa preservar a API, só pode sugerir mudanças seguras para produção etc.
• detalhes do ambiente: versão do Python, framework, sistema operacional, processo único ou múltiplos processos

Sem essas entradas, a skill ainda pode sugerir passos de profiling, mas as recomendações serão menos específicas.

Transforme um pedido vago em um prompt forte

Prompt fraco:

• “Optimize this Python code.”

Prompt melhor:

• “Use the python-performance-optimization skill to analyze this Django view. P95 latency is 1.8s under ~200 requests/min. CPU is high, memory is stable. Here is the view code and a cProfile summary. Identify the top bottlenecks, explain whether the issue is Python execution, DB access, or serialization, and propose fixes ranked by expected impact and implementation risk.”

Isso funciona melhor porque informa carga, tipo de sintoma, evidência e formato de saída esperado.

Peça diagnóstico antes de pedir reescritas

Um bom fluxo com a skill python-performance-optimization é:

1. descrever o sintoma de performance
2. fornecer código e dados de medição
3. pedir ao agente para classificar o gargalo
4. só então pedir alterações no código

Isso evita reescritas prematuras. A skill python-performance-optimization é muito mais útil quando consegue partir de métricas para chegar à intervenção.

Entradas de profiling que melhoram de fato a resposta

As melhores entradas incluem:

• resumos de cProfile para código com uso intenso de CPU
• resultados de line-profiler para funções quentes
• evidências de memory-profiler ou de crescimento de objetos para problemas de RAM
• quebras de tempo em torno de I/O, banco, HTTP e serialização
• dados de amostra representativos, não entradas artificiais ou simplificadas demais

Se você ainda não tem medições, peça primeiro que o agente monte um plano de profiling, em vez de otimizar no escuro.

Fluxo típico que a skill suporta

Um guia prático de python-performance-optimization normalmente segue esta sequência:

1. identificar a meta de performance
2. escolher o tipo certo de profiling
3. perfilar cargas representativas
4. localizar os caminhos mais quentes ou as maiores alocações
5. selecionar a otimização de menor risco e maior impacto
6. comparar benchmarks antes e depois
7. observar regressões em correção e legibilidade

Essa sequência é o principal valor da skill.

Quando usar a referência avançada

Abra references/advanced-patterns.md quando o gargalo provavelmente estiver em uma destas áreas:

• loops numéricos que podem se beneficiar de NumPy
• trabalho repetido de funções puras que pode se beneficiar de functools.lru_cache
• cargas com muito I/O que podem se beneficiar de padrões assíncronos
• trabalho caro e paralelizável em que multiprocessing pode ajudar
• aplicações com muitas queries que exigem raciocínio de otimização de banco

Não pule para esse arquivo primeiro, a menos que você já saiba a categoria do problema. Comece pelos gargalos medidos.

Bons padrões de prompt para casos comuns

Para código limitado por CPU:

• “Use the python-performance-optimization skill to review this function and cProfile output. Focus on algorithmic complexity, repeated work, and Python-level loop overhead.”

Para problemas de memória:

• “Use the python-performance-optimization skill to inspect this batch job. RSS climbs from 400MB to 3GB. Suggest likely retention causes, profiling steps, and memory-safe refactors.”

Para serviços com muito I/O:

• “Use the python-performance-optimization skill on this async API client. Requests are slow despite low CPU. Determine whether the bottleneck is blocking I/O, connection handling, serialization, or concurrency limits.”

Que tipo de resultado esperar

Espere que a skill python-performance-optimization seja mais forte em:

• escolher a abordagem certa de profiling
• interpretar padrões comuns de performance
• propor otimizações plausíveis em ordem de prioridade
• explicar os trade-offs entre cache, vetorização, paralelização e simplificação de código

Espere resultados mais fracos se você não fornecer código, formato de carga nem medições.

FAQ da skill python-performance-optimization

A python-performance-optimization para otimização de performance é melhor do que um prompt normal?

Na maioria dos casos, sim, quando você precisa de um diagnóstico estruturado em vez de sugestões soltas. Um prompt comum costuma pular direto para “use cache” ou “use NumPy”. A skill python-performance-optimization tende mais a separar primeiro problemas de CPU, memória, I/O e algoritmo.

Essa skill é amigável para iniciantes?

Sim, desde que você consiga compartilhar código e sintomas. Você não precisa ser especialista em profiling para começar. Mas iniciantes conseguem resultados muito melhores quando fornecem evidências concretas e pedem que o agente explique por que um gargalo importa antes de propor correções.

Eu preciso ter saída de profiling antes de usar?

Não, mas tê-la melhora bastante o uso da python-performance-optimization. Se você ainda não tem medições, peça ao agente que diga exatamente o que perfilar e qual categoria de ferramenta usar.

Quando eu não deveria usar essa skill?

Evite usar quando o problema estiver claramente fora da lógica da aplicação Python, como:

• infraestrutura subdimensionada
• problemas de rede
• configuração incorreta do servidor de banco sem evidência no nível da aplicação
• latência de frontend sem relação com a execução do backend em Python

Nesses casos, a skill ainda pode ajudar a estruturar a investigação, mas não é a ferramenta principal mais adequada.

Ela cobre memória além de velocidade?

Sim. O repositório cobre explicitamente profiling e otimização de memória junto com profiling de CPU e análise de tempo de execução, o que a torna mais útil do que prompts focados “só em velocidade”.

Ela pode ajudar em workloads de dados?

Sim, especialmente quando o caminho de melhoria pode envolver vetorização, batching, cache ou redução da sobrecarga de loops em Python. A referência avançada é particularmente relevante para código numérico e de processamento de dados.

Como melhorar o uso da skill python-performance-optimization

Forneça evidências de benchmark, não só o código-fonte

A melhor forma de melhorar os resultados da python-performance-optimization é fornecer:

• tempos antes/depois
• resumos de profiling
• tamanhos de entrada de amostra
• metas de throughput ou latência

Com apenas o código-fonte, o agente pode levantar hipóteses. Com medições, ele consegue priorizar.

Especifique o tipo de gargalo que você suspeita

Mesmo que você não tenha certeza, diga qual acha que é o problema:

• limitado por CPU
• limitado por memória
• limitado por banco de dados
• limitado por rede/I/O
• problema de tempo de inicialização
• problema de throughput em processamento batch

Isso ajuda a skill python-performance-optimization a escolher o caminho de diagnóstico certo e a evitar conselhos genéricos.

Inclua restrições realistas

Conselhos de otimização mudam muito conforme as restrições. Declare-as de forma direta:

• não pode mudar a API pública
• não pode adicionar NumPy
• precisa continuar legível para uma equipe júnior
• precisa rodar em AWS Lambda
• precisa preservar ordenação determinística
• o teto de memória em ambiente multi-tenant é fixo

Esses detalhes melhoram a qualidade da decisão mais do que pedir simplesmente “a melhor performance”.

Peça recomendações ranqueadas

Um prompt forte pede que o agente ordene as sugestões por:

1. impacto esperado
2. esforço de implementação
3. risco de correção
4. custo de dependências

Isso evita a falha comum em que a primeira resposta já sugere mudanças sofisticadas antes de ganhos mais simples, como reduzir trabalho repetido ou corrigir queries ineficientes.

Fique atento aos modos de falha mais comuns

A skill python-performance-optimization pode perder força quando acontece algum destes problemas:

• otimizar código que não está no hot path
• usar microbenchmarks que não representam a carga de produção
• valorizar código “esperto” demais em vez de código sustentável
• aplicar multiprocessing quando o comportamento de I/O ou da GIL o torna uma má escolha
• recomendar cache sem discutir invalidação ou custo de memória

Peça ao agente para justificar cada otimização em função do gargalo medido.

Itere depois da primeira resposta

Um bom prompt de segunda rodada se parece com:

• “Here is the updated code and new benchmark. The runtime dropped from 2.4s to 1.5s, but memory increased by 35%. Re-run the python-performance-optimization analysis and suggest the next best change with minimal memory growth.”

Isso transforma a skill em um ciclo de otimização, e não em uma reescrita de uma vez só.

Use caminhos de leitura do repositório de forma estratégica

Se a primeira resposta continuar genérica, diga ao agente para ancorar o raciocínio em:

• SKILL.md para categorias de profiling e fluxo de trabalho
• references/advanced-patterns.md para opções de implementação como vetorização, cache, gerenciamento de memória, paralelização, async I/O e benchmarking

Isso normalmente aumenta a especificidade da resposta.

Peça planos de medição quando a adoção estiver travada

Se o bloqueio for “não sabemos por onde começar”, peça um plano mínimo:

• o que medir primeiro
• qual categoria de profiler se encaixa
• onde colocar timers
• que carga reproduzir
• qual métrica de sucesso usar

Esse costuma ser um dos usos de maior valor do guia python-performance-optimization para equipes que ainda estão no começo do processo.