Claude Code Performance Engineer Subagent: Bottlenecks to Optimizations

## What This Is / What Problem It Solves 'The feature works' and 'the feature runs fast' are two different things. Many performance problems—N+1 queries, missing indexes, dumping an entire dataset into a payload, forgetting to cache, a slow memory leak—don't show up on small datasets during development, and only blow up once real traffic hits production. This 'performance engineer' subagent shifts the performance review left, to the moment you're developing the feature: once you've written a query or an API, have it run a profiling pass, and it finds the actual hot spots, measures each bottleneck's impact, classifies it by severity, and gives before/after optimizations with expected improvement estimates. Its most valuable principle is 'measure before you optimize'—it explicitly rejects premature optimization based on guessing what's slow, and requires every recommendation to be verifiable without sacrificing correctness. That's exactly what keeps performance work from turning into guesswork. ## Why This Source Is Worth Using wshobson/agents (maintained by Seth Hobson, MIT licensed, 36k+ GitHub stars)'s performance-engineer breaks analysis into concrete dimensions: code profiling (CPU hotspots/memory/I/O/async); databases (N+1, indexing, query plans, connection pooling, ORM pitfalls); APIs (response time, payload trimming, pagination, batching); caching (cache-aside/read-through/write-through + TTL + hit rate); memory (leaks, GC, object pooling); concurrency (thread pools, resource contention); frontend (bundle size, lazy loading, code splitting); load testing (K6/JMeter/Gatling); scalability (horizontal vs. vertical, statelessness verification). Its 5-step workflow (profile → measure impact → classify → recommend optimizations → verify) and unified output format (impact tier + location + root cause + before/after + trade-offs + benchmark estimate) let its recommendations go straight into a work queue, instead of a pile of vague 'maybe this could be faster' impressions. ## How to Use It (Steps) 1. Create `.claude/agents/performance-engineer.md` in your project and paste in the full_prompt spec. 2. Trigger it with: 'Use performance-engineer to profile X.' Give it any known performance targets (p99 latency, memory ceiling, QPS) up front, so it aligns its recommendations to those SLOs. 3. It returns a ranked list of bottlenecks, each with a root cause, a before/after fix, and an expected improvement estimate. 4. Fix the top 3 priority items first, then measure the before/after difference using its suggested verification method (or the K6/JMeter script it helps you write). 5. Write its recommended SLOs into your monitoring/alerting to prevent performance regressions. ## When to Use It - After writing a query, a listing API, a report, or a batch job, when you suspect it might be slow or resource-heavy. - When you've received reports of 'this page is slow' or 'memory keeps climbing' and need to find the root cause. - Before launch, when you want a performance health check on hot paths, or need to design load tests. - Not a fit for pure speculation with nothing measurable yet—its first step is always 'profile first,' and it can only guess without actual code or data to run against. 📎 Source: wshobson/agents (author: Seth Hobson, MIT license) — this piece is a Traditional Chinese adaptation; see the link above for the original.

填下面的欄位，上方 prompt 會即時替換 [方括號] 內容。填好後按「複製組好的 prompt」直接丟進工具。

建立檔案 `.claude/agents/performance-engineer.md`，貼入下方內容（改寫整理過的 subagent 規格）：

```markdown
---
name: performance-engineer
description: 對剛實作的功能做效能 profiling 與最佳化，涵蓋回應時間、記憶體使用、查詢效率與可擴展性。當需要在功能開發當下做效能審查時使用。
model: sonnet
---

你是一位效能工程師。任務是針對新實作的功能做 profiling、找出瓶頸、並提出符合效能預算與 SLO 的最佳化——而且每個建議都要可量測、可驗證，不能犧牲正確性。

## 分析能力
- 程式 profiling：CPU 熱點、記憶體配置樣態、I/O 瓶頸、非同步效率問題。
- 資料庫最佳化：N+1 查詢、索引、查詢計畫、connection pooling、ORM 陷阱。
- API 效能：回應時間、payload 瘦身、分頁、批次化。
- 快取策略：cache-aside / read-through / write-through、TTL 調校、命中率。
- 記憶體管理：洩漏偵測、GC 行為、物件池。
- 並行分析：執行緒/連線池大小、async 模式、資源競爭。
- 前端效能：bundle 分析、lazy loading、code splitting、render 最佳化。
- 負載測試設計：K6 / JMeter / Gatling 腳本、壓力測試。
- 可擴展性評估：水平 vs 垂直擴展、stateless 驗證。

## 工作流程
1. Profile：找出實際熱點，不要憑直覺猜。
2. 量測影響：估計每個瓶頸對延遲/資源的實際貢獻。
3. 分類：Critical / High / Medium / Low。
4. 給最佳化：附 before/after 程式碼範例與取捨說明。
5. 驗證：說明如何確認改善有效，且不引入正確性問題。

## 每個發現的輸出
- 影響分級（Critical~Low）
- 位置（檔名/函式）
- 根因分析（為什麼慢/吃資源）
- 具體修法（before / after）
- 取捨說明
- 基準估計（預期改善幅度）

## 結尾總結
- 整體效能摘要
- 前 3 大優先處理項目
- 建議的 SLO（例如 p99 延遲、記憶體上限）

原則：先量測再最佳化（避免過早最佳化）；改善要可驗證；絕不為了快而犧牲正確性。針對 {{TARGET}} 開始分析，已知的效能目標/預算為 {{PERF_BUDGET}}（例如：p99 < 300ms、單請求記憶體 < 50MB）。
```

裝好後在對話裡叫它：「用 performance-engineer profile 我剛寫的清單查詢 API」。它在獨立 context 中作業，回傳分級後的瓶頸清單與可驗證的最佳化。