前言¶

用 Cursor、Claude Code 這類 AI 編程工具寫後端時，生成業務代碼往往還算順手，一碰到 Postgres 就容易翻車：外鍵沒建索引、查詢全表掃描、連接池打滿、RLS 只寫在應用層……這些坑在本地小數據上看不出來，上線後纔會以慢查詢、超時、甚至數據串租戶的方式暴露出來。

2026 年 1 月，Supabase 發佈了面向 AI Agent 的 Postgres 最佳實踐 Skill：supabase-postgres-best-practices。它把官方沉澱的規則寫成 Agent Skills 標準格式，讓助手在改表、寫 SQL、配 RLS、排查性能時，按優先級去對照，而不是憑訓練記憶“猜”一套做法。本文按官方倉庫與文檔覈實後，介紹它是什麼、怎麼裝、怎麼用。

這是什麼¶

supabase-postgres-best-practices 是 Supabase 維護的 Postgres 最佳實踐 Skill（當前元數據版本爲 1.1.1，MIT 許可）。定位很明確：不只給 Supabase 託管庫用，也適用於“跑在任何地方的 Postgres”。

官方描述要求：在創建/修改表與列、做 schema 與遷移、寫 RLS 與相關測試、加索引、寫觸發器與數據庫函數、處理隊列/定時任務（如 pg_cron、pgmq）、向量檢索（pgvector）、導入數據，以及診斷慢查詢、高 CPU、超時、連接耗盡、鎖等待、膨脹、租戶數據可見性錯誤等問題之前，先加載這套規則。換句話說，它覆蓋性能，也覆蓋 schema、安全與日常 SQL 寫法。

倉庫地址：https://github.com/supabase/agent-skills/tree/main/skills/supabase-postgres-best-practices
技能目錄頁：https://skills.sh/supabase/agent-skills/supabase-postgres-best-practices
官方介紹博文：https://supabase.com/blog/postgres-best-practices-for-ai-agents

核心能力：八類規則，按影響排序¶

Skill 本體是 SKILL.md，細則在 references/ 目錄。每條規則通常包含：爲何重要、錯誤示例、正確示例，以及可選的 EXPLAIN/指標說明；涉及 Supabase 時會附帶平臺相關備註。

按影響從高到低，八個類別如下（前綴對應規則文件名）：

當前倉庫中可見的規則文件覆蓋例如：缺失索引與部分索引、連接池與連接上限、RLS 基礎與性能、主鍵/外鍵/數據類型、死鎖與短事務、分頁與批量寫入、EXPLAIN ANALYZE 與 pg_stat_statements、JSONB 與全文檢索等。官方博文曾概括爲約 30 條可引用規則；Agent 會按任務去讀對應的 references/*.md，而不是一次塞進全部上下文。

安裝與啓用¶

該 Skill 遵循 Agent Skills 開放格式，可在 Cursor、Claude Code、GitHub Copilot、VS Code、Gemini CLI 等支持該標準的工具中使用。官方推薦用 Vercel 的 skills CLI 安裝。

只裝本 Skill：

npx skills add supabase/agent-skills --skill supabase-postgres-best-practices

skills.sh 上也給出等價寫法（指向同一倉庫）：

npx skills add https://github.com/supabase/agent-skills --skill supabase-postgres-best-practices

安裝整個 supabase/agent-skills 倉庫（含 supabase 與本 Skill）：

npx skills add supabase/agent-skills

默認按項目範圍安裝，Skill 會落在倉庫裏，方便同事和雲端 Agent 共用；需要全局安裝時可加 --global。更新已安裝 Skill：

npx skills update

若使用 Claude Code，也可走插件市場：

claude plugin marketplace add supabase/agent-skills
claude plugin install postgres-best-practices@supabase-agent-skills

更完整的安裝說明見官方文檔：https://supabase.com/docs/guides/getting-started/ai-skills

裝好後一般無需額外開關：相關任務出現時，Agent 會自動發現並加載 Skill。官方還提醒：MCP（例如 Supabase MCP）負責連庫執行，本 Skill 負責“怎麼做纔對”；兩者搭配時，助手既有操作能力，也有規則約束。

典型用法¶

裝好之後，直接用自然語言即可，例如：

Optimize this Postgres query

Review my schema for performance issues

Help me add proper indexes to this table

也可以更具體地指向規則類別，比如“按 RLS 規則給多租戶訂單表寫策略並說明測試方式”，或“檢查這條遷移會不會長時間鎖表”。

下面是官方博文與規則文件裏同類示例的簡化對照，便於理解 Agent 會參照怎樣的正誤寫法。

1. WHERE/JOIN 列缺索引（query-missing-indexes）

不正確：大表上對未建索引列過濾，容易變成順序掃描。

select * from orders where customer_id = 123;
-- EXPLAIN 可能顯示：Seq Scan on orders ...

正確：在常用過濾列（以及外鍵引用側）建索引。

create index orders_customer_id_idx on orders (customer_id);

select * from orders where customer_id = 123;
-- EXPLAIN 可能顯示：Index Scan using orders_customer_id_idx ...

2. 多租戶只靠應用層過濾（官方博文 RLS 示例）

不正確：僅在應用裏拼 where user_id = ...，一旦繞過就暴露全表。

select * from orders where user_id = $current_user_id;
-- 若寫成 select * from orders; 則可能返回全部訂單

正確：在庫內啓用 RLS，並用策略約束可見行（Supabase Auth 場景常用 auth.uid()）：

alter table orders enable row level security;

create policy orders_user_policy on orders
  for all
  to authenticated
  using (user_id = auth.uid());

Agent 在寫遷移、改 schema、做性能 review 時，會按類別去讀 references/ 下的細則，再給出帶正誤對照的建議。

適用場景與注意點¶

適合這些情況：

• 用 AI 助手寫或改 Postgres schema、遷移、索引與查詢
• 配置連接池、排查連接耗盡或 serverless 下的連接問題
• 設計/審查 RLS 與權限，避免“應用層過濾看起來對了、庫層卻沒兜住”
• 做性能 review：慢查詢、鎖爭用、N+1、分頁與批量寫入
• 與 Supabase MCP 或 CLI 一起用，讓“能執行”變成“按規則執行”

需要注意：

• Skill 提供的是可引用規則與示例，不能替代真實環境的 EXPLAIN ANALYZE、監控與壓測結論。
• 規則按影響分級；落地時仍要結合表規模、讀寫比例和業務約束取捨（例如索引能加速讀，也可能增加寫成本）。
• 倉庫裏還有更偏產品面的 supabase Skill；做純 Postgres 優化優先本 Skill，做 Auth/Storage/Edge Functions 等產品集成可配合安裝 supabase。
• Supabase 會持續更新規則，生產項目建議定期執行 npx skills update。

小結¶

supabase-postgres-best-practices 把 Supabase 在託管 Postgres 中反覆見到的問題，整理成 Agent 可加載的分級規則：查詢與連接、RLS 與 schema、鎖與數據訪問模式，再到監控與高級特性。對已經在用 AI 寫後端的人來說，它補的是“正確 Postgres”這一層判斷，而不是又一份散落的文檔鏈接。

官方地址：https://github.com/supabase/agent-skills/tree/main/skills/supabase-postgres-best-practices
安裝命令：npx skills add supabase/agent-skills --skill supabase-postgres-best-practices