supabase-postgres-best-practices 是 Supabase 维护的 Postgres 规则集，适用于不只运行在 Supabase 上的数据库。它覆盖查询、连接、权限、结构、锁和诊断等方面。最有效的输入不是一句“数据库很慢”，而是具体 SQL、表规模、现有索引、调用角色和执行计划。
安装并限定首次范围
在准备分析的项目目录打开终端：
npx skills@latest add supabase/agent-skills --skill supabase-postgres-best-practices --agent claude-code
命令只选择这一项并指定 Claude Code，省略全局参数时按项目安装。随后在会话中明确调用名称，再提供材料。安装规则不会自动连接数据库，也不会替你授予读写权限。
使用 supabase-postgres-best-practices 检查这条订单查询。
我会提供 schema.sql、现有索引和 EXPLAIN 输出。
先解释瓶颈证据，再给最小修改建议、验证方法与代价。
目前只做审阅，不执行迁移；也检查不同租户是否可能看到彼此订单。
先解释执行计划，再讨论索引
说明筛选条件、关联关系和通常返回多少行。规则提供 WHERE 与 JOIN 列的索引例子，但不能仅看到顺序扫描就机械加索引：还要结合表规模、筛选比例和写入负担，检查已有索引是否已经覆盖需求。要求建议指出对应查询、预期改变和验证方式，避免一次增加许多重复索引。
如果已有执行计划，先让 Agent 解读估计行数与实际行数、过滤掉的记录、循环次数和缓冲读取。EXPLAIN ANALYZE 不只是查看说明，它会执行查询；对修改数据的语句尤其需要谨慎选择测试环境和执行范围。不要为了收集一次计划直接让分析任务变成未经安排的生产写入。
把权限正确性与速度一起检查
只在应用 SQL 中加 user_id 条件，不等于数据库已经保证租户隔离。涉及 RLS 时，给出角色、策略和用户身份如何传入；Supabase 的认证上下文与自建应用的会话变量不是可以随意替换的同一方案。要求以正确的用户角色检查自己的记录、其他人的记录和未登录场景，而不是只用管理连接看到“查询正常”。
得到建议后，先在可控数据集上对比相同查询和相同角色，再决定是否形成迁移。需要修改表结构时，记录影响、回退思路和上线时机；规则集不会自动替你完成这类工程安排。最终交付应包含问题证据、候选改动及测量结果，而不是把指南里的示例成本或提速倍数复制成你系统的结论。
把一条建议变成可审查的改动
这个 Skill 的入口文件会指向按类别划分的规则文件。分析慢查询时，不妨要求 Agent 指出它采用了哪条 query-* 或 monitor-* 规则，并说明为什么适用于你的 SQL。把真实查询、参数范围、表行数、现有索引和计划放在一起，避免它只凭“有 WHERE 就建索引”下结论。若查询涉及分页，还要说明典型偏移或游标方式；若写入频繁，新增索引的写入成本也应列入判断。
对多租户表，单独走一遍权限情境：登录用户读自己的行、读别人的行、未登录访问、后台服务角色访问。建议写成可执行的测试用例，但先确认当前环境的认证上下文和 RLS 是否真的启用。使用 service role 的成功查询不能证明普通用户受到正确隔离；反过来，一个角色测试失败，也要辨认是策略问题还是测试身份没有正确传入。
最终交付最好是“小补丁 + 验证计划”：待修改 SQL 或策略、为什么修改、在测试库如何用相同参数对比、上线怎样回退。对会改写数据的语句，不要随手运行 EXPLAIN ANALYZE 来收集计划；它会执行查询。遇到连接耗尽或锁等待，先换到对应的 conn-* 或 lock-* 规则，不把所有数据库故障都归咎于缺少索引。
示例：一条租户查询慢，同时可能越权
假设应用查询 projects 时按 organization_id 过滤，但部分请求使用后台凭据，开发者发现普通成员偶尔看到了不属于自己的项目。先提供脱敏表结构、现有 RLS 策略、调用角色、查询参数和慢查询计划，输入：“使用 supabase-postgres-best-practices 先分别诊断权限与性能。列出哪些观察可能是后台凭据绕过 RLS、哪些是普通用户策略问题；再看筛选列与现有索引。只提出测试 SQL 和候选改动，不连接生产库执行。”
验收先做正确性：以两个不同租户的普通用户身份查询自己的和对方的项目，明确各自应看到什么；后台角色结果单独记录，不能当作权限测试通过。然后用相同参数和数据规模比较查询计划、返回行数与耗时。若 Agent 只建议新增索引而没有检查调用角色，停下来先补角色证据；索引能改变速度，却不能修复错误的租户隔离。
只在数据库任务中加载这份规则
在长期项目中，可以把调用范围写进项目说明：改迁移、RLS、索引、触发器或数据库函数时使用这份 Skill；仅修改前端展示或复用现有客户端查询时不必加载。一个 Codex 用户采用了类似规则，让数据库审查集中在真正会改变查询计划、权限或模式的任务上。真正执行迁移前，仍应针对当前数据库结构查看计划、复核权限并按项目发布流程审查。