performance-engineer

Visión general de la skill performance-engineer

Qué hace la skill performance-engineer

La skill performance-engineer es un flujo de trabajo centrado en troubleshooting y optimización para diagnosticar sistemas lentos, encontrar cuellos de botella y convertir quejas vagas como “este endpoint va lento” en mejoras medibles. Está pensada para trabajo de optimización de rendimiento, no para revisión general de código, así que su valor está en obligar a seguir un ciclo de línea base-medición-profiling-verificación en lugar de adivinar.

Quién debería usar performance-engineer

Esta skill encaja bien para developers, SREs, ingenieros backend y usuarios de agentes de IA que ya tienen un sistema que inspeccionar y necesitan ayuda para acotar dónde se pierde tiempo, memoria o throughput. Es especialmente útil cuando tienes una ralentización reproducible, un objetivo de latencia o un hotspot sospechoso, pero no quieres empezar desde un prompt en blanco.

El trabajo real que resuelve

La mayoría de los usuarios no solo quieren “código más rápido”. Necesitan responder preguntas prácticas:

• ¿Qué métrica está realmente mal?
• ¿Dónde está el cuello de botella: base de datos, API, frontend, red o runtime?
• ¿Qué conviene medir antes de tocar el código?
• ¿Cómo demostramos que la optimización ayudó y no introdujo regresiones?

La skill performance-engineer aporta más valor cuando se usa para estructurar esa investigación.

Por qué esta skill es distinta de un prompt genérico

Un prompt genérico suele saltar directamente a arreglos especulativos. Esta skill es mejor para optimización de rendimiento porque pone explícitamente en el centro:

• métricas base y objetivos
• profiling antes de optimizar
• localización del cuello de botella por capa
• validación después de los cambios
• plantillas ligeras de reporting y profiling desde scripts/

Eso la hace más útil para trabajo de ingeniería real, no solo para generar ideas.

Qué revisar antes de instalarla

Esta skill encaja bien si puedes aportar:

• un codebase o endpoint para inspeccionar
• un recorrido lento reproducible
• al menos un objetivo de rendimiento medible
• permiso para ejecutar profiling, logs o comandos de benchmark

Encaja peor si tu problema es sobre todo de corrección, selección de arquitectura o estimación de costes sin síntomas de rendimiento observables.

Cómo usar la skill performance-engineer

Cómo instalar performance-engineer

Instálala desde la colección del repositorio con:

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

Si quieres evaluar la skill antes de instalarla, revisa:

• 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

Qué inputs necesita la skill performance-engineer

La skill performance-engineer funciona mejor cuando le das contexto operativo, no solo código. Algunos inputs especialmente útiles son:

• el endpoint, query, página, job o comando que va lento
• latencia, throughput, memoria o CPU actual frente al objetivo
• detalles del entorno como lenguaje, framework, runtime e infraestructura
• cómo reproducir el problema
• cualquier salida existente de profiler, traces o logs
• capa sospechosa: DB, API, frontend, red, caché o cómputo

Sin eso, la skill aún puede sugerir un proceso, pero la calidad de la respuesta baja porque tiene que inferir demasiado.

Convierte una petición vaga en un prompt sólido para performance-engineer

Débil:

Optimize this code.

Mejor:

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 qué esto funciona mejor:

• define la métrica
• da el objetivo
• especifica la carga de trabajo
• acota las capas donde probablemente esté el cuello de botella
• pide una secuencia de investigación, no ajustes aleatorios

Flujo de trabajo recomendado en la práctica

Un buen patrón de performance-engineer usage es:

1. Definir el recorrido de usuario o la operación del sistema afectada.
2. Registrar métricas base.
3. Hacer profiling o inspeccionar el recorrido lento.
4. Relacionar los hallazgos con las capas donde probablemente está el cuello de botella.
5. proponer primero la corrección más pequeña con mayor impacto.
6. Volver a medir después de cada cambio.
7. Documentar hallazgos y comprobaciones de regresión.

