performance-engineer

performance-engineer 技能總覽

performance-engineer 技能的用途

performance-engineer 技能是一套專注於疑難排解與效能優化的工作流程，用來診斷系統變慢的原因、找出瓶頸，並把像「這個 endpoint 很慢」這類模糊抱怨轉成可量測、可驗證的修正。它的設計重點是效能優化，而不是一般程式碼審查；真正的價值在於強制你走完「建立基準 → 量測 → 分析 → 驗證」的迴圈，而不是靠猜測下手。

哪些人適合使用 performance-engineer

這個技能很適合已經有系統可供檢查、但需要協助縮小問題範圍的開發者、SRE、後端工程師，以及 AI agent 使用者，尤其是在你想釐清時間、記憶體或吞吐量到底耗在哪裡的情境下特別有用。若你手上已有可重現的效能變慢案例、明確的延遲目標，或懷疑某個 hotspot，但又不想從空白 prompt 開始，performance-engineer 會很合適。

這個技能真正要解決的工作

大多數使用者要的其實不只是「讓程式變快」。他們更需要回答這些實務問題：

• 到底是哪個指標出了問題？
• 瓶頸是在 database、API、frontend、network，還是 runtime？
• 在改程式碼之前，應該先量哪些東西？
• 要怎麼證明優化真的有效，而且沒有引入行為退化？

performance-engineer 最擅長的，就是把這類調查過程整理成有條理的分析流程。

為什麼這個技能和一般 prompt 不一樣

一般 prompt 很常一開始就直接跳到推測性的修法。performance-engineer 在效能優化場景下更實用，因為它明確把重心放在：

• baseline metrics 與目標值
• 先 profiling 再優化
• 依系統層級定位 bottleneck
• 修改後再做驗證
• 使用來自 scripts/ 的輕量報告與 profiling 範本

這讓它更適合真正的工程工作，不只是用來發想點子。

安裝前先確認什麼

如果你能提供以下資訊，這個技能通常會很適合：

• 可供檢查的 codebase 或 endpoint
• 可重現的慢路徑
• 至少一個可量測的效能目標
• 允許執行 profiling、logs 或 benchmark 指令

如果你的問題主要是 correctness、架構選型，或只是成本估算，且目前沒有明顯的效能症狀，那它的適配度就比較低。

如何使用 performance-engineer 技能

如何安裝 performance-engineer

可用以下指令從 repository collection 安裝：

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 指標
• 語言、framework、runtime、infra 等環境資訊
• 問題如何重現
• 現有 profiler 輸出、traces 或 logs
• 懷疑的層級：DB、API、frontend、network、caching 或 compute

如果缺少這些資訊，技能仍然可以提供流程建議，但輸出品質通常會下降，因為它必須自行推斷太多內容。

把模糊需求改寫成高品質 prompt

較弱的寫法：

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.

為什麼這樣更好：

• 有明確定義 metric
• 有給出 target
• 有說明 workload
• 有縮小可能的 bottleneck 層級
• 要求的是調查順序，不是隨機調參

實務上建議的 performance-engineer 工作流程

一個好的 performance-engineer usage 模式通常是：

1. 定義受影響的使用者路徑或系統操作。
2. 記錄 baseline metrics。
3. 對慢路徑進行 profiling 或檢查。
4. 把發現對應到可能的 bottleneck 層級。
5. 先提出最小但高影響的修正方案。
6. 每次修改後重新量測。
7. 記錄 findings 與 regression checks。

這和技能本身的階段設計一致，也能讓優化建立在證據上，而不是直覺。

先讀哪些 repository 檔案最有效

如果你想最快上手，建議依這個順序閱讀：

1. SKILL.md：看啟用線索與分析階段
2. references/checklist.md：掌握最低限度的流程紀律
3. references/optimization.md：了解常見優化槓桿
4. references/monitoring.md：看 rollout 之後要追哪些指標
5. README.md：參考範例目標與輔助 scripts

要注意，這些 scripts 本身不是 profiler；它們是用來標準化調查輸出的範本工具。

支援實際使用的內建 scripts

這份 performance-engineer guide 有兩個支援 scripts，能帶來很實際的幫助：

• 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"

如果你希望留下可重複使用的調查紀錄，而不是一次性的聊天輸出，這兩個工具特別有價值。

performance-engineer 技能擅長偵測哪些問題

原始內容把重點放在一些常見的 bottleneck 位置，例如：

• database 問題，例如 N+1 queries、缺少 indexes、結果集過大
• API over-fetching 或序列化效率差
• 從 profiler 輸出看出的 runtime hotspots
• payload 與 network 效率問題
• hot path 上缺少 caching

也就是說，當你真的有一個需要定位的瓶頸時，這個技能最有價值；如果只是很籠統地想「把全部都變快」，效果反而沒那麼好。

提升 performance-engineer 效果的實用 prompt 結構

在呼叫 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

這種 prompt 結構通常會比單純一句「why is this slow?」產出更可執行的結果。

採用 performance-engineer 前常見的阻礙

在你正式依賴 performance-engineer install 前，要先知道它的主要限制：

