performance-engineer

performance-engineer 技能概览

performance-engineer 技能能做什么

performance-engineer 是一套聚焦于排障与优化的工作流，用来诊断系统变慢、定位瓶颈，并把“这个 endpoint 很慢”这类模糊抱怨转化为可度量、可验证的改进。它面向的是性能优化场景，而不是通用代码审查；它的核心价值在于强制你遵循“建立基线 → 测量 → 分析 profile → 验证结果”的闭环，而不是凭感觉猜问题。

谁适合使用 performance-engineer

这个技能适合开发者、SRE、后端工程师，以及已经有待排查系统的 AI-agent 用户。尤其适用于这类情况：你已经有一个可观察的系统，希望更快收敛到时间、内存或吞吐到底损失在什么地方；你手头有可复现的性能下降、明确的延迟目标，或已有怀疑的热点，但不想从一个空白提示词开始。

它真正解决的工作问题

大多数用户想要的并不只是“让代码更快”。他们通常需要回答这些更实际的问题：

• 到底是哪项指标出了问题？
• 瓶颈是在 database、API、frontend、network，还是 runtime？
• 在改代码之前，应该先测什么？
• 怎么证明优化确实有效，而且没有引入行为回退？

performance-engineer 最擅长的，就是把这类调查过程组织清楚。

为什么它和普通提示词不一样

普通提示词往往会直接跳到“可能的修复方案”。而 performance-engineer 更适合性能优化，是因为它会明确把重点放在：

• 基线指标和目标值
• 先做 profiling 再做优化
• 按层定位瓶颈
• 修改后的验证
• 来自 scripts/ 的轻量报告与 profiling 模板

这让它更像真实工程中的工作方法，而不只是生成一些点子。

安装前先确认什么

如果你能提供以下信息，这个技能会很适合你：

• 可供检查的代码库或 endpoint
• 可复现的慢路径
• 至少一个可量化的性能目标
• 允许运行 profiling、日志或 benchmark 命令

如果你的问题主要是正确性、架构选型，或者在没有任何性能症状时做成本预估，那它的适配度就会弱很多。

如何使用 performance-engineer 技能

如何安装 performance-engineer

通过仓库集合安装：

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

如果你想在安装前先评估这个技能，建议先查看：

• 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

performance-engineer 技能需要哪些输入

performance-engineer 在你提供的是“运行上下文”而不仅仅是代码时，效果最好。比较强的输入包括：

• 具体变慢的 endpoint、query、page、job 或 command
• 当前值与目标值：latency、throughput、memory 或 CPU
• 环境细节，例如 language、framework、runtime 和 infra
• 问题如何复现
• 现有的 profiler 输出、trace 或日志
• 你怀疑的层：DB、API、frontend、network、caching 或 compute

如果没有这些信息，这个技能仍然可以给出流程建议，但输出质量会下降，因为它需要自行推断的内容太多。

把模糊需求变成高质量提示词

弱一点的写法：

Optimize this code.

更好的写法：

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.

为什么这样更好：

• 它定义了指标
• 它给出了目标值
• 它说明了负载形态
• 它缩小了可能的瓶颈层范围
• 它要求的是“调查顺序”，而不是随机给优化建议

实际使用中推荐的 workflow

一个比较好的 performance-engineer usage 模式是：

1. 定义受影响的用户路径或系统操作。
2. 记录基线指标。
3. 对慢路径做 profiling 或检查。
4. 把发现映射到可能的瓶颈层。
5. 优先提出影响大、改动最小的修复。
6. 每次修改后重新测量。
7. 记录结论和回归检查项。

这和技能自身的阶段结构一致，能让优化过程始终建立在证据之上。

优先阅读哪些仓库文件

如果你想以最快路径上手，建议按这个顺序阅读：

1. SKILL.md：看激活信号和分析阶段
2. references/checklist.md：掌握最低限度的流程纪律
3. references/optimization.md：了解常见优化杠杆
4. references/monitoring.md：看上线后该追踪什么
5. README.md：查看示例目标和辅助脚本

这些 scripts 本身不是 profiler；它们是帮助你标准化调查输出的模板工具。

支持使用的内置脚本

有两个辅助脚本，能给这份 performance-engineer guide 带来很强的实操价值：

• python scripts/profile.py 会生成一个 profile 模板，包含 environment、workload 和 hotspot 等字段。
• python scripts/perf_report.py 会生成 markdown 报告，覆盖 summary、ownership、baseline metrics、findings、recommendations 和 validation。

示例：

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"

如果你想要的是可复用的调查记录，而不是一次性的聊天输出，这两个脚本会很有帮助。

这个技能擅长发现什么问题

源材料把用户引导到一些常见瓶颈位置，例如：

• database 问题，例如 N+1 queries、缺失索引或结果集过大
• API 过度取数或序列化低效
• 通过 profiler 输出发现的 runtime 热点
• payload 和 network 效率问题
• 热路径上的 caching 缺口

这意味着，当你真的有一个需要被定位的瓶颈时，这个技能最有价值；如果只是笼统地想“把所有东西都变快”，它反而没那么适合。

为了得到更好结果的实用提示词模板

在调用 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

和一句简单的“why is this slow?” 相比，这种提示词通常能产出更可执行的结果。