Esto refleja la estructura por fases de la propia skill y mantiene la optimización anclada en evidencia.

Archivos del repositorio que conviene leer primero

Lee estos archivos en este orden si quieres la ruta de adopción más rápida:

1. SKILL.md para entender las señales de activación y las fases de análisis
2. references/checklist.md para la disciplina mínima del proceso
3. references/optimization.md para palancas de optimización habituales
4. references/monitoring.md para saber qué seguir después del rollout
5. README.md para ver objetivos de ejemplo y scripts de apoyo

Los scripts no son profilers en sí mismos; son plantillas que ayudan a estandarizar la salida de la investigación.

Scripts incluidos que apoyan el uso de performance-engineer

Hay dos scripts de apoyo que aportan valor práctico a esta performance-engineer guide:

• python scripts/profile.py genera una plantilla de perfil con campos de entorno, carga de trabajo y hotspots.
• python scripts/perf_report.py genera un informe en markdown con resumen, ownership, métricas base, hallazgos, recomendaciones y validación.

Ejemplo:

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"

Resultan útiles cuando quieres notas de investigación repetibles en lugar de una respuesta aislada de chat.

Qué está optimizada para detectar la skill performance-engineer

El material fuente orienta a los usuarios hacia ubicaciones habituales de cuellos de botella, como:

• problemas de base de datos como consultas N+1, índices ausentes o conjuntos de resultados grandes
• over-fetching en APIs o serialización ineficiente
• hotspots del runtime detectados mediante salida del profiler
• ineficiencias de payload y red
• huecos de caché en rutas calientes

Eso significa que la skill aporta más valor cuando hay un cuello de botella real que aislar, no solo un deseo general de “hacer que todo vaya más rápido”.

Patrón de prompt práctico para obtener mejores resultados

Usa esta estructura al invocar 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

Este patrón de prompt suele producir resultados más accionables que una petición simple como “¿por qué va tan lento esto?”.

Bloqueos habituales al adoptar performance-engineer

Antes de basarte en performance-engineer install, ten presentes las principales limitaciones:

• no sustituye a profilers reales ni a herramientas APM
• necesita síntomas medibles para ser eficaz
• ayuda menos cuando la carga de trabajo no se puede reproducir
• no puede validar mejoras si no le das una ruta de benchmark

En otras palabras, la skill mejora el método de investigación; no genera por sí sola mediciones fiables por arte de magia.

Cuándo usar prompts normales en su lugar

Si solo necesitas una limpieza rápida de estilo de código, microoptimizaciones en un script pequeño o consejos de tuning específicos de un lenguaje sin investigación previa, un prompt estándar puede bastar. Usa la skill performance-engineer cuando haya más en juego y necesites un camino estructurado desde el síntoma hasta una corrección verificada.

Preguntas frecuentes sobre la skill performance-engineer

¿performance-engineer es buena para principiantes?

Sí, siempre que la persona principiante ya tenga un escenario de lentitud concreto. La skill ofrece una secuencia disciplinada —línea base, profiling, cuello de botella, validación— que ayuda a evitar la optimización prematura. Es menos amigable para principiantes si esperas que enseñe desde cero todos los fundamentos de observabilidad o benchmarking.

¿Qué hace que performance-engineer sea mejor que pedirle a una IA que optimice código?

La diferencia principal es el control del proceso. Un prompt normal suele sugerir caché, índices, trabajo asíncrono o refactors de inmediato. La skill performance-engineer es más útil cuando primero necesitas determinar si el problema está en la base de datos, la capa de API, el comportamiento de memoria, el tamaño del payload o un hotspot del runtime.

¿La skill incluye herramientas reales?

En parte. El repositorio incluye generadores de plantillas en scripts/profile.py y scripts/perf_report.py, además de documentación de referencia para checklist, monitoring y palancas de optimización. Aun así, necesitas tus propios profilers de runtime, logs, benchmarks y comandos específicos del entorno.

