Workflow
1. Clarify goals and boundaries
First confirm or verify from the project:
- Target metrics, such as latency, throughput, CPU, memory, query count, or bundle size.
- Reproducible scenarios, data scale, runtime environment, versions, and key configurations.
- The scope the user allows to be analyzed and modified, and whether load or profiler can be run.
When there is no clear goal, first narrow the scope using existing monitoring, benchmarks, or user-reported symptoms, and do not treat "the code looks slow" as a bottleneck conclusion.
2. Establish a baseline
Prefer reusing the project's existing startup, benchmark, trace, and profiling configurations. Under the same environment, data, and load, record:
- Warm-up method, concurrency level, number of repetitions, and statistical criteria.
- Code version, dependency versions, and configurations that affect results.
- Raw measured values and fluctuation range; when conditions permit, retain machine-readable results.
When the project cannot be run, only static analysis can be performed, and findings must be marked as "candidates pending verification".
3. Collect evidence
Choose profilers, traces, flame graphs, query plans, network timing, or memory snapshots according to the technology stack to locate where time or resources are actually consumed. Common dimensions include:
- Code: algorithmic complexity, repeated computation, allocation hotspots, synchronous blocking, and concurrency contention.
- Database: N+1 queries, scan volume, index usage, lock waits, and connection pool status.
- Network: request waterfalls, payloads, compression, cache hits, and external service latency.
Complexity analysis and code review can only prove risk; they cannot by themselves prove runtime impact.
4. Propose minimal changes
- Bind recommendations to specific evidence, files, or call chains.
- Explain the trade-offs in correctness, memory, throughput, maintenance cost, and compatibility.
- Prioritize hotspots with the strongest evidence and greatest impact; do not change multiple factors that cannot be independently attributed at the same time.
- Prepare verification and rollback methods for code, configuration, and data structure changes.
5. Re-test under the same conditions
After modification, re-test using the same environment, data, load, warm-up, and statistical criteria as the baseline, and run correctness tests for affected functionality. Report raw results, fluctuations, differences, and variables not yet controlled.
Only after actually completing same-condition measurements can definitive conclusions such as time costs, percentages, or "improved" be written.
Evidence levels
- Measured: has a reproducible baseline, profiling evidence, and actual results.
- Static inference: candidate issues derived from complexity, call relationships, or configuration, not yet measured.
- Pending verification: lacks environment, data, or permissions, and the impact cannot currently be determined.
Security and authorization boundaries
- By default, perform read-only analysis only locally or in a test environment explicitly specified by the user.
- Production environment profiling, stress testing,
EXPLAIN ANALYZEand index, cache, connection pool, CDN, or external service configuration changes must obtain explicit authorization. - Do not expose production data, credentials, or profiling artifacts containing sensitive information in the report.
- Do not remove correctness checks, reduce data scale, or change statistical criteria in order to obtain pretty numbers.
- On Windows and Linux, prioritize using the project's existing tools; platform-specific commands must state their applicable scope or provide equivalent methods.
Output
## 性能分析结果
- 目标指标与场景：
- 环境、版本与数据规模：
- 基线与测量方法：
## 发现
| 证据等级 | 位置 | 证据 | 影响与限制 |
|----------|------|------|------------|
## 改动与权衡
## 同条件复测
- 正确性验证：
- 性能结果：
- 未控制变量与待验证项：
- 回滚方式：