convex-performance-audit by get-convex/agent-skills
npx skills add https://github.com/get-convex/agent-skills --skill convex-performance-audit诊断并修复 Convex 应用程序中的性能问题,一次解决一类问题。
npx convex insights --details 报告高字节读取、文档读取或 OCC 冲突从最强的可用信号开始:
npx convex insights --details。需要时使用 --prod、--preview-name 或 。
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
--deployment-nameinsights,在放弃之前尝试 npx -y convex@latest insights --details。convex-doctor,你可以将其发现视为提示。不要强制要求使用它,也不要将其视为真相来源。收集信号后,识别问题类别并阅读匹配的参考文件。
| 信号 | 参考 |
|---|---|
| 高字节或文档读取、JS 过滤、不必要的连接 | references/hot-path-rules.md |
| OCC 冲突错误、写入争用、变更重试 | references/occ-conflicts.md |
| 高订阅数、UI 更新缓慢、过多的重新渲染 | references/subscription-cost.md |
| 函数超时、事务大小错误、大负载 | references/function-budget.md |
| 没有特定信号的普遍“速度慢” | 从 references/hot-path-rules.md 开始 |
多个问题类别可能重叠。首先阅读最相关的参考,如果症状仍然存在,再检查其他参考。
如果可能的修复具有侵入性、横切性或迁移量大,请在编辑前停止并呈现选项。
例如:
当正确性取决于在部署期间处理新旧状态时,请查阅 skills/convex-migration-helper/SKILL.md 以了解迁移工作流。
从实际项目中选择一个具体的用户流程。查看代码库、客户端页面和 API 表面,找到与症状匹配的流程。
记录:
useQuery、usePaginatedQuery 或 useMutation 的客户端调用点对于路径中的每个函数:
ctx.db.get() 和 ctx.db.query()ctx.db.patch()、ctx.db.replace() 和 ctx.db.insert()在 Convex 中,每次额外的读取都会增加事务工作,每次写入都可能使响应式订阅者失效。将读取放大和失效放大视为首要问题。
阅读与您的问题类别匹配的参考文件。每个参考都包含特定的模式、代码示例和推荐的修复顺序。
不要停留在洞察报告所提及的单个函数上。追踪访问相同表的同级读取者和写入者。
当一个访问表的函数存在性能缺陷时,审计同级函数是否存在相同的模式。
找到一个问题后,检查同一表族(包括配套的摘要或汇总表)的同级读取者和写入者。
例如:
除非有明确的产品原因,否则不要修复一个路径而让另一个路径保持旧模式。
确认以下所有事项:
references/hot-path-rules.md - 读取放大、失效、非规范化、索引、摘要表references/occ-conflicts.md - 写入争用、OCC 解决、热点文档拆分references/subscription-cost.md - 响应式查询开销、订阅粒度、点读references/function-budget.md - 执行限制、事务大小、大文档、负载大小同时查看官方的 Convex 最佳实践 页面,获取涵盖参数验证、访问控制和代码组织的其他模式,这些可能在审计过程中出现。
每周安装量
6.7K
仓库
GitHub 星标数
15
首次出现
10 天前
安全审计
安装于
codex6.7K
cursor6.7K
kimi-cli6.7K
cline6.7K
opencode6.7K
gemini-cli6.7K
Diagnose and fix performance problems in Convex applications, one problem class at a time.
npx convex insights --details reports high bytes read, documents read, or OCC conflictsStart with the strongest signal available:
npx convex insights --details. Use --prod, --preview-name, or --deployment-name when needed.
insights, try npx -y convex@latest insights --details before giving up.convex-doctor, you may treat its findings as hints. Do not require it, and do not treat it as the source of truth.After gathering signals, identify the problem class and read the matching reference file.
| Signal | Reference |
|---|---|
| High bytes or documents read, JS filtering, unnecessary joins | references/hot-path-rules.md |
| OCC conflict errors, write contention, mutation retries | references/occ-conflicts.md |
| High subscription count, slow UI updates, excessive re-renders | references/subscription-cost.md |
| Function timeouts, transaction size errors, large payloads | references/function-budget.md |
| General "it's slow" with no specific signal | Start with references/hot-path-rules.md |
Multiple problem classes can overlap. Read the most relevant reference first, then check the others if symptoms remain.
If the likely fix is invasive, cross-cutting, or migration-heavy, stop and present options before editing.
Examples:
When correctness depends on handling old and new states during a rollout, consult skills/convex-migration-helper/SKILL.md for the migration workflow.
Pick one concrete user flow from the actual project. Look at the codebase, client pages, and API surface to find the flow that matches the symptom.
Write down:
useQuery, usePaginatedQuery, or useMutationFor each function in the path:
ctx.db.get() and ctx.db.query()ctx.db.patch(), ctx.db.replace(), and ctx.db.insert()In Convex, every extra read increases transaction work, and every write can invalidate reactive subscribers. Treat read amplification and invalidation amplification as first-class problems.
Read the reference file matching your problem class. Each reference includes specific patterns, code examples, and a recommended fix order.
Do not stop at the single function named by an insight. Trace sibling readers and writers touching the same tables.
When one function touching a table has a performance bug, audit sibling functions for the same pattern.
After finding one problem, inspect both sibling readers and sibling writers for the same table family, including companion digest or summary tables.
Examples:
Do not leave one path fixed and another path on the old pattern unless there is a clear product reason.
Confirm all of these:
references/hot-path-rules.md - Read amplification, invalidation, denormalization, indexes, digest tablesreferences/occ-conflicts.md - Write contention, OCC resolution, hot document splittingreferences/subscription-cost.md - Reactive query cost, subscription granularity, point-in-time readsreferences/function-budget.md - Execution limits, transaction size, large documents, payload sizeAlso check the official Convex Best Practices page for additional patterns covering argument validation, access control, and code organization that may surface during the audit.
Weekly Installs
6.7K
Repository
GitHub Stars
15
First Seen
10 days ago
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
codex6.7K
cursor6.7K
kimi-cli6.7K
cline6.7K
opencode6.7K
gemini-cli6.7K
99,500 周安装