- Công bố Agent Skills nhằm giải quyết vấn đề AI coding agent không xử lý Postgres đúng cách, bằng cách cung cấp tường minh các quy tắc cho cơ sở dữ liệu
- Postgres có nhiều tính năng, edge case và đặc tính hiệu năng được tích lũy qua hàng chục năm, nên agent có thể tạo ra mã vẫn chạy được nhưng gây full table scan hoặc bỏ sót chính sách bảo mật
- Gồm 8 danh mục, 30 quy tắc và được sắp xếp theo mức độ ưu tiên dựa trên mức ảnh hưởng, bao phủ hiệu năng truy vấn, quản lý kết nối, bảo mật và RLS, thiết kế schema, v.v.
- Được cung cấp không phải dưới dạng tài liệu cho con người đọc, mà là một tập quy tắc để AI agent trực tiếp tham chiếu
- Khi kết hợp với MCP server, có thể xây dựng database agent sẵn sàng cho thực chiến với cả khả năng thực thi lẫn tiêu chí phán đoán
Nhận diện vấn đề: AI viết được mã nhưng không hiểu hệ thống
- AI coding agent có thể tạo ra mã đúng về mặt cú pháp, nhưng bị giới hạn ở chỗ không cân nhắc được đặc tính bên trong và rủi ro vận hành của Postgres
- Các vấn đề như truy vấn gây full table scan, đề xuất index làm giảm hiệu năng ghi, hoặc bỏ sót Row Level Security lặp đi lặp lại
- Đã ghi nhận nhiều trường hợp agent bỏ qua các yếu tố quan trọng trong môi trường production như hiệu năng, bảo mật và độ ổn định
Tổng quan về Postgres Agent Skills
- Kho tri thức dựa trên quy tắc được tạo ra để AI agent tham khảo khi viết mã Postgres
- Gồm tổng cộng 30 quy tắc trong 8 danh mục được sắp xếp theo mức độ ảnh hưởng
- Mỗi quy tắc bao gồm tiêu đề, mức ưu tiên, giải thích tầm quan trọng và ví dụ mã đúng/sai
Cấu trúc 8 danh mục quy tắc
- Mỗi quy tắc tuân theo một định dạng nhất quán, gồm tiêu đề, mức độ ảnh hưởng, mô tả và thẻ
- Query Performance (Critical): quy tắc viết truy vấn hiệu quả, tránh full table scan
- Connection Management (Critical): connection pooling, quản lý vòng đời client, giới hạn tài nguyên
- Security and RLS (Critical): chính sách Row Level Security, các mẫu kiểm soát truy cập
- Schema Design (High): cấu trúc bảng, kiểu dữ liệu, đánh giá chuẩn hóa
- Concurrency and Locking (Medium-High): cô lập transaction, tránh deadlock, quản lý lock
- Data Access Patterns (Medium): pagination, thao tác hàng loạt, thiết kế mẫu truy cập
- Monitoring and Diagnostics (Low-Medium): phân tích truy vấn, theo dõi hiệu năng, gỡ lỗi
- Advanced Features (Low): CTE, window function, extension và các tính năng riêng của Postgres
Ví dụ về quy tắc Row Level Security
- Cách sai: nếu chỉ phụ thuộc vào lọc ở tầng ứng dụng, sẽ có nguy cơ lộ toàn bộ dữ liệu do bug hoặc đường vòng truy cập
- Nếu viết theo dạng
select * from orders where user_id = $current_user_id;, khi bị bypass có thể trả về toàn bộ đơn hàng
- Cách đúng: cưỡng chế áp dụng RLS ở cấp cơ sở dữ liệu
- Bật RLS bằng
alter table orders enable row level security;
- Tạo chính sách bằng
create policy để người dùng chỉ xem được dữ liệu của chính mình
- Dùng
alter table orders force row level security; để cưỡng chế RLS cả với chủ sở hữu bảng
- Ví dụ chính sách cho role đã xác thực:
create policy orders_user_policy on orders for all to authenticated using (user_id = auth.uid());
Định dạng Agent Skills và hệ sinh thái
- Agent Skills là định dạng tài liệu dành riêng cho AI agent theo chuẩn mở, cung cấp chuyên môn theo miền cho agent; khi cần, agent có thể tự đọc và áp dụng
- Tương thích với Claude Code, Cursor, GitHub Copilot, VS Code, Gemini CLI, v.v.
- Được cung cấp dưới dạng thư mục chứa chỉ dẫn và ví dụ để agent có thể tự phát hiện và sử dụng khi cần
- Thay vì kỳ vọng agent đã học được mẫu đúng từ dữ liệu huấn luyện, nó cung cấp các quy tắc tường minh
- Đây là chuẩn mở do Anthropic định nghĩa và đang được áp dụng trên toàn ngành
- Vercel đã công bố react-best-practices, đóng gói 10 năm tri thức tối ưu hóa React và Next.js thành 40 quy tắc
- Cloudflare cũng công bố Skills cho hơn 40 dịch vụ như Workers, Pages, D1, R2
Vì sao Supabase tạo ra các quy tắc này
- Supabase vận hành Postgres trên hàng trăm nghìn dự án và chứng kiến cùng một lỗi lặp đi lặp lại
- Thiếu index trên foreign key
- Truy vấn vô tình bypass RLS
- Migration làm khóa bảng trong production
- Cạn kiệt connection pool do quản lý client kém
- Full table scan bị che giấu phía sau ORM
- Họ đã đóng gói lại tri thức vốn đã tồn tại trong đội ngũ hỗ trợ, database advisor và tài liệu thành định dạng thân thiện với agent
Mối quan hệ với MCP server
- Supabase MCP server cho phép AI agent kết nối trực tiếp tới dự án Supabase để tạo bảng, chạy truy vấn, quản lý schema và cấu hình thiết lập bằng ngôn ngữ tự nhiên
- MCP server trao cho agent khả năng thực hiện tác vụ cơ sở dữ liệu, còn best practice dạy agent cách làm đúng đắn
- Cách ví von: MCP server là vô lăng, còn best practice là lớp học lái xe
- Agent chỉ có quyền truy cập MCP có thể thực thi mọi truy vấn được yêu cầu
- Agent có cả quyền truy cập MCP và bộ quy tắc sẽ có thể cảnh báo trước khi tạo index làm khóa bảng, đề xuất chính sách RLS trước khi triển khai mã không an toàn, và cấu trúc truy vấn để tránh vấn đề hiệu năng
- MCP server phụ trách kết nối và thực thi, còn bộ best practice phụ trách phán đoán
- Agent Skills giúp cảnh báo rủi ro trước khi thực thi và định hướng lựa chọn tốt hơn
- Việc tách riêng năng lực thực thi và tiêu chí phán đoán giúp xây dựng môi trường tự động hóa an toàn và đáng tin cậy
Cách cài đặt
- Vị trí kho mã: github.com/supabase/agent-skills
- Có thể cài đặt tương tác bằng gói npm skills của Vercel
npx skills add supabase/agent-skills
- Khi dùng Claude Code, có thể cài như plugin
/plugin marketplace add supabase/agent-skills/plugin install postgres-best-practices@supabase-agent-skills
Chưa có bình luận nào.