performance-optimization

性能优化技能

分析并实施 API 调用、数据库查询和数据处理模式的性能优化。

使用场景

• 分析代码库中的性能瓶颈
• 实施批量操作
• 优化 N+1 查询模式
• 并行执行相互独立的操作
• 添加数据库索引

项目范围规则

• 优先将代码搜索范围限定在当前仓库。
• 优先将运行时性能调查范围限定在当前仓库的活跃可观测性项目。
• 只有在明确要求时，才扩展到其他项目或仓库。

用于循证重构的真实数据源

在提出深入重构或广泛架构变更之前，先通过可观测性数据验证实际热点。

对于已通过本地分析、测试或明显的静态 N+1／顺序执行模式确认的小型本地优化，可跳过 Sentry 项目发现。

Sentry MCP（主要运行时数据源）

完成项目发现后，使用 Sentry MCP 检查慢事务、慢跨度和高百分位延迟。

• 当运行时行为尚不明确、怀疑存在跨服务延迟，或考虑深入重构时，执行项目发现。
• 在提出代码变更之前，优先参考近期时间窗口和聚合视图中的证据。

agent-tools 技能（可选的实际运行情况依据）

需要基础设施、日志或数据库上下文来通过真实数据验证瓶颈时，加载 agent-tools：

• 使用 bun run logs-tool ... 查看应用日志中的耗时模式
• 使用 bun run db-tool ... 执行 SQL 检查和行数／基数检查
• 使用 bun run k8s-tool ... 查看 Pod CPU／内存限流和运行时压力

使用这些工具确认瓶颈来自应用逻辑、数据库行为还是基础设施限制。

如果当前 Agent／运行时无法使用 agent-tools，请改用以下信号：

• 使用仓库本地日志和调试插桩
• 使用测试样例和可复现的基准测试脚本
• 使用数据库查询计划和耗时输出（在可用时使用 EXPLAIN (ANALYZE, BUFFERS)）
• 无法收集基础设施级数据时，明确说明不确定性

分析工作流

1. 识别瓶颈

在代码库中搜索以下高影响模式：

• 包含 API／数据库调用的 N+1 循环
• 可并行执行的顺序独立调用
• 循环中的单条插入／更新／删除操作
• 可改为 upsert 的重复读取后写入流程

2. 应用优化

• 使用 inArray 和查找映射批量读取
• 批量写入（insert(values[])、update ... where inArray、delete ... where inArray）
• 在能够改善基数和延迟时，通过联接／子查询整合多查询流程
• 使用 Effect.all／Effect.forEach(..., { concurrency }) 和 Promise.all 并行执行相互独立的工作
• 使用 upsert 模式，避免写入前的往返读取

将完整代码示例放在参考文档中，以缩减 SKILL.md 的大小并保持跨 Agent 的可移植性。

数据库索引指南

何时添加索引

1. 单列查询：如果经常按某一列进行筛选
2. 复合查询：如果经常同时按多列进行筛选
3. ORDER BY 列：如果经常按某一列排序
4. 外键：PostgreSQL 不会自动为外键列创建索引；当外键列用于联接、筛选或级联删除／更新时，请显式创建索引

验证与测量工作流

1. 建立基线

• 记录目标路径的 p50／p95 延迟、查询次数和吞吐量。
• 在适用时记录内存和错误率信号。
• 记录基线时间窗口和工作负载假设。

2. 实施影响最大的最小变更

• 每次只更改一类热点（N+1、顺序独立调用、未批量处理的写入、缺失的索引）。
• 保持功能行为和现有错误语义不变。

3. 验证正确性

• 运行检查（bun run check）和相关测试。
• 确认错误处理和日志记录仍然恰当。
• 确认外部 API 的并发限制。

4. 在可比负载下重新测量

• 对照基线比较 p50/p95 延迟、查询次数、吞吐量和资源使用情况。
• 确认改进在统计上有意义，而非噪声。

5. 防止回归

• 随变更保留基准测试或跟踪证据。
• 如果关键优化路径的行为可能出现回归，则添加针对性测试。
• 记录任何仍需基础设施层面验证的瓶颈。

参考资料

• 查看 references/effect-parallel-patterns.md，了解 Effect 并行化模式和并发指导。
• 查看 references/drizzle-batch-patterns.md，了解 Drizzle 批处理操作、联接、预取映射和 upsert 模式。