¿performance-engineer es solo para servicios backend?

No. El README incluye objetivos de rendimiento que abarcan APIs y métricas de carga de página, y las referencias mencionan eficiencia de payload y red. Aun así, los ejemplos están más orientados a investigación de aplicaciones y servicios que a análisis profundo de renderizado frontend.

¿Cuándo no debería usar performance-engineer?

Sáltatela cuando:

• todavía no hay un problema de rendimiento medible
• solo quieres brainstorming amplio de arquitectura
• el problema es de fiabilidad o corrección, no de velocidad
• no puedes reproducir la carga de trabajo ni recoger métricas

En esos casos, la estructura de la skill aporta menos valor.

¿performance-engineer puede ayudar con el monitoring después de aplicar correcciones?

Sí. references/monitoring.md empuja a los usuarios a seguir percentiles, throughput, tasas de error y alertas de regresión. Eso es útil si quieres que la skill apoye la validación del rollout, no solo un ajuste puntual.

Cómo mejorar la skill performance-engineer

Da mejores líneas base, no solo prompts más largos

La forma más rápida de mejorar performance-engineer usage es aportar:

• latencia p50, p95 o p99 actual
• throughput y tasa de error
• síntomas de memoria o CPU
• benchmark exacto o ruta de petición
• plan de comparación antes y después

Esto aporta más valor que añadir mucho contexto narrativo.

Incluye el entorno y la forma de la carga de trabajo

El consejo de rendimiento cambia según la carga de trabajo. Indícale a la skill:

• concurrencia de peticiones
• tamaño del dataset
• estado de caché caliente o fría
• restricciones de CPU y memoria
• entorno local, staging o producción

La plantilla incluida en scripts/profile.py es un buen recordatorio de qué capturar: entorno, carga de trabajo, comando, duración y hotspots.

Pide correcciones priorizadas con pasos de validación

Un buen prompt de seguimiento es:

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.

Esto reduce las respuestas vagas del tipo “prueba de todo” y hace más barata cada iteración.

Evita los modos de fallo más comunes

Las formas más habituales en que los usuarios obtienen resultados flojos con performance-engineer son:

• no tener métricas base
• no tener una carga de trabajo reproducible
• no aportar evidencia de profiler o traces
• pedir correcciones antes de aislar el cuello de botella
• mezclar varios sistemas en una sola petición vaga

Si el primer resultado te parece genérico, normalmente falta una de esas piezas.

Usa el checklist como puerta de calidad

references/checklist.md es corto, pero importante. Trátalo como el estándar mínimo:

• métricas base registradas
• cuellos de botella identificados
• correcciones verificadas con benchmarks
• pruebas de regresión añadidas

Ese checklist es el punto en el que esta skill pasa de ser orientativa a ser operativa.

Documenta los hallazgos para que la siguiente iteración sea mejor

Después de la primera pasada, genera un informe con scripts/perf_report.py y úsalo como input en la siguiente ejecución. Esto ayuda a que la skill performance-engineer refine sus recomendaciones usando hallazgos reales, ownership y notas de validación en vez de empezar de cero cada vez.

Mejora los prompts con fragmentos de evidencia

En lugar de decir “DB seems slow”, pega un bloque de evidencia compacto, por ejemplo:

• muestra de duración de queries
• funciones principales del profiler
• resumen de spans en traces
• tiempos del endpoint por percentil

Incluso evidencia parcial mejora mucho la calidad de la respuesta porque la skill puede conectar las recomendaciones con hotspots observados en lugar de recurrir a opciones por defecto.

Entiende el límite entre diagnóstico e implementación

El flujo performance-engineer for Performance Optimization es más potente en diagnóstico, priorización y planificación de validación. Se vuelve más eficaz cuando se combina con una segunda pasada centrada en implementar la corrección elegida en tu stack. Úsala primero para decidir qué importa y luego apóyate en ayuda de coding para aplicar el cambio con seguridad.