- Agent Skills dirilis untuk mengatasi masalah agen AI coding yang tidak menangani Postgres dengan benar, dengan menyediakan aturan database secara eksplisit
- Postgres memiliki fitur yang terakumulasi selama puluhan tahun, edge case, dan karakteristik performa sehingga agen dapat bekerja, tetapi tetap bisa menghasilkan kode yang memicu full table scan atau melewatkan kebijakan keamanan
- Terdiri dari 8 kategori, 30 aturan yang disusun berdasarkan prioritas menurut dampaknya, mencakup performa kueri, manajemen koneksi, keamanan dan RLS, desain skema, dan lainnya
- Disediakan bukan sebagai dokumentasi untuk dibaca manusia, melainkan dalam bentuk kumpulan aturan yang dirujuk langsung oleh agen AI
- Jika digabungkan dengan server MCP, dimungkinkan membangun agen database siap pakai di dunia nyata yang sekaligus memiliki kemampuan eksekusi dan kriteria penilaian
Memahami masalah: AI bisa menulis kode, tetapi tidak memahami sistem
- Agen AI coding menghasilkan kode yang benar secara sintaks, tetapi memiliki keterbatasan karena tidak mempertimbangkan karakteristik internal dan risiko operasional Postgres
- Masalah seperti kueri yang memicu full table scan, usulan indeks yang menurunkan performa tulis, dan kelalaian Row Level Security terus berulang
- Telah ditemukan banyak kasus agen melewatkan faktor performa, keamanan, dan stabilitas yang penting di lingkungan produksi
Gambaran umum Postgres Agent Skills
- Repositori pengetahuan berbasis aturan yang dibuat agar agen AI dapat merujuknya saat menulis kode Postgres
- Terdiri dari 30 aturan dalam 8 kategori yang diurutkan berdasarkan dampak
- Tiap aturan mencakup judul, prioritas, penjelasan pentingnya aturan, serta contoh kode yang benar/salah
Susunan 8 kategori aturan
- Setiap aturan mengikuti format yang konsisten, mencakup judul, dampak, penjelasan, dan tag
- Query Performance (Critical): aturan untuk mencegah full table scan dan menulis kueri yang efisien
- Connection Management (Critical): connection pooling, pengelolaan siklus hidup klien, dan batas sumber daya
- Security and RLS (Critical): kebijakan Row Level Security dan pola kontrol akses
- Schema Design (High): struktur tabel, tipe data, dan penilaian normalisasi
- Concurrency and Locking (Medium-High): isolasi transaksi, pencegahan deadlock, dan pengelolaan lock
- Data Access Patterns (Medium): pagination, operasi bulk, dan desain pola akses
- Monitoring and Diagnostics (Low-Medium): analisis kueri, pelacakan performa, dan debugging
- Advanced Features (Low): fitur khas Postgres seperti CTE, window function, dan ekstensi
Contoh aturan Row Level Security
- Cara yang salah: jika hanya mengandalkan filtering di level aplikasi, ada risiko seluruh data terekspos karena bug atau bypass
- Jika ditulis dalam bentuk
select * from orders where user_id = $current_user_id;, semua pesanan bisa dikembalikan saat terjadi bypass
- Cara yang benar: menerapkan RLS secara paksa di level database
- Aktifkan RLS dengan
alter table orders enable row level security;
- Buat kebijakan dengan
create policy agar pengguna hanya dapat melihat datanya sendiri
- Paksa RLS bahkan untuk pemilik tabel dengan
alter table orders force row level security;
- Contoh kebijakan untuk role terautentikasi:
create policy orders_user_policy on orders for all to authenticated using (user_id = auth.uid());
Format Agent Skills dan ekosistemnya
- Agent Skills adalah format dokumen khusus agen AI berbasis standar terbuka yang memberikan keahlian domain kepada agen; saat diperlukan, agen dapat langsung membacanya dan menerapkannya
- Kompatibel dengan Claude Code, Cursor, GitHub Copilot, VS Code, Gemini CLI, dan lainnya
- Disediakan dalam bentuk folder berisi panduan dan contoh yang bisa ditemukan dan digunakan agen saat dibutuhkan
- Alih-alih berharap agen telah mempelajari pola yang benar dari data pelatihan, format ini memberikan aturan eksplisit
- Ini adalah standar terbuka yang didefinisikan oleh Anthropic dan sedang diadopsi secara luas di industri
- Vercel merilis react-best-practices, yang mengemas 10 tahun pengetahuan optimasi React dan Next.js ke dalam 40 aturan
- Cloudflare merilis Skills untuk lebih dari 40 layanan seperti Workers, Pages, D1, dan R2
Mengapa Supabase membuat aturan ini
- Supabase mengoperasikan Postgres di ratusan ribu proyek dan menyaksikan kesalahan yang sama terus berulang
- Indeks yang hilang pada foreign key
- Kueri yang tanpa sengaja melewati RLS
- Migrasi yang mengunci tabel di produksi
- Kehabisan connection pool akibat klien yang dikelola dengan buruk
- Full table scan yang tersembunyi di balik ORM
- Pengetahuan yang sudah ada di tim support, database advisor, dan dokumentasi dikemas ulang dalam bentuk yang ramah agen
Hubungan dengan server MCP
- Server MCP Supabase memungkinkan agen AI terhubung langsung ke proyek Supabase untuk membuat tabel, menjalankan kueri, mengelola skema, dan mengatur konfigurasi lewat bahasa alami
- Server MCP memberi agen kemampuan untuk melakukan pekerjaan database, sedangkan best practice mengajarkan cara melakukannya dengan benar
- Analogi: server MCP adalah setir, best practice adalah pelajaran mengemudi
- Agen yang hanya memiliki akses MCP dapat menjalankan semua kueri yang diminta
- Agen yang memiliki akses MCP sekaligus aturan dapat memberi peringatan sebelum membuat indeks yang mengunci tabel, menyarankan kebijakan RLS sebelum menyebarkan kode yang tidak aman, serta menyusun kueri untuk menghindari masalah performa
- Server MCP menangani koneksi dan eksekusi, sedangkan best practice menangani penilaian
- Agent Skills memperingatkan faktor risiko sebelum eksekusi dan mendorong pilihan yang lebih baik
- Dengan memisahkan kemampuan eksekusi dan kriteria penilaian, dapat dibangun lingkungan otomasi yang aman dan dapat dipercaya
Cara instalasi
- Lokasi repositori: github.com/supabase/agent-skills
- Dapat diinstal secara interaktif menggunakan paket npm skills dari Vercel
npx skills add supabase/agent-skills
- Saat menggunakan Claude Code, dapat diinstal sebagai plugin
/plugin marketplace add supabase/agent-skills/plugin install postgres-best-practices@supabase-agent-skills
Belum ada komentar.