• 它不能取代真正的 profiler 或 APM tools
• 它必須有可量測的症狀才會有效
• 若 workload 無法重現，它能提供的幫助會少很多
• 如果你沒有 benchmark path，它就無法替你驗證效能提升

換句話說，這個技能改善的是你的調查方法；它不會憑空產生可信的量測結果。

什麼時候改用一般 prompt 就夠了

如果你只是想快速整理 code style、對一個很小的 script 做 micro-optimizations，或只需要語言層面的 tuning 建議而不需要調查流程，那一般 prompt 通常就夠了。當風險更高、你需要從症狀一路走到已驗證修正的結構化路徑時，再用 performance-engineer skill 會更適合。

performance-engineer 技能常見問題

performance-engineer 適合初學者嗎？

可以，前提是這位初學者手上已經有具體的效能變慢場景。這個技能提供了一個有紀律的順序——baseline、profile、bottleneck、validate——能幫助你避免過早優化。但如果你期待它從零開始教完整的 observability 或 benchmarking 基礎，那它就沒那麼適合新手。

performance-engineer 和直接叫 AI 優化程式碼有什麼差別？

最大的差別在於流程控制。一般 prompt 常常會立刻建議 caching、indexing、async 處理或重構。performance-engineer skill 則更適合在你必須先判斷問題究竟出在 database、API layer、memory behavior、payload size，還是 runtime hotspot 的情況下使用。

這個技能有包含真正的工具嗎？

有一部分。repository 內含 scripts/profile.py 與 scripts/perf_report.py 這類範本產生器，也有 checklist、monitoring 與 optimization 槓桿的參考文件。不過你仍然需要自己準備 runtime profilers、logs、benchmarks，以及和環境相符的指令。

performance-engineer 只適用於後端服務嗎？

不是。README 裡的效能目標範例同時涵蓋 APIs 與 page-load 類型的 metrics，而 references 也提到 payload 與 network efficiency。不過整體範例仍比較偏向 application 與 service 調查，而不是深入的 frontend rendering 分析。

什麼情況下不該用 performance-engineer？

以下情況建議略過：

• 目前還沒有可量測的效能問題
• 你只是想做廣泛的架構腦力激盪
• 問題核心是 reliability 或 correctness，而不是速度
• 你無法重現 workload，也蒐集不到任何 metrics

在這些情況下，這個技能的結構化流程能帶來的價值會比較有限。

performance-engineer 能協助修正後的 monitoring 嗎？

可以。references/monitoring.md 會引導你追蹤 percentiles、throughput、error rates，以及退化告警。若你希望這個技能不只支援一次性的調校，也能支援 rollout 後的驗證，這部分就很有幫助。

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

與其把 prompt 寫得更長，不如提供更好的 baseline

想提升 performance-engineer usage，最快的方法通常是提供：

• 目前的 p50、p95 或 p99 latency
• throughput 與 error rate
• memory 或 CPU 症狀
• 精確的 benchmark 或 request path
• before-and-after comparison plan

這些資訊往往比冗長的背景敘述更有價值。

補齊環境與 workload 形狀

效能建議會隨 workload 而改變。請告訴技能：

• request concurrency
• dataset size
• cache 是 warm 還是 cold
• CPU 與 memory 限制
• 是 local、staging 還是 production 環境

內建的 scripts/profile.py 範本本身就是很好的提醒：至少要記錄 environment、workload、command、duration 與 hotspots。

要求輸出依優先級排序的修正方案與驗證步驟

一個很強的 follow-up prompt 可以這樣寫：

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 常見失敗模式

使用者從 performance-engineer 得到弱結果時，最常見的原因是：

• 沒有 baseline metrics
• 沒有可重現的 workload
• 沒有 profiler 或 trace 證據
• 還沒定位 bottleneck 就先要求修正方案
• 把多個系統混成一個模糊需求一起問

如果你第一次拿到的結果很 generic，通常就是少了上述其中一項。

把 checklist 當成品質門檻

references/checklist.md 很短，但非常重要。你可以把它視為最低標準：

• baseline metrics 已記錄
• bottlenecks 已識別
• fixes 已用 benchmarks 驗證
• regression tests 已補上

這份 checklist 正是讓這個技能從「建議型工具」變成「可落地操作流程」的關鍵。

記錄 findings，讓下一輪 performance-engineer 分析更準

做完第一輪之後，用 scripts/perf_report.py 產出報告，並把它丟回下一次執行中。這樣 performance-engineer skill 就能依據真實 findings、ownership 與 validation notes 來收斂建議，而不是每次都從頭開始。

用證據片段強化 prompt

與其只說「DB seems slow」，不如直接貼上一小段精簡證據，例如：

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

即使只是部分證據，也能大幅提升輸出品質，因為技能可以把建議連回實際觀察到的 hotspots，而不是套用預設套路。

釐清診斷與實作的邊界

performance-engineer for Performance Optimization 這套流程最強的部分，在於診斷、排序優先級與規劃驗證方式。若再搭配第二輪、專注在你所用技術棧中的實際修正實作，效果會更好。先用它判斷什麼最值得處理，再用 coding 協助安全地把變更做下去。