常见的采用障碍

在你真正依赖 performance-engineer install 之前，需要先了解几个主要限制：

• 它不能替代真正的 profiler 或 APM 工具
• 它必须基于可度量的症状才能高效工作
• 如果 workload 无法复现，它能提供的帮助会明显变少
• 如果你不给出 benchmark 路径，它也无法验证收益

换句话说，这个技能提升的是调查方法，不会凭空生成可信的测量结果。

什么情况下用普通提示词更合适

如果你只是想快速做代码风格清理、在一个很小的脚本里做微优化，或者只需要语言层面的调优建议而不想走完整调查流程，那么普通提示词可能就足够了。只有当问题影响更大、你需要一条从症状走到已验证修复的结构化路径时，performance-engineer skill 才更值得用。

performance-engineer 技能 FAQ

performance-engineer 适合新手吗？

适合，但前提是这个新手手上已经有一个明确的变慢场景。这个技能会提供一套有纪律的顺序——基线、profile、瓶颈、验证——帮助你避免过早优化。但如果你希望它从零开始系统讲清 observability 或 benchmarking 的全部基础，那它就没那么友好了。

为什么 performance-engineer 比直接让 AI 优化代码更好？

主要差别在于流程控制。普通提示词常常会立刻建议加 caching、补索引、改 async，或者直接重构。performance-engineer skill 更适合这样的情况：你首先需要判断问题到底在 database、API 层、memory 行为、payload 大小，还是 runtime 热点。

这个技能自带真实工具吗？

部分具备。仓库里包含 scripts/profile.py 和 scripts/perf_report.py 这样的模板生成器，也有 checklist、monitoring 和 optimization levers 的参考文档。但真正的 runtime profilers、日志、benchmark，以及和环境相关的命令，仍然需要你自己提供。

performance-engineer 只适用于后端服务吗？

不是。README 中的性能目标既包括 API，也包括 page-load 风格的指标，参考文档里也提到了 payload 和 network 效率。不过整体示例还是更偏向应用和服务排查，而不是深入的 frontend rendering 分析。

什么情况下不该使用 performance-engineer？

以下情况建议跳过：

• 目前还没有可度量的性能问题
• 你只是想做宽泛的架构 brainstorming
• 问题核心是可靠性或正确性，而不是速度
• 你无法复现 workload，也采集不到任何指标

在这些场景里，这个技能的结构化流程带来的价值会小很多。

performance-engineer 能帮助修复后的监控吗？

可以。references/monitoring.md 会推动用户关注 percentiles、throughput、error rates，以及针对回退的告警。如果你希望这个技能不仅帮助你做一次性调优，还能支持 rollout 后的验证，它就很有用。

如何改进 performance-engineer 技能的使用效果

提供更好的基线，而不是更长的提示词

提升 performance-engineer usage 效果最快的方法，是直接提供：

• 当前 p50、p95 或 p99 latency
• throughput 和 error rate
• memory 或 CPU 症状
• 精确的 benchmark 或 request path
• 优化前后对比计划

这些信息的价值，通常比补一大段叙述背景更高。

补充环境和 workload 形态

性能建议会随着 workload 不同而变化。告诉这个技能：

• request concurrency
• dataset size
• cache warm 还是 cold
• CPU 和 memory 限制
• 是 local、staging 还是 production 环境

仓库自带的 scripts/profile.py 模板就很好地提醒了你应该记录什么：environment、workload、command、duration 和 hotspots。

明确要求“排序后的修复建议 + 验证步骤”

一个很强的追加提示词是：

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.

这样能显著减少“什么都试试看”的模糊输出，也能让后续迭代成本更低。

避开常见失败模式

用户从 performance-engineer 得到较弱结果，最常见的原因是：

• 没有基线指标
• 没有可复现的 workload
• 没有 profiler 或 trace 证据
• 还没隔离瓶颈就先要求修复方案
• 把多个系统混成一个模糊请求一起问

如果你第一次得到的结果很泛，多半就是这里面缺了某一项。

把 checklist 当成质量闸门

references/checklist.md 很短，但非常关键。可以把它当作最低标准：

• 已记录基线指标
• 已识别瓶颈
• 已用 benchmark 验证修复
• 已补充回归测试

也正是在这份 checklist 上，这个技能才从“给建议”变成“可落地执行”。

记录结论，让下一轮更准确

第一轮排查后，用 scripts/perf_report.py 生成报告，并把报告重新喂给下一轮使用。这能帮助 performance-engineer skill 基于真实 findings、ownership 和 validation notes 来细化建议，而不是每次都从零开始。

用证据片段增强提示词

不要只说“DB seems slow”，尽量贴上一小段紧凑的证据，例如：

• query duration sample
• profiler top functions
• trace span summary
• endpoint timings by percentile

哪怕证据不完整，也能明显提高输出质量，因为这个技能可以把建议和已观察到的热点对应起来，而不是退回默认套路。

分清“诊断”与“实施”的边界

performance-engineer for Performance Optimization 这套 workflow 最强的环节是诊断、优先级排序和验证规划。把它和第二轮专注于在你的技术栈里落地修复的工作配合起来，效果会更好。先用它判断什么最重要，再借助编码帮助安全地实施修改。